# serial: serial::Serial Class Reference

serial 1.0 Cross-platformserialportlibraryforC++

- Main Page
- Namespaces
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Data Fields

All Data Structures Namespaces Files Functions Enumerations Enumerator Defines
Data Structures | Public Member Functions
serial::Serial Class Reference

`#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