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


Page generated by Doxygen 1.8.8 for MRPT 1.2.2 SVN:Unversioned directory at Tue Oct 14 02:14:08 UTC 2014