Main MRPT website > C++ reference for MRPT 1.5.7
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-2017, 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>
16 #include <mrpt/hwdrivers/link_pragmas.h>
17 
18 namespace 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  */
43  class HWDRIVERS_IMPEXP CSerialPort : public mrpt::utils::CStream
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  */
56  CSerialPort();
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  */
101  void purgeBuffers();
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  */
111  void setConfig(
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  */
121  void setTimeouts(
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(int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning)
159  {
160  MRPT_START
161  MRPT_UNUSED_PARAM(Origin);
162  MRPT_UNUSED_PARAM(Offset);
163  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
164  MRPT_END
165  }
166 
167  /** Returns the total amount of bytes in the stream.
168  */
169  uint64_t getTotalBytesCount()
170  {
171  MRPT_START
172  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
173  MRPT_END
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  {
180  MRPT_START
181  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
182  MRPT_END
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;
190  int m_baudRate;
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
mrpt::hwdrivers::CSerialPort
A communications serial port built as an implementation of a utils::CStream.
Definition: CSerialPort.h:43
THROW_EXCEPTION
#define THROW_EXCEPTION(msg)
Definition: maps/CColouredPointsMap.h:154
link_pragmas.h
mrpt::hwdrivers::CSerialPort::Seek
uint64_t Seek(int64_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
CStream.h
mrpt::utils::CStream
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:38
HWDRIVERS_IMPEXP
#define HWDRIVERS_IMPEXP
Definition: hwdrivers/include/mrpt/hwdrivers/link_pragmas.h:42
MRPT_END
#define MRPT_END
Definition: maps/CColouredPointsMap.h:370
MRPT_UNUSED_PARAM
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
Definition: maps/CColouredPointsMap.h:307
int64_t
__int64 int64_t
Definition: rptypes.h:51
mrpt::utils::CTicTac
This class implements a high-performance stopwatch.
Definition: CTicTac.h:24
mrpt::hwdrivers::CSerialPort::getPosition
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
mrpt::hwdrivers::CSerialPort::m_timer
mrpt::utils::CTicTac m_timer
Used only in ReadString.
Definition: CSerialPort.h:193
string
GLsizei const GLchar ** string
Definition: glext.h:3919
CTicTac.h
mrpt::hwdrivers::CSerialPort::setSerialPortName
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
MRPT_START
#define MRPT_START
Definition: maps/CColouredPointsMap.h:366
uint64_t
unsigned __int64 uint64_t
Definition: rptypes.h:52
mrpt
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
Definition: CParticleFilter.h:16
mrpt::hwdrivers::CSerialPort::open
void open(const std::string &COM_name)
Open the given serial port.
Definition: CSerialPort.h:79
mrpt::hwdrivers::CSerialPort::hCOM
int hCOM
The file handle (-1: Not open)
Definition: CSerialPort.h:202
mrpt::hwdrivers::CSerialPort::getTotalBytesCount
uint64_t getTotalBytesCount()
Returns the total amount of bytes in the stream.
Definition: CSerialPort.h:169
mrpt::hwdrivers::CSerialPort::m_serialName
std::string m_serialName
The complete name of the serial port device (i.e.
Definition: CSerialPort.h:189


Page generated by Doxygen 1.8.14 for MRPT 1.5.7 Git: 5902e14cc Wed Apr 24 15:04:01 2019 +0200 at lun oct 28 01:39:17 CET 2019