Skip to content

Latest commit

 

History

History
1457 lines (1304 loc) · 46.9 KB

YDLIDAR_SDK_API_for_Developers.md

File metadata and controls

1457 lines (1304 loc) · 46.9 KB

YDLIDAR SDK API for Developers

This document provides an extensive technical deep dive into how to create, manipulate and use YDLIDAR SDK's API.

Table of Contents

Samples

The first part of demonstrating YDLIDAR SDK API is to understand the ydlidar_test/tof_test/etlidar_Test example. Following are one optinal concepts: ydlidar::os_init() (basic unit) of the example.

Create A System State

In the YDLIDAR SDK, the ydlidar::os_init() is optinal unit, If you need to accept Ctrl + C or other system abnormal signals. you can use it to create a system state, and check whether the system is normal by ydlidar::os_isOk(). The system signal creation interface is as follows:

ydlidar::os_init();
  • when ydlidar::os_init() has called, the system is in an initialized state, able to accept Ctrl + C and ydlidar::os_shutdown() signals.

Code Example

Triangle LiDAR (../samples/ydlidar_test.cpp)

#include "CYdLidar.h"
#include <iostream>
#include <string>
#include <algorithm>
#include <cctype>
using namespace std;
using namespace ydlidar;
#if defined(_MSC_VER)
#pragma comment(lib, "ydlidar_sdk.lib")
#endif

int main(int argc, char *argv[]) {
  // init system signal
  ydlidar::os_init();

  CYdLidar laser;
  //////////////////////string property/////////////////
  /// lidar port
  std::string port = "/dev/ydlidar
  laser.setlidaropt(LidarPropSerialPort, port.c_str(), port.size());
  /// ignore array
  std::string ignore_array;
  ignore_array.clear();
  laser.setlidaropt(LidarPropIgnoreArray, ignore_array.c_str(),
                    ignore_array.size());

  //////////////////////int property/////////////////
  /// lidar baudrate
  int optval = 230400;
  laser.setlidaropt(LidarPropSerialBaudrate, &optval, sizeof(int));
  /// tof lidar
  int optval = TYPE_TRIANGLE;
  laser.setlidaropt(LidarPropLidarType, &optval, sizeof(int));
  /// device type
  optval = YDLIDAR_TYPE_SERIAL;
  laser.setlidaropt(LidarPropDeviceType, &optval, sizeof(int));
  /// sample rate
  optval = 9;
  laser.setlidaropt(LidarPropSampleRate, &optval, sizeof(int));
  /// abnormal count
  optval = 4;
  laser.setlidaropt(LidarPropAbnormalCheckCount, &optval, sizeof(int));

  //////////////////////bool property/////////////////
  /// fixed angle resolution
  bool b_optvalue = false;
  laser.setlidaropt(LidarPropFixedResolution, &b_optvalue, sizeof(bool));
  /// rotate 180
  laser.setlidaropt(LidarPropReversion, &b_optvalue, sizeof(bool));
  /// Counterclockwise
  laser.setlidaropt(LidarPropInverted, &b_optvalue, sizeof(bool));
  b_optvalue = true;
  laser.setlidaropt(LidarPropAutoReconnect, &b_optvalue, sizeof(bool));
  /// one-way communication
  b_optvalue = false;
  laser.setlidaropt(LidarPropSingleChannel, &b_optvalue, sizeof(bool));
  /// intensity
  b_optvalue = false;
  laser.setlidaropt(LidarPropIntenstiy, &b_optvalue, sizeof(bool));
  /// Motor DTR
  b_optvalue = false;
  laser.setlidaropt(LidarPropSupportMotorDtrCtrl, &b_optvalue, sizeof(bool));

  //////////////////////float property/////////////////
  /// unit: °
  float f_optvalue = 180.0f;
  laser.setlidaropt(LidarPropMaxAngle, &f_optvalue, sizeof(float));
  f_optvalue = -180.0f;
  laser.setlidaropt(LidarPropMinAngle, &f_optvalue, sizeof(float));
  /// unit: m
  f_optvalue = 16.f;
  laser.setlidaropt(LidarPropMaxRange, &f_optvalue, sizeof(float));
  f_optvalue = 0.1f;
  laser.setlidaropt(LidarPropMinRange, &f_optvalue, sizeof(float));
  /// unit: Hz
  f_optvalue = 10.f;
  laser.setlidaropt(LidarPropScanFrequency, &f_optvalue, sizeof(float));

  // initialize SDK and LiDAR
  bool ret = laser.initialize();
  if (ret) {//success
    //Start the device scanning routine which runs on a separate thread and enable motor.
    ret = laser.turnOn();
  } else {
    fprintf(stderr, "%s\n", laser.DescribeError());
    fflush(stderr);
  }

  // Turn On success and loop  
  while (ret && ydlidar::os_isOk()) {
    LaserScan scan;
    if (laser.doProcessSimple(scan)) {
      fprintf(stdout, "Scan received[%llu]: %u ranges is [%f]Hz\n",
              scan.stamp,
              (unsigned int)scan.points.size(), 1.0 / scan.config.scan_time);
      fflush(stdout);
    } else {
      fprintf(stderr, "Failed to get Lidar Data\n");
      fflush(stderr);
    }
  }
  // Stop the device scanning thread and disable motor.
  laser.turnOff();
  // Uninitialize the SDK and Disconnect the LiDAR.
  laser.disconnecting();
  return 0;
}

TOF LiDAR (../samples/tof_test.cpp)

#include "CYdLidar.h"
#include <iostream>
#include <string>
#include <algorithm>
#include <cctype>
using namespace std;
using namespace ydlidar;
#if defined(_MSC_VER)
#pragma comment(lib, "ydlidar_sdk.lib")
#endif

int main(int argc, char *argv[]) {
  // init system signal
  ydlidar::os_init();

  CYdLidar laser;
  //////////////////////string property/////////////////
  /// lidar port
  std::string port = "/dev/ydlidar
  laser.setlidaropt(LidarPropSerialPort, port.c_str(), port.size());
  /// ignore array
  std::string ignore_array;
  ignore_array.clear();
  laser.setlidaropt(LidarPropIgnoreArray, ignore_array.c_str(),
                    ignore_array.size());

  //////////////////////int property/////////////////
  /// lidar baudrate
  int optval = 512000;
  laser.setlidaropt(LidarPropSerialBaudrate, &optval, sizeof(int));
  /// tof lidar
  int optval = TYPE_TOF;
  laser.setlidaropt(LidarPropLidarType, &optval, sizeof(int));
  /// device type
  optval = YDLIDAR_TYPE_SERIAL;
  laser.setlidaropt(LidarPropDeviceType, &optval, sizeof(int));
  /// sample rate
  optval = 20;
  laser.setlidaropt(LidarPropSampleRate, &optval, sizeof(int));
  /// abnormal count
  optval = 4;
  laser.setlidaropt(LidarPropAbnormalCheckCount, &optval, sizeof(int));

  //////////////////////bool property/////////////////
  /// fixed angle resolution
  bool b_optvalue = false;
  laser.setlidaropt(LidarPropFixedResolution, &b_optvalue, sizeof(bool));
  /// rotate 180
  laser.setlidaropt(LidarPropReversion, &b_optvalue, sizeof(bool));
  /// Counterclockwise
  laser.setlidaropt(LidarPropInverted, &b_optvalue, sizeof(bool));
  b_optvalue = true;
  laser.setlidaropt(LidarPropAutoReconnect, &b_optvalue, sizeof(bool));
  /// one-way communication
  b_optvalue = false;
  laser.setlidaropt(LidarPropSingleChannel, &b_optvalue, sizeof(bool));
  /// intensity
  b_optvalue = false;
  laser.setlidaropt(LidarPropIntenstiy, &b_optvalue, sizeof(bool));
  /// Motor DTR
  b_optvalue = false;
  laser.setlidaropt(LidarPropSupportMotorDtrCtrl, &b_optvalue, sizeof(bool));

  //////////////////////float property/////////////////
  /// unit: °
  float f_optvalue = 180.0f;
  laser.setlidaropt(LidarPropMaxAngle, &f_optvalue, sizeof(float));
  f_optvalue = -180.0f;
  laser.setlidaropt(LidarPropMinAngle, &f_optvalue, sizeof(float));
  /// unit: m
  f_optvalue = 64.f;
  laser.setlidaropt(LidarPropMaxRange, &f_optvalue, sizeof(float));
  f_optvalue = 0.05f;
  laser.setlidaropt(LidarPropMinRange, &f_optvalue, sizeof(float));
  /// unit: Hz
  f_optvalue = 10.f;
  laser.setlidaropt(LidarPropScanFrequency, &f_optvalue, sizeof(float));

  // initialize SDK and LiDAR
  bool ret = laser.initialize();
  if (ret) {//success
    //Start the device scanning routine which runs on a separate thread and enable motor.
    ret = laser.turnOn();
  } else {
    fprintf(stderr, "%s\n", laser.DescribeError());
    fflush(stderr);
  }

  // Turn On success and loop  
  while (ret && ydlidar::os_isOk()) {
    LaserScan scan;
    if (laser.doProcessSimple(scan)) {
      fprintf(stdout, "Scan received[%llu]: %u ranges is [%f]Hz\n",
              scan.stamp,
              (unsigned int)scan.points.size(), 1.0 / scan.config.scan_time);
      fflush(stdout);
    } else {
      fprintf(stderr, "Failed to get Lidar Data\n");
      fflush(stderr);
    }
  }
  // Stop the device scanning thread and disable motor.
  laser.turnOff();
  // Uninitialize the SDK and Disconnect the LiDAR.
  laser.disconnecting();
  return 0;
}

CMake BUILD file(../samples/CMakeLists.txt)

cmake_minimum_required(VERSION 2.8)
PROJECT(ydlidar_test)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
add_definitions(-std=c++11) # Use C++11

#Include directories
INCLUDE_DIRECTORIES(
     ${CMAKE_SOURCE_DIR}
     ${CMAKE_SOURCE_DIR}/../
     ${CMAKE_CURRENT_BINARY_DIR}
)

SET(EXECUTABLE_OUTPUT_PATH ${CMAKE_BINARY_DIR})

set(curdir ${CMAKE_CURRENT_SOURCE_DIR})
FILE(GLOB APP_LIST "${curdir}/*.cpp")
foreach(child ${APP_LIST})
  string(REPLACE "${curdir}/" "" app_main ${child})
  string(REPLACE ".cpp" "" APP_NAME ${app_main})
  ADD_EXECUTABLE(${APP_NAME} ${app_main})
  TARGET_LINK_LIBRARIES(${APP_NAME} ydlidar_sdk)
endforeach()

Build and Run

  • Build: cd build & cmake ../ & make
  • Run ydlidar_test or tof_test in terminals:
    • ./ydlidar_test
    • ./tof_test
  • Examine the results: you should see message printing out in terminals.

Python

import os
import ydlidar
import time

if __name__ == "__main__":
    ydlidar.os_init();
    laser = ydlidar.CYdLidar();
    laser.setlidaropt(ydlidar.LidarPropSerialPort, "/dev/ydlidar");
    laser.setlidaropt(ydlidar.LidarPropSerialBaudrate, 230400);
    laser.setlidaropt(ydlidar.LidarPropLidarType, ydlidar.TYPE_TRIANGLE);
    laser.setlidaropt(ydlidar.LidarPropDeviceType, ydlidar.YDLIDAR_TYPE_SERIAL);
    laser.setlidaropt(ydlidar.LidarPropScanFrequency, 10.0);
    laser.setlidaropt(ydlidar.LidarPropSampleRate, 9);
    laser.setlidaropt(ydlidar.LidarPropSingleChannel, False);

    ret = laser.initialize();
    if ret:
        ret = laser.turnOn();
        scan = ydlidar.LaserScan();
        while ret and ydlidar.os_isOk() :
            r = laser.doProcessSimple(scan);
            if r:
                print("Scan received[",scan.stamp,"]:",scan.points.size(),"ranges is [",1.0/scan.config.scan_time,"]Hz");
            else :
                print("Failed to get Lidar Data")
            time.sleep(0.05);
        laser.turnOff();
    laser.disconnecting();

ThridParty Project Call Library OR Source

Introduction

There are two ways to integrate YDLIDAR SDK into your project.

Calling a compliled library

The implementation of the demo mainly includes the following steps.

Download YDLIDAR SDK

$git clone https://github.com/YDLIDAR/YDLidar-SDK

Build and Install

$cd YDLidar-SDK/build
$cmake ../
$make
$sudo make install

Note:

  • Default generate static library.
  • If you want to generate YDLidar-SDK dynamic library, Add the following options when compiling:
$cmake -DBUILD_SHARED_LIBS=ON ../ && make

Add YDLIDAR SDK to the CMakeLists file of your project

############## YDLIDAR SDK START#####################################
#find ydlidar_sdk package
find_package(ydlidar_sdk)
#Include directories
INCLUDE_DIRECTORIES(
  ${YDLIDAR_SDK_INCLUDE_DIRS}
)
#link library directories
link_directories(${YDLIDAR_SDK_LIBRARY_DIRS})

#Link your project to ydlidar_sdk library.
target_link_libraries(${PROJECT_NAME} ${YDLIDAR_SDK_LIBRARIES})

############## YDLIDAR SDK END#####################################

Detailed call Demo, see here

Add source code to the Project

The implementation of the demo mainly includes the following steps.

Copy YDLIDAR SDK to your project

$cd 'your project'
$git clone https://github.com/YDLIDAR/YDLidar-SDK

Note: The same can be downloaded and placed in your project directory.

Add YDLIDAR SDK project to the CMakeLists file of your project

############## YDLIDAR SDK START#####################################
#Include directories
INCLUDE_DIRECTORIES(
  ${CMAKE_SOURCE_DIR}
  ${CMAKE_SOURCE_DIR}/YDLidar-SDK
  ${CMAKE_SOURCE_DIR}/YDLidar-SDK/src
  ${CMAKE_CURRENT_BINARY_DIR}/YDLidar-SDK
)
#Add YDLIDAR SDK sub project
add_subdirectory(YDLidar-SDK)

#Link your project to ydlidar_sdk library.
target_link_libraries(${PROJECT_NAME} ydlidar_sdk)

############## YDLIDAR SDK END#####################################

Note:

  • If you do not want to generate samples in YDLidar-SDK, Add the following options when compiling:
$cmake -DBUILD_EXAMPLES=OFF ../ && make
  • If you want to generate YDLidar-SDK dynamic library, Add the following options when compiling:
$cmake -DBUILD_SHARED_LIBS=ON ../ && make
  • If you want to meet both of the above conditions, the operation is as follows:
$cmake -DBUILD_EXAMPLES=OFF -DBUILD_SHARED_LIBS=ON ../ && make

Detailed call Demo, see here

Development Flow

FlowChart

Development FlowChart

Sequence

Development sequenceDiagram

API Directory

CYDLidar API

For additional information and examples, refer to CYDLidar

API List

C++ API

/**
* @brief set lidar properties
* @param optname        option name
* @todo string properties
* - @ref LidarPropSerialPort
* - @ref LidarPropIgnoreArray
* @note set string property example
* @code
* CYdLidar laser;
* std::string lidar_port = "/dev/ydlidar";
* laser.setlidaropt(LidarPropSerialPort,lidar_port.c_str(), lidar_port.size());
* @endcode
* @todo int properties
* - @ref LidarPropSerialBaudrate
* - @ref LidarPropLidarType
* - @ref LidarPropDeviceType
* - @ref LidarPropSampleRate
* @note set int property example
* @code
* CYdLidar laser;
* int lidar_baudrate = 230400;
* laser.setlidaropt(LidarPropSerialPort,&lidar_baudrate, sizeof(int));
* @endcode
* @todo bool properties
* - @ref LidarPropFixedResolution
* - @ref LidarPropReversion
* - @ref LidarPropInverted
* - @ref LidarPropAutoReconnect
* - @ref LidarPropSingleChannel
* - @ref LidarPropIntenstiy
* - @ref LidarPropSupportMotorDtrCtrl
* - @ref LidarPropSupportHeartBeat
* @note set bool property example
* @code
* CYdLidar laser;
* bool lidar_fixedresolution = true;
* laser.setlidaropt(LidarPropSerialPort,&lidar_fixedresolution, sizeof(bool));
* @endcode
* @todo float properties
* - @ref LidarPropMaxRange
* - @ref LidarPropMinRange
* - @ref LidarPropMaxAngle
* - @ref LidarPropMinAngle
* - @ref LidarPropScanFrequency
* @note set float property example
* @code
* CYdLidar laser;
* float lidar_maxrange = 16.0f;
* laser.setlidaropt(LidarPropSerialPort,&lidar_maxrange, sizeof(float));
* @endcode
* @param optval         option value
* - std::string(or char*)
* - int
* - bool
* - float
* @param optlen         option length
* - data type size
* @return true if the Property is set successfully, otherwise false.
* @see LidarProperty
*/
bool setlidaropt(int optname, const void *optval, int optlen);

/**
* @brief get lidar property
* @param optname         option name
* @todo string properties
* - @ref LidarPropSerialPort
* - @ref LidarPropIgnoreArray
* @note get string property example
* @code
* CYdLidar laser;
* char lidar_port[30];
* laser.getlidaropt(LidarPropSerialPort,lidar_port, sizeof(lidar_port));
* @endcode
* @todo int properties
* - @ref LidarPropSerialBaudrate
* - @ref LidarPropLidarType
* - @ref LidarPropDeviceType
* - @ref LidarPropSampleRate
* @note get int property example
* @code
* CYdLidar laser;
* int lidar_baudrate;
* laser.getlidaropt(LidarPropSerialPort,&lidar_baudrate, sizeof(int));
* @endcode
* @todo bool properties
* - @ref LidarPropFixedResolution
* - @ref LidarPropReversion
* - @ref LidarPropInverted
* - @ref LidarPropAutoReconnect
* - @ref LidarPropSingleChannel
* - @ref LidarPropIntenstiy
* - @ref LidarPropSupportMotorDtrCtrl
* - @ref LidarPropSupportHeartBeat
* @note get bool property example
* @code
* CYdLidar laser;
* bool lidar_fixedresolution;
* laser.getlidaropt(LidarPropSerialPort,&lidar_fixedresolution, sizeof(bool));
* @endcode
* @todo float properties
* - @ref LidarPropMaxRange
* - @ref LidarPropMinRange
* - @ref LidarPropMaxAngle
* - @ref LidarPropMinAngle
* - @ref LidarPropScanFrequency
* @note set float property example
* @code
* CYdLidar laser;
* float lidar_maxrange;
* laser.getlidaropt(LidarPropSerialPort,&lidar_maxrange, sizeof(float));
* @endcode
* @param optval          option value
* - std::string(or char*)
* - int
* - bool
* - float
* @param optlen          option length
* - data type size
* @return true if the Property is get successfully, otherwise false.
* @see LidarProperty
*/
bool getlidaropt(int optname, void *optval, int optlen);
/**
 * @brief Initialize the SDK and LiDAR.
 * @return true if successfully initialized, otherwise false.
 */
bool initialize();

/**
* @brief Return LiDAR's version information in a numeric form.
* @param version Pointer to a version structure for returning the version information.
*/
void GetLidarVersion(LidarVersion &version);

/**
 * @brief Start the device scanning routine which runs on a separate thread and enable motor.
 * @return true if successfully started, otherwise false.
 */
bool  turnOn();
/**
 * @brief Get the LiDAR Scan Data. turnOn is successful before doProcessSimple scan data.
 * @param[out] outscan             LiDAR Scan Data
 * @param[out] hardwareError       hardware error status
 * @return true if successfully started, otherwise false.
 */
bool doProcessSimple(LaserScan &outscan, bool &hardwareError);
/**
 * @brief Stop the device scanning thread and disable motor.
 * @return true if successfully Stoped, otherwise false.
 */
bool  turnOff();
/**
 * @brief Uninitialize the SDK and Disconnect the LiDAR.
 */
void disconnecting();

/**
 * @brief Get the last error information of a (socket or serial)
 * @return a human-readable description of the given error information
 * or the last error information of a (socket or serial)
 */
const char *DescribeError() const;

C API

/**
 * @brief create a Lidar instance
 * @note call ::lidarDestroy destroy
 * @return created instance
 */
YDLidar *lidarCreate(void);

/**
 * @brief Destroy Lidar instance by ::lidarCreate create
 * @param lidar     CYdLidar instance
 */
void lidarDestroy(YDLidar **lidar);

/**
 * @brief set lidar properties
 * @param lidar           a lidar instance
 * @param optname        option name
 * @todo string properties
 * - @ref LidarPropSerialPort
 * - @ref LidarPropIgnoreArray
 * @note set string property example
 * @code
 * CYdLidar laser;
 * std::string lidar_port = "/dev/ydlidar";
 * laser.setlidaropt(LidarPropSerialPort,lidar_port.c_str(), lidar_port.size());
 * @endcode
 * @todo int properties
 * - @ref LidarPropSerialBaudrate
 * - @ref LidarPropLidarType
 * - @ref LidarPropDeviceType
 * - @ref LidarPropSampleRate
 * @note set int property example
 * @code
 * CYdLidar laser;
 * int lidar_baudrate = 230400;
 * laser.setlidaropt(LidarPropSerialPort,&lidar_baudrate, sizeof(int));
 * @endcode
 * @todo bool properties
 * - @ref LidarPropFixedResolution
 * - @ref LidarPropReversion
 * - @ref LidarPropInverted
 * - @ref LidarPropAutoReconnect
 * - @ref LidarPropSingleChannel
 * - @ref LidarPropIntenstiy
 * - @ref LidarPropSupportMotorDtrCtrl
 * - @ref LidarPropSupportHeartBeat
 * @note set bool property example
 * @code
 * CYdLidar laser;
 * bool lidar_fixedresolution = true;
 * laser.setlidaropt(LidarPropSerialPort,&lidar_fixedresolution, sizeof(bool));
 * @endcode
 * @todo float properties
 * - @ref LidarPropMaxRange
 * - @ref LidarPropMinRange
 * - @ref LidarPropMaxAngle
 * - @ref LidarPropMinAngle
 * - @ref LidarPropScanFrequency
 * @note set float property example
 * @code
 * CYdLidar laser;
 * float lidar_maxrange = 16.0f;
 * laser.setlidaropt(LidarPropSerialPort,&lidar_maxrange, sizeof(float));
 * @endcode
 * @param optval         option value
 * - std::string(or char*)
 * - int
 * - bool
 * - float
 * @param optlen         option length
 * - data type size
 * @return true if the Property is set successfully, otherwise false.
 * @see LidarProperty
 */
bool setlidaropt(YDLidar *lidar, int optname, const void *optval, int optlen);

/**
 * @brief get lidar property
 * @param lidar           a lidar instance
 * @param optname         option name
 * @todo string properties
 * - @ref LidarPropSerialPort
 * - @ref LidarPropIgnoreArray
 * @note get string property example
 * @code
 * CYdLidar laser;
 * char lidar_port[30];
 * laser.getlidaropt(LidarPropSerialPort,lidar_port, sizeof(lidar_port));
 * @endcode
 * @todo int properties
 * - @ref LidarPropSerialBaudrate
 * - @ref LidarPropLidarType
 * - @ref LidarPropDeviceType
 * - @ref LidarPropSampleRate
 * @note get int property example
 * @code
 * CYdLidar laser;
 * int lidar_baudrate;
 * laser.getlidaropt(LidarPropSerialPort,&lidar_baudrate, sizeof(int));
 * @endcode
 * @todo bool properties
 * - @ref LidarPropFixedResolution
 * - @ref LidarPropReversion
 * - @ref LidarPropInverted
 * - @ref LidarPropAutoReconnect
 * - @ref LidarPropSingleChannel
 * - @ref LidarPropIntenstiy
 * - @ref LidarPropSupportMotorDtrCtrl
 * - @ref LidarPropSupportHeartBeat
 * @note get bool property example
 * @code
 * CYdLidar laser;
 * bool lidar_fixedresolution;
 * laser.getlidaropt(LidarPropSerialPort,&lidar_fixedresolution, sizeof(bool));
 * @endcode
 * @todo float properties
 * - @ref LidarPropMaxRange
 * - @ref LidarPropMinRange
 * - @ref LidarPropMaxAngle
 * - @ref LidarPropMinAngle
 * - @ref LidarPropScanFrequency
 * @note set float property example
 * @code
 * CYdLidar laser;
 * float lidar_maxrange;
 * laser.getlidaropt(LidarPropSerialPort,&lidar_maxrange, sizeof(float));
 * @endcode
 * @param optval          option value
 * - std::string(or char*)
 * - int
 * - bool
 * - float
 * @param optlen          option length
 * - data type size
 * @return true if the Property is get successfully, otherwise false.
 * @see LidarProperty
 */
bool getlidaropt(YDLidar *lidar, int optname, void *optval, int optlen);

/**
* Return SDK's version information in a numeric form.
* @param version Pointer to a version for returning the version information.
*/
void GetSdkVersion(char *version);

/**
 * Initialize the SDK.
 * @return true if successfully initialized, otherwise false.
 */
bool initialize(YDLidar *lidar);

/**
* @brief Return LiDAR's version information in a numeric form.
* @param version Pointer to a version structure for returning the version information.
*/
void GetLidarVersion(YDLidar *lidar, LidarVersion *version);

/**
 * Start the device scanning routine which runs on a separate thread.
 * @return true if successfully started, otherwise false.
 */
bool turnOn(YDLidar *lidar);

/**
 * @brief Get the LiDAR Scan Data. turnOn is successful before doProcessSimple scan data.
 * @param[in] lidar          LiDAR instance
 * @param[out] outscan       LiDAR Scan Data
 * @return true if successfully started, otherwise false.
 */
bool doProcessSimple(YDLidar *lidar, LaserFan *outscan);
/**
 * @brief Stop the device scanning thread and disable motor.
 * @return true if successfully Stoped, otherwise false.
 */
bool  turnOff(YDLidar *lidar);
/**
 * @brief Uninitialize the SDK and Disconnect the LiDAR.
 */
void disconnecting(YDLidar *lidar);

/**
 * @brief Get the last error information of a (socket or serial)
 * @return a human-readable description of the given error information
 * or the last error information of a (socket or serial)
 */
const char *DescribeError(YDLidar *lidar);

/**
 * @brief initialize system signals
 */
void os_init();
/**
 * @brief isOk
 * @return true if successfully initialize, otherwise false.
 */
bool os_isOk();
/**
 * @brief os_shutdown
 */
void os_shutdown();

/**
 * @brief get lidar serial port
 * @param ports serial port lists
 * @return valid port number
 */
int lidarPortList(LidarPort *ports);

YDlidarDriver API

For additional information and examples, refer to YDlidarDriver

API List

  /**
   * @brief Connecting Lidar \n
   * After the connection if successful, you must use ::disconnect to close
   * @param[in] port_path    serial port
   * @param[in] baudrate    serial baudrate,YDLIDAR-SS:
   *     230400 G2-SS-1 R2-SS-1
   * @return connection status
   * @retval 0     success
   * @retval < 0   failed
   * @note After the connection if successful, you must use ::disconnect to close
   * @see function ::YDlidarDriver::disconnect ()
   */
  virtual result_t connect(const char *port_path, uint32_t baudrate);

  /**
   * @brief Returns a human-readable description of the given error code
   *  or the last error code of a socket or serial port
   * @param isTCP   TCP or UDP
   * @return error information
   */
  virtual const char *DescribeError(bool isTCP = true);


  /*!
  * @brief Disconnect the LiDAR.
  */
  virtual void disconnect();

  /**
  * @brief Get SDK Version \n
  * static function
  * @return Version
  */
  virtual std::string getSDKVersion();

  /**
   * @brief lidarPortList Get Lidar Port lists
   * @return online lidars
   */
  static std::map<std::string, std::string> lidarPortList();


  /**
   * @brief Is the Lidar in the scan \n
   * @return scanning status
   * @retval true     scanning
   * @retval false    non-scanning
   */
  virtual bool isscanning() const;

  /**
   * @brief Is it connected to the lidar \n
   * @return connection status
   * @retval true     connected
   * @retval false    Non-connected
   */
  virtual bool isconnected() const;

  /**
   * @brief Is there intensity \n
   * @param[in] isintensities    intentsity
   *   true	intensity
   *   false no intensity
   */
  virtual void setIntensities(const bool &isintensities);

  /**
   * @brief whether to support hot plug \n
   * @param[in] enable    hot plug :
   *   true	support
   *   false no support
   */
  virtual void setAutoReconnect(const bool &enable);

  /**
   * @brief get Health status \n
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE or RESULT_TIMEOUT   failed
   */
  virtual result_t getHealth(device_health &health,
                             uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief get Device information \n
   * @param[in] info     Device information
   * @param[in] timeout  timeout
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE or RESULT_TIMEOUT   failed
   */
  virtual result_t getDeviceInfo(device_info &info,
                                 uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Turn on scanning \n
   * @param[in] force    Scan mode
   * @param[in] timeout  timeout
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Just turn it on once
   */
  virtual result_t startScan(bool force = false,
                             uint32_t timeout = DEFAULT_TIMEOUT) ;

  /**
   * @brief turn off scanning \n
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   */
  virtual result_t stop();


  /**
   * @brief Get a circle of laser data \n
   * @param[in] nodebuffer Laser data
   * @param[in] count      one circle of laser points
   * @param[in] timeout    timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Before starting, you must start the start the scan successfully with the ::startScan function
   */
  virtual result_t grabScanData(node_info *nodebuffer, size_t &count,
                                uint32_t timeout = DEFAULT_TIMEOUT) ;


  /**
   * @brief Normalized angle \n
   * Normalize the angel between 0 and 360
   * @param[in] nodebuffer Laser data
   * @param[in] count      one circle of laser points
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Before the normalization, you must use the ::grabScanData function to get the laser data successfully.
   */
  result_t ascendScanData(node_info *nodebuffer, size_t count);

  /**
  * @brief reset lidar \n
  * @param[in] timeout      timeout
  * @return return status
  * @retval RESULT_OK       success
  * @retval RESULT_FAILE    failed
  * @note Non-scan state, perform currect operation.
  */
  result_t reset(uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief start motor \n
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   */
  result_t startMotor();

  /**
   * @brief stop motor \n
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   */
  result_t stopMotor();

  /**
  * @brief Get lidar scan frequency \n
  * @param[in] frequency    scanning frequency
  * @param[in] timeout      timeout
  * @return return status
  * @retval RESULT_OK       success
  * @retval RESULT_FAILE    failed
  * @note Non-scan state, perform currect operation.
  */
  virtual  result_t getScanFrequency(scan_frequency &frequency,
                                     uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Increase the scanning frequency by 1.0 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyAdd(scan_frequency &frequency,
                                       uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Reduce the scanning frequency by 1.0 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyDis(scan_frequency &frequency,
                                       uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Increase the scanning frequency by 0.1 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyAddMic(scan_frequency &frequency,
                                          uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Reduce the scanning frequency by 0.1 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyDisMic(scan_frequency &frequency,
                                          uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Get lidar sampling frequency \n
   * @param[in] frequency    sampling frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t getSamplingRate(sampling_rate &rate,
                                   uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Set the lidar sampling frequency \n
   * @param[in] rate       sampling frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setSamplingRate(sampling_rate &rate,
                                   uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief get lidar zero offset angle \n
   * @param[in] angle      zero offset angle
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t getZeroOffsetAngle(offset_angle &angle,
                                      uint32_t timeout = DEFAULT_TIMEOUT);

ETLidarDriver API

For additional information and examples, refer to ETLidarDriver

API List

  /**
   * @brief Connecting Lidar \n
   * After the connection if successful, you must use ::disconnect to close
   * @param[in] port_path    Ip Address
   * @param[in] baudrate     network port
   * @return connection status
   * @retval 0     success
   * @retval < 0   failed
   * @note After the connection if successful, you must use ::disconnect to close
   * @see function ::YDlidarDriver::disconnect ()
   */
  virtual result_t connect(const char *port_path, uint32_t baudrate = 8000);


  /**
   * @brief Returns a human-readable description of the given error code
   *  or the last error code of a socket
   * @param isTCP   TCP or UDP
   * @return error information
   */
  virtual const char *DescribeError(bool isTCP = true);

  /**
  * @brief Disconnect from ETLidar device.
  */
  virtual void disconnect();

  /**
  * @brief Get SDK Version
  * @return version
  */
  virtual std::string getSDKVersion();

  /**
   * @brief Is the Lidar in the scan \n
   * @return scanning status
   * @retval true     scanning
   * @retval false    non-scanning
   */
  virtual bool isscanning() const;

  /**
   * @brief Is it connected to the lidar \n
   * @return connection status
   * @retval true     connected
   * @retval false    Non-connected
   */
  virtual bool isconnected() const;

  /**
   * @brief Is there intensity \n
   * @param[in] isintensities    intentsity
   *   true	intensity
   *   false no intensity
   */
  virtual void setIntensities(const bool &isintensities);

  /**
   * @brief whether to support hot plug \n
   * @param[in] enable    hot plug :
   *   true	support
   *   false no support
   */
  virtual void setAutoReconnect(const bool &enable);

  /**
   * @brief get Health status \n
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE or RESULT_TIMEOUT   failed
   */
  virtual result_t getHealth(device_health &health,
                             uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief get Device information \n
   * @param[in] info     Device information
   * @param[in] timeout  timeout
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE or RESULT_TIMEOUT   failed
   */
  virtual result_t getDeviceInfo(device_info &info,
                                 uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Turn on scanning \n
   * @param[in] force    Scan mode
   * @param[in] timeout  timeout
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Just turn it on once
   */
  virtual result_t startScan(bool force = false,
                             uint32_t timeout = DEFAULT_TIMEOUT) ;

  /**
   * @brief turn off scanning \n
   * @return result status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   */
  virtual result_t stop();


  /**
   * @brief Get a circle of laser data \n
   * @param[in] nodebuffer Laser data
   * @param[in] count      one circle of laser points
   * @param[in] timeout    timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Before starting, you must start the start the scan successfully with the ::startScan function
   */
  virtual result_t grabScanData(node_info *nodebuffer, size_t &count,
                                uint32_t timeout = DEFAULT_TIMEOUT) ;

  /**
   * @brief Get lidar scan frequency \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t getScanFrequency(scan_frequency &frequency,
                                    uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Increase the scanning frequency by 1.0 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyAdd(scan_frequency &frequency,
                                       uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Reduce the scanning frequency by 1.0 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyDis(scan_frequency &frequency,
                                       uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Increase the scanning frequency by 0.1 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyAddMic(scan_frequency &frequency,
                                          uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Reduce the scanning frequency by 0.1 HZ \n
   * @param[in] frequency    scanning frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setScanFrequencyDisMic(scan_frequency &frequency,
                                          uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Get lidar sampling frequency \n
   * @param[in] frequency    sampling frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t getSamplingRate(sampling_rate &rate,
                                   uint32_t timeout = DEFAULT_TIMEOUT);

  /**
   * @brief Set the lidar sampling frequency \n
   * @param[in] rate       sampling frequency
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t setSamplingRate(sampling_rate &rate,
                                   uint32_t timeout = DEFAULT_TIMEOUT);
  /**
   * @brief get lidar zero offset angle \n
   * @param[in] angle      zero offset angle
   * @param[in] timeout      timeout
   * @return return status
   * @retval RESULT_OK       success
   * @retval RESULT_FAILE    failed
   * @note Non-scan state, perform currect operation.
   */
  virtual result_t getZeroOffsetAngle(offset_angle &angle,
                                      uint32_t timeout = DEFAULT_TIMEOUT);


  /**
  * @brief Get current scan configuration.
  * @returns scanCfg structure.
  */
  bool getScanCfg(lidarConfig &config, const std::string &ip_address = "");

  /**
  * @brief Get current scan update configuration.
  * @returns scanCfg structure.
  */
  lidarConfig getFinishedScanCfg();

  /**
   * @brief updateScanCfg
   * @param config
   */
  void updateScanCfg(const lidarConfig &config);

Parameter Table

The Table that the user uses to perform parameter related operations:

  • Set the parameter related API by table.

For additional information and examples, refer to Parameter

Table List - Models

LIDAR Model Baudrate SampleRate(K) Range(m) Frequency(HZ) Intenstiy(bit) SingleChannel voltage(V)
F4 1 115200 4 0.12~12 5~12 false false 4.8~5.2
S4 4 115200 4 0.10~8.0 5~12 (PWM) false false 4.8~5.2
S4B 4/11 153600 4 0.10~8.0 5~12(PWM) true(8) false 4.8~5.2
S2 4/12 115200 3 0.10~8.0 4~8(PWM) false true 4.8~5.2
G4 5 230400 9/8/4 0.28/0.26/0.1~16 5~12 false false 4.8~5.2
X4 6 128000 5 0.12~10 5~12(PWM) false false 4.8~5.2
X2/X2L 6 115200 3 0.10~8.0 4~8(PWM) false true 4.8~5.2
G4PRO 7 230400 9/8/4 0.28/0.26/0.1~16 5~12 false false 4.8~5.2
F4PRO 8 230400 4/6 0.12~12 5~12 false false 4.8~5.2
R2 9 230400 5 0.12~16 5~12 false false 4.8~5.2
G6 13 512000 18/16/8 0.28/0.26/0.1~25 5~12 false false 4.8~5.2
G2A 14 230400 5 0.12~12 5~12 false false 4.8~5.2
G2 15 230400 5 0.28~16 5~12 true(8) false 4.8~5.2
G2C 16 115200 4 0.1~12 5~12 false false 4.8~5.2
G4B 17 512000 10 0.12~16 5~12 true(10) false 4.8~5.2
G4C 18 115200 4 0.1~12 5~12 false false 4.8~5.2
G1 19 230400 9 0.28~16 5~12 false false 4.8~5.2
TX8   100 115200 4 0.1~8 4~8(PWM) false true 4.8~5.2
TX20   100 115200 4 0.1~20 4~8(PWM) false true 4.8~5.2
TG15   100 512000 20/18/10 0.05~30 3~16 false false 4.8~5.2
TG30   101 512000 20/18/10 0.05~30 3~16 false false 4.8~5.2
TG50   102 512000 20/18/10 0.05~50 3~16 false false 4.8~5.2
T15   200 8000 20 0.05~15 10-35 true false 4.8~5.2
T30   200 8000 20 0.05~30 10-35 true false 4.8~5.2

Table List - SerialBaudrate

LiDAR SerialBaudrate
F4/S2/X2/X2L/S4/TX8/TX20/G4C 115200
X4 128000
S4B 153600
G1/G2/R2/G4/G4PRO/F4PRO 230400
G2A/G2C 230400
G6/G4B/TG15/TG30/TG50 512000
T5/T15(network) 8000

Table List - SampleRate

LiDAR SampleRate
G4/F4 4,8,9
F4PRO 4,6
G6 8,16,18
G4B 10
G1 9
G2A/G2/R2/X4 5
S4/S4B/G4C/TX8/TX20 4
G2C 4
S2 3
TG15/TG30/TG50 10,18,20
T5/T15 20

Table List - ScanFrequency

LiDAR ScanFrequency
S2/X2/X2L/TX8/TX20 4~8(PWM)
F4/F4PRO/G4/G4PRO/R2 5~12
G6/G2A/G2/G2C/G4B/G4C/G1 5~12
S4/S4B/X4 5~12(PWM)
TG15/TG30/TG50 3~16
T5/T15 5~40

Table List - SingleChannel

LiDAR SingleChannel
G1/G2/G2A/G2C false
G4/G4B/G4PRO/G6/F4/F4PRO false
S4/S4B/X4/R2/G4C false
S2/X2/X2L true
TG15/TG30/TG50 false
TX8/TX20 true
T5/T15 false
true

Table List - LidarType

LiDAR LidarType
G1/G2A/G2/G2C TYPE_TRIANGLE
G4/G4B/G4C/G4PRO TYPE_TRIANGLE
G6/F4/F4PRO TYPE_TRIANGLE
S4/S4B/X4/R2/S2/X2/X2L TYPE_TRIANGLE
TG15/TG30/TG50/TX8/TX20 TYPE_TOF
T5/T15 TYPE_TOF_NET

Table List - Intensity

LiDAR Intensity
S4B/G2/G4B true
G4/G4C/G4PRO/F4/F4PRO/G6 false
G1/G2A/G2C/R2 false
S2/X2/X2L/X4 false
TG15/TG30/TG50 false
TX8/TX20 false
T5/T15 true
false

Table List - SupportMotorDtrCtrl

S4/S4B/S2/X2/X2L/X4 SupportMotorDtrCtrl
S4/S4B/S2/X2/X2L/X4 true
TX8/TX20 true
G4/G4C/G4PRO/F4/F4PRO/G6 false
G1/G2A/G2C/R2/G2/G4B false
TG15/TG30/TG50 false
T5/T15 false