class mrpt::hwdrivers::CGPSInterface

Overview

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):

_images/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

    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)

    [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.

See also:

CGPS_NTRIP, CNTRIPEmitter, mrpt::obs::CObservationGPS

#include <mrpt/hwdrivers/CGPSInterface.h>

class CGPSInterface:
    public mrpt::system::COutputLogger,
    public mrpt::hwdrivers::CGenericSensor
{
public:
    // typedefs

    typedef bool(CGPSInterface::*)(size_t&out_minimum_rx_buf_to_decide) ptr_parser_t;

    // enums

    enum PARSERS;

    // construction

    CGPSInterface();

    // methods

    void setSerialPortName(const std::string& COM_port);
    std::string getSerialPortName() const;
    void setParser(PARSERS parser);
    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>()
        );

    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;
    void enableAppendMsgTypeToSensorLabel(bool enable);
    void setRawDumpFilePrefix(const std::string& filePrefix);
    std::string getRawDumpFilePrefix() const;
    bool sendCustomCommand(const void* data, size_t datalen);
    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);
    virtual void doProcess();
    bool isGPS_connected();
    bool isAIMConfigured();
    std::string getLastGGA(bool reset = true);
    static bool parse_NMEA(const std::string& cmd_line, mrpt::obs::CObservationGPS& out_obs, const bool verbose = false);
};

Inherited Members

public:
    // structs

    struct TMsg;

    // methods

    CGenericSensor& operator = (const CGenericSensor&);
    virtual void doProcess() = 0;

Construction

CGPSInterface()

Default ctor.

Methods

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.

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.

Call before CGenericSensor::initialize()

Parameters:

csExternalStream

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.

 
void setRawDumpFilePrefix(const std::string& filePrefix)

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

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. Can be used to change its behavior online as needed.

Returns:

false on communication error

virtual void doProcess()

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

Parameters:

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.

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

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

 
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