Main MRPT website > C++ reference
MRPT logo

CSerialPort.h

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2011  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 
00029 #ifndef CSERIALPORT_H
00030 #define CSERIALPORT_H
00031 
00032 #include <mrpt/config.h>
00033 #include <mrpt/utils/CStream.h>
00034 #include <mrpt/utils/CTicTac.h>
00035 #include <mrpt/utils/stl_extensions.h>
00036 #include <queue>
00037 
00038 #include <mrpt/hwdrivers/link_pragmas.h>
00039 
00040 namespace mrpt
00041 {
00042         namespace hwdrivers
00043         {
00044                 using namespace mrpt::utils;
00045                 /** A communications serial port built as an implementation of a utils::CStream.
00046                  * On communication errors (eg. the given port number does not exist, timeouts,...), most of the methods will
00047                  * raise an exception of the class "std::exception"
00048                  *
00049                  *  The serial port to open is passed in the constructor in the form of a string description,
00050                  *   which is platform dependent.
00051                  *
00052                  *  In windows they are numbered "COM1"-"COM4" and "\\.\COMXXX" for numbers above.
00053                  *    It is recomended to always use the prefix "\\.\" despite the actual port number.
00054                  *
00055                  *  In Linux the name must refer to the device, for example: "ttyUSB0","ttyS0". If the name string does not
00056                  *   start with "/" (an absolute path), the constructor will assume the prefix "/dev/".
00057                  *
00058                  *  History:
00059                  *    - 1/DEC/2005:  (JLBC) First version
00060                  *    - 20/DEC/2006: (JLBC) Integration into the MRPT framework
00061                  *    - 12/DEC/2007: (JLBC) Added support for Linux.
00062                  *
00063                  * \todo Add the internal buffer to the Windows implementation also
00064                  */
00065                 class HWDRIVERS_IMPEXP CSerialPort : public CStream
00066                 {
00067                         friend class PosixSignalDispatcherImpl;
00068                 public:
00069                         /** Constructor
00070                          * \param portName The serial port to open. See comments at the begining of this page.
00071                          * \param openNow Whether to try to open the port now. If not selected, the port should be open later with "open()".
00072                          *
00073                          */
00074                         CSerialPort( const std::string &portName, bool openNow = true );
00075 
00076                         /** Default constructor: it does not open any port - later you must call "setSerialPortName" and then "open"
00077                          */
00078                         CSerialPort();
00079 
00080                         /** Destructor
00081                         */
00082                         virtual ~CSerialPort();
00083 
00084                         /** Sets the serial port to open (it is an error to try to change this while open yet).
00085                           * \sa open, close
00086                           */
00087                         void setSerialPortName( const std::string &COM_name )
00088                         {
00089                                 if (isOpen()) THROW_EXCEPTION("Cannot change serial port while open");
00090                                 m_serialName = COM_name;
00091                         }
00092 
00093                         /** Open the port. If is already open results in no action.
00094                         * \exception std::exception On communication errors
00095                         */
00096                         void  open();
00097 
00098                         /** Open the given serial port. If it is already open and the name does not match, an exception is raised.
00099                         * \exception std::exception On communication errors or a different serial port already open.
00100                         */
00101                         void  open(const std::string &COM_name)
00102                         {
00103                                 if (isOpen() && m_serialName!=COM_name) THROW_EXCEPTION("Cannot change serial port while open");
00104                                 if (!isOpen())
00105                                 {
00106                                         setSerialPortName(COM_name);
00107                                         open();
00108                                 }
00109                         }
00110 
00111 
00112                         /** Close the port. If is already closed, results in no action.
00113                         */
00114                         void  close();
00115 
00116                         /** Returns if port has been correctly open.
00117                         */
00118                         bool  isOpen();
00119 
00120                         /** Purge tx and rx buffers.
00121                            * \exception std::exception On communication errors
00122                            */
00123                         void  purgeBuffers();
00124 
00125                         /** Changes the configuration of the port.
00126                         *  \param parity  0:No parity, 1:Odd, 2:Even (WINDOWS ONLY: 3:Mark, 4:Space)
00127                         *  \param baudRate The desired baud rate Accepted values: 50 - 230400
00128                         *  \param bits Bits per word (typ. 8) Accepted values: 5,6,7,8.
00129                         *  \param nStopBits Stop bits (typ. 1) Accepted values: 1,2
00130                         *  \param enableFlowControl Whether to enable the hardware flow control (RTS/CTS) (default=no)
00131                         * \exception std::exception On communication errors
00132                         */
00133                         void  setConfig(
00134                                 int baudRate,
00135                                 int parity = 0,
00136                                 int bits = 8,
00137                                 int nStopBits = 1,
00138                                 bool enableFlowControl=false);
00139 
00140                         /** Changes the timeouts of the port, in milliseconds.
00141                         * \exception std::exception On communication errors
00142                         */
00143                         void  setTimeouts(
00144                                 int             ReadIntervalTimeout,
00145                                 int             ReadTotalTimeoutMultiplier,
00146                                 int             ReadTotalTimeoutConstant,
00147                                 int             WriteTotalTimeoutMultiplier,
00148                                 int             WriteTotalTimeoutConstant );
00149 
00150 
00151                         /** 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.
00152                           * \exception std::exception On communication errors
00153                          */
00154                         size_t  Read(void *Buffer, size_t Count);
00155 
00156                         /** Reads one text line from the serial port in POSIX "canonical mode".
00157                           *  This method reads from the serial port until one of the characters in \a eol are found.
00158                           * \param eol_chars A line reception is finished when one of these characters is found. Default: LF (10), CR (13).
00159                           * \param total_timeout_ms If >0, the maximum number of milliseconds to wait.
00160                           * \param out_timeout If provided, will hold true on return if a timeout ocurred, false on a valid read.
00161                           * \return The read string, without the final
00162                           * \exception std::exception On communication errors
00163                           */
00164                         std::string ReadString(const int total_timeout_ms=-1, bool *out_timeout =NULL, const char *eol_chars = "\r\n");
00165 
00166                         /** Implements the virtual method responsible for writing to the stream.
00167                          *  Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
00168                         * \exception std::exception On communication errors
00169                          */
00170                         size_t  Write(const void *Buffer, size_t Count);
00171 
00172 
00173                         /** Introduces a pure virtual method for moving to a specified position in the streamed resource.
00174                          *   he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:
00175                          *      - sFromBeginning        (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
00176                          *      - sFromCurrent          Offset is from the current position in the resource. Seek moves to Position + Offset.
00177                          *      - 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.
00178                          * \return Seek returns the new value of the Position property.
00179                          */
00180                         uint64_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning)
00181                         {
00182                                 MRPT_START
00183                                 MRPT_UNUSED_PARAM(Origin);
00184                                 MRPT_UNUSED_PARAM(Offset);
00185                                 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
00186                                 MRPT_END
00187                         }
00188 
00189                         /** Returns the total amount of bytes in the stream.
00190                          */
00191                         uint64_t getTotalBytesCount()
00192                         {
00193                                 MRPT_START
00194                                 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
00195                                 MRPT_END
00196                         }
00197 
00198                         /** Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
00199                          */
00200                         uint64_t getPosition()
00201                         {
00202                                 MRPT_START
00203                                 THROW_EXCEPTION("Method not applicable to serial communications port CStream!");
00204                                 MRPT_END
00205                         }
00206 
00207                 protected:
00208 
00209                         /** The complete name of the serial port device (i.e. "\\.\COM10","/dev/ttyS2",...)
00210                           */
00211                         std::string     m_serialName;
00212                         int                             m_baudRate;
00213                         int                             m_totalTimeout_ms,m_interBytesTimeout_ms;
00214 
00215                         CTicTac                 m_timer; //!< Used only in \a ReadString
00216 
00217                 #ifdef MRPT_OS_WINDOWS
00218                         // WINDOWS
00219                         void            *hCOM;
00220                 #else
00221                         // LINUX
00222                         /** The file handle (-1: Not open)
00223                           */
00224                         int             hCOM;
00225                         // size_t  ReadUnbuffered(void *Buffer, size_t Count); // JL: Remove??
00226                 #endif
00227 
00228                 }; // end of class
00229 
00230         } // end of namespace
00231 } // end of namespace
00232 
00233 #endif



Page generated by Doxygen 1.7.3 for MRPT 0.9.4 SVN: at Sat Mar 26 06:16:28 UTC 2011