Main MRPT website > C++ reference
MRPT logo
CSerialPort.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 
29 #ifndef CSERIALPORT_H
30 #define CSERIALPORT_H
31 
32 #include <mrpt/config.h>
33 #include <mrpt/utils/CStream.h>
34 #include <mrpt/utils/CTicTac.h>
35 #include <mrpt/utils/stl_extensions.h>
36 #include <queue>
37 
38 #include <mrpt/hwdrivers/link_pragmas.h>
39 
40 namespace mrpt
41 {
42  namespace hwdrivers
43  {
44  using namespace mrpt::utils;
45  /** A communications serial port built as an implementation of a utils::CStream.
46  * On communication errors (eg. the given port number does not exist, timeouts,...), most of the methods will
47  * raise an exception of the class "std::exception"
48  *
49  * The serial port to open is passed in the constructor in the form of a string description,
50  * which is platform dependent.
51  *
52  * In windows they are numbered "COM1"-"COM4" and "\\.\COMXXX" for numbers above.
53  * It is recomended to always use the prefix "\\.\" despite the actual port number.
54  *
55  * In Linux the name must refer to the device, for example: "ttyUSB0","ttyS0". If the name string does not
56  * start with "/" (an absolute path), the constructor will assume the prefix "/dev/".
57  *
58  * History:
59  * - 1/DEC/2005: (JLBC) First version
60  * - 20/DEC/2006: (JLBC) Integration into the MRPT framework
61  * - 12/DEC/2007: (JLBC) Added support for Linux.
62  *
63  * \todo Add the internal buffer to the Windows implementation also
64  * \ingroup mrpt_hwdrivers_grp
65  */
66  class HWDRIVERS_IMPEXP CSerialPort : public CStream
67  {
68  friend class PosixSignalDispatcherImpl;
69  public:
70  /** Constructor
71  * \param portName The serial port to open. See comments at the begining of this page.
72  * \param openNow Whether to try to open the port now. If not selected, the port should be open later with "open()".
73  *
74  */
75  CSerialPort( const std::string &portName, bool openNow = true );
76 
77  /** Default constructor: it does not open any port - later you must call "setSerialPortName" and then "open"
78  */
79  CSerialPort();
80 
81  /** Destructor
82  */
83  virtual ~CSerialPort();
84 
85  /** Sets the serial port to open (it is an error to try to change this while open yet).
86  * \sa open, close
87  */
88  void setSerialPortName( const std::string &COM_name )
89  {
90  if (isOpen()) THROW_EXCEPTION("Cannot change serial port while open");
91  m_serialName = COM_name;
92  }
93 
94  /** Open the port. If is already open results in no action.
95  * \exception std::exception On communication errors
96  */
97  void open();
98 
99  /** Open the given serial port. If it is already open and the name does not match, an exception is raised.
100  * \exception std::exception On communication errors or a different serial port already open.
101  */
102  void open(const std::string &COM_name)
103  {
104  if (isOpen() && m_serialName!=COM_name) THROW_EXCEPTION("Cannot change serial port while open");
105  if (!isOpen())
106  {
107  setSerialPortName(COM_name);
108  open();
109  }
110  }
111 
112 
113  /** Close the port. If is already closed, results in no action.
114  */
115  void close();
116 
117  /** Returns if port has been correctly open.
118  */
119  bool isOpen();
120 
121  /** Purge tx and rx buffers.
122  * \exception std::exception On communication errors
123  */
124  void purgeBuffers();
125 
126  /** Changes the configuration of the port.
127  * \param parity 0:No parity, 1:Odd, 2:Even (WINDOWS ONLY: 3:Mark, 4:Space)
128  * \param baudRate The desired baud rate Accepted values: 50 - 230400
129  * \param bits Bits per word (typ. 8) Accepted values: 5,6,7,8.
130  * \param nStopBits Stop bits (typ. 1) Accepted values: 1,2
131  * \param enableFlowControl Whether to enable the hardware flow control (RTS/CTS) (default=no)
132  * \exception std::exception On communication errors
133  */
134  void setConfig(
135  int baudRate,
136  int parity = 0,
137  int bits = 8,
138  int nStopBits = 1,
139  bool enableFlowControl=false);
140 
141  /** Changes the timeouts of the port, in milliseconds.
142  * \exception std::exception On communication errors
143  */
144  void setTimeouts(
145  int ReadIntervalTimeout,
146  int ReadTotalTimeoutMultiplier,
147  int ReadTotalTimeoutConstant,
148  int WriteTotalTimeoutMultiplier,
149  int WriteTotalTimeoutConstant );
150 
151 
152  /** 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.
153  * \exception std::exception On communication errors
154  */
155  size_t Read(void *Buffer, size_t Count);
156 
157  /** Reads one text line from the serial port in POSIX "canonical mode".
158  * This method reads from the serial port until one of the characters in \a eol are found.
159  * \param eol_chars A line reception is finished when one of these characters is found. Default: LF (10), CR (13).
160  * \param total_timeout_ms If >0, the maximum number of milliseconds to wait.
161  * \param out_timeout If provided, will hold true on return if a timeout ocurred, false on a valid read.
162  * \return The read string, without the final
163  * \exception std::exception On communication errors
164  */
165  std::string ReadString(const int total_timeout_ms=-1, bool *out_timeout =NULL, const char *eol_chars = "\r\n");
166 
167  /** Implements the virtual method responsible for writing to the stream.
168  * Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
169  * \exception std::exception On communication errors
170  */
171  size_t Write(const void *Buffer, size_t Count);
172 
173 
174  /** Introduces a pure virtual method for moving to a specified position in the streamed resource.
175  * he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:
176  * - sFromBeginning (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
177  * - sFromCurrent Offset is from the current position in the resource. Seek moves to Position + Offset.
178  * - 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.
179  * \return Seek returns the new value of the Position property.
180  */
181  uint64_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning)
182  {
183  MRPT_START
184  MRPT_UNUSED_PARAM(Origin);
185  MRPT_UNUSED_PARAM(Offset);
186  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
187  MRPT_END
188  }
189 
190  /** Returns the total amount of bytes in the stream.
191  */
192  uint64_t getTotalBytesCount()
193  {
194  MRPT_START
195  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
196  MRPT_END
197  }
198 
199  /** Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
200  */
201  uint64_t getPosition()
202  {
203  MRPT_START
204  THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
205  MRPT_END
206  }
207 
208  protected:
209 
210  /** The complete name of the serial port device (i.e. "\\.\COM10","/dev/ttyS2",...)
211  */
212  std::string m_serialName;
213  int m_baudRate;
214  int m_totalTimeout_ms,m_interBytesTimeout_ms;
215 
216  CTicTac m_timer; //!< Used only in \a ReadString
217 
218  #ifdef MRPT_OS_WINDOWS
219  // WINDOWS
220  void *hCOM;
221  #else
222  // LINUX
223  /** The file handle (-1: Not open)
224  */
225  int hCOM;
226  // size_t ReadUnbuffered(void *Buffer, size_t Count); // JL: Remove??
227  #endif
228 
229  }; // end of class
230 
231  } // end of namespace
232 } // end of namespace
233 
234 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013