Reading LiDAR Data

I. Experiment Objective

Learn how to receive the ranging data of the T-mini Plus LiDAR through the UART serial port on the ESP32-S3 platform. Master LiDAR data protocol parsing, ring buffer management, and multi-angle distance reading methods, laying the foundation for subsequent mapping, navigation, and obstacle avoidance functions.

II. Experiment Principle

1. Keywords

2. Technical Architecture

The program adopts a three-layer architecture of serial reception + ring buffer + protocol parsing, with data passing layer by layer from the hardware to the application.

main/main.c
    └── Lidar_tminiplus_Get_Distance(angle)  /  Lidar_tminiplus_Get_Msg()
         └── components/lidar_tminiplus/         LiDAR driver encapsulation layer
              ├── lidar_tminiplus.c / .h        Data reception task + 360° data management
              └── tminiplus.c / .h              Protocol parsing layer (state machine + checksum)
                   └── components/uart1/        UART1 serial driver
                        ├── uart1.c / .h        Hardware initialization + transmit/receive interfaces
                        └── components/ring_buffer/  Ring buffer (1024 bytes)

Data flow: LiDAR UART output → ESP32 UART1 RX (GPIO18) → Uart1_Rx_Task reception task → ring buffer → Lidar_tminiplus_Task protocol parsing state machine → 360° scan data array.

III. Experiment Steps

1. Hardware Preparation

2. Prerequisites

1. Set up the ESP32-IDF development environment

2. Connect the MicroROS-V2 control board to the computer via USB

3. Connect the T-mini Plus LiDAR correctly to the control board (UART interface)

4. Turn on the chassis power to supply power to the LiDAR

3. Compile and Flash

​x

cd ~/esp/base_samples/read_lidar
source ~/esp/esp-idf/export.sh
idf.py build flash monitor

To exit the monitor: press Ctrl + ].

4. Stopping Method

In the terminal, press Ctrl+] to exit the serial monitor.

IV. Experiment Result

After flashing and running the program, you can see the following output in the serial monitor terminal:

xxxxxxxxxx
hello yahboom
I (1002) LIDAR_MAIN: Nice to meet you!
I (1012) UART1: Start Uart1_Rx_Task with core:0
I (1012) LIDAR_MAIN: distance:455, 523, 789, 1234
I (1212) LIDAR_MAIN: distance:452, 521, 785, 1230
I (1412) LIDAR_MAIN: distance:458, 525, 790, 1235

• A set of distance values (in mm) for 4 angles is output every 200ms

• The 4 values correspond to the 1°, 90°, 180°, and 270° directions

• Cover the LiDAR with a hand or an object in different directions, and the distance value of the corresponding angle will change

• The distance value changes with the actual distance of the obstacle; in an open environment it may show the maximum range value

V. Program Analysis

Source code paths:

• Firmware source: ~/esp/base_samples/read_lidar/main/main.c

• LiDAR driver: ~/esp/base_samples/read_lidar/components/lidar_tminiplus/lidar_tminiplus.h, lidar_tminiplus.c, tminiplus.h, tminiplus.c

• UART driver: ~/esp/base_samples/read_lidar/components/uart1/uart1.h, uart1.c

1. Directory Structure

xxxxxxxxxx
read_lidar/
├── CMakeLists.txt
├── main/
│   ├── CMakeLists.txt
│   └── main.c
└── components/
    ├── lidar_tminiplus/        # T-mini Plus LiDAR driver encapsulation
    │   ├── lidar_tminiplus.h
    │   ├── lidar_tminiplus.c
    │   ├── tminiplus.h         # Protocol layer
    │   └── tminiplus.c
    ├── uart1/                  # UART1 serial driver
    │   ├── uart1.h
    │   └── uart1.c
    └── ring_buffer/            # Ring buffer
        ├── ring_buffer.h
        └── ring_buffer.c

2. Main Program Logic

main/main.c implements the LiDAR data collection function:

1. Initialize the UART1 serial port

2. Call tminiplus_GPIO_Init() to initialize the LiDAR driver and start the data reception task

3. Send the start command {0xA5, 0x60} to wake up the LiDAR and start scanning

4. Loop to read the distance values of 4 specific angles (1°, 90°, 180°, 270°) and print them

xxxxxxxxxx
static const uint8_t s_start_cmd[2] = {0xA5, 0x60};

Uart1_Init();
tminiplus_GPIO_Init();
Uart1_Send_Data((uint8_t *)s_start_cmd, sizeof(s_start_cmd));

while (1) {
    for (int i = 0; i < 4; i++) {
        distances[i] = Lidar_tminiplus_Get_Distance(points[i]);
    }
    ESP_LOGI(TAG, "distance:%d, %d, %d, %d",
             distances[0], distances[1], distances[2], distances[3]);
    vTaskDelay(pdMS_TO_TICKS(200));
}

3. Key Components

UART1 serial driver

Files: components/uart/uart1.h, components/uart/uart1.c

Pin configuration:

Parameter definition file: ~/esp/base_samples/read_lidar/components/uart1/uart1.h

Communication parameters:

• Baud rate: 230400

• Data bits: 8 bits

• Parity: None

• Stop bits: 1 bit

• Hardware flow control: Disabled

Working mechanism:

Uart1_Init() initializes the UART hardware and installs the driver, and also creates a reception task Uart1_Rx_Task that continuously reads data from the UART hardware and stores it in the ring buffer.

Core functions:

• Uart1_Init() — Initializes the UART1 serial port with a baud rate of 230400 and creates the reception task (stack size 5KB, priority 5)

• Uart1_Send_Data(uint8_t* data, uint16_t len) — Sends data

• Uart1_Available() — Returns the number of readable bytes in the ring buffer

• Uart1_Read() — Reads one byte from the ring buffer

Ring buffer

Files: components/ring_buffer/ring_buffer.h, components/ring_buffer/ring_buffer.c

Used as a temporary cache for UART data reception, implementing a first-in-first-out data buffering mechanism to avoid data loss.

Buffer size: 1024 bytes (RX1_BUF_SIZE).

T-mini Plus LiDAR protocol layer

Files: components/lidar_tminiplus/tminiplus.h, components/lidar_tminiplus/tminiplus.c

Data structures:

xxxxxxxxxx
#define TMINIPLUS_POINT_NUM  360U   // 360 sampling points per revolution

typedef struct __attribute__((packed)) {
    float angle;            // Angle (0°~360°)
    uint16_t distance;      // Distance (mm)
    uint8_t intensity;      // Signal strength
} tminiplus_ros_point_t;

typedef struct __attribute__((packed)) {
    uint16_t size;
    tminiplus_ros_point_t point[360];
} tminiplus_ros_data_t;

Data packet format:

A LiDAR data packet consists of a 10-byte fixed header and variable-length sampling data:

Angle calculation formula:

xxxxxxxxxx
// Angle value = (register value >> 1) / 64.0
static float tminiplus_Level1_Start_End_Angle(uint16_t value) {
    return (float)(value >> 1) / 64.0f;
}

Distance decoding:

The raw distance value needs to be converted (shift right by 2 bits to remove the interference filtering flag):

xxxxxxxxxx
// Distance value = ((raw value >> 8) << 6) | ((raw value & 0x00FF) >> 2)
static uint16_t tminiplus_Si_To_Distance(uint16_t si_temp) {
    return (uint16_t)(((si_temp >> 8) << 6) | ((si_temp & 0x00FFU) >> 2));
}

Data reception state machine:

tminiplus_Data_Receive() uses a state machine to parse the serial data stream:

xxxxxxxxxx
RX_WAIT_AA -> RX_WAIT_55 -> RX_CT -> RX_LSN -> RX_FSA_L -> RX_FSA_H
  -> RX_LSA_L -> RX_LSA_H -> RX_CS_L -> RX_CS_H -> RX_DATA

• After detecting the packet header 0xAA 0x55, parsing begins

• Calculate the data length based on the LSN field, and receive the complete data packet after confirming it is within the buffer range

• After reception is complete, perform checksum verification

• If verification passes, update the LiDAR data and mark that a new data packet has arrived

Checksum algorithm:

xxxxxxxxxx
result = PH ^ (LSN<<8 | CT) ^ FSA ^ LSA;
for each point: result ^= intensity ^ distance;
// Verify that result == CS

LiDAR driver encapsulation layer

Files: components/lidar_tminiplus/lidar_tminiplus.h, components/lidar_tminiplus/lidar_tminiplus.c

Data reception task:

tminiplus_GPIO_Init() creates a dedicated task Lidar_tminiplus_Task during initialization (pinned to core 1, stack size 10KB, priority 10). This task continuously reads data from the UART and feeds it into the protocol state machine for parsing. When a complete new data packet is received, it calls Lidar_tminiplus_Update_Scan_Data() to update the 360° scan data.

ROS2 message structure initialization:

Lidar_Ros_Init() initializes the LaserScan message structure:

Data inversion (ENABLE_DATA_INVERSION):

Because the physical installation direction of the LiDAR may be inconsistent with the coordinate system definition of the robot, the tminiplus_remap_index() function remaps the angle index to ensure that 0° corresponds to directly in front of the robot. Specifically, the index is shifted by 180° and then modulo is applied.

Core functions:

• tminiplus_GPIO_Init() — Initializes the LiDAR driver and starts the data reception task

• Lidar_tminiplus_Get_Distance(uint16_t angle) — Gets the distance value at the specified angle (unit mm), angle range 0~359

• Lidar_tminiplus_stop_Scan(uint8_t on) — Stops the LiDAR scanning (sends the stop command {0xA5, 0x65})

• Lidar_tminiplus_Get_Msg() — Gets the complete LaserScan message (ROS2 message structure)

VI. Common Problems