SDK頭文件介紹
1、頭文件簡介：
rplidar.h //一般情況下開發的項目中僅需要引入該頭文件即可使用 RPLIDAR SDK 的所有功能。 rplidar_driver.h //定義了 SDK 核心驅動接口: RPlidarDriver 的類聲明。 rplidar_protocol.h //定義了 RPLIDAR 通訊協議文檔中描述的底層相關數據結構和常量定義。 rplidar_cmd.h //定義了 RPLIDAR 通訊協議文檔中描述的各類請求/應答相關的數據結構和常量定義。 rptypes.h //平台無關的結構和常量定義
2、頭文件解析
（1）rplidar_protocol.h
#pragma once
// RP-Lidar Input Packets #define RPLIDAR_CMD_SYNC_BYTE 0xA5 //請求報文開始字節 #define RPLIDAR_CMDFLAG_HAS_PAYLOAD 0x80 //情報報文負載 #define RPLIDAR_ANS_SYNC_BYTE1 0xA5 //應答報文起始標志1 #define RPLIDAR_ANS_SYNC_BYTE2 0x5A //應答報文起始標志2 #define RPLIDAR_ANS_PKTFLAG_LOOP 0x1 //多次應答模式 #define RPLIDAR_ANS_HEADER_SIZE_MASK 0x3FFFFFFF #define RPLIDAR_ANS_HEADER_SUBTYPE_SHIFT (30) #if defined(_WIN32) #pragma pack(1) #endif //請求報文格式 typedef struct _rplidar_cmd_packet_t { _u8 syncByte; //must be RPLIDAR_CMD_SYNC_BYTE //起始標志 _u8 cmd_flag; //請求命令 _u8 size; //負載長度 _u8 data[0]; //請求負載數據 } __attribute__((packed)) rplidar_cmd_packet_t; //__attribute__ ((packed)) 的作用就是告訴編譯器取消結構在編譯過程中的優化對齊,按照實際占用字節數進行對齊 //使用之后才會是幾字節就是幾字節，否則就每個變量的字節長度都跟結構體中變量字節長度最長相同 //應答報文格式 typedef struct _rplidar_ans_header_t { _u8 syncByte1; // must be RPLIDAR_ANS_SYNC_BYTE1 //起始標志1 _u8 syncByte2; // must be RPLIDAR_ANS_SYNC_BYTE2 //起始標志2 _u32 size_q30_subtype; // see _u32 size:30; _u32 subType:2; //應答報文長度 _u8 type; //應答模式 } __attribute__((packed)) rplidar_ans_header_t; #if defined(_WIN32) #pragma pack() #endif
（2）rplidar_cmd.h
#pragma once #include "rplidar_protocol.h" // Commands //----------------------------------------- // Commands without payload and response #define RPLIDAR_CMD_STOP 0x25 //離開掃描模式，進入空閑狀態 #define RPLIDAR_CMD_SCAN 0x20 //請求進入掃描采樣狀態 #define RPLIDAR_CMD_FORCE_SCAN 0x21 //請求進入掃描采樣狀態，強制數據輸出 #define RPLIDAR_CMD_RESET 0x40 //測距核心軟重啟 // Commands without payload but have response #define RPLIDAR_CMD_GET_DEVICE_INFO 0x50 //獲取設備序列號等信息 #define RPLIDAR_CMD_GET_DEVICE_HEALTH 0x52 //獲取設備健康狀態 #define RPLIDAR_CMD_GET_SAMPLERATE 0x59 //added in fw 1.17 獲取單詞激光測距的用時 // Commands with payload and have response #define RPLIDAR_CMD_EXPRESS_SCAN 0x82 //added in fw 1.17 請求進入掃描狀態，幷工作在最高采樣頻率下 //add for A2 to set RPLIDAR motor pwm when using accessory board #define RPLIDAR_CMD_SET_MOTOR_PWM 0xF0 #define RPLIDAR_CMD_GET_ACC_BOARD_FLAG 0xFF #if defined(_WIN32) //如果是win32下編譯則執行 #pragma pack(1) //結構體邊界設置為1字節，也就是說儲存在內存中是連續的 #endif // Payloads // ------------------------------------------ #define RPLIDAR_EXPRESS_SCAN_MODE_NORMAL 0 #define RPLIDAR_EXPRESS_SCAN_MODE_FIXANGLE 1 typedef struct _rplidar_payload_express_scan_t { //帶有負載的數據包 _u8 working_mode; _u32 reserved; } __attribute__((packed)) rplidar_payload_express_scan_t; #define MAX_MOTOR_PWM 1023 //電機PWM最大值 #define DEFAULT_MOTOR_PWM 660 //電機PWM默認值 //電機PWM結構 typedef struct _rplidar_payload_motor_pwm_t { _u16 pwm_value; } __attribute__((packed)) rplidar_payload_motor_pwm_t; // ??????????? typedef struct _rplidar_payload_acc_board_flag_t { _u32 reserved; } __attribute__((packed)) rplidar_payload_acc_board_flag_t; // Response // ------------------------------------------ #define RPLIDAR_ANS_TYPE_DEVINFO 0x4 //設備信心獲取 起始應答結尾 #define RPLIDAR_ANS_TYPE_DEVHEALTH 0x6 //設備健康狀態獲取 起始應答結尾 #define RPLIDAR_ANS_TYPE_MEASUREMENT 0x81 //普通采集 // Added in FW ver 1.17 #define RPLIDAR_ANS_TYPE_MEASUREMENT_CAPSULED 0x82 //高速采集 // Added in FW ver 1.17 #define RPLIDAR_ANS_TYPE_SAMPLE_RATE 0x15 // #define RPLIDAR_ANS_TYPE_ACC_BOARD_FLAG 0xFF #define RPLIDAR_RESP_ACC_BOARD_FLAG_MOTOR_CTRL_SUPPORT_MASK (0x1) typedef struct _rplidar_response_acc_board_flag_t { _u32 support_flag; } __attribute__((packed)) rplidar_response_acc_board_flag_t; //設備狀態 #define RPLIDAR_STATUS_OK 0x0 #define RPLIDAR_STATUS_WARNING 0x1 #define RPLIDAR_STATUS_ERROR 0x2 #define RPLIDAR_RESP_MEASUREMENT_SYNCBIT (0x1<<0) #define RPLIDAR_RESP_MEASUREMENT_QUALITY_SHIFT 2 #define RPLIDAR_RESP_MEASUREMENT_CHECKBIT (0x1<<0) #define RPLIDAR_RESP_MEASUREMENT_ANGLE_SHIFT 1 //激光測距勇士獲取數據包 typedef struct _rplidar_response_sample_rate_t { _u16 std_sample_duration_us; //在標准掃描模式下，設備測距核心進行單次激光測距的耗時 單位：微秒 _u16 express_sample_duration_us; //在高速采樣模式下，設備測距核心進行單次激光測距的耗時 單位：微妙 } __attribute__((packed)) rplidar_response_sample_rate_t; typedef struct _rplidar_response_measurement_node_t { _u8 sync_quality; // syncbit:1;syncbit_inverse:1;quality:6; //信號質量 _u16 angle_q6_checkbit; // check_bit:1;angle_q6:15; //測距點相對於RPLIDAR朝向夾角 實際角度 = angle_q6 / 64.0 Deg _u16 distance_q2; //測距點相對於RPLIDAR的距離 實際距離 = distance_q2 / 4.0 mm } __attribute__((packed)) rplidar_response_measurement_node_t; //[distance_sync flags] #define RPLIDAR_RESP_MEASUREMENT_EXP_ANGLE_MASK (0x3) #define RPLIDAR_RESP_MEASUREMENT_EXP_DISTANCE_MASK (0xFC) typedef struct _rplidar_response_cabin_nodes_t { _u16 distance_angle_1; // see [distance_sync flags] _u16 distance_angle_2; // see [distance_sync flags] _u8 offset_angles_q3; } __attribute__((packed)) rplidar_response_cabin_nodes_t; #define RPLIDAR_RESP_MEASUREMENT_EXP_SYNC_1 0xA #define RPLIDAR_RESP_MEASUREMENT_EXP_SYNC_2 0x5 #define RPLIDAR_RESP_MEASUREMENT_EXP_SYNCBIT (0x1<<15) typedef struct _rplidar_response_capsule_measurement_nodes_t { _u8 s_checksum_1; // see [s_checksum_1] _u8 s_checksum_2; // see [s_checksum_1] _u16 start_angle_sync_q6; rplidar_response_cabin_nodes_t cabins[16]; } __attribute__((packed)) rplidar_response_capsule_measurement_nodes_t; //設備信息數據報文 typedef struct _rplidar_response_device_info_t { _u8 model; _u16 firmware_version; _u8 hardware_version; _u8 serialnum[16]; } __attribute__((packed)) rplidar_response_device_info_t; //設備健康信息數據報文 typedef struct _rplidar_response_device_health_t { _u8 status; _u16 error_code; } __attribute__((packed)) rplidar_response_device_health_t; #if defined(_WIN32) #pragma pack() #endif
（3）rplidar_driver.h
#pragma once #ifndef __cplusplus #error "The RPlidar SDK requires a C++ compiler to be built" #endif namespace rp { namespace standalone{ namespace rplidar { class RPlidarDriver { public: enum { DEFAULT_TIMEOUT = 2000, //2000 ms }; enum { DRIVER_TYPE_SERIALPORT = 0x0, }; public: /// Create an RPLIDAR Driver Instance /// This interface should be invoked first before any other operations /// /// \param drivertype the connection type used by the driver. static RPlidarDriver * CreateDriver(_u32 drivertype = DRIVER_TYPE_SERIALPORT); //靜態創建對象接口 /// Dispose the RPLIDAR Driver Instance specified by the drv parameter /// Applications should invoke this interface when the driver instance is no longer used in order to free memory static void DisposeDriver(RPlidarDriver * drv); //靜態接口函數析構RPlidar實例 public: /// Open the specified serial port and connect to a target RPLIDAR device /// /// \param port_path the device path of the serial port /// e.g. on Windows, it may be com3 or \\.\com10 /// on Unix-Like OS, it may be /dev/ttyS1, /dev/ttyUSB2, etc /// /// \param baudrate the baudrate used /// For most RPLIDAR models, the baudrate should be set to 115200 /// /// \param flag other flags /// Reserved for future use, always set to Zero virtual u_result connect(const char * port_path, _u32 baudrate, _u32 flag = 0) = 0; //設備連接函數,調用時會默認停止電機旋轉，測試時需要使用startMotor啟動電機旋轉 /// Disconnect with the RPLIDAR and close the serial port virtual void disconnect() = 0; //斷開鏈接 /// Returns TRUE when the connection has been established virtual bool isConnected() = 0; /// Ask the RPLIDAR core system to reset it self /// The host system can use the Reset operation to help RPLIDAR escape the self-protection mode. /// // \param timeout The operation timeout value (in millisecond) for the serial port communication virtual u_result reset(_u32 timeout = DEFAULT_TIMEOUT) = 0; /// Retrieve the health status of the RPLIDAR /// The host system can use this operation to check whether RPLIDAR is in the self-protection mode. /// /// \param health The health status info returned from the RPLIDAR /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication virtual u_result getHealth(rplidar_response_device_health_t & health, _u32 timeout = DEFAULT_TIMEOUT) = 0; //獲取 RPLIDAR 設備的健康狀態 /// Get the device information of the RPLIDAR include the serial number, firmware version, device model etc. /// /// \param info The device information returned from the RPLIDAR /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication virtual u_result getDeviceInfo(rplidar_response_device_info_t & info, _u32 timeout = DEFAULT_TIMEOUT) = 0; //獲取 RPLIDAR 設備序列號、固件版本等信息 /// Get the sample duration information of the RPLIDAR. /// /// \param rateInfo The sample duration information returned from the RPLIDAR /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication virtual u_result getSampleDuration_uS(rplidar_response_sample_rate_t & rateInfo, _u32 timeout = DEFAULT_TIMEOUT) = 0; //獲取 RPLIDAR 分別在標准 Scan 以及 ExpressScan 模 //式下單次激光采樣的用時。 單位為微秒(uS) /// Set the RPLIDAR's motor pwm when using accessory board, currently valid for A2 only. /// /// \param pwm The motor pwm value would like to set virtual u_result setMotorPWM(_u16 pwm) = 0; //向開發套件的 USB 附件板發送特定的 PWM 占空比,控制RPLIDAR 掃描電機轉速。 /// Start RPLIDAR's motor when using accessory board virtual u_result startMotor() = 0; //啟動電機 /// Stop RPLIDAR's motor when using accessory board virtual u_result stopMotor() = 0; //停止電機 /// Check whether the device support motor control. /// Note: this API will disable grab. /// /// \param support Return the result. /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication. virtual u_result checkMotorCtrlSupport(bool & support, _u32 timeout = DEFAULT_TIMEOUT) = 0; //檢測附件板是否支持電機 PWM 控制。 /// Calcuate RPLIDAR's current scanning frequency from the given scan data /// Please refer to the application note doc for details /// Remark: the calcuation will be incorrect if the specified scan data doesn't contains enough data /// /// \param inExpressMode Indicate whether the RPLIDAR is in express mode /// /// \param count The number of sample nodes inside the given buffer /// /// \param frequency The scanning frequency (in HZ) calcuated by the interface. /// /// \param is4kmode Return whether the RPLIDAR is working on 4k sample rate mode. virtual u_result getFrequency(bool inExpressMode, size_t count, float & frequency, bool & is4kmode) = 0; //從實現抓取的一圈掃描數據序列計算 RPLIDAR 的轉速 /// Ask the RPLIDAR core system to enter the scan mode(Normal/Express, Express mode is 4k mode) /// A background thread will be created by the RPLIDAR driver to fetch the scan data continuously. /// User Application can use the grabScanData() interface to retrieved the scan data cached previous by this background thread. /// /// \param force Force the core system to output scan data regardless whether the scanning motor is rotating or not. /// /// \param autoExpressMode Force the core system to trying express mode first, if the system does not support express mode, it will use normal mode.
///
/// \param timeout The operation timeout value (in millisecond) for the serial port communication.
//開始掃描，（正常模式，還有一個特別模式2.0能用）
virtual u_result startScan(bool force = false, bool autoExpressMode = true) = 0;
virtual u_result startScanNormal(bool force, _u32 timeout = DEFAULT_TIMEOUT) = 0;
virtual u_result startScanExpress(bool fixedAngle, _u32 timeout = DEFAULT_TIMEOUT) = 0;
/// Check whether the device support express mode.
///
/// \param support Return the result.
///
/// \param timeout The operation timeout value (in millisecond) for the serial port communication.
//檢測是否能用這個模式
virtual u_result checkExpressScanSupported(bool & support, _u32 timeout = DEFAULT_TIMEOUT) = 0;
/// Ask the RPLIDAR core system to stop the current scan operation and enter idle state. The background thread will be terminated
///
/// \param timeout The operation timeout value (in millisecond) for the serial port communication
//停止
virtual u_result stop(_u32 timeout = DEFAULT_TIMEOUT) = 0;
/// Wait and grab a complete 0-360 degree scan data previously received.
/// The grabbed scan data returned by this interface always has the following charactistics:
///
/// 1) The first node of the grabbed data array (nodebuffer[0]) must be the first sample of a scan, i.e. the start_bit == 1
/// 2) All data nodes are belong to exactly ONE complete 360-degrees's scan
/// 3) Note, the angle data in one scan may not be ascending. You can use API ascendScanData to reorder the nodebuffer.
///
/// \param nodebuffer Buffer provided by the caller application to store the scan data
///
/// \param count The caller must initialize this parameter to set the max data count of the provided buffer (in unit of rplidar_response_measurement_node_t).
/// Once the interface returns, this parameter will store the actual received data count.
///
/// \param timeout Max duration allowed to wait for a complete scan data, nothing will be stored to the nodebuffer if a complete 360-degrees' scan data cannot to be ready timely.
///
/// The interface will return RESULT_OPERATION_TIMEOUT to indicate that no complete 360-degrees' scan can be retrieved withing the given timeout duration.
///
/// \The caller application can set the timeout value to Zero(0) to make this interface always returns immediately to achieve non-block operation.
//得到掃描數據
virtual u_result grabScanData(rplidar_response_measurement_node_t * nodebuffer, size_t & count, _u32 timeout = DEFAULT_TIMEOUT) = 0;
/// Ascending the scan data according to the angle value in the scan.
///
/// \param nodebuffer Buffer provided by the caller application to do the reorder. Should be retrived from the grabScanData
///
/// \param count The caller must initialize this parameter to set the max data count of the provided buffer (in unit of rplidar_response_measurement_node_t).
/// Once the interface returns, this parameter will store the actual received data count.
/// The interface will return RESULT_OPERATION_FAIL when all the scan data is invalid.
//根據角度值傳輸掃描數據
virtual u_result ascendScanData(rplidar_response_measurement_node_t * nodebuffer, size_t count) = 0;
protected:
RPlidarDriver() {}
virtual ~RPlidarDriver() {}
};
}}}
\param timeout The operation timeout value (in millisecond) for the serial port communication. virtual u_result startScan(bool force = false, bool autoExpressMode = true) = 0; //請求 RPLIDAR 核心開始進行測距掃描,開始輸出數據 //如 RPLIDAR 支持 ExpressScan 模式,且程序使用默認參數調用 //startScan()時,SDK 將自動使用 ExpressScan 模式 virtual u_result startScanNormal(bool force, _u32 timeout = DEFAULT_TIMEOUT) = 0; //強制以標准 Scan 模式進行測距掃描 virtual u_result startScanExpress(bool fixedAngle, _u32 timeout = DEFAULT_TIMEOUT) = 0; //強制進行高速掃描測距(ExpressScan)模式 //如果 RPLIDAR 固件不支持 ExpressScan 模式,該函數將執行失敗。 /// Check whether the device support express mode. /// /// \param support Return the result. /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication. virtual u_result checkExpressScanSupported(bool & support, _u32 timeout = DEFAULT_TIMEOUT) = 0; //檢查 RPLIDAR 是否支持 ExpressScan 模式 /// Ask the RPLIDAR core system to stop the current scan operation and enter idle state. The background thread will be terminated /// /// \param timeout The operation timeout value (in millisecond) for the serial port communication virtual u_result stop(_u32 timeout = DEFAULT_TIMEOUT) = 0; //請求 RPLIDAR 核心停止測距掃描 /// Wait and grab a complete 0-360 degree scan data previously received. /// The grabbed scan data returned by this interface always has the following charactistics: /// /// 1) The first node of the grabbed data array (nodebuffer[0]) must be the first sample of a scan, i.e. the start_bit == 1 /// 2) All data nodes are belong to exactly ONE complete 360-degrees's scan /// 3) Note, the angle data in one scan may not be ascending. You can use API ascendScanData to reorder the nodebuffer. /// /// \param nodebuffer Buffer provided by the caller application to store the scan data /// /// \param count The caller must initialize this parameter to set the max data count of the provided buffer (in unit of rplidar_response_measurement_node_t). /// Once the interface returns, this parameter will store the actual received data count. /// /// \param timeout Max duration allowed to wait for a complete scan data, nothing will be stored to the nodebuffer if a complete 360-degrees' scan data cannot to be ready timely. /// /// The interface will return RESULT_OPERATION_TIMEOUT to indicate that no complete 360-degrees' scan can be retrieved withing the given timeout duration. /// /// \The caller application can set the timeout value to Zero(0) to make this interface always returns immediately to achieve non-block operation. virtual u_result grabScanData(rplidar_response_measurement_node_t * nodebuffer, size_t & count, _u32 timeout = DEFAULT_TIMEOUT) = 0; //抓取一圈掃描測距數據序列 /// Ascending the scan data according to the angle value in the scan. /// /// \param nodebuffer Buffer provided by the caller application to do the reorder. Should be retrived from the grabScanData /// /// \param count The caller must initialize this parameter to set the max data count of the provided buffer (in unit of rplidar_response_measurement_node_t). /// Once the interface returns, this parameter will store the actual received data count. /// The interface will return RESULT_OPERATION_FAIL when all the scan data is invalid. virtual u_result ascendScanData(rplidar_response_measurement_node_t * nodebuffer, size_t count) = 0; //對通過 grabScanData()獲取的掃描數據按照角度遞增排序。 protected: RPlidarDriver() {} virtual ~RPlidarDriver() {} }; }}}
3、ultra_simlpe