Menu
▾
▴
UART Sensor Protocol
There is a newer version of this page. You can find it here.
UART Sensor Protocol
This page is a documentation of the UART protocol spoken by LEGO EV3 sensors. It was derived from publicly available source code and reverse engineering. This is work in progress.
General Rules
The EV3 and attached sensors send and receive messages. There are four types of messages:
- System message
- Command message
- Info message
- Data message
Each message follows one of the following structures:
- message byte (system messages)
- message byte, payload, checksum byte (command and data messages)
- message byte, info byte, payload, checksum byte (info messages)
The checksum byte is the XOR over the message byte, the info byte (if present), all bytes of the payload, and 0xFF.
The message byte has a special structure: 0bXXLLLYYY. The two most significant bits indicate the type f the message:
| XX | Description |
|---|---|
| 00 | System message |
| 01 | Command message |
| 10 | Info message |
| 11 | Date message |
Bits 3-5 of the message byte indicate the length of the payload. To be more precise, the size of the payload is exactly 20bLLL bytes. Thus, the length of a payload must always be a power of 2 and the protocol allows for payloads of at most 128 bytes while actual implementations seem to assume a maximum payload length of 32 bytes. Including the checksum byte, command and data messages thus have a total length of 20bLLL+2 bytes and info messages have a total size of 20bLLL+3 bytes.
System messages have a total length of one. (There may be an exception to that, see the ESC message below.)
Communication with a sensor starts at a speed of 2400 baud. The baud rate can be increased to a higher speed after the initial handshake. The maximum baud rate is reported by the sensor.
Integers larger than 8 bit are encoded using little endian.
System Messages
| Message Byte | Description |
|---|---|
| 0b00000000 | SYNC |
| 0b00000010 | NACK |
| 0b00000100 | ACK |
| 0b00LLL110 | ESC (reserved for future use) |
Command Messages
| Message Byte | Payload | Description |
|---|---|---|
| 0b01000000 | T | TYPE: sensor type T is the type of the sensor (1byte) |
| 0b01001001 | M, V | MODES: sensor modes M+1 is the number of modes supported (1-8) V+1 is the number of modes to be shown (V <= M) |
| 0b01010010 | SSSS | SPEED: maximum sensor baud rate SSSS (32 bit integer) is the maximum baud rate supported by the sensor |
| 0b01000011 | M | SELECT: select mode M (0-7) |
| 0b01LLL100 | <data></data> | WRITE: TODO Note: Has a payload of 0bLLL bytes? |
Info Messages
| Message Byte | Info Byte | Payload | Description |
|---|---|---|---|
| 0b10LLLMMM | 0 | <string></string> | NAME: name of mode 0bMMM <string> is an ASCII string, padded with zeros to a length of exactly 20bLLL characters</string> |
| 0b10011MMM | 1 | LLLL, HHHH | RAW: TODO |
| 0b10011MMM | 2 | LLLL, HHHH | PCT: TODO |
| 0b10011MMM | 3 | LLLL, HHHH | SI: TODO |
| 0b10LLLMMM | 4 | <string></string> | SYMBOL: TODO |
| 0b10010MMM | 0x80 | S, T, F, D | FORMAT: format of the sensor data in mode 0bMMM S: the number of items T: the data type of the items (see table) F: the number of digits to show (including decimals and the decimal point) D: the number of decimals to show |
| Data Type | Description |
|---|---|
| 0 | 8 bit integer |
| 1 | 16 bit integer |
| 2 | 32 bit integer |
| 3 | 32 bit floating point |
Data Messages
| Message Byte | Payload | Description |
|---|---|---|
| 0b11LLLMMM | <data></data> | DATA: the sensor return data <data> are the sensor readings for mode 0bMMM, padded to a length of exactly 20bLLL bytes.</data> |
Messages from Host to Sensor
- System messages: ACK, NACK
- Command messages: SELECT, WRITE
Message from Sensor to Host
- System messages: ACK
- Command messages: TYPE, MODES, SPEED
- Info messages: NAME, RAW, PCT, SI, SYMBOL, FORMAT
- Data messages: DATA
How it all work together
| Host | Sensor |
|---|---|
| baud rate is 2400 | baud rate is 2400 |
| send TYPE, MODES, and SPEED | |
| per mode, send NAME, RAW, PCT, SI, and FORMAT | |
| wait for ACK | send ACK |
| send ACK | wait for ACK |
| change baud rate | change baud rate |
| DATA | |
| DATA | |
| NACK | |
| DATA | |
| DATA | |
| SELECT | |
| DATA | |
| DATA | |
| NACK | |
| DATA | |
| DATA |
The MODES command message is optional. A default of M=V=1 is assumed.
The SPEED command message is optional. Default value is unclear.
The info messages for the mode with the highest number must be sent first.
Per mode, NAME must be the first and FORMAT must be the last info message. RAW, PCT, and SI are optional. The following defaults are used when the info message are not sent:
- RAW: 0.0 - 1023.0
- PCT: 0.0 - 100.0
- SI: 0.0 - 1.0
Unclear: The last FORMAT messages indicates default mode? Available material strongly suggests sending mode info in descending order (by mode number) in which case mode 0 is always default.
Timing
There must be a delay of at least 10ms between consecutive FORMAT and NAME messages.
A device must send a data message at least every 100ms, but at most every 1ms.
A device should also send a data message after receiving a NACK.
The host should send a NACK every 100ms.
A device should reset if it does not receiving a NACK for 1s. Also, if it does not receive the ACK within 80ms after sending the last FORMAT message, it should reset.
Error Handling
The host may force a reset of the device by not sending any NACKs, e.g. after receiving too many invalid data messages.
If the device does not receive the the initial ACK from the host, the device must reset.
The timeout after which the reset should happen is unclear.
Issues
- It not clear whether the ESC system message may have a payload or even a checksum byte. The meaning of bits 3-5 is unclear.
- The WRITE command message is unclear.
- The protocol does not include an acknowledgement to commands like SELECT. Thus, the host must check subsequent data messages to see whether the sensor switched to the correct mode.