Crate adafruit_gps[−][src]

Expand description

Adafruit_gps

This is a port from the adafruit python code that reads the output from their GPS systems. This crate has been tested on a MTK3339 chip on a raspberry pi zero.

  • Python code: https://github.com/adafruit/Adafruit_CircuitPython_GPS
  • GPS module docs: https://learn.adafruit.com/adafruit-ultimate-gps/
  • PMTK commands https://cdn-shop.adafruit.com/datasheets/PMTK_A11.pdf

Modules

The PMTK module is a way of easily sending command to the GPS, changing it’s settings.

The nmea module reads the data given by the GPS. Use the gps.update() trait to get easy to use data, but for specific use cases custom commands can be read.

Hardware specs

Please read the docs for the specific GPS module you are using.

Update rate is likely 1Hz to 10Hz. If increasing the update rate, the baud rate may also need to be increased. A rule of thumb is, one sentence is 256 bytes -> at 9600 baud rate, 37.5 sentences per second.

Module Outputs

gps.update() outputs a GpsSentence enum which mostly gives other structs for different sentence types

GpsSentence enum types:

  • GGA(GgaData) -> GgaData: Latitude, Longitude, Position fix, Satellites seen, HDOP, altitude, Geoidal Seperation, Age of difference correction.
  • VTG(VtgData) -> VtgData: Course (true), Course (magnetic), speed knots, speed kph.
  • GSA(GsaData) -> GsaData: List of satellites used, PDOP, HDOP, VDOP.
  • GSV(Vec) -> Satellites: Satellites in view data: sat id, elevation, azimuth and SNR for each sat seen.
  • GLL(GllData) -> GllData: Latitude, Longitude only.
  • RMC(RmcData) -> RmcData: UTC, Latitude, Longitude, speed, course, date, magnetic variation.
  • NoConnection -> The gps is not connected, no bytes are being received
  • InvalidBytes -> Bytes being received are not valid, probably port baud rate and gps baud rate mismatch
  • InvalidSentence -> Sentence outputted has incorrect checksum, the sentence was probably incomplete.

Some technical information

Dilution of precision

DOP is dilution of precision, a measure of error based on the position of the satellites. The smaller the number the better (1 is excellent).

The DOP is determined by the arrangement of the satellites being tracked. The DOP can be either vertical or horizontal as different satellite arrangements affect the vertical and horizontal DOP differently.

See This wikipeia page for details

Geoid and Mean sea level

Measuring height is difficult because where 0m is exactly is hard to establish.

The geoid is the shape that the ocean would take under the influence of gravity and the earth’s rotation alone, ignoring tides and wind.

The WGS84 ellipsoid is the ideal smooth surface shape of the earth, with no mountains or trenches.

The height of the geoid given by GgaData geoidal_sep is the difference between the geoid and the WGS84 ellipsoid. It ranges from +85 m to -106 m.

A reading of +47 for geoidal_sep means the geoid is 47 metres above the WGS84 ellipsoid.

Mean sea level is locally defined and changes depending on location. Therefore, altitude given by the gps is, in my opinion, not overly useful for precise elevation, but rather is useful in measuring the difference in height between objects.

Saving data

GpsSentence types can be written and read to a bytes file using the the append_to() and read_from() traits: See examples/example_io.rs for details.

use adafruit_gps::GpsSentence;
use adafruit_gps::gga::GgaData;
let data: Vec<GpsSentence> = GpsSentence::read_from("file"); // Read from file

GpsSentence::GGA(GgaData::default()).append_to("file"); // Append a single item to a file

Modules

gga

GGA: UTC, Latitude, Longitude, Fix quality, Satellites used, HDOP, MSL altitude, Geoidal separation Age of difference correction.

gll

Longitude and Latitude data only

gsa

Overall Satellite data.

gsv

Parse GSV sentence

rmc

Recommended Minimum data

vtg

Vector track an Speed over the Ground

Structs

Gps

This is the main struct around which all commands are centered. It allows for communication with the GPS module via the open port.

NmeaOutput

Enums

GpsSentence

Enum for the gps.update() method.

Functions

set_baud_rate

Sets baud rate for the gps If the baud rate you are trying to set is not compatible with the current frequency the update will fail. Therefore change the frequency first (probably to 1000 miliseconds) and then change the baud rate.