MRPT  2.0.4
CGPSInterface.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2020, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 
10 #pragma once
11 
12 #include <mrpt/comms/CSerialPort.h>
17 #include <mrpt/obs/obs_frwds.h>
18 #include <mrpt/poses/CPoint3D.h>
21 
22 namespace mrpt::hwdrivers
23 {
24 /** A class capable of reading GPS/GNSS/GNSS+IMU receiver data, from a serial
25  * port or from any input stream,
26  * and \b parsing the ASCII/binary stream into indivual messages \b stored in
27  * mrpt::obs::CObservationGPS objects.
28  *
29  * Typical input streams are serial ports or raw GPS log files. By default, the
30  * serial port selected by CGPSInterface::setSerialPortName()
31  * or as set in the configuration file will be open upon call to
32  * CGenericSensor::initialize().
33  * Alternatively, an external stream can be bound with
34  * CGPSInterface::bindStream() before calling CGenericSensor::initialize().
35  * This feature can be used to parse commands from a file, a TCP/IP stream, a
36  * memory block, etc.
37  *
38  * The parsers in the enum type CGPSInterface::PARSERS are supported as
39  * parameter `parser` in the
40  * configuration file below or in method CGPSInterface::setParser():
41  * - `NONE`: Do not try to parse the messages into CObservation's. Only useful
42  * if combined with `raw_dump_file_prefix`
43  * - `AUTO`: Try to automatically identify the format of incomming data.
44  * - `NMEA` (NMEA 0183, ASCII messages): Default parser. Supported frames:
45  * GGA, RMC,... See full list of messages in children of
46  * mrpt::obs::gnss::gnss_message
47  * - `NOVATEL_OEM6` (Novatel OEM6, binary frames): Supported frames:
48  * BESTPOS,... Note that receiving a correct IONUTC msg is required for a
49  * correct timestamping of subsequent frames. See full list of messages in
50  * children of mrpt::obs::gnss::gnss_message
51  *
52  * See available parameters below, and an example config file for
53  * rawlog-grabber
54  * [here](https://github.com/MRPT/mrpt/blob/master/share/mrpt/config_files/rawlog-grabber/gps.ini)
55  *
56  * \code
57  * PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
58  * -------------------------------------------------------
59  * [supplied_section_name]
60  *
61  * # Serial port configuration:
62  * COM_port_WIN = COM3
63  * COM_port_LIN = ttyUSB0
64  * baudRate = 4800 // The baudrate of the communications (typ. 4800 or
65  * 9600 bauds)
66  *
67  * # (Default:true) Whether to append the GNNS message type to CObservation
68  * `sensorLabel` field
69  * sensor_label_append_msg_type = true
70  *
71  * # Select a parser for GNSS data:
72  * # Up-to-date list of supported parsers available in
73  * https://reference.mrpt.org/devel/classmrpt_1_1hwdrivers_1_1_c_g_p_s_interface.html
74  * parser = AUTO
75  *
76  * # If uncommented and non-empty, raw binary/ascii data received from the
77  * serial port will be also dumped
78  * # into a file named after this prefix, plus date/time and extension `.gps`.
79  * #raw_dump_file_prefix = RAWGPS
80  *
81  * # 3D position (and orientation, for GNSS+IMUs) of the sensed point (antenna
82  * phase center) relative to the vehicle/robot frame:
83  * pose_x = 0 // (meters)
84  * pose_y = 0
85  * pose_z = 0
86  * pose_yaw = 0 // (deg)
87  * pose_pitch = 0
88  * pose_roll = 0
89  *
90  * # Optional: list of custom commands to be sent to the GNSS receiver to set
91  * it up.
92  * # An arbitrary number of commands can be defined, but their names must be
93  * "setup_cmd%d" starting at "1".
94  * # Commands will be sent by index order. Binary commands instead of ASCII
95  * strings can be set programmatically, not from a config file.
96  * # custom_cmds_delay = 0.1 // (Default=0.1) Delay in seconds between
97  * consecutive set-up commands
98  * # custom_cmds_append_CRLF = true // (Default:true) Append "\r\n" to each
99  * command
100  * # setup_cmd1 = XXXXX
101  * # setup_cmd2 = XXXXX
102  * # setup_cmd3 = XXXXX
103  *
104  * # Optional: list of commands to be sent upon disconnection (e.g. object
105  * destructor)
106  * # shutdown_cmd1 = XXXX
107  * # shutdown_cmd2 = XXXX
108  *
109  * \endcode
110  *
111  * Note that the `customInit` field, supported in MRPT <1.4.0 will be still
112  * parsed and obeyed, but since it has been superseded
113  * by the new mechanism to establish set-up commands, it is no further
114  * documented here.
115  *
116  * The next picture summarizes existing MRPT classes related to GPS / GNSS
117  * devices (CGPSInterface, CNTRIPEmitter, CGPS_NTRIP):
118  *
119  * <div align=center> <img src="mrpt_gps_classes_usage.png"> </div>
120  *
121  * <b>VERSIONS HISTORY:</b>
122  * - 09/JUN/2006: First version (JLBC)
123  * - 04/JUN/2008: Added virtual methods for device-specific initialization
124  * commands.
125  * - 10/JUN/2008: Converted into CGenericSensor class (there are no inhirited
126  * classes anymore).
127  * - 07/DEC/2012: Added public static method to parse NMEA strings.
128  * - 17/JUN/2014: Added GGA feedback.
129  * - 01/FEB/2016: API changed for MTPT 1.4.0
130  *
131  * \note Verbose debug info will be dumped to cout if the environment variable
132  * "MRPT_HWDRIVERS_VERBOSE" is set to "1", or if you call
133  * CGenericSensor::enableVerbose(true)
134  * \note
135  * \note <b>[API changed in MRPT 1.4.0]</b> mrpt::hwdrivers::CGPSInterface API
136  * clean-up and made more generic so any stream can be used to parse GNSS
137  * messages, not only serial ports.
138  *
139  * \sa CGPS_NTRIP, CNTRIPEmitter, mrpt::obs::CObservationGPS
140  * \ingroup mrpt_hwdrivers_grp
141  */
143 {
145 
146  public:
147  /** Read about parser selection in the documentation for CGPSInterface */
148  enum PARSERS
149  {
150  NONE = -2,
151  AUTO = -1,
152  NMEA = 0,
154  };
155 
156  /** Default ctor */
157  CGPSInterface();
158  /** Dtor */
159  ~CGPSInterface() override;
160 
161  void doProcess() override; // See docs in parent class
162 
163  /** Returns true if communications work, i.e. if some message has been
164  * received. */
165  bool isGPS_connected();
166  /** Returns true if the last message from the GPS indicates that the signal
167  * from sats has been acquired. */
168  bool isGPS_signalAcquired();
169 
170  /** \name Set-up and configuration
171  * @{ */
172  /** Set the serial port to use (COM1, ttyUSB0, etc). */
173  void setSerialPortName(const std::string& COM_port);
174  /** Get the serial port to use (COM1, ttyUSB0, etc). */
175  std::string getSerialPortName() const;
176 
177  /** Select the parser for incomming data, among the options enumerated in \a
178  * CGPSInterface */
179  void setParser(PARSERS parser);
180  PARSERS getParser() const;
181 
182  /** This enforces the use of a given user stream, instead of trying to open
183  * the serial port set in this class parameters.
184  * \param[in] csExternalStream If not NULL, read/write operations to the
185  * stream will be guarded by this critical section.
186  * The stream object is not deleted. It is the user responsibility to keep
187  * that object allocated during the entire life of this object.
188  * \note Call before CGenericSensor::initialize()
189  */
190  void bindStream(
191  const std::shared_ptr<mrpt::io::CStream>& external_stream,
192  const std::shared_ptr<std::mutex>& csOptionalExternalStream =
194 
196  void setSetupCommandsDelay(const double delay_secs);
197  double getSetupCommandsDelay() const;
198 
199  void setSetupCommands(const std::vector<std::string>& cmds);
200  const std::vector<std::string>& getSetupCommands() const;
201 
202  void setShutdownCommands(const std::vector<std::string>& cmds);
203  const std::vector<std::string>& getShutdownCommands() const;
204 
205  void enableSetupCommandsAppendCRLF(const bool enable);
207 
209  {
211  }
212 
213  /** If set to non-empty, RAW GPS serial data will be also dumped to a
214  * separate file. */
215  void setRawDumpFilePrefix(const std::string& filePrefix)
216  {
217  m_raw_dump_file_prefix = filePrefix;
218  }
219  std::string getRawDumpFilePrefix() const { return m_raw_dump_file_prefix; }
220  /** Send a custom data block to the GNSS device right now. Can be used to
221  change its behavior online as needed.
222  \return false on communication error */
223  bool sendCustomCommand(const void* data, const size_t datalen);
224  /** @} */
225 
226  inline bool isAIMConfigured() { return m_topcon_AIMConfigured; }
227  /** Parses one line of NMEA data from a GPS receiver, and writes the
228  * recognized fields (if any) into an observation object.
229  * Recognized frame types are those listed for the `NMEA` parser in the
230  * documentation of CGPSInterface
231  * \return true if some new data field has been correctly parsed and
232  * inserted into out_obs
233  */
234  static bool parse_NMEA(
235  const std::string& cmd_line, mrpt::obs::CObservationGPS& out_obs,
236  const bool verbose = false);
237 
238  /** Gets the latest GGA command or an empty string if no newer GGA command
239  * was received since the last call to this method.
240  * \param[in] reset If set to true, will empty the GGA cache so next calls
241  * will return an empty string if no new frame is received.
242  */
243  std::string getLastGGA(bool reset = true);
244 
245  using ptr_parser_t =
246  bool (CGPSInterface::*)(size_t& out_minimum_rx_buf_to_decide);
247 
248  /** @name Parser implementations: each method must try to parse the first
249  * bytes in the
250  * incoming buffer, and return false if the available data does not match
251  * the expected format, so we must skip 1 byte and try again.
252  * @{ */
253  bool implement_parser_NMEA(size_t& out_minimum_rx_buf_to_decide);
254  bool implement_parser_NOVATEL_OEM6(size_t& out_minimum_rx_buf_to_decide);
255  /** @} */
256 
257  protected:
258  /** Implements custom messages to be sent to the GPS unit just after
259  * connection and before normal use.
260  * Returns false or raise an exception if something goes wrong. */
262  /** Like OnConnectionEstablished() for sending optional shutdown commands */
263  bool OnConnectionShutdown();
264 
266 
267  /** Typically a CSerialPort created by this class, but may be set
268  * externally. */
272  std::make_shared<std::mutex>();
274 
276  std::string m_customInit;
277 
278  /** See the class documentation at the top for expected parameters */
280  const mrpt::config::CConfigFileBase& configSource,
281  const std::string& iniSection) override;
282 
283  /** If not empty, will send a cmd "set,/par/pos/pd/port,...". Example value:
284  * "/dev/ser/b" */
285  void setJAVAD_rtk_src_port(const std::string& s)
286  {
288  }
289 
290  /** Only used when "m_JAVAD_rtk_src_port" is not empty */
291  void setJAVAD_rtk_src_baud(unsigned int baud)
292  {
293  m_JAVAD_rtk_src_baud = baud;
294  }
295 
296  /** Only used when "m_JAVAD_rtk_src_port" is not empty: format of RTK
297  * corrections: "cmr", "rtcm", "rtcm3", etc. */
298  void setJAVAD_rtk_format(const std::string& s) { m_JAVAD_rtk_format = s; }
299  /** Set Advanced Input Mode for the primary port.
300  This can be used to send RTK corrections to the device using the same
301  port that it's used for the commands.
302  The RTK correction stream must be re-packaged into a special frame with
303  prefix ">>" */
304  bool setJAVAD_AIM_mode();
305 
306  /** Unset Advanced Input Mode for the primary port and use it only as a
307  * command port. */
308  bool unsetJAVAD_AIM_mode();
309 
310  private:
311  /** Auxiliary buffer for readings */
315  std::string m_COMname;
316  int m_COMbauds{4800};
318  bool m_GPS_comsWork{false};
321  double m_custom_cmds_delay{0.1};
323  std::vector<std::string> m_setup_cmds;
324  std::vector<std::string> m_shutdown_cmds;
325 
326  /** \name Legacy support for TopCon RTK configuration
327  * @{ */
328  /** If not empty, will send a cmd "set,/par/pos/pd/port,...". Example value:
329  * "/dev/ser/b" */
330  std::string m_JAVAD_rtk_src_port;
331  /** Only used when "m_JAVAD_rtk_src_port" is not empty */
332  unsigned int m_JAVAD_rtk_src_baud{0};
333  /** Only used when "m_JAVAD_rtk_src_port" is not empty: format of RTK
334  * corrections: "cmr", "rtcm", "rtcm3", etc. */
335  std::string m_JAVAD_rtk_format;
336 
337  /** Use this mode for receive RTK corrections from a external source through
338  * the primary port */
339  bool m_topcon_useAIMMode{false};
340  /** Indicates if the AIM has been properly set up. */
342  /** The period in seconds which the data should be provided by the GPS */
343  double m_topcon_data_period{0.2};
344  /** Private auxiliary method. Raises exception on error. */
345  void JAVAD_sendMessage(const char* str, bool waitForAnswer = true);
346  /** @} */
347 
348  /** Returns true if the COM port is already open, or try to open it in other
349  * case.
350  * \return true if everything goes OK, or false if there are problems
351  * opening the port. */
352  bool tryToOpenTheCOM();
353 
354  /** Process data in "m_buffer" to extract GPS messages, and remove them from
355  * the buffer. */
356  void parseBuffer();
357 
358  /** Queue out now the messages in \a m_just_parsed_messages, leaving it
359  * empty */
360  void flushParsedMessagesNow();
361  /** A private copy of the last received gps datum */
363  /** Used in getLastGGA() */
364  std::string m_last_GGA;
365 }; // end class
366 } // namespace mrpt::hwdrivers
368 using namespace mrpt::hwdrivers;
372 MRPT_FILL_ENUM_MEMBER(CGPSInterface, NOVATEL_OEM6);
A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabbe...
PARSERS
Read about parser selection in the documentation for CGPSInterface.
A class capable of reading GPS/GNSS/GNSS+IMU receiver data, from a serial port or from any input stre...
std::shared_ptr< std::mutex > m_data_stream_cs
void JAVAD_sendMessage(const char *str, bool waitForAnswer=true)
Private auxiliary method.
void setJAVAD_rtk_src_baud(unsigned int baud)
Only used when "m_JAVAD_rtk_src_port" is not empty.
bool isGPS_connected()
Returns true if communications work, i.e.
mrpt::obs::CObservationGPS m_just_parsed_messages
A private copy of the last received gps datum.
const std::vector< std::string > & getSetupCommands() const
bool OnConnectionShutdown()
Like OnConnectionEstablished() for sending optional shutdown commands.
bool unsetJAVAD_AIM_mode()
Unset Advanced Input Mode for the primary port and use it only as a command port. ...
bool m_topcon_AIMConfigured
Indicates if the AIM has been properly set up.
Contains classes for various device interfaces.
bool(CGPSInterface::*)(size_t &out_minimum_rx_buf_to_decide) ptr_parser_t
void enableSetupCommandsAppendCRLF(const bool enable)
void parseBuffer()
Process data in "m_buffer" to extract GPS messages, and remove them from the buffer.
bool sendCustomCommand(const void *data, const size_t datalen)
Send a custom data block to the GNSS device right now.
bool tryToOpenTheCOM()
Returns true if the COM port is already open, or try to open it in other case.
unsigned int m_JAVAD_rtk_src_baud
Only used when "m_JAVAD_rtk_src_port" is not empty.
std::string m_JAVAD_rtk_src_port
If not empty, will send a cmd "set,/par/pos/pd/port,...".
void setJAVAD_rtk_format(const std::string &s)
Only used when "m_JAVAD_rtk_src_port" is not empty: format of RTK corrections: "cmr", "rtcm", "rtcm3", etc.
bool isEnabledSetupCommandsAppendCRLF() const
std::string getRawDumpFilePrefix() const
mrpt::Clock::time_point TTimeStamp
A system independent time type, it holds the the number of 100-nanosecond intervals since January 1...
Definition: datetime.h:40
This class allows loading and storing values and vectors of different types from a configuration text...
void doProcess() override
This method will be invoked at a minimum rate of "process_rate" (Hz)
bool implement_parser_NMEA(size_t &out_minimum_rx_buf_to_decide)
Versatile class for consistent logging and management of output messages.
void setSetupCommands(const std::vector< std::string > &cmds)
void setSetupCommandsDelay(const double delay_secs)
std::string m_JAVAD_rtk_format
Only used when "m_JAVAD_rtk_src_port" is not empty: format of RTK corrections: "cmr", "rtcm", "rtcm3", etc.
std::shared_ptr< std::mutex > m_data_stream_mine_cs
bool implement_parser_NOVATEL_OEM6(size_t &out_minimum_rx_buf_to_decide)
#define MRPT_ENUM_TYPE_END()
Definition: TEnumType.h:78
This CStream derived class allow using a file as a write-only, binary stream.
bool OnConnectionEstablished()
Implements custom messages to be sent to the GPS unit just after connection and before normal use...
static bool parse_NMEA(const std::string &cmd_line, mrpt::obs::CObservationGPS &out_obs, const bool verbose=false)
Parses one line of NMEA data from a GPS receiver, and writes the recognized fields (if any) into an o...
std::vector< std::string > m_setup_cmds
void loadConfig_sensorSpecific(const mrpt::config::CConfigFileBase &configSource, const std::string &iniSection) override
See the class documentation at the top for expected parameters.
std::string getSerialPortName() const
Get the serial port to use (COM1, ttyUSB0, etc).
#define DEFINE_GENERIC_SENSOR(class_name)
This declaration must be inserted in all CGenericSensor classes definition, within the class declarat...
mrpt::io::CFileOutputStream m_raw_output_file
void setJAVAD_rtk_src_port(const std::string &s)
If not empty, will send a cmd "set,/par/pos/pd/port,...".
A class used to store a 3D pose (a 3D translation + a rotation in 3D).
Definition: CPose3D.h:85
bool isGPS_signalAcquired()
Returns true if the last message from the GPS indicates that the signal from sats has been acquired...
bool setJAVAD_AIM_mode()
Set Advanced Input Mode for the primary port.
std::shared_ptr< mrpt::io::CStream > m_data_stream
Typically a CSerialPort created by this class, but may be set externally.
std::string getLastGGA(bool reset=true)
Gets the latest GGA command or an empty string if no newer GGA command was received since the last ca...
double m_topcon_data_period
The period in seconds which the data should be provided by the GPS.
mrpt::containers::circular_buffer< uint8_t > m_rx_buffer
Auxiliary buffer for readings.
mrpt::system::TTimeStamp m_last_timestamp
std::vector< std::string > m_shutdown_cmds
This class stores messages from GNSS or GNSS+IMU devices, from consumer-grade inexpensive GPS receive...
#define MRPT_ENUM_TYPE_BEGIN(_ENUM_TYPE_WITH_NS)
Definition: TEnumType.h:62
std::string m_last_GGA
Used in getLastGGA()
bool m_topcon_useAIMMode
Use this mode for receive RTK corrections from a external source through the primary port...
void flushParsedMessagesNow()
Queue out now the messages in m_just_parsed_messages, leaving it empty.
MRPT_FILL_ENUM_MEMBER(CGPSInterface, NONE)
void setRawDumpFilePrefix(const std::string &filePrefix)
If set to non-empty, RAW GPS serial data will be also dumped to a separate file.
void setSerialPortName(const std::string &COM_port)
Set the serial port to use (COM1, ttyUSB0, etc).
void setParser(PARSERS parser)
Select the parser for incomming data, among the options enumerated in CGPSInterface.
const std::vector< std::string > & getShutdownCommands() const
void bindStream(const std::shared_ptr< mrpt::io::CStream > &external_stream, const std::shared_ptr< std::mutex > &csOptionalExternalStream=std::shared_ptr< std::mutex >())
This enforces the use of a given user stream, instead of trying to open the serial port set in this c...
void enableAppendMsgTypeToSensorLabel(bool enable)
static struct FontData data
Definition: gltext.cpp:144
void setShutdownCommands(const std::vector< std::string > &cmds)



Page generated by Doxygen 1.8.14 for MRPT 2.0.4 Git: 33de1d0ad Sat Jun 20 11:02:42 2020 +0200 at sáb jun 20 17:35:17 CEST 2020