In addition to direct communication with the Raspberry Pi, VMX-pi can simultaneously communicate sensor data to a client (e.g., a RoboRio robot controller) via a custom protocol which communicates over USB Serial connection. This protocol defines messages sent between the VMX-pi and the client over the serial USB interface, and includes an error detection capability to ensure corrupted data is not used by the client.
The VMX-pi 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-MXP.
Source code that implements the VMX-pi ASCII and binary protocols in C/C++ and Java are available online to simplify adding support for the VMX-pi protocol to a software project.
Message Structure
ASCII Protocol Messages
Each VMX-pi 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 VMX-pi 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 VMX-pi 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 Digital 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 VMX-pi 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, VMX-pi begins transmitting YPR Updates upon power up. The Stream Configuration Command is sent in order to change the type of VMX-pi 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, VMX-pi 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 VMX-pi 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 VMX-pi have been reset to 0.
| Byte Offset | Element | Data Type |
| 0 | Action | Uint8 (NAVX_INTEGRATION_CTL) |
| 1 | Parameter | Uint32 |