Serial Protocol

In order to communicate sensor data to a client (e.g., a RoboRio robot controller) the navX-sensor software uses a custom protocol. This protocol defines messages sent between the navX-sensor and the client over a serial interface, and includes an error detection capability to ensure corrupted data is not used by the client.

The navX-sensor Serial protocol uses two message types, the legacy ASCII messages initially introduced in the nav6 sensor, and the modern binary messages introduced in the navX-sensor.

Source code that implements the navX-sensor ASCII and binary protocols in Java and C++ are provided to simplify adding support for the navX-sensor protocol to a software project.

Message Structure

ASCII Protocol Messages

Each navX-sensor Serial ASCII protocol message has the following structure:

Start of Message Message ID Message Body Message Termination
1 byte 1 byte length is message-type dependent 4 bytes

Binary Protocol Messages

Each navX-sensor Serial Binary protocol message has the following structure:

Start of Message Binary Message Indicator Binary Message Length Message ID Message Body Message Termination
1 byte 1 byte 1 byte 1 byte length is message-type dependent 4 bytes

Data Type Encoding (ASCII)

Base16 encoding is used for ASCII message elements, as follows:

Data Type Encoding Example
Float (Sign)(100s)(10s)(1s).(10ths)(100ths) ‘-132.96’. ‘ 257.38’
8-bit Integer (HighNibble)(LowNibble) ‘E9’
16-bit Integer (HighByte,HighNibble)(HighByte,LowNibble)(LowByte,HighNibble)(LowByte,LowNibble) ‘1A0F’

Data Type Encoding (Binary)

Binary encoding is used for all Binary message elements.  All Binary-formatted data types that are signed are encoded as 2’s complement.  All multi-byte data types are in little-endian format.  Certain non-standard ‘packed’ data types are used to increase storage efficiency.

Data Type Range Byte Count
Unsigned Byte 0 to 255 1
Unsigned Short 0 to 65535 2
Signed Short -32768 to 32768 2
Signed Hundredths -327.68 to 327.67 2
Unsigned Hundredths 0.0 to 655.35 2
Signed Thousandths -32.768 to 32.767 2
Signed Pi Radians -2 to 2 2
Q16.16 -32768.9999 to 32767.9999 4
Unsigned Long 0 to 4294967295 4

*Unsigned Hundredths:  original value * 100 rounded to nearest integer
*Signed Hundredths:  original value * 100 rounded to nearest integer
*Signed Thousandths:  original value * 1000 rounded to nearest integer
*Signed Pi Radians:  original value * 16384 rounded to nearest integer

Start of Message

Each message begins with “start of message” indicator (a ‘!’ character), which indicates that the following bytes contain a message.

Binary Message Indicator

Each binary message includes a “binary message” indicator (a ‘#’ character), which indicates that the following bytes contain a binary message.

Binary Message Length

Each Binary message contains a length value (a value from 0-255), which indicates that the number of bytes which follow in the Message Body and Message Termination.

Message ID

The Message ID indicates the type of message, which may be one of the following:

ID Message Type Encoding
‘y’ Yaw/Pitch/Roll/Compass Heading Update ASCII
‘g’ Raw Data Update ASCII
‘p’ AHRS + Position Data Update Binary
‘S’ Stream Configuration Command ASCII
‘s’ Stream Configuration Response ASCII
‘I’ Integration Control Command Binary
‘j’ Integration Control Response Binary

Message Body

The message body differs depending upon the Message Type; the various Message Body specifications are listed below.

Message Termination

The final four bytes of each Serial protocol message contain a Base16 unsigned 8-bit checksum (encoded in 2 bytes as an ASCII 8-bit integer) followed by a carriage return and then a line feed character.

Checksum

The checksum is calculated by adding each byte of the message except the bytes within the Message Termination itself. The checksum is accumulated within an 8-bit unsigned byte.

New Line

The carriage return (0x10) and newline characters (0x13) are present at the end of the message so that when the message is displayed in a console window, a new line will be inserted in the console at the end of the message.

Message Body Definitions

Yaw/Pitch/Roll/Compass Heading Update Message

The Yaw/Pitch/Roll/Compass Heading Update message indicates the navX-sensor current orientation and heading, in units of degrees, as follows:

Byte Offset Element Data Type Unit
0 Yaw Float Degrees (-180 to 180)
7 Pitch Float Degrees (-180 to 180)
14 Roll Float Degrees (-180 to 180)
21 Compass Heading Float Degrees (0 to 360)

Raw Data Update Message

The Raw Data update message communicates the raw gyro, accelerometer, magnetometer and temperature data. This data bypasses the navX-Sensor Motion Processor, and allows the individual sensors to be used directly without any intervening processing. This can allow the following types of use:

  • Access to instantaneous measures of angular velocity in each of the X, Y and Z axes, provided by the tri-axial gyroscopes. Note that the accelerometer and gyroscope data has already had bias calibration applied.
  • Additionally, raw magnetometer data is provided. Note that the raw magnetometer data may have already had soft/hard iron calibration applied, if the navX-sensor magnetometer calibration procedure has already been completed.
Byte Offset Element Data Type
0 Gyro X (15-bits, signed) 16-bit Integer
4 Gyro Y (15-bits, signed) 16-bit Integer
8 Gyro Z (15-bits, signed) 16-bit Integer
12 Acceleration X (16-bits, signed) 16-bit Integer
16 Acceleration Y (16-bits, signed) 16-bit Integer
20 Acceleration Z (16-bits, signed) 16-bit Integer
24 Magnetometer X (12 bits, signed) 16-bit Integer
28 Magnetometer Y (12 bits, signed) 16-bit Integer
32 Magnetometer Z (12 bits, signed) 16-bit Integer
36 Temperature (Centigrade degrees) Float

Gyro Device Units:  value in deg/sec * gyro full scale range

Accelerometer Device Units:  value in G * accelerometer full scale range

Magnetometer Device Units: value in uTesla * .15

AHRS / Position Data Update

Byte Offset Element Data Type Unit
0 Yaw Signed Hundredths Degrees
2 Pitch Signed Hundredths Degrees
4 Roll Signed Hundredths Degrees
6 Compass Heading Unsigned Hundredths Degrees
8 Altitude Signed 16:16 Meters
12 Fused Heading Unsigned Hundredths Degrees
14 Linear Accel X Signed Thousandths G
16 Linear Accel Y Signed Thousandths G
18 Linear Accel Z Signed Thousandths G
20 Velocity X Signed 16:16 Meters/Sec
24 Velocity Y Signed 16:16 Meters/Sec
28 Velocity Z Signed 16:16 Meters/Sec
32 Displacement X Signed 16:16 Meters
36 Displacement Y Signed 16:16 Meters
40 Displacement Z Signed 16:16 Meters
44 Quaternion W Signed Pi Radians Pi Radians
46 Quaternion X Signed Pi Radians Pi Radians
48 Quaternion Y Signed Pi Radians Pi Radians
50 Quaternion Z Signed Pi Radians Pi Radians
52 MPU Temp Signed Hundredths Centigrade
54 Op. Status Uint8  NAVX_OP_STATUS
55 Sensor Status Uint8 NAVX_SENSOR_STATUS
56 Cal. Status Uint8 NAVX_CAL_STATUS
57 Selftest Status Uint8 NAVX_SELFTEST_STATUS

Stream Configuration Command

By default, a navX-sensor begins transmitting YPR Updates upon power up. The Stream Configuration Command is sent in order to change the type of navX-sensor Streaming Update transmitted to the client.

Byte Offset Element Data Type
0 Stream Type 8-bit ASCII Character
1 Update Rate (Hz) – Valid range: 4-60 8-bit Integer
Stream Type Description
‘y’ Yaw, Pitch, Roll & Compass Heading Update
‘g’ Gyro (Raw) Data Update
‘p’ AHRS + Position Data Update

Stream Configuration Response

Whenever a Stream Configuration Command is received a navX-sensor responds by sending a Stream Configuration Response message, which is formatted as follows:

Byte Offset Element Data Type
0 Stream Type 8-bit ASCII Character
1 Gyroscope Full Scale Range (Degrees/sec) 16-bit Integer
5 Accelerometer Full Scale Range (G) 16-bit Integer
9 Update Rate (Hz) 16-bit Integer
13 Calibrated Yaw Offset (Degrees) Float
20 Reserved 16-bit Integer
24 Reserved 16-bit Integer
28 Reserved 16-bit Integer
32 Reserved 16-bit Integer
36 Flags 16-bit Integer
Flag value Desription
0, 1 Startup Gyro Calibration in progress
2 Startup Gyro Calibration complete

Integration Control Command

The Integration Control Command is sent in order to cause certain values being integrated on the navX-sensor to be reset to 0.

Byte Offset Element Data Type
0 Action Uint8 (NAVX_INTEGRATION_CTL)
1 Parameter Uint32

Integration Control Response

The Integration Control Response is sent in response to an Integration Control Command, confiming that certain values being integrated on the navX-sensor have been reset to 0.

Byte Offset Element Data Type
0 Action Uint8 (NAVX_INTEGRATION_CTL)
1 Parameter Uint32