packet_structure

Packet Structure

Freescale's sensor fusion kit (upon which the initial MIG offering is based), utilizes 2-way communications over UART between sensor board and Windows PC or Android devicerunning the Freescale Sensor Fusion Toolkit (this combination is referred to as "controller" below). Sensor and fusion samples are sent from sensor board to controller for visualization, and commands are sent back to effect fusion operation. This page illustrates the packet structures used. These are included in C files Events.c and drivers.c.

This document was extracted from the in-app documentation of the Freescale Sensor Fusion Toolbox for Android.

Development board to Controller

Packet Type 1

Byte #	Function	Units
0	Packet Start = 0x7E	None
1	Packet Type = 01	None
2	Packet #	This number increments by 1 for each sample. Rolls over at 0xFF to 0x00.
6:3	Timestamp	1 LSB = 1.00 microseconds (Previously 1.33. Updated 2013.07.18)
8:7	ACC X	1 LSB = 122.07 micro-g's
10:9	ACC Y	1 LSB = 122.07 micro-g's
12:11	ACC Z	1 LSB = 122.07 micro-g's
14:13	MAG X	1 LSB = 0.1 microTesla
16:15	MAG Y	1 LSB = 0.1 microTesla
18:17	MAG Z	1 LSB = 0.1 microTesla
20:19	GYRO X	1 LSB = 872.66 micro-radians/sec (0.05 dps)
22:21	GYRO Y	1 LSB = 872.66 micro-radians/sec (0.05 dps)
24:23	GYRO Z	1 LSB = 872.66 micro-radians/sec (0.05 dps)
26:25	quaternion q0	1 LSB = 1/30,000 (unitless)
28:27	quaternion q1	1 LSB = 1/30,000 (unitless)
30:29	quaternion q2	1 LSB = 1/30,000 (unitless)
32:31	quaternion q3	1 LSB = 1/30,000 (unitless)
33	Flags	Bit field with the following bit definitions: Bits 3:0 = 0x1 = quaternion is derived from accel only Bits 3:0 = 0x2 = quaternion is derived from mag/accel algorithm Bits 3:0 = 0x3 = quaternion is derived from gyro only algorithm Bits 3:0 = 0x4 = quaternion is derived from accel/gyro algorithm Bits 3:0 = 0x6 = quaternion is derived from 2D magnetometer only algorithm Bits 3:0 = 0x8 = quaternion is derived from 9-axis mag/accel/gyro algorithm Bits 3:0 = all other values are reserved Bits 5:4 = 00 = Data is NED Frame of Reference Bits 5:4 = 01 = Data is Android Frame of Reference Bits 5:4 = 10 = Data is Windows Frame of Reference Bits 5:4 = 11 = RESERVED Bits 7:6 = RESERVED
34	Board ID	Numeric field with the following possible values: 0 = Xtrinsic Windows 8 Sensor Platform Rev 0.5 1 = FRDM-KL25Z with Freescale Sensor Shield 2 = FRDM-K20D50M with Freescale Sensor Shield 4 = FRDM-KL26Z with Freescale Sensor Shield 5 = FRDM-K64F with Freescale Sensor Shield 6 = RESERVED 7 = KL46Z 8 = KL46Z Standalone All others reserved. <BR>Contact [email protected] if you are interested in having another board added to this list. </TD></TR> <TR><TD>35</TD><TD>Packet END = 0x7E</TD><TD>None</TD></TR>

The development board to controller protocol is a streaming data protocol (using RFCOMM). Packets are delimited by inserting a special byte (0x7E) between packets. This means that we must provide a means for transmitting 0x7E within the packet payload. This is done on the transmission side by making the following substitutions:

The controller does the inverse mapping as the data stream is received. Partial packets are discarded. The options menu has a "Toggle Hex Display" option available for those those intrepid developers brave enough to try coding their own board interface.

Packet Type 2: Debug

The development board may send 1 to n 16-bit words to the app for display on the Device view. This view is enabled via a checkbox in the Preferences screen.

<TR><TD>2n+5</TD><TD>Packet END = 0x7E</TD><TD>None</TD></TR>

Byte #	Function	Units
0	Packet Start = 0x7E	None
1	Packet Type = 0x02	None
2	Packet #	This number increments by 1 for each sample. Rolls over at 0xFF to 0x00.
4:3	Software version number	First of "n" debug words to transmit
6:5	Systick Counter	Multiply by 20 to get number of systicks to compute one orientation with the current algorithm
8:7	Debug Word1	1st of "n" debug words to transmit
10:9	Debug Word2	Second of "n" debug words to transmit
...	...	...
2n+4:2n+5	Debug Wordn	Last of "n" debug words to transmit

The Device view of the Freescale Sensor Fusion Toolbox will display the following whenever a debug packet is received:

• Embedded Software Version (corresponds to the THISBUILD macro value defined in proj_config.h of the Xtrinsic Sensor Fusion Library for Kinetis MCUs)
• The number of system tick timer (SysTick) cycles which elapsed during the last sensor fusion calculation. Google "ARM SysTick" for details.
• Which Freedom board created this data stream (from Packet type 1)

Packet Type 3: Angular Rate

This packet type is used to send angular rate values to the controller. This view is enabled via a checkbox in the Preferences screen.

Byte #	Function	Units
0	Packet Start = 0x7E	None
1	Packet Type = 03	None
2	Packet #	This number increments by 1 for each sample. Rolls over at 0xFF to 0x00.
6:3	Timestamp	1 LSB = 1.00 microseconds (Previously 1.33. Updated 2013.07.18)
8:7	X	1 LSB = 872.66 micro-radians/sec (0.05 dps)
10:9	Y	1 LSB = 872.66 micro-radians/sec (0.05 dps)
12:11	Z	1 LSB = 872.66 micro-radians/sec (0.05 dps)
13	Packet END = 0x7E	None

Packet Type 4: Euler Angles

This packet type is used to send roll/pitch/compass heading information to the controller. This view is enabled via a checkbox in the Preferences screen.

Byte #	Function	Units
0	Packet Start = 0x7E	None
1	Packet Type = 04	None
2	Packet #	This number increments by 1 for each sample. Rolls over at 0xFF to 0x00.
6:3	Timestamp	1 LSB = 1.00 microseconds (Previously 1.33. Updated 2013.07.18)
8:7	X	1 LSB = 0.1 degree
10:9	Y	1 LSB = 0.1 degree
12:11	Z	1 LSB = 0.1 degree
13	Packet END = 0x7E	None

Packet Type 5: Altitude/Temperature

This packet type is used to send altitude and temperature information. This data is not currently consumed by the the Android version of the Xtrinsic Sensor Fusion Toolbox, although it is supported by the PC version.

Byte #	Function	Units
0	Packet Start = 0x7E	None
1	Packet Type = 05	None
2	Packet #	This number increments by 1 for each sample. Rolls over at 0xFF to 0x00.
6:3	Timestamp	1 LSB = 1.00 microseconds
10:7	Altitude	1 LSB = 1 mm
12:11	Temperature	1 LSB = 0.01 C
13	Packet END = 0x7E	None

Packet Type 6: Magnetic Packet

This packet type is used to send information about the magnetic calibration. This data is not currently consumed by the the Android version of the Xtrinsic Sensor Fusion Toolbox, although it is supported by the PC version. The format is subject to change.

Controller to Development Board

The command protocol below is preliminary, and is subject to change.

Possible 4 byte commands are shown below. Substitute a space for each "_" to enforce the 4-byte width..

• "DB+_" = debug packet on (default) (transmitted via "Options Menu->Enable debug")
• "DB-_" = debug packet off (transmitted via "Options Menu->Disable debug")
• "Q3__" = transmit 3-axis quaternion in standard packet (transmitted when "Remote accel" is selected on the Source/Algorithms spinner)
• "Q6MA" = transmit 6-axis mag/accel quaternion in standard packet (transmitted when "Remote mag/accel" is selected on the Source/Algorithms spinner)
• "Q6AG" = transmit 6-axis accel/gyro quaternion in standard packet (transmitted when "Remote accel/gyro" is selected on the Source/Algorithms spinner)
• "Q9__" = transmit 9-axis quaternion in standard packet (default) (transmitted when "Remote 9-axis" is selected on the Source/Algorithms spinner)
• "RPC+" = Roll/Pitch/Compass on
• "RPC-" = Roll/Pitch/Compass off (default)
• "RST_" = Soft reset (not implemented at this time)
• "VG+ " = Enable virtual gyro
• "VG- " = Disable virtual gyro (default)

Note that the commands above can request that the embedded board perform computations in a specific way. Where applicable, the "Flags" field of Packet type 1 should be checked to confirm that the proper operation has taken place.

Packet Structure by Freescale Semiconductor is licensed under a Creative Commons Attribution 4.0 International License.