#include <serial.h>

Data Structures
class	ScopedReadLock
class	ScopedWriteLock
Public Member Functions
	Serial (const std::string &port="", unsigned long baudrate=9600, long timeout=0, 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 ()
size_t	read (unsigned char *buffer, size_t size)
size_t	read (std::vector< unsigned char > &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 unsigned char *data, size_t size)
size_t	write (const std::vector< unsigned char > &data)
size_t	write (const std::string &data)
void	setPort (const std::string &port)
std::string	getPort () const
void	setTimeout (long timeout)
long	getTimeout () const
void	setBaudrate (unsigned long baudrate)
unsigned long	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	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 = `""`,
		unsigned long	baudrate = `9600`,
		long	timeout = `0`,
		bytesize_t	bytesize = `eightbits`,
		parity_t	parity = `parity_none`,
		stopbits_t	stopbits = `stopbits_one`,
		flowcontrol_t	flowcontrol = `flowcontrol_none`
	)

Constructor, creates a SerialPortBoost object and opens the port.

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 integer that represents the buadrate
timeout	A long that represents the time (in milliseconds) until a timeout on reads occur. Setting this to zero (0) will cause reading to be non-blocking, i.e. the available data will be returned immediately, but it will not block to wait for more. Setting this to a number less than zero (-1) will result in infinite blocking behaviour, i.e. the serial port will block until either size bytes have been read or an exception has occured.
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
buffer_size	The maximum size of the internal buffer, defaults to 256 bytes (2^8).

Exceptions:

PortNotOpenedException

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(this->pimpl_);
  ScopedWriteLock(this->pimpl_);
  pimpl_->flush ();
  read_cache_.clear ();
}

void Serial::flushInput ( )

Flush only the input buffer

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

void Serial::flushOutput ( )

Flush only the output buffer

{
  ScopedWriteLock(this->pimpl_);
  pimpl_->flushOutput ();
  read_cache_.clear ();
}

unsigned long 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:

InvalidConfigurationException

{
  return pimpl_->getBaudrate ();
}

bytesize_t Serial::getBytesize ( ) const

Gets the bytesize for the serial port.

See also:: Serial::setBytesize

Exceptions:

InvalidConfigurationException

{
  return pimpl_->getBytesize ();
}

bool Serial::getCD ( )

{
  return pimpl_->getCD ();
}

bool Serial::getCTS ( )

{
  return pimpl_->getCTS ();
}

bool Serial::getDSR ( )

{
  return pimpl_->getDSR ();
}

flowcontrol_t Serial::getFlowcontrol ( ) const

Gets the flow control for the serial port.

See also:: Serial::setFlowcontrol

Exceptions:

InvalidConfigurationException

{
  return pimpl_->getFlowcontrol ();
}

parity_t Serial::getParity ( ) const

Gets the parity for the serial port.

See also:: Serial::setParity

Exceptions:

InvalidConfigurationException

{
  return pimpl_->getParity ();
}

string Serial::getPort ( ) const

Gets the serial port identifier.

See also:: Serial::setPort

Exceptions:

InvalidConfigurationException

{
  return pimpl_->getPort ();
}

bool Serial::getRI ( )

{
  return pimpl_->getRI ();
}

stopbits_t Serial::getStopbits ( ) const

Gets the stopbits for the serial port.

See also:: Serial::setStopbits

Exceptions:

InvalidConfigurationException

{
  return pimpl_->getStopbits ();
}

long Serial::getTimeout ( ) const

Gets the timeout for reads in seconds.

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 portname is set and the port isn't alreay 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::SerialExecption
serial::IOException

{
  pimpl_->open ();
}

size_t Serial::read	(	unsigned char *	buffer,
		size_t	size
	)

Read a given amount of bytes from the serial port.

If a timeout is set it may return less characters than requested. With no timeout it will block until the requested number of bytes have been read or until an exception occurs.

Parameters:

size	A size_t defining how many bytes to be read.

Returns:: A std::string containing the data read.

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

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

{
  ScopedReadLock (this->pimpl_);
  unsigned char *buffer_ = new unsigned char[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`
	)

{
  ScopedReadLock (this->pimpl_);
  unsigned char *buffer_ = new unsigned char[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 )

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

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.

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

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

Reads in multiple lines until the serail 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.

{
  ScopedReadLock (this->pimpl_);
  std::vector<std::string> lines;
  size_t eol_len = eol.length ();
  unsigned char *buffer_ = static_cast<unsigned char*>
    (alloca (size * sizeof (unsigned char)));
  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 )

{
  pimpl_->sendBreak (duration);
}

void Serial::setBaudrate ( unsigned long 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:

InvalidConfigurationException

{
  pimpl_->setBaudrate (baudrate);
}

void Serial::setBreak ( bool level = 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:

InvalidConfigurationException

{
  pimpl_->setBytesize (bytesize);
}

void Serial::setDTR ( bool level = 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:

InvalidConfigurationException

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

InvalidConfigurationException

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

InvalidConfigurationException

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

void Serial::setRTS ( bool level = 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:

InvalidConfigurationException

{
  pimpl_->setStopbits (stopbits);
}

void Serial::setTimeout ( long timeout )

Sets the timeout for reads in milliseconds.

Parameters:

timeout A long that represents the time (in milliseconds) until a timeout on reads occur. Setting this to zero (0) will cause reading to be non-blocking, i.e. the available data will be returned immediately, but it will not block to wait for more. Setting this to a number less than zero (-1) will result in infinite blocking behaviour, i.e. the serial port will block until either size bytes have been read or an exception has occured.

{
  pimpl_->setTimeout (timeout);
}

size_t serial::Serial::write	(	const unsigned char *	data,
		size_t	size
	)

Write a string to the serial port.

Parameters:

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

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

size_t serial::Serial::write ( const std::vector< unsigned char > & data )

size_t serial::Serial::write ( const std::string & data )

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

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

Data Structures

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation