Binary packet structure V2¶
Table of Contents
For the shearwater board, we modified the packet structure (in particularly the packet type (PT) byte content). The main reason for altering packet type is adding additional sensors. For shearwater, we have batch size of more then 16 registers for processed registers.
|
|
|
PT |
address |
D0 , D1 , …, DN-1, DN |
Checksum1 |
Checksum0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5 |
Byte 6, 7, … , N-1, N |
Byte N+1 |
Byte N+2 |
packet start |
type |
address |
data bytes |
Checksum |
|||
We introduce the following changes in the packet type (PT) byte:
The “Batch Length” BL is renamed to “Data Length” DL;
The “Is Batch” bit is now removed. If \(\text{Data Length} > 1\), then the packet shall be considered as batch packet;
The “Data Length” bitfield has 5-bit length (see the table below);
The “Command Failed” CF bit is replaced by the “Error” ERR.
If the execution from the packet failed for some reason, the error code is transferred back as 4-byte payload (see below). Before a separate command with different address was sent to indicate type of error. Now as answer should come error bit, and error code.
bit: |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
meaning: |
Has Data |
DL4 |
DL3 |
DL2 |
DL1 |
DL0 |
hidden |
ERR |
Bit(s) |
Description |
|---|---|
7 |
Has Data: If the packet contains data, this bit is set (1). If not, this bit is cleared (0). |
6:2 |
Data Length (DL): Five bits specifying the number of the 32-bit-data fields in the packet, e.g.: \(1\;\textbf{DL} = 1 \times 4 \; \text{bytes} = 4 \; \text{bytes}\) \(3\;\textbf{DL} = 3 \times 4 \; \text{bytes} = 12 \; \text{bytes}\) \(18\;\textbf{DL} = 18 \times 4 \; \text{bytes} = 72 \;\text{bytes}\) \(22\;\textbf{DL} = 22 \times 4 \; \text{bytes} = 88 \; \text{bytes}\) Unused if bit 7 is cleared. The maximum data length is therefore \(2^5 - 1 = 31\) |
1 |
Hidden: If set, then the packet address specified in the “address” field is a “hidden” address. Hidden registers are used to store factory calibration and filter tuning coefficients that do not typically need to be viewed or modified by the user. |
0 |
Packet Error (ERR): Used by the RSL board to report when a packet operation has failed. Must be set to zero for all packets written to the RSL boards. This bit is only set by the RSL board to indicate the error with processing / executing the packet |
The address byte specifies which register will be involved in the operation:
During a read operation (Has Data = 0), the address specifies which register to read.
During a write operation (Has Data = 1), the address specifies where to place the data contained in the data section of the packet.
For a batch read/write operation, the address byte specifies the starting address of the operation.
The “Data Bytes” section of the packet contains data to be written to one or more registers. No byte in the packet states explicitly how many bytes are in this section because it is possible to determine the number of data bytes that should be in the packet by evaluating the PT byte.
If the “Has Data” bit in the PT byte is cleared (Has Data = 0), then there are no data bytes in the packet and the “Checksum” immediately follows the address. If, on the other hand, the “Has Data” bit is set (Has Data = 1) then the number of bytes in the data section depends on the value of the “Is Batch” and “Batch Length” portions of the PT byte.
For a batch operation (Data Length > 1), the length of the packet data section is equal to:
Note that the batch length refers to the number of registers in the batch, NOT the number of bytes. Registers are \(4\) bytes long.
For a non-batch operation (\(\text{Data Length} = 1\)), the length of the data section is equal to 4 bytes (one register). The data section lengths and total packet lengths for different PT configurations are shown below.
Has Data |
Data Length |
Data Section Length (bytes) |
Total Packet Length (bytes) |
|---|---|---|---|
\(0\) |
N/A |
\(0\) |
\(7\) |
\(1\) |
\(1\) |
\(4\) |
\(11\) |
\(1\) |
\(1 < \text{DL} \leq 31\) |
\(4 \times (\text{Data Length})\) |
\(7 + 4 \times (\text{Data Length})\) |
The two checksum bytes consist of the unsigned 16-bit sum of all preceding bytes in the packet, including the packet header.
When the ERR bit is set, then the packet has 4 byte string payload, which specifies the reported error code (which starts with “E” (or 69d / 0x45 hex), and follows with the 3-digit error code, e.g. “E001”.
The error codes are specified in the table below.
Error code |
Description |
|---|---|
|
Invalid packet address |
|
Incorrect packet checksum |
|
Incorrect packet structure |
Read Operations¶
To initiate a serial read of one or more registers aboard the sensor, a packet should be sent to the RSL board with the “Has Data” bit cleared. This tells the device that this will be a read operation from the address specified in the packet’s “Address” byte. If the \(\text{Data Length} > 1\), then the packet will trigger a batch read in which the “Address” byte specifies the address of the first register to be read.
In response to a read packet, the RSL serial interface will send a packet in which the “Has Data” bit is set, and the “Data Length” bits are equivalent to those of the packet that triggered the read operation. The register data will be contained in the “Data Bytes” section of the packet.
Write Operations¶
To initiate a serial write into one or more registers aboard the sensor, a packet should be sent to the board with the “Has Data” bit set. This tells the device that the incoming packet contains data that should be written to the register specified by the packet’s “Address” byte. If a batch write operation is to be performed, the Data length field content shall be more then 1, and the “Data Length” bits shall indicate the number of registers that are to be written to.
In response to a write packet,
the RSL serial response will update the contents of the specified register(s) with
the contents of the data section of the packet.
It will then transmit a COMMAND_COMPLETE packet to indicate
that the write operation succeeded.
A COMMAND_COMPLETE packet is a packet with PT = 0 (no data)
and with an address matching the address of the register
to which the write operation was made,
or the start address of the write operation if this was a batch write.
Note that the COMMAND_COMPLETE packet is equivalent to a packet
that would cause the board to initiate a read operation on
the address to which data was just written.
Since the packet is going from the sensor to the host, however,
its meaning is different (it would not make sense for the board
to request the contents of one of its registers from an external host).
Command Operations¶
There are a variety of register address that do not correspond with actual physical registers aboard. The command registers are special ones, reading or writing from which are to cause the sensor to execute specific actions (there are commands for executing calibration operations, resetting the onboard filters, etc. See the Register Map V2 in this document for more details).
To initiate a command, simply send a packet to the board with the command’s address in the packet “Address” byte. The PT byte should be set to zero for a command operation.
If the RSL board successfully completes the specified command,
then a COMMAND_COMPLETE packet is returned with the command address
in the “Address” byte of the response packet.
If the command fails, the device responds by sending a COMMAND_FAILED packet.
The COMMAND_FAILED packet is equivalent to the COMMAND_COMPLETE packet except that the
“Error” bit in the PT byte is set (ERR = 1).
In some cases, a command will cause specific packets to be sent other than the
COMMAND_COMPLETE packet.
The GET_FW_BUILD_ID command will, for example, return a packet containing the version
of the firmware installed on the RSL board.
In this and similar cases, the COMMAND_COMPLETE packet is not sent.
Broadcasted packets¶
It is possible to configure the following packets to be sent periodically from the RSL board:
ALL_RAW_PACKET¶
The ALL_RAW_PACKET has the structure defined in the table below.
The Data Length of the packet is \(18\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
|
|
23 |
|
|
24 |
Reserved |
|
25 |
Reserved |
|
26 |
|
|
27 |
|
|
28 |
|
|
29 |
|
|
30 |
|
|
31 |
|
|
32 |
|
|
33 |
|
|
34 |
|
|
35 |
|
|
36 |
Reserved |
|
37 |
Reserved |
|
38 |
|
|
39 |
|
|
40 |
|
|
41 |
|
|
42 |
|
|
43 |
|
|
44 |
|
|
45 |
|
|
46 |
|
|
47 |
|
|
48 |
|
|
49 |
|
|
50 |
|
|
51 |
|
|
52 |
|
|
53 |
|
|
54 |
|
|
55 |
|
|
56 |
|
|
57 |
|
|
58 |
|
|
59 |
|
|
60 |
|
|
61 |
|
|
62 |
|
|
63 |
|
|
64 |
Reserved |
|
65 |
Reserved |
|
66 |
|
|
67 |
|
|
68 |
|
|
69 |
|
|
70 |
|
|
71 |
|
|
72 |
|
|
73 |
|
|
74 |
|
|
75 |
|
|
76 |
|
|
77 |
|
|
78 |
Checksum 1 |
|
79 |
Checksum 2 |
RAW_GYRO_1_PACKET¶
The RAW_GYRO_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(3\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
Checksum 1 |
|
19 |
Checksum 2 |
RAW_GYRO_2_PACKET¶
The RAW_GYRO_2_PACKET has the structure defined in the table below.
The Data Length of the packet is \(3\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
Checksum 1 |
|
19 |
Checksum 2 |
RAW_ACCEL_1_PACKET¶
The frequency of sending the RAW_ACCEL_1_PACKET broadcast messages
is defined by the field RAW_ACCEL_1_RATE in the CREG_COM_RATES1 register.
Note: if ALL_RAW_RATE field of the register CREG_COM_RATES2 is not 0, then
packet with all raw sensor data (ALL_RAW_PACKET) will be sent instead,
since ALL_RAW_PACKET has higher priority.
The RAW_ACCEL_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(3\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
Checksum 1 |
|
19 |
Checksum 2 |
RAW_MAG_1_PACKET¶
The RAW_MAG_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(4\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
Checksum 1 |
|
23 |
Checksum 2 |
RAW_MAG_2_PACKET¶
The RAW_MAG_2_PACKET has the structure defined in the table below.
The Data Length of the packet is \(3\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
Checksum 1 |
|
19 |
Checksum 2 |
RAW_TEMPERATURE_PACKET¶
The RAW_TEMPERATURE_PACKET has the structure defined in the table below.
The Data Length of the packet is \(2\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
Checksum 1 |
|
15 |
Checksum 2 |
ALL_PROC_PACKET¶
The ALL_PROC_PACKET has the structure defined in the table below.
The Data Length of the packet is \(22\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
|
|
23 |
|
|
24 |
|
|
25 |
|
|
26 |
|
|
27 |
|
|
28 |
|
|
29 |
|
|
30 |
|
|
31 |
|
|
32 |
|
|
33 |
|
|
34 |
|
|
35 |
|
|
36 |
|
|
37 |
|
|
38 |
|
|
39 |
|
|
40 |
|
|
41 |
|
|
42 |
|
|
43 |
|
|
44 |
|
|
45 |
|
|
46 |
|
|
47 |
|
|
48 |
|
|
49 |
|
|
50 |
|
|
51 |
|
|
52 |
|
|
53 |
|
|
54 |
|
|
55 |
|
|
56 |
|
|
57 |
|
|
58 |
|
|
59 |
|
|
60 |
|
|
61 |
|
|
62 |
|
|
63 |
|
|
64 |
|
|
65 |
|
|
66 |
|
|
67 |
|
|
68 |
|
|
69 |
|
|
70 |
|
|
71 |
|
|
72 |
|
|
73 |
|
|
74 |
|
|
75 |
|
|
76 |
|
|
77 |
|
|
78 |
|
|
79 |
|
|
80 |
|
|
81 |
|
|
82 |
|
|
83 |
|
|
84 |
|
|
85 |
|
|
86 |
|
|
87 |
|
|
88 |
|
|
89 |
|
|
90 |
|
|
91 |
|
|
92 |
|
|
93 |
|
|
94 |
Checksum 1 |
|
95 |
Checksum 2 |
PROC_GYRO_1_PACKET¶
The PROC_GYRO_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(4\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
Checksum 1 |
|
23 |
Checksum 2 |
PROC_GYRO_2_PACKET¶
The PROC_GYRO_2_PACKET has the structure defined in the table below.
The Data Length of the packet is \(4\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
Checksum 1 |
|
23 |
Checksum 2 |
PROC_ACCEL_1_PACKET¶
The PROC_ACCEL_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(4\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
Checksum 1 |
|
23 |
Checksum 2 |
PROC_MAG_1_PACKET¶
The PROC_MAG_1_PACKET has the structure defined in the table below.
The Data Length of the packet is \(5\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
|
|
23 |
|
|
24 |
|
|
25 |
|
|
26 |
Checksum 1 |
|
27 |
Checksum 2 |
PROC_MAG_2_PACKET¶
The PROC_MAG_2_PACKET has the structure defined in the table below.
The Data Length of the packet is \(5\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
21 |
|
|
22 |
|
|
23 |
|
|
24 |
|
|
25 |
|
|
26 |
Checksum 1 |
|
27 |
Checksum 2 |
EULER_PHI_THETA¶
The EULER_PHI_THETA has the structure defined in the table below.
The Data Length of the packet is \(5\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
Reserved |
|
13 |
Reserved |
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
Reserved |
|
21 |
Reserved |
|
22 |
|
|
23 |
|
|
24 |
|
|
25 |
|
|
26 |
Checksum 1 |
|
27 |
Checksum 2 |
HEALTH¶
The HEALTH has the structure defined in the table below.
The Data Length of the packet is \(1\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
Checksum 1 |
|
11 |
Checksum 2 |
QUATERNION¶
The QUATERNION has the structure defined in the table below.
The Data Length of the packet is \(3\), hence the packet total length:
Byte |
Content |
Register Payload |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
Packet type |
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
Checksum 1 |
|
19 |
Checksum 2 |