Detailed Description

A communications serial port built as an implementation of a utils::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.

Todo:: Add the internal buffer to the Windows implementation also

Definition at line 65 of file CSerialPort.h.

#include <mrpt/hwdrivers/CSerialPort.h>

Inheritance diagram for mrpt::hwdrivers::CSerialPort:

[legend]

List of all members.

Public Member Functions
	CSerialPort (const std::string &portName, bool openNow=true)
	Constructor.
	CSerialPort ()
	Default constructor: it does not open any port - later you must call "setSerialPortName" and then "open".
virtual	~CSerialPort ()
	Destructor.
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).
void	open ()
	Open the port.
void	open (const std::string &COM_name)
	Open the given serial port.
void	close ()
	Close the port.
bool	isOpen ()
	Returns if port has been correctly open.
void	purgeBuffers ()
	Purge tx and rx buffers.
void	setConfig (int baudRate, int parity=0, int bits=8, int nStopBits=1, bool enableFlowControl=false)
	Changes the configuration of the port.
void	setTimeouts (int ReadIntervalTimeout, int ReadTotalTimeoutMultiplier, int ReadTotalTimeoutConstant, int WriteTotalTimeoutMultiplier, int WriteTotalTimeoutConstant)
	Changes the timeouts of the port, in milliseconds.
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.
std::string	ReadString (const int total_timeout_ms=-1, bool out_timeout=NULL, const char eol_chars="\r\n")
	Reads one text line from the serial port in POSIX "canonical mode".
size_t	Write (const void *Buffer, size_t Count)
	Implements the virtual method responsible for writing to the stream.
uint64_t	Seek (long Offset, CStream::TSeekOrigin Origin=sFromBeginning)
	Introduces a pure virtual method for moving to a specified position in the streamed resource.
uint64_t	getTotalBytesCount ()
	Returns the total amount of bytes in the stream.
uint64_t	getPosition ()
	Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
Protected Attributes
std::string	m_serialName
	The complete name of the serial port device (i.e.
int	m_baudRate
int	m_totalTimeout_ms
int	m_interBytesTimeout_ms
CTicTac	m_timer
	Used only in ReadString.
int	hCOM
	The file handle (-1: Not open)
Friends
class	PosixSignalDispatcherImpl

Constructor & Destructor Documentation

mrpt::hwdrivers::CSerialPort::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()".

mrpt::hwdrivers::CSerialPort::CSerialPort ( )

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

virtual mrpt::hwdrivers::CSerialPort::~CSerialPort ( ) [virtual]

Destructor.

Member Function Documentation

void mrpt::hwdrivers::CSerialPort::close ( )

Close the port.

If is already closed, results in no action.

uint64_t mrpt::hwdrivers::CSerialPort::getPosition ( ) [inline, virtual]

Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.

Implements mrpt::utils::CStream.

Definition at line 200 of file CSerialPort.h.

References MRPT_END, MRPT_START, and THROW_EXCEPTION.

uint64_t mrpt::hwdrivers::CSerialPort::getTotalBytesCount ( ) [inline, virtual]

Returns the total amount of bytes in the stream.

Implements mrpt::utils::CStream.

Definition at line 191 of file CSerialPort.h.

References MRPT_END, MRPT_START, and THROW_EXCEPTION.

bool mrpt::hwdrivers::CSerialPort::isOpen ( )

Returns if port has been correctly open.

void mrpt::hwdrivers::CSerialPort::open ( )

Open the port.

If is already open results in no action.

Exceptions:

std::exception On communication errors

void mrpt::hwdrivers::CSerialPort::open ( const std::string & COM_name ) [inline]

Open the given serial port.

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

Exceptions:

std::exception On communication errors or a different serial port already open.

Definition at line 101 of file CSerialPort.h.

References THROW_EXCEPTION.

void mrpt::hwdrivers::CSerialPort::purgeBuffers ( )

Purge tx and rx buffers.

Exceptions:

std::exception On communication errors

size_t mrpt::hwdrivers::CSerialPort::Read	(	void *	Buffer,
		size_t	Count
	)		`[virtual]`

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.

Exceptions:

std::exception On communication errors

Implements mrpt::utils::CStream.

std::string mrpt::hwdrivers::CSerialPort::ReadString	(	const int	total_timeout_ms = `-1`,
		bool *	out_timeout = `NULL`,
		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.

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.

Returns:: The read string, without the final

Exceptions:

std::exception On communication errors

uint64_t mrpt::hwdrivers::CSerialPort::Seek	(	long	Offset,
		CStream::TSeekOrigin	Origin = `sFromBeginning`
	)		`[inline, virtual]`

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.

Implements mrpt::utils::CStream.

Definition at line 180 of file CSerialPort.h.

References MRPT_END, MRPT_START, MRPT_UNUSED_PARAM, and THROW_EXCEPTION.

void mrpt::hwdrivers::CSerialPort::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)

Exceptions:

std::exception On communication errors

void mrpt::hwdrivers::CSerialPort::setSerialPortName ( const std::string & COM_name ) [inline]

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

See also:: open, close

Definition at line 87 of file CSerialPort.h.

References THROW_EXCEPTION.

void mrpt::hwdrivers::CSerialPort::setTimeouts	(	int	ReadIntervalTimeout,
		int	ReadTotalTimeoutMultiplier,
		int	ReadTotalTimeoutConstant,
		int	WriteTotalTimeoutMultiplier,
		int	WriteTotalTimeoutConstant
	)