DOCSEARCHbyAlgolia
Submit Docs

YDLidar SDK

repository·master·Indexed 42 days ago

https://github.com/ydlidar/ydlidar-sdk

A multi-language development kit (C/C++, Python, C#) for interfacing with YDLidar products. It enables users to control sensors and retrieve laser scan data via serial or network protocols. The SDK includes a communication protocol, core implementation, and high-level APIs for Linux and Windows 7/10. Version 1.0.0 provides specialized quick start guides for general users, hardware installation, and developers.

Tokens
28.4K
Snippets
58
Records
124
Agent score
52%

What's inside YDLidar SDK

  1. Introduction to YDLidar SDK

    master

    YDLidar SDK is a software development kit designed for all YDLIDAR products. It provides a standardized way to connect to YDLidar sensors and receive Laser scan data. The SDK is built on C/C++ and implements the YDLidar SDK Communication Protocol, offering high-level APIs for multiple programming languages.

    The SDK includes:

    • Communication Protocol: Defines control commands and data formats.
    • SDK Core: The underlying implementation of the protocol.
    • SDK API: Interfaces for developers.
    • Samples/Demos: Implementation examples for Linux/Windows (C/C++) and Python.

  2. Supported hardware and LiDAR models

    master

    Supported Development Boards

    Development boards with a processor frequency > 30MHz are generally compatible with LiDARs having a sampling rate < 6K. For higher sampling rates or modified configurations, a frequency > 100MHz is required.

    Supported LiDAR Models

    The YDLidar-SDK supports all standard EAI (YDLIDAR) commercial LiDAR models. For custom or specialized versions, you must contact EAI directly.

  4. Initialize and manage LiDAR lifecycle

    master

    To use a LiDAR with the SDK, follow this lifecycle:

    1. ydlidar::os_init(): Call this first to initialize system signals (like SIGINT) to allow clean exits via Ctrl-C.
    2. laser.initialize(): Configures the SDK and hardware. Returns false if the port is incorrect, permissions are missing, or baud rate/type settings are wrong.
    3. laser.turnOn(): Starts the scanning routine in a separate thread and enables the motor. Returns false if the LiDAR stalls or power is unstable.
    4. ydlidar::os_isOk(): Check this in your main loop. It returns false if a SIGINT (Ctrl-C) is received or if ydlidar::os_shutdown() is called.
    5. laser.turnOff(): Stops the scanning thread and disables the motor.
    6. laser.disconnecting(): Uninitializes the SDK and disconnects from the hardware.

  5. The YDLidar SDK operational lifecycle

    master

    The YDLidar SDK follows a specific operational flow to ensure the hardware is correctly initialized and managed. The typical lifecycle involves:

    1. Initialization: Set parameters and initialize the SDK.
    2. Connection: Attempt to connect to the device and receive device information.
    3. Activation: Turn on the LiDAR (Start LiDAR).
    4. Data Acquisition: Continuously retrieve laser scan data (e.g., via doProcessSimple).
    5. Shutdown: Turn off the LiDAR and disconnect from the device.

    If initialization or connection fails, the process should attempt to retry or proceed to a safe disconnection/shutdown state.

    sequenceDiagram
note over UserProgram: Set Paramters
note over UserProgram: Initialize SDK
UserProgram->Command: Get LiDAR Information
Command-->UserProgram: Device connected and Devce Information recevied
note over UserProgram: TurnOn
UserProgram->Command: Start LiDAR 
Command-->UserProgram: LiDAR Started successfully
UserProgram->LaserScan: Get Laser Scan Data
LaserScan-->UserProgram:  Laser Scan Data Recvied
note over UserProgram: doProcessSimple
loop Laser Scan Data
  LaserScan->UserProgram: doProcessSimple
end
note over UserProgram: TurnOff
UserProgram->Command: TurnOff 
note over UserProgram: disconnecting
UserProgram->Command: disconnecting

  6. Understand the YDLIDAR SDK Communication Protocol

    master
    For low-level integration or debugging, refer to the YDLIDAR SDK Communication Protocol documentation. This covers the specific data packet structures and command sequences used by the SDK to communicate with the LiDAR hardware.

  7. Initialize and control the LiDAR lifecycle

    master

    To use the LiDAR, follow this lifecycle sequence:

    1. ydlidar::os_init(): Initializes system signals and installs a SIGINT handler (enabling Ctrl-C handling). This makes ydlidar::os_isOk() return false when the user interrupts the program.
    2. laser.initialize(): Initializes the SDK and the hardware. It may fail if the serial port is incorrect, permissions are missing, or baudrate/type settings are wrong. Use laser.DescribeError() to diagnose failures.
    3. laser.turnOn(): Starts the scanning routine in a separate thread and enables the motor. It may fail if the motor stalls or power supply is unstable.
    4. laser.doProcessSimple(scan): Retrieves the latest LaserScan data into the provided scan object.
    5. laser.turnOff(): Stops the scanning thread and disables the motor.
    6. laser.disconnecting(): Uninitializes the SDK and disconnects from the hardware.

    Loop Control: Use while (ret && ydlidar::os_isOk()) to keep the application running until the LiDAR fails or the user sends a SIGINT.

  8. Understand the YDLidar SDK Package Format

    master

    The LiDAR transmits point cloud data as hexadecimal packets over a serial port. The packet structure varies depending on whether the LiDAR supports intensity data.

    Common Packet Fields

    FieldNameDescription
    PH (2B)Packet headerFixed at 0x55AA (little-endian: 0xAA, 0x55)
    CT (1B)Package type0x00 (CT & 0x01) = Normal point cloud; 0x01 (CT & 0x01) = Zero packet
    LSN (1B)Sample Data NumberNumber of sampling points in the packet. For zero packets, this is 1
    FSA (2B)Starting angleAngle of the first sample point
    LSA (2B)End angleAngle of the last sample point
    CS (2B)Check codeTwo-byte XOR checksum
    SiSampling dataDistance/Intensity data (size depends on LiDAR type)

    Sampling Data (Si) Variations

    • No Intensity: Si is 2 bytes per sample (Distance only).
    • With Intensity: Si is 3 bytes per sample. The format is [Intensity (1B), Distance (2B)].

  10. How to manage system signals with os_init() and os_isOk()

    master

    In the YDLIDAR SDK, ydlidar::os_init() is an optional utility used to create a system state that allows the application to gracefully handle system signals like Ctrl + C or other abnormal signals.

    Once ydlidar::os_init() has been called, the system is in an initialized state and can accept ydlidar::os_shutdown() signals. You can check if the system is still in a normal, running state by calling ydlidar::os_isOk() within your main execution loop.

    // Initialize system signal handling
ydlidar::os_init();

// ... in your loop ...
while (ret && ydlidar::os_isOk()) {
    // perform lidar operations
}

  11. How YDLidar SDK Architecture works

    master

    The YDLidar SDK acts as an intermediary between user applications and LiDAR sensors using either Serial or Network communication.

    Core Components

    • Command Handler: Responsible for receiving and sending control commands to the sensor.
    • LaserScan Handler: Responsible for the transmission and processing of Laser Scan Data.
    • C++ API: Built upon the Command and LaserScan Handlers.

    Connection Methods

    1. Direct Serial Connection: The host establishes individual communication with each LiDAR unit connected via Serial.
    2. Adapter Board Connection: The host communicates with a single YDLidar Adapter board, which in turn manages communication with each individual LiDAR unit.