class mrpt::comms::CSerialPort

Overview

A communications serial port implementing the interface mrpt::io::CStream.

On communication errors (eg. the given port number does not exist, timeouts,…), most of the methods will raise an exception of the class std::exception

The serial port to open is passed in the constructor in the form of a string description, which is platform dependent.

In Windows they are numbered “COM1”-“COM4” and “\.COMXXX” for numbers above. It is recommended to always use the prefix “\." despite the actual port number.

In Linux the name must refer to the device, for example: “ttyUSB0”,”ttyS0”. If the name string does not start with “/” (an absolute path), the constructor will assume the prefix “/dev/”.

History:

1/DEC/2005: (JLBC) First version
20/DEC/2006: (JLBC) Integration into the MRPT framework
12/DEC/2007: (JLBC) Added support for Linux.
22/AUG/2017: (JLBC) Moved to new module mrpt-comms

Todo Add the internal buffer to the Windows implementation also

#include <mrpt/comms/CSerialPort.h>

class CSerialPort: public mrpt::io::CStream
{
public:
    // construction

    CSerialPort(const std::string& portName, bool openNow = true);
    CSerialPort();

    // methods

    void setSerialPortName(const std::string& COM_name);
    void open();
    void open(const std::string& COM_name);
    void close();
    bool isOpen() const;
    void purgeBuffers();

    void setConfig(
        int baudRate,
        int parity = 0,
        int bits = 8,
        int nStopBits = 1,
        bool enableFlowControl = false
        );

    void setTimeouts(
        int ReadIntervalTimeout,
        int ReadTotalTimeoutMultiplier,
        int ReadTotalTimeoutConstant,
        int WriteTotalTimeoutMultiplier,
        int WriteTotalTimeoutConstant
        );

    virtual size_t Read(void* Buffer, size_t Count);

    std::string ReadString(
        const int total_timeout_ms = -1,
        bool* out_timeout = nullptr,
        const char* eol_chars = "\r\n"
        );

    virtual size_t Write(const void* Buffer, size_t Count);
    uint64_t Seek(int64_t off, CStream::TSeekOrigin o = sFromBeginning);
    virtual uint64_t getTotalBytesCount() const;
    virtual uint64_t getPosition() 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;

Construction

CSerialPort(const std::string& portName, bool openNow = true)

Constructor.

Parameters:

portName	The serial port to open. See comments at the begining of this page.
openNow	Whether to try to open the port now. If not selected, the port should be open later with “open()”.

CSerialPort()

Default constructor: it does not open any port - later you must call “setSerialPortName” and then “open”.

Methods

void setSerialPortName(const std::string& COM_name)

Sets the serial port to open (it is an error to try to change this while open yet).

See also:

open, close

void open()

Open the port.

If is already open results in no action.

Parameters:

std::exception

On communication errors

void open(const std::string& COM_name)

Open the given serial port.

If it is already open and the name does not match, an exception is raised.

Parameters:

std::exception

On communication errors or a different serial port already open.

void close()

Close the port.

If is already closed, results in no action.

bool isOpen() const

Returns if port has been correctly open.

void purgeBuffers()

Purge tx and rx buffers.

Parameters:

std::exception

On communication errors

void setConfig(
    int baudRate,
    int parity = 0,
    int bits = 8,
    int nStopBits = 1,
    bool enableFlowControl = false
    )

Changes the configuration of the port.

Parameters:

parity	0:No parity, 1:Odd, 2:Even (WINDOWS ONLY: 3:Mark, 4:Space)
baudRate	The desired baud rate Accepted values: 50 - 230400
bits	Bits per word (typ. 8) Accepted values: 5,6,7,8.
nStopBits	Stop bits (typ. 1) Accepted values: 1,2
enableFlowControl	Whether to enable the hardware flow control (RTS/CTS) (default=no)
std::exception	On communication errors

void setTimeouts(
    int ReadIntervalTimeout,
    int ReadTotalTimeoutMultiplier,
    int ReadTotalTimeoutConstant,
    int WriteTotalTimeoutMultiplier,
    int WriteTotalTimeoutConstant
    )

Changes the timeouts of the port, in milliseconds.

Parameters:

std::exception

On communication errors

virtual size_t Read(void* Buffer, size_t Count)

Implements the virtual method responsible for reading from the stream - Unlike CStream::ReadBuffer, this method will not raise an exception on zero bytes read, as long as there is not any fatal error in the communications.

Parameters:

std::exception

On communication errors

std::string ReadString(
    const int total_timeout_ms = -1,
    bool* out_timeout = nullptr,
    const char* eol_chars = "\r\n"
    )

Reads one text line from the serial port in POSIX “canonical mode”.

This method reads from the serial port until one of the characters in eol are found. This method reads from the serial port until one of the characters in eol are found.

Parameters:

eol_chars	A line reception is finished when one of these characters is found. Default: LF (10), CR (13).
total_timeout_ms	If >0, the maximum number of milliseconds to wait.
out_timeout	If provided, will hold true on return if a timeout ocurred, false on a valid read.
std::exception	On communication errors

Returns:

The read string, without the final

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 off, CStream::TSeekOrigin o = sFromBeginning)

not applicable in a serial port

virtual uint64_t getTotalBytesCount() const

not applicable in a serial port

virtual uint64_t getPosition() const

not applicable in a serial port