00001 /* +---------------------------------------------------------------------------+ 00002 | The Mobile Robot Programming Toolkit (MRPT) C++ library | 00003 | | 00004 | http://mrpt.sourceforge.net/ | 00005 | | 00006 | Copyright (C) 2005-2010 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 CGenericSensor_H 00030 #define CGenericSensor_H 00031 00032 #include <mrpt/utils/CConfigFileBase.h> 00033 #include <mrpt/slam/CObservation.h> 00034 #include <mrpt/synch.h> 00035 #include <mrpt/system/threads.h> 00036 00037 #include <mrpt/hwdrivers/link_pragmas.h> 00038 00039 00040 namespace mrpt 00041 { 00042 /** Contains classes for various device interfaces. 00043 */ 00044 namespace hwdrivers 00045 { 00046 class HWDRIVERS_IMPEXP CGenericSensor; 00047 00048 /** A structure for runtime ID class type information in the context of hwdrivers::CGenericSensor. 00049 */ 00050 struct HWDRIVERS_IMPEXP TSensorClassId 00051 { 00052 const char* className; //!< Class name 00053 CGenericSensor* (*ptrCreateObject)(); //!< Pointer to class constructor 00054 }; 00055 00056 typedef stlplus::smart_ptr<CGenericSensor> CGenericSensorPtr; 00057 00058 /** A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabber. 00059 * Derived classes should be designed with the following execution flow in mind: 00060 * - Object constructor 00061 * - CGenericSensor::loadConfig: The following parameters are common to all sensors in rawlog-grabber (they are automatically loaded by rawlog-grabber) - see each class documentation for additional parameters: 00062 * - "process_rate": (Mandatory) The rate in Hertz (Hz) at which the sensor thread should invoke "doProcess". 00063 * - "max_queue_len": (Optional) The maximum number of objects in the observations queue (default is 200). If overflow occurs, an error message will be issued at run-time. 00064 * - "grab_decimation": (Optional) Grab only 1 out of N observations captured by the sensor (default is 1, i.e. do not decimate). 00065 * - CGenericSensor::initialize 00066 * - CGenericSensor::doProcess 00067 * - CGenericSensor::getObservations 00068 * 00069 * Notice that there are helper methods for managing the internal list of objects (see CGenericSensor::appendObservation). 00070 * 00071 * <b>Class Factory:</b> This is also a factory of derived classes, through the static method CGenericSensor::createSensor 00072 * 00073 * 00074 * For more details on RawLogGrabber refer to the wiki page: 00075 * http://www.mrpt.org/Application:RawLogGrabber 00076 */ 00077 class HWDRIVERS_IMPEXP CGenericSensor: public mrpt::utils::CUncopiable 00078 { 00079 public: 00080 virtual const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const = 0; 00081 00082 typedef std::multimap< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObservations; 00083 typedef std::pair< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObsPair; 00084 00085 /** The current state of the sensor 00086 * \sa CGenericSensor::getState 00087 */ 00088 enum TSensorState 00089 { 00090 ssInitializing = 0, 00091 ssWorking, 00092 ssError 00093 }; 00094 00095 /** The current state of the sensor */ 00096 TSensorState getState() const { return m_state; } 00097 00098 double getProcessRate() const { return m_process_rate; } 00099 00100 private: 00101 synch::CCriticalSection m_csObjList; //!< The critical section for m_objList 00102 TListObservations m_objList; //!< The queue of objects to be returned by getObservations 00103 00104 /** Used in registerClass */ 00105 static std::map< std::string , const TSensorClassId *> m_knownClasses; 00106 00107 // DECLARE_UNCOPIABLE( CGenericSensor ) 00108 00109 00110 protected: 00111 // === Common settings to any sensor, loaded in "loadConfig" ==== 00112 double m_process_rate; //!< See CGenericSensor 00113 size_t m_max_queue_len; //!< See CGenericSensor 00114 size_t m_grab_decimation; //!< If set to N>=2, only 1 out of N observations will be saved to m_objList. 00115 // ====================================== 00116 00117 size_t m_grab_decimation_counter; //!< Used when "m_grab_decimation" is enabled 00118 00119 00120 TSensorState m_state; 00121 00122 /** This method must be called by derived classes to enqueue a new observation in the list to be returned by getObservations. 00123 * Passed objects must be created in dynamic memory and a smart pointer passed. Example of creation: 00124 \code 00125 CObservationGPSPtr o = CObservationGPSPtr( new CObservationGPS() ); 00126 o-> .... // Set data 00127 appendObservation(o); 00128 \endcode 00129 */ 00130 void appendObservation( const mrpt::utils::CSerializablePtr &obj); 00131 00132 /** Register a class into the internal list of "CGenericSensor" descendents. 00133 * Used internally in the macros DEFINE_GENERIC_SENSOR, etc... 00134 */ 00135 static void registerClass(const TSensorClassId* pNewClass); 00136 00137 00138 /** Auxiliary structure used for CSerializable runtime class ID support. 00139 */ 00140 struct CLASSINIT_GENERIC_SENSOR 00141 { 00142 CLASSINIT_GENERIC_SENSOR(const TSensorClassId* pNewClass) 00143 { 00144 CGenericSensor::registerClass(pNewClass); 00145 } 00146 }; 00147 00148 /** Loads specific configuration for the device from a given source of configuration parameters, for example, an ".ini" file, loading from the section "[iniSection]" (see utils::CConfigFileBase and derived classes) 00149 * \exception This method must throw an exception with a descriptive message if some critical parameter is missing or has an invalid value. 00150 */ 00151 virtual void loadConfig_sensorSpecific( 00152 const mrpt::utils::CConfigFileBase &configSource, 00153 const std::string §ion ) = 0; 00154 00155 public: 00156 /** Creates a sensor by a name of the class. 00157 * Typically the user may want to create a smart pointer around the returned pointer, whis is made with: 00158 * \code 00159 * CGenericSensorPtr sensor = CGenericSensorPtr( CGenericSensor::createSensor("XXX") ); 00160 * \endcode 00161 * \return A pointer to a new class, or NULL if class name is unknown. 00162 */ 00163 static CGenericSensor* createSensor(const std::string &className); 00164 00165 /** Just like createSensor, but returning a smart pointer to the newly created sensor object. */ 00166 static inline CGenericSensorPtr createSensorPtr(const std::string &className) 00167 { 00168 return CGenericSensorPtr(createSensor(className)); 00169 } 00170 00171 /** Constructor */ 00172 CGenericSensor( ); 00173 00174 /** Destructor */ 00175 virtual ~CGenericSensor(); 00176 00177 /** Loads the generic settings common to any sensor (See CGenericSensor), then call to "loadConfig_sensorSpecific" 00178 * \exception This method throws an exception with a descriptive message if some critical parameter is missing or has an invalid value. 00179 */ 00180 void loadConfig( 00181 const mrpt::utils::CConfigFileBase &configSource, 00182 const std::string §ion ); 00183 00184 /** This method can or cannot be implemented in the derived class, depending on the need for it. 00185 * \exception This method must throw an exception with a descriptive message if some critical error is found. 00186 */ 00187 virtual void initialize() 00188 { } // Default method does nothing. 00189 00190 /** This method will be invoked at a minimum rate of "process_rate" (Hz) 00191 * \exception This method must throw an exception with a descriptive message if some critical error is found. 00192 */ 00193 virtual void doProcess() = 0; 00194 00195 /** Returns a list of enqueued objects, emptying it (thread-safe). The objects must be freed by the invoker. 00196 */ 00197 void getObservations( TListObservations &lstObjects ); 00198 00199 }; // end of class 00200 00201 00202 #define SENSOR_CLASS_ID(class_name) \ 00203 static_cast<const mrpt::hwdrivers::TSensorClassId*>(& mrpt::hwdrivers::class_name::class##class_name) 00204 00205 #define SENSOR_IS_CLASS( ptrObj, class_name ) (ptrObj->GetRuntimeClass()==SENSOR_CLASS_ID(class_name)) 00206 00207 00208 /** This declaration must be inserted in all CGenericSensor classes definition, within the class declaration. 00209 */ 00210 #define DEFINE_GENERIC_SENSOR(class_name) \ 00211 protected: \ 00212 static mrpt::hwdrivers::CGenericSensor::CLASSINIT_GENERIC_SENSOR _init_##class_name;\ 00213 public: \ 00214 static mrpt::hwdrivers::TSensorClassId class##class_name; \ 00215 virtual const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const; \ 00216 static mrpt::hwdrivers::CGenericSensor* CreateObject(); \ 00217 static void doRegister() \ 00218 { CGenericSensor::registerClass( SENSOR_CLASS_ID( class_name ) ); } 00219 00220 /** This must be inserted in all CGenericSensor classes implementation files: 00221 */ 00222 #define IMPLEMENTS_GENERIC_SENSOR(class_name, NameSpace) \ 00223 mrpt::hwdrivers::CGenericSensor* NameSpace::class_name::CreateObject() \ 00224 { return static_cast<hwdrivers::CGenericSensor*>( new NameSpace::class_name ); } \ 00225 mrpt::hwdrivers::TSensorClassId NameSpace::class_name::class##class_name = { \ 00226 #class_name, NameSpace::class_name::CreateObject }; \ 00227 const mrpt::hwdrivers::TSensorClassId* NameSpace::class_name::GetRuntimeClass() const \ 00228 { return SENSOR_CLASS_ID(class_name); } 00229 00230 00231 } // end of namespace 00232 } // end of namespace 00233 00234 #endif
| Page generated by Doxygen 1.6.1 for MRPT 0.9.0 SVN: at Mon Jun 7 06:47:58 UTC 2010 |
