Chain ToF UART Control Protocol (Documentation V1)

1. Basic Information

2. Data Frame Format

All packets start with 0xAA 0x55 and end with 0x55 0xAA. Multi-byte length fields are entered low byte first.

2.1 Request Frame Format

Request Frame:
  AA 55 <Length_low> <Length_high> <Index> <Cmd> <Req Data...> <CRC> 55 AA

2.2 Response Frame Format

Response Frame:
  AA 55 <Length_low> <Length_high> <Index> <Cmd> <Resp Data...> <CRC> 55 AA

2.3 Response Data Convention

3. Checksum

CRC = (Index + Cmd + Data[0] + ... + Data[n]) & 0xFF

3.1 Checksum Example

#include <stddef.h>
#include <stdint.h>

uint8_t chain_calc_crc(uint8_t index, uint8_t cmd,
                       const uint8_t *data, size_t data_len)
{
    uint16_t sum = index + cmd;

    for (size_t i = 0; i < data_len; i++) {
        sum += data[i];
    }

    return (uint8_t)(sum & 0xFF);
}

4. Quick overview of commands

5. Command Details

5.1 Set RGB value - Cmd 0x20

Request data

Input parameters: Index_id (device index ID), Index (starting coordinates of the RGB lamp), Num (number of RGB to be set), RGB value

Request Frame:
  AA 55 | 0x05+Num*3 | 0x00 | Index_id | 0x20 | Index | Num | R | G | B | ... | CRC | 55 AA

Response Data

Return parameters: Operation_status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x20 | Operation_status | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Index is the starting coordinate of the RGB light, starting from 0. The TOF device has only one RGB light, so Index = 0, Num = 1

5.2 Get RGB value - Cmd 0x21

Request data

Input parameters: Index_id (device index ID), Index (starting coordinates of RGB lights), Num (number of RGB lights to be read)

Request Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0x21 | Index | Num | CRC | 55 AA

Response Data

Return parameter: RGB value

Response Frame:
  AA 55 | 0x04+Num*3/0x04 | 0x00 | Index_id | 0x21 | Operation_status | R | G | B | ... | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Index is the starting coordinate of the RGB light, starting from 0. The TOF device has only one RGB light, so Index = 0, Num = 1
3. The operation failed and the returned data packet did not contain RGB values.

5.3 Set RGB light brightness - Cmd 0x22

Request data

Input parameters: Index_id (device index ID), Light (RGB brightness, 0~100, default 40), Save_to_flash (whether to save to internal Flash)

Request Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0x22 | Light | Save_to_flash | CRC | 55 AA

Response Data

Return parameters: Operation_status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x22 | Operation_status | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Save_to_flash Whether to save internal Flash
   • 0: Do not save
   • 1：Save
3. Successful setting takes effect immediately
4. Saving to the internal Flash requires erasing the page, which is a time-consuming process (about 20ms). During this period, the serial port interrupt will be turned off, and frequent operations will affect the life of the device. If you need to adjust the brightness frequently, please avoid saving to the internal Flash every time.

5.4 Get RGB light brightness - Cmd 0x23

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x23 | CRC | 55 AA

Response Data

Return parameters: Light (RGB brightness)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x23 | Light | CRC | 55 AA

Things to note

5.5 Get ToF measurement distance - Cmd 0x50

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x50 | CRC | 55 AA

Response Data

Return parameters: Measure_distance

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x50 | Measure_distance_low | Measure_distance_high | CRC | 55 AA

Things to note

1. Measure_distance = (uint16_t)(Measure_distance_high <<8) | Measure_distance_low (unit: mm)

5.6 Set measurement time - Cmd 0x51

Request data

Input parameters: Index_id (device index ID), Time

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x51 | Time | CRC | 55 AA

Response Data

Return parameters: Operation_status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x51 | Operation_status | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Time measurement time (the longer the measurement time, the higher the accuracy) Value：20～200ms Default：33ms
3. This instruction requires changing the configuration of VL53L0X, which is time-consuming.

5.7 Get measurement mode - Cmd 0x52

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x52 | CRC | 55 AA

Response Data

Return parameters: Mode

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x52 | Time | CRC | 55 AA

Things to note

1. Time measurement time (the longer the measurement time, the higher the accuracy) Value：20～200ms Default：33ms

5.8 Set measurement mode - Cmd 0x53

Request data

Input parameters: Index_id (device index ID), Mode

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x53 | Mode | CRC | 55 AA

Response Data

Return parameters: Operation_status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x53 | Operation_status | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Mode measurement mode
   • 0: Stop mode (stop measurement, lowest power consumption)
   • 1: Single-shot mode (no active sampling by default, manual triggering is required, power consumption is proportional to the trigger frequency)
   • 2: Continuous mode (default active sampling, automatic cycle sampling, maximum power consumption) Default：2

5.9 Get measurement mode - Cmd 0x54

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x54 | CRC | 55 AA

Response Data

Return parameters: Mode

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x54 | Mode | CRC | 55 AA

Things to note

1. Mode measurement mode
   • 0: Stop mode (stop measurement, lowest power consumption)
   • 1: Single-shot mode (no active sampling by default, manual triggering is required, power consumption is proportional to the trigger frequency)
   • 2: Continuous mode (default active sampling, automatic cycle sampling, maximum power consumption) Default：2

5.10 Set measurement status - Cmd 0x55

Request data

Input parameters: Index_id (device index ID), Status (measurement status)

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x55 | Status | CRC | 55 AA

Response Data

Return parameters: Operation_status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x55 | Operation_status | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Status measurement status
   • 0: No measurement (stop mode is always 0)
   • 1: Measurement (continuous mode is always 1)
3. It is not allowed to change the status to 1 in stop mode, and it is not allowed to change the status to 0 in continuous mode. Illegal settings will return failure.
4. When the measurement in single mode is completed and other modes are converted to single mode, the flag bit will be actively set to 0.
5. When other modes are converted to stop mode, the flag bit will be automatically set to 0.
6. When other modes are converted to continuous mode, the flag bit will be automatically set to 1.

5.11 Get measurement status - Cmd 0x56

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x56 | CRC | 55 AA

Response Data

Return parameters: Status (measurement status)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x56 | Status | CRC | 55 AA

Things to note

1. Status measurement mode
   • 0: No measurement (stop mode is always 0)
   • 1: Measurement (continuous mode is always 1)

5.12 Get the measurement completion flag - Cmd 0x57

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x57 | CRC | 55 AA

Response Data

Return parameters: Flag (completion flag)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x57 | Flag | CRC | 55 AA

Things to note

1. Flag measurement flag
   • 0: Measurement not completed
   • 1: Measurement completed
2. Read the measurement result (instruction code: 0x50), this flag will be set to 0, and the flag will be set to 1 once the collection is completed.

5.13 Query the unique UID of the device - Cmd 0xF8

Request data

Input parameters: Index_id (device index ID), UID_Type

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xF8 | UID_Type | CRC | 55 AA

Response Data

Return parameters: Operation_status, UID

Response Frame:
  AA 55 | 0x04+4/12 | 0x00 | Index_id | 0xF8 | Operation_status | UID (multi-byte) | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. UID_Type UID type
   • 0：4byte UID
   • 1：12byte UID

5.14 Query the upgrade program version number - Cmd 0xF9

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xF9 | CRC | 55 AA

Response Data

Return parameters: Bootloader_version

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xF9 | Bootloader_version | CRC | 55 AA

Things to note

5.15 Query the device software version number - Cmd 0xFA

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xFA | CRC | 55 AA

Response Data

Return parameters: Firmware_version

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xFA | Firmware_version | CRC | 55 AA

Things to note

5.16 Query device type - Cmd 0xFB

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xFB | CRC | 55 AA

Response Data

Return parameters: Device_type

Response Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0xFB | Device_type_low | Device_type_high | CRC | 55 AA

Things to note

1. Device_type = (uint16_t)((Device_type_high << 8) | Device_type_low)
2. The device type code of ToF is 0x0005

5.17 Enumeration request, sent by the end device of chain link change, and sent by the device when it is powered on, notifying the host to update the link device status - Cmd 0xFC

Request data

Input parameters: none

Request Frame:
  Device-initiated report，No host request frame

Response Data

Return parameters: none

Response Frame:
  Device-initiated report，No response frame

Things to note

None.

5.18 Heartbeat packet, regular communication between chain devices, you can self-discover whether it is an end device, and the host can also use the heartbeat packet to determine whether there is a chain device connected - Cmd 0xFD

Request data

Input parameters: none

Request Frame:
  AA 55 | 0x03 | 0x00 | 0xFF | 0xFD | CRC | 55 AA

Response Data

Return parameters: none

Response Frame:
  AA 55 | 0x03 | 0x00 | 0xFF | 0xFD | CRC | 55 AA

Things to note

5.19 Enumerate to obtain the number of cascaded devices - Cmd 0xFE

Request data

Input parameter: Send_num (default 0, used to record the number of devices)

Request Frame:
  AA 55 | 0x04 | 0x00 | 0xFF | 0xFE | Send_num | CRC | 55 AA

Response Data

Return parameter: Receive_num (the value represents the number of devices)

Response Frame:
  AA 55 | 0x04 | 0x00 | 0xFF | 0xFE | Receive_num | CRC | 55 AA

Things to note

None.

6. Status code/enumeration value

6.1 Operating status

Other modes, ranges, and event enumeration values are defined in the "Notes" of the corresponding instructions.

7. Version records