GPS Device Interface. More...

#include <ArGPS.h>

Inherited by ArNovatelGPS [virtual], ArSimulatedGPS [virtual], and ArTrimbleGPS [virtual].

Public Types
enum	{ ReadFinished = ArNMEAParser::ParseFinished, ReadError = ArNMEAParser::ParseError, ReadData = ArNMEAParser::ParseData, ReadUpdated = ArNMEAParser::ParseUpdated }
	Flags to indicates what the read() method did. More...

Public Member Functions
bool	blockingConnect (unsigned long connectTimeout=20000)
	Same as connect(). More...

virtual bool	connect (unsigned long connectTimeout=20000)
	Check that the device connection (e.g. More...

ArDeviceConnection *	getDeviceConnection () const
	Return device connection in use (or NULL if none)

void	lock ()
	Locks a mutex object contained by this class. More...

void	logData () const
	Log last received data using ArLog. More...

void	printData (bool labels=true) const
	Print basic navigation data on one line to standard output, with no newline at end. More...

void	printDataLabelsHeader () const

virtual int	read (unsigned long maxTime=0)
	Read some data from the device connection, and update stored data as complete messages are received. More...

int	readWithLock (unsigned int maxTime)
	Calls lock(), calls read(maxTime), then calls unlock(). More...

void	setDeviceConnection (ArDeviceConnection *deviceConn)
	Set device connection to use.

void	setIgnoreChecksum (bool ignore)
	Set whether checksum sent with NMEA messages is ignored.

void	unlock ()
	Unlocks a mutex object contained by this class. More...

Public Attributes
enum ArGPS:: { ... }	ReadFlags
	Flags to indicates what the read() method did. More...

Protected Member Functions
virtual bool	initDevice ()
	Subclasses may override to send device initialization/configuration commands and set up device-specific message handlers. More...

bool	waitForData (unsigned long timeout)
	Block until data is read from GPS. More...

enum	FixType { NoFix, BadFix, GPSFix, DGPSFix, PPSFix, RTKinFix, FloatRTKinFix, DeadReckFix, ManualFix, SimulatedFix, UnknownFixType, OmnistarConverging = FloatRTKinFix, OmnistarConverged = RTKinFix }
	Data accessors. More...

Data	myData

ArMutex	myMutex

ArDeviceConnection *	myDevice

bool	myCreatedOwnDeviceCon

ArRetFunctorC< bool, ArGPS >	myParseArgsCallback

ArArgumentParser *	myArgParser

ArNMEAParser	myNMEAParser

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPRMCHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPGGAHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myPGRMEHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myPGRMZHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myHCHDxHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPGSAHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPGSVHandler

unsigned int	mySNRSum

unsigned short	mySNRNum

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPMSSHandler

ArFunctor1C< ArGPS, ArNMEAParser::Message >	myGPGSTHandler

const ArGPS::Data &	getCurrentDataRef () const
	Access all of the internally stored data directly. More...

FixType	getFixType () const
	(from NMEA GPGGA)

const char *	getFixTypeName () const
	(from NMEA GPGGA)

bool	havePosition () const
	(from NMEA GPRMC)

bool	haveLatitude () const
	(from NMEA GPRMC)

bool	haveLongitude () const
	(from NMEA GPRMC)

double	getLatitude () const

double	getLongitude () const

ArTime	getTimeReceivedPosition () const

bool	haveSpeed () const
	(from NMEA GPRMC)

double	getSpeed () const

ArTime	getGPSPositionTimestamp () const
	Timestamp provided by GPS device along with position. More...

int	getNumSatellitesTracked () const

bool	haveDGPSStation () const
	(from NMEA GPGGA)

unsigned short	getDGPSStationID () const
	(from NMEA GPGGA)

bool	haveGarminPositionError () const

double	getGarminPositionError () const
	GPS device's error estimation in meters (from a Garmin-specific message PGRME, most GPS receivers will not provide this)

bool	haveGarminVerticalPositionError () const

double	getGarminVerticalPositionError () const

bool	haveCompassHeadingMag () const
	Have a compass heading value relative to magnetic north. More...

bool	haveCompassHeadingTrue () const
	Have a compass heading value relative to true north (using GPS/compass device's configured declination). More...

double	getCompassHeadingMag () const
	Heading from magnetic north. More...

double	getCompassHeadingTrue () const
	Heading from true north. More...

void	setCompassHeadingMag (double val)
	Manually set compass value. More...

void	setCompassHeadingTrue (double val)
	Manually set compass value. More...

void	setCompassHeadingMagWithLock (double val)
	Manually set compass value. More...

void	setCompassHeadingTrueWithLock (double val)
	Manually set compass value. More...

bool	haveAltitude () const
	Altitude above sea level calculated from satellite positions (see also haveAltimiter()) (from NMEA GPGGA, if provided)

double	getAltitude () const
	Altitude above sea level (meters), calculated from satellite positions (see also getAltimiter()) (from NMEA GPGGA, if provided)

bool	haveAltimeter () const
	Some receivers may have an additional altitude from an altimiter (meters above sea level) (from PGRMZ, if receiver provides it)

double	getAltimeter () const
	Some receivers may have an additional altitude from an altimiter (meters above sea level) (from PGRMZ, if receiver provides it)

bool	haveHDOP () const
	(from NMEA GPGGA)

double	getHDOP () const
	(from NMEA GPGGA)

bool	haveVDOP () const
	(from NMEA GPGGA)

double	getVDOP () const
	(from NMEA GPGGA)

bool	havePDOP () const
	(from NMEA GPGGA)

double	getPDOP () const
	(from NMEA GPGGA)

bool	haveSNR () const
	(from NMEA GPGSV)

double	getMeanSNR () const
	dB (from NMEA GPGSV)

bool	haveBeaconInfo () const
	Whether we have any DGPS stationary beacon info (from NMEA GPMSS)

double	getBeaconSignalStrength () const
	DGPS stationary beacon signal strength (dB) (from NMEA GPMSS)

double	getBeaconSNR () const
	DGPS stationary beacon signal to noise (dB) (from NMEA GPMSS)

double	getBeaconFreq () const
	DGPS stationary beacon frequency (kHz) (from NMEA GPMSS)

unsigned short	getBecaonBPS () const
	DGPS stationary beacon bitrate (bits per second) (from NMEA GPMSS)

unsigned short	getBeaconChannel () const
	DGPS stationary beacon channel (from NMEA GPMSS)

bool	haveErrorEllipse () const
	Whether we have a position error estimate (as standard deviations in latitude and longitude) (from NMEA GPGST)

ArPose	getErrorEllipse () const
	Standard deviation of position error (latitude and longitude), meters. More...

bool	haveLatLonError () const
	Whether we have latitude or longitude error estimates (from NMEA GPGST)

ArPose	getLatLonError () const
	Standard deviation of latitude and longitude error, meters. More...

double	getLatitudeError () const
	Standard deviation of latitude and longitude error, meters. More...

double	getLongitudeError () const
	Standard deviation of latitude and longitude error, meters. More...

bool	haveAltitudeError () const

double	getAltitudeError () const
	Standard deviation of altitude error, meters. (from NMEA GPGST, if provided)

bool	haveInputsRMS () const
	(from NMEA GPGST)

double	getInputsRMS () const
	(from NMEA GPGST)

void	addNMEAHandler (const char message, ArNMEAParser::Handler handler)
	Set a handler for an NMEA message. More...

void	removeNMEAHandler (const char *message)

void	replaceNMEAHandler (const char message, ArNMEAParser::Handler handler)

bool	readFloatFromString (const std::string &str, double target, double(convf)(double)=NULL) const

bool	readUShortFromString (const std::string &str, unsigned short target, unsigned short(convf)(unsigned short)=NULL) const

bool	readFloatFromStringVec (const std::vector< std::string > vec, size_t i, double target, double(*convf)(double)=NULL) const

bool	readUShortFromStringVec (const std::vector< std::string > vec, size_t i, unsigned short target, unsigned short(*convf)(unsigned short)=NULL) const

void	handleGPRMC (ArNMEAParser::Message msg)

void	handleGPGGA (ArNMEAParser::Message msg)

void	handlePGRME (ArNMEAParser::Message msg)

void	handlePGRMZ (ArNMEAParser::Message msg)

void	handleHCHDx (ArNMEAParser::Message msg)

void	handleGPGSA (ArNMEAParser::Message msg)

void	handleGPGSV (ArNMEAParser::Message msg)

void	handleGPMSS (ArNMEAParser::Message msg)

void	handleGPGST (ArNMEAParser::Message msg)

bool	readTimeFromString (const std::string &s, ArTime *time) const

void	parseGPRMC (const ArNMEAParser::Message &msg, double &latitudeResult, double &longitudeResult, bool &qualityFlagResult, bool &gotPosition, ArTime &timeGotPositionResult, ArTime &gpsTimestampResult, bool &gotSpeedResult, double &speedResult)
	Parse a GPRMC message (in msg) and place results in provided variables. More...

static const char *	getFixTypeName (FixType type)

static double	gpsDegminToDegrees (double degmin)

static double	knotsToMPS (double knots)

static double	mpsToMph (const double mps)
	Convert meters per second to miles per hour.

static double	metersToFeet (double m)

static double	feetToMeters (double f)

Detailed Description

GPS Device Interface.

Connects to GPS device over a serial port or other device connection and reads data. Supports GPS devices sending standard NMEA format data (specifically the GPRMC, GPGGA, GPGSA, GPGRME, and optionally GPGSV, PGRMZ, PGRME, HCHDG/T/M and GPHDG/T/M messages). If your GPS device supports several data formats or modes, select NMEA output in its configuration.

The preferred method of creating and setting up a new ArGPS object is to use ArGPSConnector, which creates an instance of ArGPS or a subclass, and creates and opens its device connection, based on command-line parameters. (To manually create an ArGPS object, create an ArDeviceConnection instance and call setDeviceConnection(), then open that device connection and call connect().

For either method, to get new data from the GPS, must call read() or readWithLock() periodically, ideally at a rate equal to or faster than your GPS sends data (usually one second). You can do this from a Sensor Intetrpretation Task in ArRobot, or a seperate thread. If you are calling read() from a loop in a new thread,

Here is an example of calling readWithLock() from a sensor interpretation task. The integer argument given to the functor constructor is a milisecond timeout that is passed to readWithLock() and prevents it from blocking too long if it doesn't read any data. It is important to do this in a robot task, or the robot task cycle will be blocked and cause problems.

ArRetFunctor1C<ArGPS, int, unsigned int> gpsReadFunc(myGPS, &ArGPS::readWithLock, 10);

myRobot->addSensorInterpretationTask("GPS read", 100, &gpsReadFunc);

If you use your own loop or thread, then it ought to include a call to ArUtil::sleep() for at least several hundred miliseconds to avoid starving other threads, since read() will return immediately if there is no data to read rather than blocking.

For each piece of data provided by this class, there is a flag indicating whether it was received from the GPS and set. Not all GPS models return all kinds of information, or it may be disabled in some way in a GPS's internal configuration, or the GPS may not yet have started sending the data (e.g. still acquiring satellites). Also, not all data will be received by one call to read(), and especially immediately after connecting and starting to read data, it may take a few seconds for data to be obtained. Furthermore, it may take some time for the GPS to calculate data with full accuracy.

See also: gpsExample.cpp; gpsRobotTaskExample.cpp

This class is not inherently thread safe. Stored data is updated by read(), so if accessing from multiple threads, call lock() before calling any data accessor methods (methods starting with "get"), or read(), and call unlock() when done. You can also call readWithLock() to do a locked read in one function call.

Note: ArGPS only provides access to the data reported by a GPS. The position reported by a GPS is in degrees on the surface of the earth (WGS84 datum), not in the cartesian coordinate system used by the robot odometry or ArMap. You can use the subclasses of Ar3DPoint (ArLLACoords, etc) to convert between different geographical coordinate systems, which may help you match GPS coordinates to the robot pose coordinate system.

Examples:: gpsExample.cpp, and gpsRobotTaskExample.cpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Flags to indicates what the read() method did.

i.e. If nothing was done, then the result will be 0. To check a read() return result result to see if data was updated, use (result & ReadUpdated). To check if there was an error, use (result & ReadError).

These happen to match the flags in ArNMEAParser.

◆ FixType

enum ArGPS::FixType

Data accessors.

Access the last received data from the GPS

Member Function Documentation

◆ addNMEAHandler()

void ArGPS::addNMEAHandler	(	const char *	message,
		ArNMEAParser::Handler *	handler
	)

inline

Set a handler for an NMEA message.

Mostly for internal use or to be used by related classes, but you could use for ususual or custom messages emitted by a device that you wish to be handled outside of the ArGPS class.

◆ blockingConnect()

bool ArGPS::blockingConnect ( unsigned long connectTimeout = 20000 )

inline

Same as connect().

See connect().

◆ connect()

bool ArGPS::connect ( unsigned long connectTimeout = 20000 )

virtual

Check that the device connection (e.g.

serial port) is open, and that data is being received from GPS.

Subclasses may override this method so that device-specific initialization commands may be sent.

Returns: false if there is no device connection or the device connection is not open, or if there is an error sending device initialization commands, or if no data is received after calling read() every 100 ms for connectTimeout ms. Otherwise, return true.

See also: blockingConnect()

Examples:: gpsExample.cpp, and gpsRobotTaskExample.cpp.

◆ getCompassHeadingMag()

double ArGPS::getCompassHeadingMag ( ) const

inline

Heading from magnetic north.

Note: The GPS or compass device must be configured to send HCHDM messages to receive compass data. Only some GPS receivers support this.

◆ getCompassHeadingTrue()

double ArGPS::getCompassHeadingTrue ( ) const

inline

Heading from true north.

Note: The GPS or compass device must be configured to send HCHDT messages to receive compass data. Only some GPS receivers support this.

◆ getCurrentDataRef()

const ArGPS::Data& ArGPS::getCurrentDataRef ( ) const

inline

Access all of the internally stored data directly.

See also: ArGPS::Data

◆ getErrorEllipse()

ArPose ArGPS::getErrorEllipse ( ) const

inline

Standard deviation of position error (latitude and longitude), meters.

Theta in ArPose is orientation of ellipse from true north, Y is the length of the major axis on that orientation, X the minor. (from NMEA GPGST)

Note: Values may be inf or NaN (if GPS supplies "Inf" or "NAN")

◆ getGarminVerticalPositionError()

double ArGPS::getGarminVerticalPositionError ( ) const

inline

Returns: An altitude error estimation (from a Garmin-specific message PGRME, most GPS receivers will not provide this)

◆ getGPSPositionTimestamp()

ArTime ArGPS::getGPSPositionTimestamp ( ) const

inline

Timestamp provided by GPS device along with position.

(from NMEA GPRMC)

◆ getLatitude()

double ArGPS::getLatitude ( ) const

inline

Returns: latitude in decimal degrees. (from NMEA GPRMC)

◆ getLatitudeError()

double ArGPS::getLatitudeError ( ) const

inline

Standard deviation of latitude and longitude error, meters.

Theta value in ArPose is unused.

Note: May only be provided by GPS in certain fix modes (e.g. Trimble AgGPS provides it in Omnistar and RTK modes, but not in GPS or DGPS modes).; Values may be inf or NaN (if GPS supplies "Inf" or "NAN") (from NMEA GPGST)

◆ getLatLonError()

ArPose ArGPS::getLatLonError ( ) const

inline

Standard deviation of latitude and longitude error, meters.

Theta value in ArPose is unused.

Note: May only be provided by GPS in certain fix modes (e.g. Trimble AgGPS provides it in Omnistar and RTK modes, but not in GPS or DGPS modes).; Values may be inf or NaN (if GPS supplies "Inf" or "NAN") (from NMEA GPGST)

◆ getLongitude()

double ArGPS::getLongitude ( ) const

inline

Returns: longitude in decimal degrees. (from NMEA GPRMC)

◆ getLongitudeError()

double ArGPS::getLongitudeError ( ) const

inline

Standard deviation of latitude and longitude error, meters.

Theta value in ArPose is unused.

Note: May only be provided by GPS in certain fix modes (e.g. Trimble AgGPS provides it in Omnistar and RTK modes, but not in GPS or DGPS modes).; Values may be inf or NaN (if GPS supplies "Inf" or "NAN") (from NMEA GPGST)

◆ getSpeed()

double ArGPS::getSpeed ( ) const

inline

Returns: GPS' measured speed converted to meters per second, if provided (from NMEA GPRMC, if provided)

◆ getTimeReceivedPosition()

ArTime ArGPS::getTimeReceivedPosition ( ) const

inline

Returns: copy of an ArTime object set to the time that ArGPS read and received latitude and longitude data from the GPS. (from NMEA GPRMC)

◆ haveCompassHeadingMag()

bool ArGPS::haveCompassHeadingMag ( ) const

inline

Have a compass heading value relative to magnetic north.

Note: The GPS or compass device must be configured to send HCHDM messages to receive compass data. Only some GPS receivers support this.

◆ haveCompassHeadingTrue()

bool ArGPS::haveCompassHeadingTrue ( ) const

inline

Have a compass heading value relative to true north (using GPS/compass device's configured declination).

Note: The GPS or compass device must be configured to send HCHDT messages to receive compass data. Only some GPS receivers support this.

◆ haveGarminPositionError()

bool ArGPS::haveGarminPositionError ( ) const

inline

Returns: whether GPS provided a distance error estimation (from a Garmin-specific message PGRME, most GPS receivers will not provide this)

◆ haveGarminVerticalPositionError()

bool ArGPS::haveGarminVerticalPositionError ( ) const

inline

Returns: whether GPS provided an altitude error estimation (from a Garmin-specific message PGRME, most GPS receivers will not provide this)

◆ initDevice()

virtual bool ArGPS::initDevice ( )

inlineprotectedvirtual

Subclasses may override to send device initialization/configuration commands and set up device-specific message handlers.

(Default behavior is to do nothing and return true.)

◆ lock()

void ArGPS::lock ( )

inline

Locks a mutex object contained by this class.

No other method (except readWithLock()) in ArGPS locks or unlocks this mutex, it is provided for you to use when accessing ArGPS from multiple threads.

◆ logData()

void ArGPS::logData ( ) const

Log last received data using ArLog.

◆ parseGPRMC()

void ArGPS::parseGPRMC	(	const ArNMEAParser::Message &	msg,
		double &	latitudeResult,
		double &	longitudeResult,
		bool &	qualityFlagResult,
		bool &	gotPosition,
		ArTime &	timeGotPositionResult,
		ArTime &	gpsTimestampResult,
		bool &	gotSpeedResult,
		double &	speedResult
	)

protected

Parse a GPRMC message (in msg) and place results in provided variables.

(Can be used by subclasses to store results of GPRMC differently than normal.)

Since: Aria 2.7.2

◆ printData()

void ArGPS::printData ( bool labels = true ) const

Print basic navigation data on one line to standard output, with no newline at end.

Examples:: gpsExample.cpp.

◆ read()

int ArGPS::read ( unsigned long maxTime = 0 )

virtual

Read some data from the device connection, and update stored data as complete messages are received.

Parameters

maxTime If nonzero, return when this time limit is reached, even if there is still data available to read. If zero, then don't return until all available data has been exhausted or an error occurs. Be careful setting this parameter to 0: read() could block for an arbitrary amount of time, even forever if for some reason data is recieved from the device faster than read() can read and parse it.

Returns: A mask of ReadFlags codes, combined with bitwise or (|), or 0 if no attempt to read from the device occured (for example because the maxTime timeout was reached before the first attempt to read occured). The flags will include ReadError if there was as error reading from the device connection, ReadData if some data was read, ReadUpdated if data was read and a full message was successfully read and stored data was updated in ArGPS, ReadFinished if all available data was read.

Examples:: gpsExample.cpp.

◆ readWithLock()

int ArGPS::readWithLock ( unsigned int maxTime )

inline

Calls lock(), calls read(maxTime), then calls unlock().

Note, this could end up keeping ArGPS locked until maxTime is reached, or for any amount of time if maxTime is 0, so watch out for that.

◆ setCompassHeadingMag()

void ArGPS::setCompassHeadingMag ( double val )

inline

Manually set compass value.

◆ setCompassHeadingMagWithLock()

void ArGPS::setCompassHeadingMagWithLock ( double val )

inline

Manually set compass value.

◆ setCompassHeadingTrue()

void ArGPS::setCompassHeadingTrue ( double val )

inline

Manually set compass value.

◆ setCompassHeadingTrueWithLock()

void ArGPS::setCompassHeadingTrueWithLock ( double val )

inline

Manually set compass value.

◆ unlock()

void ArGPS::unlock ( )

inline

Unlocks a mutex object contained by this class.

No other method (except readWithLock()) in ArGPS locks or unlocks this mutex, it is provided for you to use when accessing ArGPS from multiple threads.

◆ waitForData()

bool ArGPS::waitForData ( unsigned long timeout )

protected

Block until data is read from GPS.

Waits by calling read() every 100 ms for timeout ms.

Member Data Documentation

◆ ReadFlags

enum { ... } ArGPS::ReadFlags

Flags to indicates what the read() method did.

i.e. If nothing was done, then the result will be 0. To check a read() return result result to see if data was updated, use (result & ReadUpdated). To check if there was an error, use (result & ReadError).

These happen to match the flags in ArNMEAParser.

The documentation for this class was generated from the following files:

ArGPS.h
ArGPS.cpp

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ FixType

Member Function Documentation

◆ addNMEAHandler()

◆ blockingConnect()

◆ connect()

◆ getCompassHeadingMag()

◆ getCompassHeadingTrue()

◆ getCurrentDataRef()

◆ getErrorEllipse()

◆ getGarminVerticalPositionError()

◆ getGPSPositionTimestamp()

◆ getLatitude()

◆ getLatitudeError()

◆ getLatLonError()

◆ getLongitude()

◆ getLongitudeError()

◆ getSpeed()

◆ getTimeReceivedPosition()

◆ haveCompassHeadingMag()

◆ haveCompassHeadingTrue()

◆ haveGarminPositionError()

◆ haveGarminVerticalPositionError()

◆ initDevice()

◆ lock()

◆ logData()

◆ parseGPRMC()

◆ printData()

◆ read()

◆ readWithLock()

◆ setCompassHeadingMag()

◆ setCompassHeadingMagWithLock()

◆ setCompassHeadingTrue()

◆ setCompassHeadingTrueWithLock()

◆ unlock()

◆ waitForData()

Member Data Documentation

◆ ReadFlags