The GPS Class is designed to work with the Adafruit Ultimate GPS Hat. This page documents the public API of the GPS Class.
GPS gps = new GPS();
Commands
The class supports several methods which write command strings to the GPS module.
SetSentencesReportingAsync
This is an asynchronous method with a return type of Task. SetSentencesReportingAsync issues the PMTK314 command to the GPS module.
The method takes 6 arguments, each of which is the frequency of update for the corresponding NMEA sentence type. each argument takes an integer value of 0 to 5, where
0: for no sentence reporting
1: once every position fix
2: once for every two position fixes
3..5: once for every 3 to 5 position fixes
The arguments, in order, are
GLLfreqRMCfreqVTGfreqGGAfreqGSAfreqGSVfreq
public async Task SetSentencesReportingAsync(int GLLfreq, int RMCfreq, int VTGfreq, int GGAfreq, int GSAfreq, int GSVfreq)
SetUpdateFrequencyAsync
This is an asynchronous method with a return type of Task. SetUpdateFrequencyAsync issues the PMTK220 command to the GPS module.
The method takes a single argument of type double, which is the desired location reporting frequency in Hz. Values range from 0.1 to 10, where 0.1 is one location update every ten seconds, and 10 is 10 location updates per second.
public async Task SetUpdateFrequencyAsync(double freqHz)
SetBaudRateAsync
This is an asynchronous method with a return type of Task. SetBaudRateAsync issues the PMTK251 command to the GPS module.
The method takes a single argument of type unsigned integer, which is the desired baudrate setting for the GPS module. Note that this is the baudrate setting of the module itself, and does not affect the baud rate of the host computer.
public async Task SetBaudRateAsync(uint baudrate)
SendPMTKCommandAsync
This is an asynchronous method with a return type of Task. SendPMTKCommandAsync is a generic routine for sending an arbitrary PMTK command to the GPS module.
The method takes a single argument of type string, which is the text of the PMTK command. the command string must be a complete PMTK command, including the leading '$', the checksum, and the trailing characters.
See this link for a PMTK checksum calculator.
public async Task SendPMTKCommandAsync(string pmtk)
Serial Control
Connected
A simple predicate property, taking no aruments, which returns true if the serial port on the host computer has been successfully opened. Note that this does not necessarily mean that communications with the GPS module have been established. Serial ports by nature are connectionless. This command assumes that the GPS is correctly attached to the host computer and is operational.
public bool Connected
ConnectToUARTAsync
This is an asynchronous method with a return type of Task. The method is used to open a serial port object on the hoat computer.
the method takes two optional arguments: a baudrate of type unsigned integer, and a UART ID of type string. Default values are 9600 baud and "UART0". "UART0" identifies the built-in Raspberry Pi serial port.
Call this method once to open a serial connection to the GPS module.
public async Task ConnectToUARTAsync(uint baudRate = 9600, string uartID = "UART0")
StartReading
This is a syncronous method that launches the GPS read task. After a successful call to ConnectToUART, call this method to begin reading GPS data.
public void StartReading()
StopReading
This is a syncronous method that cancels the GPS read task. Call this method to stop reading GPS data.
public void StopReading()
DisconnectFromUART
This is a synchronous method that stops reading the GPS and closes and disposes the serial port object. After calling this method, you must again call ConnectToUART and StartReading to resume receiving GPS data
public void DisconnectFromUART()
Data Classes
There is a data class associated with each type of NMEA sentence recognized by the GPS Class. Sentences are parsed and the results made available in objects of these types.
The GPS Class only supports the fiollowing NMEA sentence types: RMC, GGA, GLL, VTG, GSA, and GSV.
For details on the contents of these NMEA sentences, please see this page: http://aprs.gids.nl/nmea/
GPSRMC
This is a data class defined within the GPS Class. Objects of this type are used to return parsed RMC sentence information to the host application. The following properties of the class are defined:
public DateTime TimeStamp { get; set; }
public bool Valid { get; set; }
public double? Latitude { get; set; }
public string LatHemisphere { get; set; }
public double? Longitude { get; set; }
public string LonHemisphere { get; set; }
public double? Speed { get; set; }
public double? Course { get; set; }
public DateTime DateStamp { get; set; }
public double? MagVariation { get; set; }
public string VarDirection { get; set; }
public double? LatDegrees { get; set; }
public double? LonDegrees { get; set; }
GPSGGA
This is a data class defined within the GPS Class. Objects of this type are used to return parsed GGA sentence information to the host application. The following properties of the class are defined:
public enum FixQuality { noFix = 0, gpsFix = 1, dgpsFix = 2 }
public DateTime TimeStamp { get; set; }
public double? Latitude { get; set; }
public string LatHemisphere { get; set; }
public double? Longitude { get; set; }
public string LonHemisphere { get; set; }
public FixQuality Quality { get; set; }
public int? Satellites { get; set; }
public double? Dilution { get; set; }
public double? Altitude { get; set; }
public string AltUnits { get; set; }
public double? Geoidal { get; set; }
public string GeoidalUnits { get; set; }
public double? DGPSAge { get; set; }
public int? DGPS_ID { get; set; }
public double? LatDegrees { get; set; }
public double? LonDegrees { get; set; }
GPSGLL
This is a data class defined within the GPS Class. Objects of this type are used to return parsed GLL sentence information to the host application. The following properties of the class are defined:
public DateTime TimeStamp { get; set; }
public bool Valid { get; set; }
public double? Latitude { get; set; }
public string LatHemisphere { get; set; }
public double? Longitude { get; set; }
public string LonHemisphere { get; set; }
public double? LatDegrees { get; set; }
public double? LonDegrees { get; set; }
GPSVTG
This is a data class defined within the GPS Class. Objects of this type are used to return parsed VTG sentence information to the host application. The following properties of the class are defined:
public double? TrackTrue { get; set; }
public string TT { get; set; }
public double? TrackMag { get; set; }
public string TM { get; set; }
public double? SpeedKnots { get; set; }
public string SKn { get; set; }
public double? SpeedKm { get; set; }
public string SKm { get; set; }
public string Mode { get; set; }
GPSGSA
This is a data class defined within the GPS Class. Objects of this type are used to return parsed GSA sentence information to the host application. The following properties of the class are defined:
public enum FixType { noFix = 1, fix2D = 2, fix3D = 3 }
public string Mode { get; set; }
public FixType Fix { get; set; }
public List<int?> SVIDs { get; set; }
public double? PDOP { get; set; }
public double? HDOP { get; set; }
public double? VDOP { get; set; }
GPSGSV
This is a data class defined within the GPS Class. Objects of this type are used to return parsed GSV sentence information to the host application. The following properties of the class are defined:
public int? MsgCount { get; set; }
public int? MsgNumber { get; set; }
public int? Satellites { get; set; }
public List<SVRecord> SVList { get; set; }
The SVList property contains a list of SVRecord objects The SVRecord class is defined within the GPSGSV class.
The list may be up to 4 elements in length. The properties of the SVRecord class are as follows:
public int? PRN { get; set; }
public int? Elevation { get; set; }
public int? Azimuth { get; set; }
public int? SNR { get; set; }
Event Handlers
When an NMEA sentence is successfully received and parsead, the GPS Class issues an event containing the data class associated with that sentence. The events are as follows:
public event RMCEventHandler RMCEvent; public event GLLEventHandler GLLEvent; public event VTGEventHandler VTGEvent; public event GGAEventHandler GGAEvent; public event GSAEventHandler GSAEvent; public event GSVEventHandler GSVEvent;
To use these events, define an event handler in your code, and add that handler to the event list. Event handlers take two aruments, the sending object, and the sentence data class.
A sample event handler follows:
private void OnGGAEvent(object sender, GPS.GPSGGA GGA)
{
if (GGA.Quality != GPS.GPSGGA.FixQuality.noFix)
{
AltitudeTextBox.Text = GGA.Altitude.ToString();
SatellitesTextBox.Text = GGA.Satellites.ToString();
AltUnitsTextBox.Text = GGA.AltUnits;
}
else
{
AltitudeTextBox.Text = "";
SatellitesTextBox.Text = "";
AltUnitsTextBox.Text = "";
}
}
Associate your handler with the event by adding it to the event list:
gps.GGAEvent += OnGGAEvent;
