serial::Serial Class Reference

#include <serial.h>

Data Structures
class	ScopedReadLock
class	ScopedWriteLock

Public Member Functions
	Serial (const std::string &port="", uint32_t baudrate=9600, Timeout timeout=Timeout(), bytesize_t bytesize=eightbits, parity_t parity=parity_none, stopbits_t stopbits=stopbits_one, flowcontrol_t flowcontrol=flowcontrol_none)
virtual	~Serial ()
void	open ()
bool	isOpen () const
void	close ()
size_t	available ()
bool	waitReadable ()
void	waitByteTimes (size_t count)
size_t	read (uint8_t *buffer, size_t size)
size_t	read (std::vector< uint8_t > &buffer, size_t size=1)
size_t	read (std::string &buffer, size_t size=1)
std::string	read (size_t size=1)
size_t	readline (std::string &buffer, size_t size=65536, std::string eol="\n")
std::string	readline (size_t size=65536, std::string eol="\n")
std::vector< std::string >	readlines (size_t size=65536, std::string eol="\n")
size_t	write (const uint8_t *data, size_t size)
size_t	write (const std::vector< uint8_t > &data)
size_t	write (const std::string &data)
void	setPort (const std::string &port)
std::string	getPort () const
void	setTimeout (Timeout &timeout)
void	setTimeout (uint32_t inter_byte_timeout, uint32_t read_timeout_constant, uint32_t read_timeout_multiplier, uint32_t write_timeout_constant, uint32_t write_timeout_multiplier)
Timeout	getTimeout () const
void	setBaudrate (uint32_t baudrate)
uint32_t	getBaudrate () const
void	setBytesize (bytesize_t bytesize)
bytesize_t	getBytesize () const
void	setParity (parity_t parity)
parity_t	getParity () const
void	setStopbits (stopbits_t stopbits)
stopbits_t	getStopbits () const
void	setFlowcontrol (flowcontrol_t flowcontrol)
flowcontrol_t	getFlowcontrol () const
void	flush ()
void	flushInput ()
void	flushOutput ()
void	sendBreak (int duration)
void	setBreak (bool level=true)
void	setRTS (bool level=true)
void	setDTR (bool level=true)
bool	waitForChange ()
bool	getCTS ()
bool	getDSR ()
bool	getRI ()
bool	getCD ()

Detailed Description

Class that provides a portable serial port interface.

Constructor & Destructor Documentation

serial::Serial::Serial	(	const std::string &	port = "",
		uint32_t	baudrate = 9600,
		Timeout	timeout = Timeout(),
		bytesize_t	bytesize = eightbits,
		parity_t	parity = parity_none,
		stopbits_t	stopbits = stopbits_one,
		flowcontrol_t	flowcontrol = flowcontrol_none
	)

Creates a Serial object and opens the port if a port is specified, otherwise it remains closed until serial::Serial::open is called.

Parameters

port	A std::string containing the address of the serial port, which would be something like 'COM1' on Windows and '/dev/ttyS0' on Linux.
baudrate	An unsigned 32-bit integer that represents the baudrate
timeout	A serial::Timeout struct that defines the timeout conditions for the serial port.

See also

serial::Timeout

Parameters

bytesize	Size of each byte in the serial transmission of data, default is eightbits, possible values are: fivebits, sixbits, sevenbits, eightbits
parity	Method of parity, default is parity_none, possible values are: parity_none, parity_odd, parity_even
stopbits	Number of stop bits used, default is stopbits_one, possible values are: stopbits_one, stopbits_one_point_five, stopbits_two
flowcontrol	Type of flowcontrol used, default is flowcontrol_none, possible values are: flowcontrol_none, flowcontrol_software, flowcontrol_hardware

Exceptions

serial::PortNotOpenedException
serial::IOException
std::invalid_argument

Serial::~Serial ( )

virtual

Destructor

{
  delete pimpl_;
}

Member Function Documentation

size_t Serial::available

(

)

Return the number of characters in the buffer.

{
  return pimpl_->available ();
}

void Serial::close

(

)

Closes the serial port.

{
  pimpl_->close ();
}

void Serial::flush

(

)

Flush the input and output buffers

{
  ScopedReadLock rlock(this->pimpl_);
  ScopedWriteLock wlock(this->pimpl_);
  pimpl_->flush ();
}

void Serial::flushInput

(

)

Flush only the input buffer

{
  ScopedReadLock lock(this->pimpl_);
  pimpl_->flushInput ();
}

void Serial::flushOutput

(

)

Flush only the output buffer

{
  ScopedWriteLock lock(this->pimpl_);
  pimpl_->flushOutput ();
}

uint32_t Serial::getBaudrate

(

)

const

Gets the baudrate for the serial port.

Returns

An integer that sets the baud rate for the serial port.

See also

Serial::setBaudrate

Exceptions

std::invalid_argument

{
  return uint32_t(pimpl_->getBaudrate ());
}

bytesize_t Serial::getBytesize

(

)

const

Gets the bytesize for the serial port.

See also

Serial::setBytesize

Exceptions

std::invalid_argument

{
  return pimpl_->getBytesize ();
}

bool Serial::getCD

(

)

Returns the current status of the CD line.

{
  return pimpl_->getCD ();
}

bool Serial::getCTS

(

)

Returns the current status of the CTS line.

{
  return pimpl_->getCTS ();
}

bool Serial::getDSR

(

)

Returns the current status of the DSR line.

{
  return pimpl_->getDSR ();
}

flowcontrol_t Serial::getFlowcontrol

(

)

const

Gets the flow control for the serial port.

See also

Serial::setFlowcontrol

Exceptions

std::invalid_argument

{
  return pimpl_->getFlowcontrol ();
}

parity_t Serial::getParity

(

)

const

Gets the parity for the serial port.

See also

Serial::setParity

Exceptions

std::invalid_argument

{
  return pimpl_->getParity ();
}

string Serial::getPort

(

)

const

Gets the serial port identifier.

See also

Serial::setPort

Exceptions

std::invalid_argument

{
  return pimpl_->getPort ();
}

bool Serial::getRI

(

)

Returns the current status of the RI line.

{
  return pimpl_->getRI ();
}

stopbits_t Serial::getStopbits

(

)

const

Gets the stopbits for the serial port.

See also

Serial::setStopbits

Exceptions

std::invalid_argument

{
  return pimpl_->getStopbits ();
}

serial::Timeout Serial::getTimeout

(

)

const

Gets the timeout for reads in seconds.

Returns

A Timeout struct containing the inter_byte_timeout, and read and write timeout constants and multipliers.

See also

Serial::setTimeout

                          {
  return pimpl_->getTimeout ();
}

bool Serial::isOpen

(

)

const

Gets the open status of the serial port.

Returns

Returns true if the port is open, false otherwise.

{
  return pimpl_->isOpen ();
}

void Serial::open

(

)

Opens the serial port as long as the port is set and the port isn't already open.

If the port is provided to the constructor then an explicit call to open is not needed.

See also

Serial::Serial

Exceptions

std::invalid_argument
serial::SerialException
serial::IOException

{
  pimpl_->open ();
}

size_t Serial::read	(	uint8_t *	buffer,
		size_t	size
	)

Read a given amount of bytes from the serial port into a given buffer.

The read function will return in one of three cases:

• The number of requested bytes was read.
  • In this case the number of bytes requested will match the size_t returned by read.
• A timeout occurred, in this case the number of bytes read will not match the amount requested, but no exception will be thrown. One of two possible timeouts occurred:
  • The inter byte timeout expired, this means that number of milliseconds elapsed between receiving bytes from the serial port exceeded the inter byte timeout.
  • The total timeout expired, which is calculated by multiplying the read timeout multiplier by the number of requested bytes and then added to the read timeout constant. If that total number of milliseconds elapses after the initial call to read a timeout will occur.
• An exception occurred, in this case an actual exception will be thrown.

Parameters

buffer	An uint8_t array of at least the requested size.
size	A size_t defining how many bytes to be read.

Returns

A size_t representing the number of bytes read as a result of the call to read.

Exceptions

serial::PortNotOpenedException
serial::SerialException

{
  ScopedReadLock lock(this->pimpl_);
  return this->pimpl_->read (buffer, size);
}

size_t Serial::read	(	std::vector< uint8_t > &	buffer,
		size_t	size = 1
	)

Read a given amount of bytes from the serial port into a give buffer.

Parameters

buffer	A reference to a std::vector of uint8_t.
size	A size_t defining how many bytes to be read.

Returns

A size_t representing the number of bytes read as a result of the call to read.

Exceptions

serial::PortNotOpenedException
serial::SerialException

{
  ScopedReadLock lock(this->pimpl_);
  uint8_t *buffer_ = new uint8_t[size];
  size_t bytes_read = this->pimpl_->read (buffer_, size);
  buffer.insert (buffer.end (), buffer_, buffer_+bytes_read);
  delete[] buffer_;
  return bytes_read;
}

size_t Serial::read	(	std::string &	buffer,
		size_t	size = 1
	)

Read a given amount of bytes from the serial port into a give buffer.

Parameters

buffer	A reference to a std::string.
size	A size_t defining how many bytes to be read.

Returns

A size_t representing the number of bytes read as a result of the call to read.

Exceptions

serial::PortNotOpenedException
serial::SerialException

{
  ScopedReadLock lock(this->pimpl_);
  uint8_t *buffer_ = new uint8_t[size];
  size_t bytes_read = this->pimpl_->read (buffer_, size);
  buffer.append (reinterpret_cast<const char*>(buffer_), bytes_read);
  delete[] buffer_;
  return bytes_read;
}

string Serial::read

(

size_t

size = 1

)

Read a given amount of bytes from the serial port and return a string containing the data.

Parameters

size	A size_t defining how many bytes to be read.

Returns

A std::string containing the data read from the port.

Exceptions

serial::PortNotOpenedException
serial::SerialException

{
  std::string buffer;
  this->read (buffer, size);
  return buffer;
}

size_t serial::Serial::readline	(	std::string &	buffer,
		size_t	size = 65536,
		std::string	eol = "\n"
	)

Reads in a line or until a given delimiter has been processed.

Reads from the serial port until a single line has been read.

Parameters

buffer	A std::string reference used to store the data.
size	A maximum length of a line, defaults to 65536 (2^16)
eol	A string to match against for the EOL.

Returns

A size_t representing the number of bytes read.

Exceptions

serial::PortNotOpenedException
serial::SerialException

std::string serial::Serial::readline	(	size_t	size = 65536,
		std::string	eol = "\n"
	)

Reads in a line or until a given delimiter has been processed.

Reads from the serial port until a single line has been read.

Parameters

size	A maximum length of a line, defaults to 65536 (2^16)
eol	A string to match against for the EOL.

Returns

A std::string containing the line.

Exceptions

serial::PortNotOpenedException
serial::SerialException

vector< string > Serial::readlines	(	size_t	size = 65536,
		std::string	eol = "\n"
	)

Reads in multiple lines until the serial port times out.

This requires a timeout > 0 before it can be run. It will read until a timeout occurs and return a list of strings.

Parameters

size	A maximum length of combined lines, defaults to 65536 (2^16)
eol	A string to match against for the EOL.

Returns

A vector<string> containing the lines.

Exceptions

serial::PortNotOpenedException
serial::SerialException

{
  ScopedReadLock lock(this->pimpl_);
  std::vector<std::string> lines;
  size_t eol_len = eol.length ();
  uint8_t *buffer_ = static_cast<uint8_t*>
    (alloca (size * sizeof (uint8_t)));
  size_t read_so_far = 0;
  size_t start_of_line = 0;
  while (read_so_far < size) {
    size_t bytes_read = this->read_ (buffer_+read_so_far, 1);
    read_so_far += bytes_read;
    if (bytes_read == 0) {
      if (start_of_line != read_so_far) {
        lines.push_back (
          string (reinterpret_cast<const char*> (buffer_ + start_of_line),
            read_so_far - start_of_line));
      }
      break; // Timeout occured on reading 1 byte
    }
    if (string (reinterpret_cast<const char*>
         (buffer_ + read_so_far - eol_len), eol_len) == eol) {
      // EOL found
      lines.push_back(
        string(reinterpret_cast<const char*> (buffer_ + start_of_line),
          read_so_far - start_of_line));
      start_of_line = read_so_far;
    }
    if (read_so_far == size) {
      if (start_of_line != read_so_far) {
        lines.push_back(
          string(reinterpret_cast<const char*> (buffer_ + start_of_line),
            read_so_far - start_of_line));
      }
      break; // Reached the maximum read length
    }
  }
  return lines;
}

void Serial::sendBreak

(

int

duration

)

Sends the RS-232 break signal. See tcsendbreak(3).

{
  pimpl_->sendBreak (duration);
}

void Serial::setBaudrate

(

uint32_t

baudrate

)

Sets the baudrate for the serial port.

Possible baudrates depends on the system but some safe baudrates include: 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200 Some other baudrates that are supported by some comports: 128000, 153600, 230400, 256000, 460800, 921600

Parameters

baudrate

An integer that sets the baud rate for the serial port.

Exceptions

std::invalid_argument

{
  pimpl_->setBaudrate (baudrate);
}

void Serial::setBreak

(

bool

level = true

)

Set the break condition to a given level. Defaults to true.

{
  pimpl_->setBreak (level);
}

void Serial::setBytesize

(

bytesize_t

bytesize

)

Sets the bytesize for the serial port.

Parameters

bytesize

Size of each byte in the serial transmission of data, default is eightbits, possible values are: fivebits, sixbits, sevenbits, eightbits

Exceptions

std::invalid_argument

{
  pimpl_->setBytesize (bytesize);
}

void Serial::setDTR

(

bool

level = true

)

Set the DTR handshaking line to the given level. Defaults to true.

{
  pimpl_->setDTR (level);
}

void Serial::setFlowcontrol

(

flowcontrol_t

flowcontrol

)

Sets the flow control for the serial port.

Parameters

flowcontrol

Type of flowcontrol used, default is flowcontrol_none, possible values are: flowcontrol_none, flowcontrol_software, flowcontrol_hardware

Exceptions

std::invalid_argument

{
  pimpl_->setFlowcontrol (flowcontrol);
}

void Serial::setParity

(

parity_t

parity

)

Sets the parity for the serial port.

Parameters

parity

Method of parity, default is parity_none, possible values are: parity_none, parity_odd, parity_even

Exceptions

std::invalid_argument

{
  pimpl_->setParity (parity);
}

void Serial::setPort

(

const std::string &

port

)

Sets the serial port identifier.

Parameters

port	A const std::string reference containing the address of the serial port, which would be something like 'COM1' on Windows and '/dev/ttyS0' on Linux.

Exceptions

std::invalid_argument

{
  ScopedReadLock rlock(this->pimpl_);
  ScopedWriteLock wlock(this->pimpl_);
  bool was_open = pimpl_->isOpen ();
  if (was_open) close();
  pimpl_->setPort (port);
  if (was_open) open ();
}

void Serial::setRTS

(

bool

level = true

)

Set the RTS handshaking line to the given level. Defaults to true.

{
  pimpl_->setRTS (level);
}

void Serial::setStopbits

(

stopbits_t

stopbits

)

Sets the stopbits for the serial port.

Parameters

stopbits

Number of stop bits used, default is stopbits_one, possible values are: stopbits_one, stopbits_one_point_five, stopbits_two

Exceptions

std::invalid_argument

{
  pimpl_->setStopbits (stopbits);
}

void Serial::setTimeout

(

serial::Timeout &

timeout

)

Sets the timeout for reads and writes using the Timeout struct.

There are two timeout conditions described here:

• The inter byte timeout:
  • The inter_byte_timeout component of serial::Timeout defines the maximum amount of time, in milliseconds, between receiving bytes on the serial port that can pass before a timeout occurs. Setting this to zero will prevent inter byte timeouts from occurring.
• Total time timeout:
  • The constant and multiplier component of this timeout condition, for both read and write, are defined in serial::Timeout. This timeout occurs if the total time since the read or write call was made exceeds the specified time in milliseconds.
  • The limit is defined by multiplying the multiplier component by the number of requested bytes and adding that product to the constant component. In this way if you want a read call, for example, to timeout after exactly one second regardless of the number of bytes you asked for then set the read_timeout_constant component of serial::Timeout to 1000 and the read_timeout_multiplier to zero. This timeout condition can be used in conjunction with the inter byte timeout condition with out any problems, timeout will simply occur when one of the two timeout conditions is met. This allows users to have maximum control over the trade-off between responsiveness and efficiency.

Read and write functions will return in one of three cases. When the reading or writing is complete, when a timeout occurs, or when an exception occurs.

A timeout of 0 enables non-blocking mode.

Parameters

timeout

A serial::Timeout struct containing the inter byte timeout, and the read and write timeout constants and multipliers.

See also

serial::Timeout

{
  pimpl_->setTimeout (timeout);
}

void serial::Serial::setTimeout ( uint32_t  inter_byte_timeout, uint32_t  read_timeout_constant, uint32_t  read_timeout_multiplier, uint32_t  write_timeout_constant, uint32_t  write_timeout_multiplier  )

inline

Sets the timeout for reads and writes.

  {
    Timeout timeout(inter_byte_timeout, read_timeout_constant,
                    read_timeout_multiplier, write_timeout_constant,
                    write_timeout_multiplier);
    return setTimeout(timeout);
  }

void Serial::waitByteTimes

(

size_t

count

)

Block for a period of time corresponding to the transmission time of count characters at present serial settings. This may be used in con- junction with waitReadable to read larger blocks of data from the port.

{
  pimpl_->waitByteTimes(count);
}

bool Serial::waitForChange

(

)

Blocks until CTS, DSR, RI, CD changes or something interrupts it.

Can throw an exception if an error occurs while waiting. You can check the status of CTS, DSR, RI, and CD once this returns. Uses TIOCMIWAIT via ioctl if available (mostly only on Linux) with a resolution of less than +-1ms and as good as +-0.2ms. Otherwise a polling method is used which can give +-2ms.

Returns

Returns true if one of the lines changed, false if something else occurred.

Exceptions

SerialException

{
  return pimpl_->waitForChange();
}

bool Serial::waitReadable

(

)

Block until there is serial data to read or read_timeout_constant number of milliseconds have elapsed. The return value is true when the function exits with the port in a readable state, false otherwise (due to timeout or select interruption).

{
  serial::Timeout timeout(pimpl_->getTimeout ());
  return pimpl_->waitReadable(timeout.read_timeout_constant);
}

size_t Serial::write	(	const uint8_t *	data,
		size_t	size
	)

Write a string to the serial port.

Parameters

data	A const reference containing the data to be written to the serial port.
size	A size_t that indicates how many bytes should be written from the given data buffer.

Returns

A size_t representing the number of bytes actually written to the serial port.

Exceptions

serial::PortNotOpenedException
serial::SerialException
serial::IOException

{
  ScopedWriteLock lock(this->pimpl_);
  return this->write_(data, size);
}

size_t Serial::write

(

const std::vector< uint8_t > &

data

)

Write a string to the serial port.

Parameters

data	A const reference containing the data to be written to the serial port.

Returns

A size_t representing the number of bytes actually written to the serial port.

Exceptions

serial::PortNotOpenedException
serial::SerialException
serial::IOException

{
  ScopedWriteLock lock(this->pimpl_);
  return this->write_ (&data[0], data.size());
}

size_t serial::Serial::write

(

const std::string &

data

)

Write a string to the serial port.

Parameters

data	A const reference containing the data to be written to the serial port.

Returns

A size_t representing the number of bytes actually written to the serial port.

Exceptions

serial::PortNotOpenedException
serial::SerialException
serial::IOException

---

The documentation for this class was generated from the following files:

• include/serial/serial.h
• src/serial.cc