rplidar_driver.h

00001 /*
00002  *  RPLIDAR SDK
00003  *
00004  *  Copyright (c) 2009 - 2014 RoboPeak Team
00005  *  http://www.robopeak.com
00006  *  Copyright (c) 2014 - 2019 Shanghai Slamtec Co., Ltd.
00007  *  http://www.slamtec.com
00008  *
00009  */
00010 /*
00011  * Redistribution and use in source and binary forms, with or without 
00012  * modification, are permitted provided that the following conditions are met:
00013  *
00014  * 1. Redistributions of source code must retain the above copyright notice, 
00015  *    this list of conditions and the following disclaimer.
00016  *
00017  * 2. Redistributions in binary form must reproduce the above copyright notice, 
00018  *    this list of conditions and the following disclaimer in the documentation 
00019  *    and/or other materials provided with the distribution.
00020  *
00021  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
00022  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
00023  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
00024  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
00025  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00026  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
00027  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
00028  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
00029  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
00030  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
00031  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00032  *
00033  */
00034 
00035 #pragma once
00036 #include "mbed.h"
00037 #include "inc/rptypes.h"
00038 #include "inc/rplidar_cmd.h"
00039 #include "inc/rplidar_protocol.h"
00040 #include <vector>
00041 #include "rplidar.h"
00042 
00043 #ifndef DEPRECATED
00044     #ifdef __GNUC__
00045         #define DEPRECATED(func) func __attribute__ ((deprecated))
00046     #elif defined(_MSC_VER)
00047         #define DEPRECATED(func) __declspec(deprecated) func
00048     #else
00049         #pragma message("WARNING: You need to implement DEPRECATED for this compiler")
00050         #define DEPRECATED(func) func
00051     #endif
00052 #endif
00053 
00054 // namespace rp { namespace standalone{ namespace rplidar {
00055 
00056 struct RplidarScanMode {
00057     uint16_t    id;
00058     float   us_per_sample;   // microseconds per sample
00059     float   max_distance;    // max distance
00060     uint8_t     ans_type;         // the answer type of the scam mode, its value should be RPLIDAR_ANS_TYPE_MEASUREMENT*
00061     char    scan_mode[64];    // name of scan mode, max 63 characters
00062 };
00063 
00064 enum {
00065     DRIVER_TYPE_SERIALPORT = 0x0,
00066     DRIVER_TYPE_TCP = 0x1,
00067 };
00068 
00069 class ChannelDevice
00070 {
00071 public:
00072     virtual bool bind(const char*, uint32_t ) = 0;
00073     virtual bool open() {return true;}
00074     virtual void close() = 0;
00075     virtual void flush() {return;}
00076     virtual bool waitfordata(size_t data_count,uint32_t timeout = -1, size_t * returned_size = NULL) = 0;
00077     virtual int senddata(const uint8_t * data, size_t size) = 0;
00078     virtual int recvdata(unsigned char * data, size_t size) = 0;
00079     virtual void setDTR() {return;}
00080     virtual void clearDTR() {return;}
00081     virtual void ReleaseRxTx() {return;}
00082 };
00083 
00084 class RPlidarDriver {
00085 public:
00086     enum {
00087         DEFAULT_TIMEOUT = 2000, //2000 ms
00088     };
00089 
00090     enum {
00091         MAX_SCAN_NODES = 8192,
00092     };
00093 
00094     enum {
00095         LEGACY_SAMPLE_DURATION = 476,
00096     };
00097 
00098 public:
00099     /// Create an RPLIDAR Driver Instance
00100     /// This interface should be invoked first before any other operations
00101     ///
00102     /// \param drivertype the connection type used by the driver. 
00103     static RPlidarDriver * CreateDriver(uint32_t drivertype = DRIVER_TYPE_SERIALPORT);
00104 
00105     /// Dispose the RPLIDAR Driver Instance specified by the drv parameter
00106     /// Applications should invoke this interface when the driver instance is no longer used in order to free memory
00107     static void DisposeDriver(RPlidarDriver * drv);
00108 
00109 
00110     /// Open the specified serial port and connect to a target RPLIDAR device
00111     ///
00112     /// \param port_path     the device path of the serial port 
00113     ///        e.g. on Windows, it may be com3 or \\.\com10 
00114     ///             on Unix-Like OS, it may be /dev/ttyS1, /dev/ttyUSB2, etc
00115     ///
00116     /// \param baudrate      the baudrate used
00117     ///        For most RPLIDAR models, the baudrate should be set to 115200
00118     ///
00119     /// \param flag          other flags
00120     ///        Reserved for future use, always set to Zero
00121     virtual u_result connect(const char *, uint32_t, uint32_t flag = 0) = 0;
00122 
00123 
00124     /// Disconnect with the RPLIDAR and close the serial port
00125     virtual void disconnect() = 0;
00126 
00127     /// Returns TRUE when the connection has been established
00128     virtual bool isConnected() = 0;
00129 
00130     /// Ask the RPLIDAR core system to reset it self
00131     /// The host system can use the Reset operation to help RPLIDAR escape the self-protection mode.
00132     ///
00133     ///  \param timeout       The operation timeout value (in millisecond) for the serial port communication                     
00134     virtual u_result reset(uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00135 
00136     virtual u_result clearNetSerialRxCache() = 0;
00137     // FW1.24
00138     /// Get all scan modes that supported by lidar
00139     virtual u_result getAllSupportedScanModes(std::vector<RplidarScanMode>& outModes, uint32_t timeoutInMs = DEFAULT_TIMEOUT) = 0;
00140 
00141     /// Get typical scan mode of lidar
00142     virtual u_result getTypicalScanMode(uint16_t& outMode, uint32_t timeoutInMs = DEFAULT_TIMEOUT) = 0;
00143 
00144     /// Start scan
00145     ///
00146     /// \param force            Force the core system to output scan data regardless whether the scanning motor is rotating or not.
00147     /// \param useTypicalScan   Use lidar's typical scan mode or use the compatibility mode (2k sps)
00148     /// \param options          Scan options (please use 0)
00149     /// \param outUsedScanMode  The scan mode selected by lidar
00150     virtual u_result startScan(bool force, bool useTypicalScan, uint32_t options = 0, RplidarScanMode* outUsedScanMode = NULL) = 0;
00151 
00152     /// Start scan in specific mode
00153     ///
00154     /// \param force            Force the core system to output scan data regardless whether the scanning motor is rotating or not.
00155     /// \param scanMode         The scan mode id (use getAllSupportedScanModes to get supported modes)
00156     /// \param options          Scan options (please use 0)
00157     /// \param outUsedScanMode  The scan mode selected by lidar
00158     virtual u_result startScanExpress(bool force, uint16_t scanMode, uint32_t options = 0, RplidarScanMode* outUsedScanMode = NULL, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00159 
00160     /// Retrieve the health status of the RPLIDAR
00161     /// The host system can use this operation to check whether RPLIDAR is in the self-protection mode.
00162     ///
00163     /// \param health        The health status info returned from the RPLIDAR
00164     ///
00165     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication     
00166     virtual u_result getHealth(rplidar_response_device_health_t & health, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00167 
00168     /// Get the device information of the RPLIDAR include the serial number, firmware version, device model etc.
00169     /// 
00170     /// \param info          The device information returned from the RPLIDAR
00171     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication  
00172     virtual u_result getDeviceInfo(rplidar_response_device_info_t & info, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00173 
00174     /// Get the sample duration information of the RPLIDAR.
00175     /// DEPRECATED, please use RplidarScanMode::us_per_sample
00176     ///
00177     /// \param rateInfo      The sample duration information returned from the RPLIDAR
00178     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication
00179     DEPRECATED(virtual u_result getSampleDuration_uS(rplidar_response_sample_rate_t & rateInfo, uint32_t timeout = DEFAULT_TIMEOUT)) = 0;
00180     
00181     /// Set the RPLIDAR's motor pwm when using accessory board, currently valid for A2 only.
00182     /// 
00183     /// \param pwm           The motor pwm value would like to set 
00184     virtual u_result setMotorPWM(uint16_t pwm) = 0;
00185 
00186     /// Start RPLIDAR's motor when using accessory board
00187     virtual u_result startMotor() = 0;
00188 
00189     /// Stop RPLIDAR's motor when using accessory board
00190     virtual u_result stopMotor() = 0;
00191 
00192     /// Check whether the device support motor control.
00193     /// Note: this API will disable grab.
00194     /// 
00195     /// \param support       Return the result.
00196     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication. 
00197     virtual u_result checkMotorCtrlSupport(bool & support, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00198 
00199     /// Calculate RPLIDAR's current scanning frequency from the given scan data
00200     /// DEPRECATED, please use getFrequency(RplidarScanMode, size_t)
00201     ///
00202     /// Please refer to the application note doc for details
00203     /// Remark: the calcuation will be incorrect if the specified scan data doesn't contains enough data
00204     ///
00205     /// \param inExpressMode Indicate whether the RPLIDAR is in express mode
00206     /// \param count         The number of sample nodes inside the given buffer
00207     /// \param frequency     The scanning frequency (in HZ) calcuated by the interface.
00208     /// \param is4kmode      Return whether the RPLIDAR is working on 4k sample rate mode.
00209     DEPRECATED(virtual u_result getFrequency(bool inExpressMode, size_t count, float & frequency, bool & is4kmode)) = 0;
00210 
00211     /// Calculate RPLIDAR's current scanning frequency from the given scan data
00212     /// Please refer to the application note doc for details
00213     /// Remark: the calcuation will be incorrect if the specified scan data doesn't contains enough data
00214     ///
00215     /// \param scanMode      Lidar's current scan mode
00216     /// \param count         The number of sample nodes inside the given buffer
00217     virtual u_result getFrequency(const RplidarScanMode& scanMode, size_t count, float & frequency) = 0;
00218 
00219     /// Ask the RPLIDAR core system to enter the scan mode(Normal/Express, Express mode is 4k mode)
00220     /// A background thread will be created by the RPLIDAR driver to fetch the scan data continuously.
00221     /// User Application can use the grabScanData() interface to retrieved the scan data cached previous by this background thread.
00222     ///
00223     /// \param force         Force the core system to output scan data regardless whether the scanning motor is rotating or not.
00224     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication.
00225     virtual u_result startScanNormal(bool force, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00226     
00227     /// Check whether the device support express mode.
00228     /// DEPRECATED, please use getAllSupportedScanModes
00229     ///
00230     /// \param support       Return the result.
00231     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication.
00232     DEPRECATED(virtual u_result checkExpressScanSupported(bool & support, uint32_t timeout = DEFAULT_TIMEOUT)) = 0;
00233 
00234     /// Ask the RPLIDAR core system to stop the current scan operation and enter idle state. The background thread will be terminated
00235     ///
00236     /// \param timeout       The operation timeout value (in millisecond) for the serial port communication 
00237     virtual u_result stop(uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00238 
00239 
00240     /// Wait and grab a complete 0-360 degree scan data previously received. 
00241     /// NOTE: This method only support distance less than 16.38 meters, for longer distance, please use grabScanDataHq
00242     /// The grabbed scan data returned by this interface always has the following charactistics:
00243     ///
00244     /// 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
00245     /// 2) All data nodes are belong to exactly ONE complete 360-degrees's scan
00246     /// 3) Note, the angle data in one scan may not be ascending. You can use API ascendScanData to reorder the nodebuffer.
00247     ///
00248     /// \param nodebuffer     Buffer provided by the caller application to store the scan data
00249     ///
00250     /// \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).
00251     ///                       Once the interface returns, this parameter will store the actual received data count.
00252     ///
00253     /// \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.
00254     ///
00255     /// The interface will return RESULT_OPERATION_TIMEOUT to indicate that no complete 360-degrees' scan can be retrieved withing the given timeout duration. 
00256     ///
00257     /// \The caller application can set the timeout value to Zero(0) to make this interface always returns immediately to achieve non-block operation.
00258     DEPRECATED(virtual u_result grabScanData(rplidar_response_measurement_node_t * nodebuffer, size_t & count, uint32_t timeout = DEFAULT_TIMEOUT)) = 0;
00259 
00260     /// Wait and grab a complete 0-360 degree scan data previously received. 
00261     /// The grabbed scan data returned by this interface always has the following charactistics:
00262     ///
00263     /// 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
00264     /// 2) All data nodes are belong to exactly ONE complete 360-degrees's scan
00265     /// 3) Note, the angle data in one scan may not be ascending. You can use API ascendScanData to reorder the nodebuffer.
00266     ///
00267     /// \param nodebuffer     Buffer provided by the caller application to store the scan data
00268     ///
00269     /// \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).
00270     ///                       Once the interface returns, this parameter will store the actual received data count.
00271     ///
00272     /// \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.
00273     ///
00274     /// The interface will return RESULT_OPERATION_TIMEOUT to indicate that no complete 360-degrees' scan can be retrieved withing the given timeout duration. 
00275     ///
00276     /// \The caller application can set the timeout value to Zero(0) to make this interface always returns immediately to achieve non-block operation.
00277     virtual u_result grabScanDataHq(rplidar_response_measurement_node_hq_t * nodebuffer, size_t & count, uint32_t timeout = DEFAULT_TIMEOUT) = 0;
00278 
00279     /// Ascending the scan data according to the angle value in the scan.
00280     ///
00281     /// \param nodebuffer     Buffer provided by the caller application to do the reorder. Should be retrived from the grabScanData
00282     ///
00283     /// \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).
00284     ///                       Once the interface returns, this parameter will store the actual received data count.
00285     /// The interface will return RESULT_OPERATION_FAIL when all the scan data is invalid. 
00286     DEPRECATED(virtual u_result ascendScanData(rplidar_response_measurement_node_t * nodebuffer, size_t count)) = 0;
00287 
00288     /// Ascending the scan data according to the angle value in the scan.
00289     ///
00290     /// \param nodebuffer     Buffer provided by the caller application to do the reorder. Should be retrived from the grabScanData
00291     ///
00292     /// \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).
00293     ///                       Once the interface returns, this parameter will store the actual received data count.
00294     /// The interface will return RESULT_OPERATION_FAIL when all the scan data is invalid. 
00295     virtual u_result ascendScanData(rplidar_response_measurement_node_hq_t * nodebuffer, size_t count) = 0;
00296 
00297     /// Return received scan points even if it's not complete scan
00298     ///
00299     /// \param nodebuffer     Buffer provided by the caller application to store the scan data
00300     ///
00301     /// \param count          Once the interface returns, this parameter will store the actual received data count.
00302     ///
00303     /// The interface will return RESULT_OPERATION_TIMEOUT to indicate that not even a single node can be retrieved since last call. 
00304     DEPRECATED(virtual u_result getScanDataWithInterval(rplidar_response_measurement_node_t * nodebuffer, size_t & count)) = 0;
00305 
00306     /// Return received scan points even if it's not complete scan
00307     ///
00308     /// \param nodebuffer     Buffer provided by the caller application to store the scan data
00309     ///
00310     /// \param count          Once the interface returns, this parameter will store the actual received data count.
00311     ///
00312     /// The interface will return RESULT_OPERATION_TIMEOUT to indicate that not even a single node can be retrieved since last call. 
00313     virtual u_result getScanDataWithIntervalHq(rplidar_response_measurement_node_hq_t * nodebuffer, size_t & count) = 0;
00314 
00315     virtual ~RPlidarDriver() {}
00316 protected:
00317     RPlidarDriver(){}
00318 
00319 public:
00320     ChannelDevice* _chanDev;
00321 };
00322 
00323 
00324 
00325 
00326 // }}}
00327