GPS Class

The GPS Class is designed to work with the Adafruit Ultimate GPS Hat. This page documents the public API of the GPS Class.

Adafruit Ultimate GPS HAT for Raspberry Pi A+/B+/Pi 2/Pi 3

PRODUCT ID: 2324
It's 10PM, do you know where your Raspberry Pi is? If you had this GPS HAT, you would! This new HAT from Adafruit adds our celebrated Ultimate GPS on it, so you can add...
$44.95
IN STOCK

Constructor

The class has a single constructor, GPS(), which takes no arguments. Example:

Download: file
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

GLLfreq
RMCfreq
VTGfreq
GGAfreq
GSAfreq
GSVfreq

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
public void StartReading()

StopReading

This is a syncronous method that cancels the GPS read task.  Call this method to stop reading GPS data.

Download: file
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

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
 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:

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
gps.GGAEvent += OnGGAEvent;
This guide was first published on Nov 22, 2016. It was last updated on Nov 22, 2016. This page (GPS Class) was last updated on Sep 14, 2019.