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 recomended 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:
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