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.
Definition: CSerialPort.h:158
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.
Definition: CSerialPort.h:169
uint64_t getPosition()
Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the l...
Definition: CSerialPort.h:178
std::string m_serialName
The complete name of the serial port device (i.e.
Definition: CSerialPort.h:189
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)
Definition: CSerialPort.h:202
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.
Definition: CSerialPort.h:193
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
Definition: mrpt_macros.h:349
#define MRPT_END
Definition: mrpt_macros.h:353
#define THROW_EXCEPTION(msg)
Definition: mrpt_macros.h:110
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
Definition: mrpt_macros.h:290
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.



Page generated by Doxygen 1.9.6 for MRPT 1.4.0 SVN: at Thu Jan 19 22:37:47 UTC 2023