Main MRPT website > C++ reference
MRPT logo

CInterfaceFTDI.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 CInterfaceFTDI_H
00030 #define CInterfaceFTDI_H
00031 
00032 #include <mrpt/config.h>
00033 #include <mrpt/utils/CStream.h>
00034 #include <mrpt/utils/stl_extensions.h>
00035 
00036 #include <mrpt/hwdrivers/link_pragmas.h>
00037 
00038 namespace mrpt
00039 {
00040         namespace hwdrivers
00041         {
00042 
00043                 /** A list of FTDI devices and their descriptors.
00044                   * \sa CInterfaceFTDI::ListAllDevices
00045                   */
00046                 struct HWDRIVERS_IMPEXP TFTDIDevice
00047                 {
00048                         std::string     ftdi_manufacturer;
00049                         std::string     ftdi_description;
00050                         std::string     ftdi_serial;
00051 
00052                         uint16_t                usb_idVendor;
00053                         uint16_t                usb_idProduct;
00054                         uint8_t                 usb_serialNumber;
00055 
00056         #if defined(MRPT_OS_LINUX) || defined(MRPT_OS_APPLE)
00057                         /** Only for Linux: the corresponding libusb's  "usb_device*" */
00058                         void                    *usb_device_struct;
00059         #endif
00060                 };
00061 
00062                 /** Print out all the information of a FTDI device in textual form. */
00063                 std::ostream HWDRIVERS_IMPEXP  &operator << ( std::ostream &o, const TFTDIDevice &d);
00064 
00065                 /** Used in  CInterfaceFTDI::ListAllDevices */
00066                 typedef  std::deque<TFTDIDevice> TFTDIDeviceList;
00067 
00068                 /** A definition of a CStream actually representing a USB connection to a FTDI chip.
00069                  *
00070                  *  This class implements the communication with FT245BM / FT245RL chips.
00071                  *   Using this class makes a program to depend on:
00072                  *              - Windows: "FT2XX.DLL" and the device drivers (see FTDI website).
00073                  *              - Linux: "libusb.so" (quite standard!), and "libftdi.so" only if linking against the dynamic library.
00074                  *
00075                  *  If there is any error during the communications (or loading the Windows DLL), a std::exception will be raised.
00076                  *
00077                  *  To write bulk data, use CStream::ReadBuffer and CStream::WriteBuffer. See also the derived classes for
00078                  *   higher level communication: CInterfaceFTDIMessages
00079                  *
00080                  * Warning: Avoid defining an object of this class in a global scope if you want to catch all potential
00081                  *      exceptions during the constructors (like DLL not found, etc...)
00082                  *
00083                  * VERSIONS:
00084                  *              - 11/APR/2005: Initial development. JLBC
00085                  *              - 16/FEB/2007: Integration into the MRPT framework. Support for device serial numbers. JLBC
00086                  *              - 15/APR/2008: Implemented for Linux using libftdi. JLBC
00087                  *
00088                  * \sa CInterfaceFTDIMessages, CStream
00089                  */
00090                 class HWDRIVERS_IMPEXP CInterfaceFTDI : public utils::CStream
00091                 {
00092                 public:
00093                         /** Constructor, which loads driver interface (the DLL under Windows).
00094                           */
00095                         CInterfaceFTDI();
00096 
00097                         /** Destructor, which closes the connection with the chip and unloads the driver interface.
00098                           */
00099                         virtual ~CInterfaceFTDI();
00100 
00101                         /** This object cannot be copied */
00102                         CInterfaceFTDI(const CInterfaceFTDI &o);
00103 
00104                         /** This object cannot be copied */
00105                         CInterfaceFTDI& operator =(const CInterfaceFTDI &o);
00106 
00107                         /** Checks whether the chip has been successfully open.
00108                           * \sa OpenBySerialNumber, OpenByDescription
00109                           */
00110                         bool  isOpen();
00111 
00112                         /** Open by device serial number
00113                           */
00114                         void  OpenBySerialNumber( const std::string &serialNumber );
00115 
00116                         /** Open by device description
00117                           */
00118                         void  OpenByDescription( const std::string &description );
00119 
00120                         /** Close the USB device */
00121                         void  Close();
00122 
00123                         /** Reset the USB device */
00124                         void  ResetDevice();
00125 
00126                         /** Purge the I/O buffers */
00127                         void  Purge();
00128 
00129                         /** Change the latency timer (in milliseconds) implemented on the FTDI chip: for a few ms, data is not sent to the PC waiting for possible more data, to save USB trafic. */
00130                         void  SetLatencyTimer (unsigned char latency_ms);
00131 
00132                         /** Change read & write timeouts, in milliseconds. */
00133                         void  SetTimeouts(unsigned long dwReadTimeout_ms, unsigned long dwWriteTimeout_ms);
00134 
00135 
00136                         /** Generates a list with all FTDI devices connected right now.
00137                           */
00138                         void ListAllDevices( TFTDIDeviceList &outList );
00139 
00140                         /** Tries to read, raising no exception if not all the bytes are available, but raising one if there is some communication error.
00141                          */
00142                         size_t  ReadSync(void *Buffer, size_t Count)
00143                         {
00144                                 return Read(Buffer,Count);
00145                         }
00146 
00147                         /** Tries to write, raising no exception if not all the bytes are available, but raising one if there is some communication error.
00148                          */
00149                         size_t  WriteSync(const void *Buffer, size_t Count)
00150                         {
00151                                 return Write(Buffer,Count);
00152                         }
00153 
00154                         /** Reads a block of bytes from the stream into Buffer, and returns the amound of bytes actually read, without waiting for more extra bytes to arrive (just those already enqued in the stream).
00155                          *  In this class this method actually behaves as expected and does not fallback to ReadBuffer().
00156                          *      \exception std::exception On any error, or if ZERO bytes are read.
00157                          */
00158                         virtual size_t  ReadBufferImmediate(void *Buffer, size_t Count);
00159 
00160                 protected:
00161                         /** Introduces a pure virtual method responsible for reading from the stream.
00162                           *  It integrates a cache buffer to speed-up sequences of many, small readings.
00163                           */
00164                         size_t  Read(void *Buffer, size_t Count);
00165 
00166                         mrpt::utils::circular_buffer<uint8_t>    m_readBuffer;  //!< Used in Read
00167 
00168                         /** Introduces a pure virtual method responsible for writing to the stream.
00169                          *  Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
00170                          */
00171                         size_t  Write(const void *Buffer, size_t Count);
00172 
00173                         /** This virtual method does nothing in this class.
00174                          */
00175                         uint64_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning);
00176 
00177                         /** This virtual method does nothing in this class.
00178                          */
00179                         uint64_t getTotalBytesCount();
00180 
00181                         /** This virtual method does nothing in this class.
00182                          */
00183                         uint64_t getPosition();
00184 
00185 
00186                         void  ftdi_read(void  *lpvBuffer, unsigned long dwBuffSize, unsigned long  *lpdwBytesRead);
00187                         void  ftdi_write(const void  *lpvBuffer, unsigned long dwBuffSize, unsigned long  *lpdwBytes);
00188 
00189         #if defined(MRPT_OS_WINDOWS)
00190                 private:
00191                         void  checkErrorAndRaise(int errorCode);
00192 
00193                         void  ftdi_open(void* pvDevice);
00194                         void  ftdi_openEx(void* pArg1, unsigned long dwFlags);
00195                         void  ftdi_listDevices(void *pArg1, void *pArg2, unsigned long dwFlags);
00196                         void  ftdi_getQueueStatus(unsigned long  *lpdwAmountInRxQueue);
00197 
00198                         void                            *m_hmodule;
00199                         unsigned long           m_ftHandle;
00200 
00201                         void            loadDriver();
00202 
00203                         enum FT_STATUS
00204                         {
00205                                 dummy
00206                         };
00207 
00208                         typedef FT_STATUS (__stdcall *PtrToOpen)(void*, unsigned long  *);
00209                         PtrToOpen m_pOpen;
00210 
00211                         typedef FT_STATUS (__stdcall *PtrToOpenEx)(void*, unsigned long, unsigned long  *);
00212                         PtrToOpenEx m_pOpenEx;
00213 
00214                         typedef FT_STATUS (__stdcall *PtrToListDevices)(void*, void*, unsigned long);
00215                         PtrToListDevices m_pListDevices;
00216 
00217                         typedef FT_STATUS (__stdcall *PtrToClose)(unsigned long );
00218                         PtrToClose m_pClose;
00219 
00220                         typedef FT_STATUS (__stdcall *PtrToRead)(unsigned long , void  *, unsigned long, unsigned long  *);
00221                         PtrToRead m_pRead;
00222 
00223                         typedef FT_STATUS (__stdcall *PtrToWrite)(unsigned long , const void  *, unsigned long, unsigned long  *);
00224                         PtrToWrite m_pWrite;
00225 
00226                         typedef FT_STATUS (__stdcall *PtrToResetDevice)(unsigned long );
00227                         PtrToResetDevice m_pResetDevice;
00228 
00229                         typedef FT_STATUS (__stdcall *PtrToPurge)(unsigned long , unsigned long);
00230                         PtrToPurge m_pPurge;
00231 
00232                         typedef FT_STATUS (__stdcall *PtrToSetTimeouts)(unsigned long , unsigned long, unsigned long);
00233                         PtrToSetTimeouts m_pSetTimeouts;
00234 
00235                         typedef FT_STATUS (__stdcall *PtrToGetQueueStatus)(unsigned long , unsigned long  *);
00236                         PtrToGetQueueStatus m_pGetQueueStatus;
00237 
00238                         typedef FT_STATUS (__stdcall *PtrToSetLatencyTimer )(unsigned long , unsigned char);
00239                         PtrToSetLatencyTimer m_pSetLatencyTimer;
00240 
00241         #else
00242                 // Declarations for Linux:
00243                         void            *m_ftdi_context;
00244 
00245                         /** Process recursively a USB device and its children: */
00246                         void recursive_fill_list_devices( void *usb_device_structure , TFTDIDeviceList &outList );
00247 
00248 
00249         #endif
00250 
00251 
00252                 }; // end of class
00253 
00254         } // end of namespace
00255 } // end of namespace
00256 
00257 #endif



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