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?() |
| 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.
創建一個串口對象，如果制定了端口號，那么這個串口將打開，否則現在不會打開，會等到調用open函數的時候再打開
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.（地址值：Windows系統類似于COM1,LINUX系統類似于/dev/ttyS0這樣的款式） |
| baudrate | An unsigned 32-bit integer that represents the baudrate波特率：是一個32位的int類型數據 |
| timeout | A?serial::Timeout?struct that defines the timeout conditions for the serial port.超時的時間值 |
See also:
serial::Timeout
Parameters:（對上面的timeout結構體詳細介紹，一下是結構體的成員變量）
| bytesize 字長 | Size of each byte in the serial transmission of data, default is eightbits, possible values are: fivebits, sixbits, sevenbits, eightbits默認字長是8位，可以是5，6，7，8好像不能是9位 |
| 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:
| 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 ();
}
| 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:
| InvalidConfigurationException |
{return uint32_t(pimpl_->getBaudrate ());
}
| bytesize_t?Serial::getBytesize | ( | ) | const |
Gets the bytesize for the serial port.設置“數據字長”一般是8位
See also:
Serial::setBytesize
Exceptions:
| InvalidConfigurationException |
{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:
| 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 | ( | ) |
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:
| InvalidConfigurationException |
{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::SerialExecption | |
| 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.一個uint8_t數據類型的數組，長度至少達到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.（從串口讀取了多少個字符串就把字符串長度作為返回值，所以可以根據返回值是否等于size參數判斷是否發生異常）
{ScopedReadLock (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.
{ScopedReadLock (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.
{ScopedReadLock (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.
{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.
| 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.
| 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.
{ScopedReadLock (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 foundlines.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:
| InvalidConfigurationException |
{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:
| InvalidConfigurationException |
{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:
| 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 | ) |
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:
| InvalidConfigurationException |
{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 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.
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);}
| 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();
}
| 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.
{ScopedWriteLock(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.
{ScopedWriteLock(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.
The documentation for this class was generated from the following files:
- include/serial/serial.h
- src/serial.cc
