Main MRPT website > C++ reference for MRPT 1.4.0
CSerialPort.h
Go to the documentation of this file.
1/* +---------------------------------------------------------------------------+
2 | Mobile Robot Programming Toolkit (MRPT) |
3 | http://www.mrpt.org/ |
4 | |
5 | Copyright (c) 2005-2016, Individual contributors, see AUTHORS file |
6 | See: http://www.mrpt.org/Authors - All rights reserved. |
7 | Released under BSD License. See details in http://www.mrpt.org/License |
8 +---------------------------------------------------------------------------+ */
9
10#ifndef CSERIALPORT_H
11#define CSERIALPORT_H
12
13#include <mrpt/config.h>
14#include <mrpt/utils/CStream.h>
15#include <mrpt/utils/CTicTac.h>
17
18namespace mrpt
19{
20 namespace hwdrivers
21 {
22 /** A communications serial port built as an implementation of a utils::CStream.
23 * On communication errors (eg. the given port number does not exist, timeouts,...), most of the methods will
24 * raise an exception of the class "std::exception"
25 *
26 * The serial port to open is passed in the constructor in the form of a string description,
27 * which is platform dependent.
28 *
29 * In windows they are numbered "COM1"-"COM4" and "\\.\COMXXX" for numbers above.
30 * It is recomended to always use the prefix "\\.\" despite the actual port number.
31 *
32 * In Linux the name must refer to the device, for example: "ttyUSB0","ttyS0". If the name string does not
33 * start with "/" (an absolute path), the constructor will assume the prefix "/dev/".
34 *
35 * History:
36 * - 1/DEC/2005: (JLBC) First version
37 * - 20/DEC/2006: (JLBC) Integration into the MRPT framework
38 * - 12/DEC/2007: (JLBC) Added support for Linux.
39 *
40 * \todo Add the internal buffer to the Windows implementation also
41 * \ingroup mrpt_hwdrivers_grp
42 */
44 {
45 friend class PosixSignalDispatcherImpl;
46 public:
47 /** Constructor
48 * \param portName The serial port to open. See comments at the begining of this page.
49 * \param openNow Whether to try to open the port now. If not selected, the port should be open later with "open()".
50 *
51 */
52 CSerialPort( const std::string &portName, bool openNow = true );
53
54 /** Default constructor: it does not open any port - later you must call "setSerialPortName" and then "open"
55 */
57
58 /** Destructor
59 */
60 virtual ~CSerialPort();
61
62 /** Sets the serial port to open (it is an error to try to change this while open yet).
63 * \sa open, close
64 */
65 void setSerialPortName( const std::string &COM_name )
66 {
67 if (isOpen()) THROW_EXCEPTION("Cannot change serial port while open");
68 m_serialName = COM_name;
69 }
70
71 /** Open the port. If is already open results in no action.
72 * \exception std::exception On communication errors
73 */
74 void open();
75
76 /** Open the given serial port. If it is already open and the name does not match, an exception is raised.
77 * \exception std::exception On communication errors or a different serial port already open.
78 */
79 void open(const std::string &COM_name)
80 {
81 if (isOpen() && m_serialName!=COM_name) THROW_EXCEPTION("Cannot change serial port while open");
82 if (!isOpen())
83 {
84 setSerialPortName(COM_name);
85 open();
86 }
87 }
88
89
90 /** Close the port. If is already closed, results in no action.
91 */
92 void close();
93
94 /** Returns if port has been correctly open.
95 */
96 bool isOpen() const;
97
98 /** Purge tx and rx buffers.
99 * \exception std::exception On communication errors
100 */
102
103 /** Changes the configuration of the port.
104 * \param parity 0:No parity, 1:Odd, 2:Even (WINDOWS ONLY: 3:Mark, 4:Space)
105 * \param baudRate The desired baud rate Accepted values: 50 - 230400
106 * \param bits Bits per word (typ. 8) Accepted values: 5,6,7,8.
107 * \param nStopBits Stop bits (typ. 1) Accepted values: 1,2
108 * \param enableFlowControl Whether to enable the hardware flow control (RTS/CTS) (default=no)
109 * \exception std::exception On communication errors
110 */
112 int baudRate,
113 int parity = 0,
114 int bits = 8,
115 int nStopBits = 1,
116 bool enableFlowControl=false);
117
118 /** Changes the timeouts of the port, in milliseconds.
119 * \exception std::exception On communication errors
120 */
122 int ReadIntervalTimeout,
123 int ReadTotalTimeoutMultiplier,
124 int ReadTotalTimeoutConstant,
125 int WriteTotalTimeoutMultiplier,
126 int WriteTotalTimeoutConstant );
127
128
129 /** 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.
130 * \exception std::exception On communication errors
131 */
132 size_t Read(void *Buffer, size_t Count);
133
134 /** Reads one text line from the serial port in POSIX "canonical mode".
135 * This method reads from the serial port until one of the characters in \a eol are found.
136 * \param eol_chars A line reception is finished when one of these characters is found. Default: LF (10), CR (13).
137 * \param total_timeout_ms If >0, the maximum number of milliseconds to wait.
138 * \param out_timeout If provided, will hold true on return if a timeout ocurred, false on a valid read.
139 * \return The read string, without the final
140 * \exception std::exception On communication errors
141 */
142 std::string ReadString(const int total_timeout_ms=-1, bool *out_timeout =NULL, const char *eol_chars = "\r\n");
143
144 /** Implements the virtual method responsible for writing to the stream.
145 * Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
146 * \exception std::exception On communication errors
147 */
148 size_t Write(const void *Buffer, size_t Count);
149
150
151 /** Introduces a pure virtual method for moving to a specified position in the streamed resource.
152 * he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:
153 * - sFromBeginning (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
154 * - sFromCurrent Offset is from the current position in the resource. Seek moves to Position + Offset.
155 * - 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.
156 * \return Seek returns the new value of the Position property.
157 */
158 uint64_t Seek(uint64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning)
159 {
161 MRPT_UNUSED_PARAM(Origin);
162 MRPT_UNUSED_PARAM(Offset);
163 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
165 }
166
167 /** Returns the total amount of bytes in the stream.
168 */
170 {
172 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
174 }
175
176 /** Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
177 */
178 uint64_t getPosition()
179 {
181 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
183 }
184
185 protected:
186
187 /** The complete name of the serial port device (i.e. "\\.\COM10","/dev/ttyS2",...)
188 */
189 std::string m_serialName;
191 int m_totalTimeout_ms,m_interBytesTimeout_ms;
192
193 mrpt::utils::CTicTac m_timer; //!< Used only in \a ReadString
194
195 #ifdef MRPT_OS_WINDOWS
196 // WINDOWS
197 void *hCOM;
198 #else
199 // LINUX
200 /** The file handle (-1: Not open)
201 */
202 int hCOM;
203 // size_t ReadUnbuffered(void *Buffer, size_t Count); // JL: Remove??
204 #endif
205
206 }; // end of class
207
208 } // end of namespace
209} // end of namespace
210
211#endif
A communications serial port built as an implementation of a utils::CStream.
Definition CSerialPort.h:44
uint64_t Seek(uint64_t Offset, CStream::TSeekOrigin Origin=sFromBeginning)
Introduces a pure virtual method for moving to a specified position in the streamed resource.
void open()
Open the port.
CSerialPort()
Default constructor: it does not open any port - later you must call "setSerialPortName" and then "op...
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).
Definition CSerialPort.h:65
void setConfig(int baudRate, int parity=0, int bits=8, int nStopBits=1, bool enableFlowControl=false)
Changes the configuration of the port.
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 l...
std::string m_serialName
The complete name of the serial port device (i.e.
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,...
virtual ~CSerialPort()
Destructor.
bool isOpen() const
Returns if port has been correctly open.
int hCOM
The file handle (-1: Not open)
size_t Write(const void *Buffer, size_t Count)
Implements the virtual method responsible for writing to the stream.
mrpt::utils::CTicTac m_timer
Used only in ReadString.
void close()
Close the port.
CSerialPort(const std::string &portName, bool openNow=true)
Constructor.
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".
void open(const std::string &COM_name)
Open the given serial port.
Definition CSerialPort.h:79
void purgeBuffers()
Purge tx and rx buffers.
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition CStream.h:39
This class implements a high-performance stopwatch.
Definition CTicTac.h:25
#define HWDRIVERS_IMPEXP
#define MRPT_START
#define MRPT_END
#define THROW_EXCEPTION(msg)
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.



Page generated by Doxygen 1.9.7 for MRPT 1.4.0 SVN: at Tue Jun 13 14:10:35 UTC 2023