class mrpt::hwdrivers::CBoardSonars

Overview

This “software driver” implements the communication protocol for interfacing a Ultrasonic range finder SRF10 through a custom USB board.

In this class the “bind” is ignored since it is designed for USB connections only, thus it internally generate the required object for simplicity of use. The serial number of the USB device is used to open it on the first call to “doProcess”, thus you must call “loadConfig” before this, or manually call “setDeviceSerialNumber”. The default serial number is “SONAR001”

Warning: Avoid defining an object of this class in a global scope if you want to catch all potential exceptions during the constructors (like USB interface DLL not found, etc…)

 PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
-------------------------------------------------------
  [supplied_section_name]
  USB_serialNumber=SONAR001
  gain=6            ; Value between 0 and 16, for analog gains between 40
and 700.
  maxRange=4.0      ; In meters, used for device internal timer.
  minTimeBetweenPings=0.3  ; In seconds

  ; The order in which sonars will be fired, indexed by their I2C addresses
[0,15]
  ;  Up to 16 devices, but you can put any number of devices (from 1 to 16).
  firingOrder=0 1 2 3

#include <mrpt/hwdrivers/CBoardSonars.h>

class CBoardSonars:
    public mrpt::comms::CInterfaceFTDI,
    public mrpt::hwdrivers::CGenericSensor
{
public:
    // enums

    enum TSeekOrigin;

    // construction

    CBoardSonars();

    // methods

    bool queryFirmwareVersion(std::string& out_firmwareVersion);
    bool getObservation(mrpt::obs::CObservationRange& obs);
    bool programI2CAddress(uint8_t currentAddress, uint8_t newAddress);
    virtual void doProcess();
    bool isOpen();
    void OpenBySerialNumber(const std::string& serialNumber);
    void OpenByDescription(const std::string& description);
    void Close();
    void ResetDevice();
    void Purge();
    void SetLatencyTimer(unsigned char latency_ms);
    void SetTimeouts(unsigned long dwReadTimeout_ms, unsigned long dwWriteTimeout_ms);
    void ListAllDevices(TFTDIDeviceList& outList);
    size_t ReadSync(void* Buffer, size_t Count);
    size_t WriteSync(const void* Buffer, size_t Count);
    virtual size_t ReadBufferImmediate(void* Buffer, size_t Count);
    virtual size_t Read(void* Buffer, size_t Count);
    virtual size_t Write(const void* Buffer, size_t Count);
    uint64_t Seek(int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning);
    virtual uint64_t Seek(int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning) = 0;
    virtual uint64_t getTotalBytesCount() const;
    virtual uint64_t getPosition() const;
    virtual int printf(const char* fmt, ...);

    template <typename CONTAINER_TYPE>
    int void printf_vector(
        const char* fmt,
        const CONTAINER_TYPE& V,
        char separator = ','
        );

    bool getline(std::string& out_str);
    virtual std::string getStreamDescription() const;
};

Inherited Members

public:
    // methods

    virtual size_t Read(void* Buffer, size_t Count) = 0;
    virtual size_t Write(const void* Buffer, size_t Count) = 0;
    virtual uint64_t getTotalBytesCount() const = 0;
    virtual uint64_t getPosition() const = 0;
    CInterfaceFTDI& operator = (const CInterfaceFTDI& o);
    CGenericSensor& operator = (const CGenericSensor&);
    virtual void doProcess() = 0;

Construction

CBoardSonars()

Constructor.

Methods

bool queryFirmwareVersion(std::string& out_firmwareVersion)

Query the firmware version on the device (can be used to test communications).

Returns:

true on success, false on communications errors or device not found.

bool getObservation(mrpt::obs::CObservationRange& obs)

Request the latest range measurements.

Returns:

true on success, false on communications errors or device not found.

bool programI2CAddress(uint8_t currentAddress, uint8_t newAddress)

Requests a command of “change address” for a given SRF10 device.

currentAddress and newAddress are the I2C addresses in the range 0 to 15 (mapped to 0xE0 to 0xFE internally).

Returns:

true on success, false on communications errors or device not found.

virtual void doProcess()

This method will be invoked at a minimum rate of “process_rate” (Hz)

Parameters:

This	method must throw an exception with a descriptive message if some critical error is found.

bool isOpen()

Checks whether the chip has been successfully open.

See also:

OpenBySerialNumber, OpenByDescription

void OpenBySerialNumber(const std::string& serialNumber)

Open by device serial number.

void OpenByDescription(const std::string& description)

Open by device description.

void Close()

Close the USB device.

void ResetDevice()

Reset the USB device.

void Purge()

Purge the I/O buffers.

void SetLatencyTimer(unsigned char latency_ms)

Change the latency timer (in milliseconds) implemented on the FTDI chip: for a few ms, data is not sent to the PC waiting for possible more data, to save USB trafic.

void SetTimeouts(
    unsigned long dwReadTimeout_ms,
    unsigned long dwWriteTimeout_ms
    )

Change read & write timeouts, in milliseconds.

void ListAllDevices(TFTDIDeviceList& outList)

Generates a list with all FTDI devices connected right now.

size_t ReadSync(void* Buffer, size_t Count)

Tries to read, raising no exception if not all the bytes are available, but raising one if there is some communication error.

size_t WriteSync(const void* Buffer, size_t Count)

Tries to write, raising no exception if not all the bytes are available, but raising one if there is some communication error.

virtual size_t ReadBufferImmediate(void* Buffer, size_t Count)

Reads a block of bytes from the stream into Buffer, and returns the amound of bytes actually read, without waiting for more extra bytes to arrive (just those already enqued in the stream).

In this class this method actually behaves as expected and does not fallback to ReadBuffer().

Parameters:

std::exception

On any error, or if ZERO bytes are read.

virtual size_t Read(void* Buffer, size_t Count)

Introduces a pure virtual method responsible for reading from the stream.

It integrates a cache buffer to speed-up sequences of many, small readings.

virtual size_t Write(const void* Buffer, size_t Count)

Introduces a pure virtual method responsible for writing to the stream.

Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.

uint64_t Seek(int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning)

This virtual method does nothing in this class.

virtual uint64_t Seek(int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning) = 0

Introduces a pure virtual method for moving to a specified position in the streamed resource.

he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

sFromBeginning (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
sFromCurrent Offset is from the current position in the resource. Seek moves to Position + Offset.
sFromEnd Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Returns:

Seek returns the new value of the Position property.

virtual uint64_t getTotalBytesCount() const

This virtual method does nothing in this class.

virtual uint64_t getPosition() const

This virtual method does nothing in this class.

virtual int printf(const char* fmt, ...)

Writes a string to the stream in a textual form.