Class CGPSInterface

Inheritance Relationships

Base Types

Class Documentation

class CGPSInterface : public mrpt::system::COutputLogger, public mrpt::hwdrivers::CGenericSensor

A class capable of reading GPS/GNSS/GNSS+IMU receiver data, from a serial port or from any input stream, and parsing the ASCII/binary stream into indivual messages stored in mrpt::obs::CObservationGPS objects.

Typical input streams are serial ports or raw GPS log files. By default, the serial port selected by CGPSInterface::setSerialPortName() or as set in the configuration file will be open upon call to CGenericSensor::initialize(). Alternatively, an external stream can be bound with CGPSInterface::bindStream() before calling CGenericSensor::initialize(). This feature can be used to parse commands from a file, a TCP/IP stream, a memory block, etc.

The parsers in the enum type CGPSInterface::PARSERS are supported as parameter parser in the configuration file below or in method CGPSInterface::setParser():

  • NONE: Do not try to parse the messages into CObservation’s. Only useful if combined with raw_dump_file_prefix

  • AUTO: Try to automatically identify the format of incoming data.

  • NMEA (NMEA 0183, ASCII messages): Default parser. Supported frames: GGA, RMC,… See full list of messages in children of mrpt::obs::gnss::gnss_message

  • NOVATEL_OEM6 (Novatel OEM6, binary frames): Supported frames: BESTPOS,… Note that receiving a correct IONUTC msg is required for a correct timestamping of subsequent frames. See full list of messages in children of mrpt::obs::gnss::gnss_message

See available parameters below, and an example config file for rawlog-grabber here

 PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
-------------------------------------------------------
[supplied_section_name]

 # Serial port configuration:
 COM_port_WIN = COM3
 COM_port_LIN = ttyUSB0
 baudRate     = 4800   // The baudrate of the communications (typ. 4800 or
9600 bauds)

 # (Default:true) Whether to append the GNSS message type to CObservation
`sensorLabel` field
 sensor_label_append_msg_type = true

 # Select a parser for GNSS data:
 # Up-to-date list of supported parsers available in
https://reference.mrpt.org/devel/classmrpt_1_1hwdrivers_1_1_c_g_p_s_interface.html
 parser =  AUTO

 # If uncommented and non-empty, raw binary/ascii data received from the
serial port will be also dumped
 # into a file named after this prefix, plus date/time and extension `.gps`.
 #raw_dump_file_prefix = RAWGPS

 # 3D position (and orientation, for GNSS+IMUs) of the sensed point (antenna
phase center) relative to the vehicle/robot frame:
 pose_x       = 0      // (meters)
 pose_y       = 0
 pose_z       = 0
 pose_yaw     = 0      // (deg)
 pose_pitch   = 0
 pose_roll    = 0

 # Optional: list of custom commands to be sent to the GNSS receiver to set
it up.
 # An arbitrary number of commands can be defined, but their names must be
"setup_cmd%d" starting at "1".
 # Commands will be sent by index order. Binary commands instead of ASCII
strings can be set programmatically, not from a config file.
 # custom_cmds_delay   = 0.1   // (Default=0.1) Delay in seconds between
consecutive set-up commands
 # custom_cmds_append_CRLF = true    // (Default:true) Append "\r\n" to each
command
 # setup_cmd1 = XXXXX
 # setup_cmd2 = XXXXX
 # setup_cmd3 = XXXXX

 # Optional: list of commands to be sent upon disconnection (e.g. object
destructor)
 # shutdown_cmd1 = XXXX
 # shutdown_cmd2 = XXXX

Note that the customInit field, supported in MRPT <1.4.0 will be still parsed and obeyed, but since it has been superseded by the new mechanism to establish set-up commands, it is no further documented here.

The next picture summarizes existing MRPT classes related to GPS / GNSS devices (CGPSInterface, CNTRIPEmitter, CGPS_NTRIP):

../../output_staging/generated/doxygen/xml/mrpt_gps_classes_usage.png

VERSIONS HISTORY:

  • 09/JUN/2006: First version (JLBC)

  • 04/JUN/2008: Added virtual methods for device-specific initialization commands.

  • 10/JUN/2008: Converted into CGenericSensor class (there are no inhirited classes anymore).

  • 07/DEC/2012: Added public static method to parse NMEA strings.

  • 17/JUN/2014: Added GGA feedback.

  • 01/FEB/2016: API changed for MTPT 1.4.0

    See also

    CGPS_NTRIP, CNTRIPEmitter, mrpt::obs::CObservationGPS

Note

Verbose debug info will be dumped to cout if the environment variable “MRPT_HWDRIVERS_VERBOSE” is set to “1”, or if you call CGenericSensor::enableVerbose(true)

Note

Note

[API changed in MRPT 1.4.0] mrpt::hwdrivers::CGPSInterface API clean-up and made more generic so any stream can be used to parse GNSS messages, not only serial ports.

Set-up and configuration

void setSerialPortName(const std::string &COM_port)

Set the serial port to use (COM1, ttyUSB0, etc).

std::string getSerialPortName() const

Get the serial port to use (COM1, ttyUSB0, etc).

void setParser(PARSERS parser)

Select the parser for incoming data, among the options enumerated in CGPSInterface

PARSERS getParser() 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 class parameters.

Note

Call before CGenericSensor::initialize()

Parameters:

csExternalStream – [in] If not NULL, read/write operations to the stream will be guarded by this critical section. The stream object is not deleted. It is the user responsibility to keep that object allocated during the entire life of this object.

inline bool useExternalStream() const
void setSetupCommandsDelay(const double delay_secs)
double getSetupCommandsDelay() const
void setSetupCommands(const std::vector<std::string> &cmds)
const std::vector<std::string> &getSetupCommands() const
void setShutdownCommands(const std::vector<std::string> &cmds)
const std::vector<std::string> &getShutdownCommands() const
void enableSetupCommandsAppendCRLF(const bool enable)
bool isEnabledSetupCommandsAppendCRLF() const
inline void enableAppendMsgTypeToSensorLabel(bool enable)
inline void setRawDumpFilePrefix(const std::string &filePrefix)

If set to non-empty, RAW GPS serial data will be also dumped to a separate file.

inline std::string getRawDumpFilePrefix() const
bool sendCustomCommand(const void *data, size_t datalen)

Send a custom data block to the GNSS device right now. Can be used to change its behavior online as needed.

Returns:

false on communication error

Parser implementations: each method must try to parse the first

bytes in the incoming buffer, and return false if the available data does not match the expected format, so we must skip 1 byte and try again.

bool implement_parser_NMEA(size_t &out_minimum_rx_buf_to_decide)
bool implement_parser_NOVATEL_OEM6(size_t &out_minimum_rx_buf_to_decide)

Public Types

enum PARSERS

Read about parser selection in the documentation for CGPSInterface

Values:

enumerator NONE
enumerator AUTO
enumerator NMEA
enumerator NOVATEL_OEM6
using ptr_parser_t = bool (CGPSInterface::*)(size_t &out_minimum_rx_buf_to_decide)

Public Functions

CGPSInterface()

Default ctor

~CGPSInterface() override

Dtor

virtual void doProcess() override

This method will be invoked at a minimum rate of “process_rate” (Hz)

Throws:

This – method must throw an exception with a descriptive message if some critical error is found.

bool isGPS_connected()

Returns true if communications work, i.e. if some message has been received.

inline bool isAIMConfigured()
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 call to this method.

Parameters:

reset – [in] If set to true, will empty the GGA cache so next calls will return an empty string if no new frame is received.

Public Static Functions

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 observation object. Recognized frame types are those listed for the NMEA parser in the documentation of CGPSInterface

Returns:

true if some new data field has been correctly parsed and inserted into out_obs

Protected Functions

bool OnConnectionEstablished()

Implements custom messages to be sent to the GPS unit just after connection and before normal use. Returns false or raise an exception if something goes wrong.

bool OnConnectionShutdown()

Like OnConnectionEstablished() for sending optional shutdown commands

bool legacy_topcon_setup_commands()
virtual void loadConfig_sensorSpecific(const mrpt::config::CConfigFileBase &configSource, const std::string &iniSection) override

See the class documentation at the top for expected parameters

inline void setJAVAD_rtk_src_port(const std::string &s)

If not empty, will send a cmd “set,/par/pos/pd/port,…”. Example value: “/dev/ser/b”

inline void setJAVAD_rtk_src_baud(unsigned int baud)

Only used when “m_JAVAD_rtk_src_port” is not empty

inline 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 setJAVAD_AIM_mode()

Set Advanced Input Mode for the primary port. This can be used to send RTK corrections to the device using the same port that it’s used for the commands. The RTK correction stream must be re-packaged into a special frame with prefix “>>”

bool unsetJAVAD_AIM_mode()

Unset Advanced Input Mode for the primary port and use it only as a command port.

Protected Attributes

std::shared_ptr<mrpt::io::CStream> m_data_stream

Typically a CSerialPort created by this class, but may be set externally.

std::shared_ptr<std::mutex> m_data_stream_cs
std::shared_ptr<std::mutex> m_data_stream_mine_cs = std::make_shared<std::mutex>()
bool m_data_stream_is_external = {false}
poses::CPose3D m_sensorPose
std::string m_customInit