Adafruit GPS Library
|
The GPS class. More...
#include <Adafruit_GPS.h>
Public Member Functions | |
bool | begin (uint32_t baud_or_i2caddr) |
Start the HW or SW serial port. More... | |
Adafruit_GPS (HardwareSerial *ser) | |
Constructor when using SoftwareSerial. More... | |
Adafruit_GPS (Stream *data) | |
Constructor when using Stream. More... | |
Adafruit_GPS (TwoWire *theWire) | |
Constructor when using I2C. More... | |
Adafruit_GPS (SPIClass *theSPI, int8_t cspin) | |
Constructor when using SPI. More... | |
Adafruit_GPS () | |
Constructor when there are no communications attached. | |
void | common_init (void) |
Initialization code used by all constructor types. | |
virtual | ~Adafruit_GPS () |
Destroy the object. More... | |
size_t | available (void) |
How many bytes are available to read - part of 'Print'-class functionality. More... | |
size_t | write (uint8_t) |
Write a byte to the underlying transport - part of 'Print'-class functionality. More... | |
char | read (void) |
Read one character from the GPS device. More... | |
void | sendCommand (const char *) |
Send a command to the GPS device. More... | |
bool | newNMEAreceived () |
Check to see if a new NMEA line has been received. More... | |
void | pause (bool b) |
Pause/unpause receiving new data. More... | |
char * | lastNMEA (void) |
Returns the last NMEA line received and unsets the received flag. More... | |
bool | waitForSentence (const char *wait, uint8_t max=MAXWAITSENTENCE, bool usingInterrupts=false) |
Wait for a specified sentence from the device. More... | |
bool | LOCUS_StartLogger (void) |
Start the LOCUS logger. More... | |
bool | LOCUS_StopLogger (void) |
Stop the LOCUS logger. More... | |
bool | LOCUS_ReadStatus (void) |
Read the logger status. More... | |
bool | standby (void) |
Standby Mode Switches. More... | |
bool | wakeup (void) |
Wake the sensor up. More... | |
nmea_float_t | secondsSinceFix () |
Time in seconds since the last position fix was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no position fix is received for this long. More... | |
nmea_float_t | secondsSinceTime () |
Time in seconds since the last GPS time was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no GPS time is received for this long. More... | |
nmea_float_t | secondsSinceDate () |
Time in seconds since the last GPS date was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no GPS date is received for this long. More... | |
void | resetSentTime () |
Fakes time of receipt of a sentence. Use between build() and parse() to make the timing look like the sentence arrived from the GPS. | |
bool | parse (char *) |
Parse a standard NMEA string and update the relevant variables. Sentences start with a $, then a two character source identifier, then a three character sentence identifier that defines the format, then a comma and more comma separated fields defined by the sentence name. There are many sentences listed that are not yet supported, including proprietary sentences that start with P, like the $PMTK commands to the GPS modules. See the build() function and http://fort21.ru/download/NMEAdescription.pdf for sentence descriptions. More... | |
bool | check (char *nmea) |
Check an NMEA string for basic format, valid source ID and valid and valid sentence ID. Update the values of thisCheck, thisSource and thisSentence. More... | |
bool | onList (char *nmea, const char **list) |
Check if an NMEA string is valid and is on a list, perhaps to decide if it should be passed to a particular NMEA device. More... | |
uint8_t | parseHex (char c) |
Parse a hex character and return the appropriate decimal value. More... | |
char * | build (char *nmea, const char *thisSource, const char *thisSentence, char ref='R', bool noCRLF=false) |
Build an NMEA sentence string based on the relevant variables. Sentences start with a $, then a two character source identifier, then a three character sentence name that defines the format, then a comma and more comma separated fields defined by the sentence name. There are many sentences listed that are not yet supported. Most of these sentence definitions were found at http://fort21.ru/download/NMEAdescription.pdf. More... | |
void | addChecksum (char *buff) |
Add *CS where CS is the two character hex checksum for all but the first character in the string. The checksum is the result of an exclusive or of all the characters in the string. Also useful if you are creating new PMTK strings for controlling a GPS module and need a checksum added. More... | |
void | newDataValue (nmea_index_t tag, nmea_float_t v) |
Update the value and history information with a new value. Call whenever a new data value is received. The function does nothing if the NMEA extensions are not enabled. More... | |
nmea_float_t | get (nmea_index_t idx) |
Clearer approach to retrieving NMEA values by allowing calls that look like nmea.get(NMEA_TWA) instead of val[NMEA_TWA].latest. Use newDataValue() to set the values. More... | |
nmea_float_t | getSmoothed (nmea_index_t idx) |
Clearer approach to retrieving NMEA values. More... | |
void | initDataValue (nmea_index_t idx, char *label=NULL, char *fmt=NULL, char *unit=NULL, unsigned long response=0, nmea_value_type_t type=NMEA_SIMPLE_FLOAT) |
Initialize the contents of a data value table entry. More... | |
nmea_history_t * | initHistory (nmea_index_t idx, nmea_float_t scale=10.0, nmea_float_t offset=0.0, unsigned historyInterval=20, unsigned historyN=192) |
Attempt to add history to a data value table entry. If it fails to malloc the space, history will not be added. Test the pointer for a check if needed. Select scale and offset values carefully so that operations and results will fit inside 16 bit integer limits. For example a scale of 1.0 and an offset of 100000.0 would be a good choice for atmospheric pressure in Pa with values ranging ~ +/- 3500, while a scale of 10.0 would be pushing the integer limits. More... | |
void | removeHistory (nmea_index_t idx) |
Remove history from a data value table entry, if it has been added. More... | |
void | showDataValue (nmea_index_t idx, int n=7) |
Print out the current state of a data value. Primarily useful as a debugging aid. More... | |
bool | isCompoundAngle (nmea_index_t idx) |
Check if it is a compound angle. More... | |
nmea_float_t | boatAngle (nmea_float_t s, nmea_float_t c) |
Estimate a direction in -180 to 180 degree range from the values of the sine and cosine of the compound angle, which could be noisy. More... | |
nmea_float_t | compassAngle (nmea_float_t s, nmea_float_t c) |
Estimate a direction in 0 to 360 degree range from the values of the sine and cosine of the compound angle, which could be noisy. More... | |
Public Attributes | |
int | thisCheck = 0 |
the results of the check on the current sentence | |
char | thisSource [NMEA_MAX_SOURCE_ID] |
the first two letters of the current sentence, e.g. WI, GP More... | |
char | thisSentence [NMEA_MAX_SENTENCE_ID] |
the next three letters of the current sentence, e.g. GLL, RMC More... | |
char | lastSource [NMEA_MAX_SOURCE_ID] |
char | lastSentence [NMEA_MAX_SENTENCE_ID] |
uint8_t | hour |
GMT hours. | |
uint8_t | minute |
GMT minutes. | |
uint8_t | seconds |
GMT seconds. | |
uint16_t | milliseconds |
GMT milliseconds. | |
uint8_t | year |
GMT year. | |
uint8_t | month |
GMT month. | |
uint8_t | day |
GMT day. | |
nmea_float_t | latitude |
nmea_float_t | longitude |
int32_t | latitude_fixed |
int32_t | longitude_fixed |
nmea_float_t | latitudeDegrees |
Latitude in decimal degrees. | |
nmea_float_t | longitudeDegrees |
Longitude in decimal degrees. | |
nmea_float_t | geoidheight |
Diff between geoid height and WGS84 height. | |
nmea_float_t | altitude |
Altitude in meters above MSL. | |
nmea_float_t | speed |
Current speed over ground in knots. | |
nmea_float_t | angle |
Course in degrees from true north. | |
nmea_float_t | magvariation |
Magnetic variation in degrees (vs. true north) | |
nmea_float_t | HDOP |
nmea_float_t | VDOP |
nmea_float_t | PDOP |
char | lat = 'X' |
N/S. | |
char | lon = 'X' |
E/W. | |
char | mag = 'X' |
Magnetic variation direction. | |
bool | fix |
Have a fix? | |
uint8_t | fixquality |
Fix quality (0, 1, 2 = Invalid, GPS, DGPS) | |
uint8_t | fixquality_3d |
3D fix quality (1, 3, 3 = Nofix, 2D fix, 3D fix) | |
uint8_t | satellites |
Number of satellites in use. | |
uint8_t | antenna |
Antenna that is used (from PGTOP) | |
uint16_t | LOCUS_serial |
Log serial number. | |
uint16_t | LOCUS_records |
Log number of data record. | |
uint8_t | LOCUS_type |
Log type, 0: Overlap, 1: FullStop. | |
uint8_t | LOCUS_mode |
Logging mode, 0x08 interval logger. | |
uint8_t | LOCUS_config |
Contents of configuration. | |
uint8_t | LOCUS_interval |
Interval setting. | |
uint8_t | LOCUS_distance |
Distance setting. | |
uint8_t | LOCUS_speed |
Speed setting. | |
uint8_t | LOCUS_status |
0: Logging, 1: Stop logging | |
uint8_t | LOCUS_percent |
Log life used percentage. | |
nmea_datavalue_t | val [NMEA_MAX_INDEX] |
nmea_float_t | depthToKeel |
depth from surface to bottom of keel in metres More... | |
nmea_float_t | depthToTransducer |
depth of transducer below the surface in metres More... | |
char | toID [NMEA_MAX_WP_ID] |
id of waypoint going to on this segment of the route More... | |
char | fromID [NMEA_MAX_WP_ID] |
id of waypoint coming from on this segment of the route More... | |
char | txtTXT [63] = {0} |
text content from most recent TXT sentence | |
int | txtTot = 0 |
total TXT sentences in group | |
int | txtID = 0 |
id of the text message | |
int | txtN = 0 |
the TXT sentence number | |
The GPS class.
Adafruit_GPS::Adafruit_GPS | ( | HardwareSerial * | ser | ) |
Constructor when using SoftwareSerial.
ser | Pointer to SoftwareSerial device |
Constructor when using HardwareSerial
ser | Pointer to a HardwareSerial object |
Adafruit_GPS::Adafruit_GPS | ( | Stream * | data | ) |
Constructor when using Stream.
data | Pointer to a Stream object |
Adafruit_GPS::Adafruit_GPS | ( | TwoWire * | theWire | ) |
Constructor when using I2C.
theWire | Pointer to an I2C TwoWire object |
Adafruit_GPS::Adafruit_GPS | ( | SPIClass * | theSPI, |
int8_t | cspin | ||
) |
Constructor when using SPI.
theSPI | Pointer to an SPI device object |
cspin | The pin connected to the GPS CS, can be -1 if unused |
|
virtual |
Destroy the object.
bool Adafruit_GPS::begin | ( | uint32_t | baud_or_i2caddr | ) |
Start the HW or SW serial port.
baud_or_i2caddr | Baud rate if using serial, I2C address if using I2C |
size_t Adafruit_GPS::available | ( | void | ) |
How many bytes are available to read - part of 'Print'-class functionality.
size_t Adafruit_GPS::write | ( | uint8_t | c | ) |
Write a byte to the underlying transport - part of 'Print'-class functionality.
c | A single byte to send |
char Adafruit_GPS::read | ( | void | ) |
Read one character from the GPS device.
Call very frequently and multiple times per opportunity or the buffer may overflow if there are frequent NMEA sentences. An 82 character NMEA sentence 10 times per second will require 820 calls per second, and once a loop() may not be enough. Check for newNMEAreceived() after at least every 10 calls, or you may miss some short sentences.
void Adafruit_GPS::sendCommand | ( | const char * | str | ) |
Send a command to the GPS device.
str | Pointer to a string holding the command to send |
bool Adafruit_GPS::newNMEAreceived | ( | void | ) |
Check to see if a new NMEA line has been received.
void Adafruit_GPS::pause | ( | bool | p | ) |
Pause/unpause receiving new data.
p | True = pause, false = unpause |
char * Adafruit_GPS::lastNMEA | ( | void | ) |
Returns the last NMEA line received and unsets the received flag.
bool Adafruit_GPS::waitForSentence | ( | const char * | wait4me, |
uint8_t | max = MAXWAITSENTENCE , |
||
bool | usingInterrupts = false |
||
) |
Wait for a specified sentence from the device.
wait4me | Pointer to a string holding the desired response |
max | How long to wait, default is MAXWAITSENTENCE |
usingInterrupts | True if using interrupts to read from the GPS (default is false) |
bool Adafruit_GPS::LOCUS_StartLogger | ( | void | ) |
Start the LOCUS logger.
bool Adafruit_GPS::LOCUS_StopLogger | ( | void | ) |
Stop the LOCUS logger.
bool Adafruit_GPS::LOCUS_ReadStatus | ( | void | ) |
Read the logger status.
bool Adafruit_GPS::standby | ( | void | ) |
Standby Mode Switches.
bool Adafruit_GPS::wakeup | ( | void | ) |
Wake the sensor up.
nmea_float_t Adafruit_GPS::secondsSinceFix | ( | ) |
Time in seconds since the last position fix was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no position fix is received for this long.
nmea_float_t Adafruit_GPS::secondsSinceTime | ( | ) |
Time in seconds since the last GPS time was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no GPS time is received for this long.
nmea_float_t Adafruit_GPS::secondsSinceDate | ( | ) |
Time in seconds since the last GPS date was obtained. The time returned is limited to 2^32 milliseconds, which is about 49.7 days. It will wrap around to zero if no GPS date is received for this long.
bool Adafruit_GPS::parse | ( | char * | nmea | ) |
Parse a standard NMEA string and update the relevant variables. Sentences start with a $, then a two character source identifier, then a three character sentence identifier that defines the format, then a comma and more comma separated fields defined by the sentence name. There are many sentences listed that are not yet supported, including proprietary sentences that start with P, like the $PMTK commands to the GPS modules. See the build() function and http://fort21.ru/download/NMEAdescription.pdf for sentence descriptions.
Encapsulated data sentences are supported by NMEA-183, and start with ! instead of $. https://gpsd.gitlab.io/gpsd/AIVDM.html provides details about encapsulated data sentences used in AIS.
parse() permits, but does not require Carriage Return and Line Feed at the end of sentences. The end of the sentence is recognized by the * for the checksum. parse() will not recognize a sentence without a valid checksum.
NMEA_EXTENSIONS must be defined in order to parse more than basic GPS module sentences.
nmea | Pointer to the NMEA string |
bool Adafruit_GPS::check | ( | char * | nmea | ) |
Check an NMEA string for basic format, valid source ID and valid and valid sentence ID. Update the values of thisCheck, thisSource and thisSentence.
nmea | Pointer to the NMEA string |
bool Adafruit_GPS::onList | ( | char * | nmea, |
const char ** | list | ||
) |
Check if an NMEA string is valid and is on a list, perhaps to decide if it should be passed to a particular NMEA device.
nmea | Pointer to the NMEA string |
list | A list of strings, with the final entry "ZZ" |
uint8_t Adafruit_GPS::parseHex | ( | char | c | ) |
Parse a hex character and return the appropriate decimal value.
c | Hex character, e.g. '0' or 'B' |
char * Adafruit_GPS::build | ( | char * | nmea, |
const char * | thisSource, | ||
const char * | thisSentence, | ||
char | ref = 'R' , |
||
bool | noCRLF = false |
||
) |
Build an NMEA sentence string based on the relevant variables. Sentences start with a $, then a two character source identifier, then a three character sentence name that defines the format, then a comma and more comma separated fields defined by the sentence name. There are many sentences listed that are not yet supported. Most of these sentence definitions were found at http://fort21.ru/download/NMEAdescription.pdf.
build() will work with other lengths for source and sentence to allow extension to building proprietary sentences like $PMTK220,100*2F.
build() will not work properly in an environment that does not support the f floating point formatter in sprintf(), and will return NULL. Floating point arguments to sprintf() are explicitly cast to double to avoid warnings in some compilers.
build() adds Carriage Return and Line Feed to sentences to conform to NMEA-183, so send your output with a print, not a println.
The resulting sentence may be corrupted if the input data is corrupt. In particular, the sentence will be truncated if any of the character data is 0, e.g. if lat is not set to 'N' or 'S'.
Some of the data in these test sentences may be arbitrary, e.g. for the TXT sentence which has a more complicated protocol for multiple lines sent as a message set. Also, the data in the class variables are presumed to be valid, so these sentences may contain values that are stale, or the result of initialization rather than measurement.
nmea | Pointer to the NMEA string buffer. Must be big enough to hold the sentence. No guarantee what will be in it if the building of the sentence fails. |
thisSource | Pointer to the source name string (2 upper case) |
thisSentence | Pointer to the sentence name string (3 upper case) |
ref | Reference for the sentence, usually relative (R) or true (T) |
noCRLF | set true to disable adding CR/LF to comply with NMEA-183 |
void Adafruit_GPS::addChecksum | ( | char * | buff | ) |
Add *CS where CS is the two character hex checksum for all but the first character in the string. The checksum is the result of an exclusive or of all the characters in the string. Also useful if you are creating new PMTK strings for controlling a GPS module and need a checksum added.
buff | Pointer to the string, which must be long enough |
void Adafruit_GPS::newDataValue | ( | nmea_index_t | idx, |
nmea_float_t | v | ||
) |
Update the value and history information with a new value. Call whenever a new data value is received. The function does nothing if the NMEA extensions are not enabled.
idx | The data index for which a new value has been received |
v | The new value received |
nmea_float_t Adafruit_GPS::get | ( | nmea_index_t | idx | ) |
Clearer approach to retrieving NMEA values by allowing calls that look like nmea.get(NMEA_TWA) instead of val[NMEA_TWA].latest. Use newDataValue() to set the values.
idx | the NMEA value's index |
nmea_float_t Adafruit_GPS::getSmoothed | ( | nmea_index_t | idx | ) |
Clearer approach to retrieving NMEA values.
idx | the NMEA value's index |
void Adafruit_GPS::initDataValue | ( | nmea_index_t | idx, |
char * | label = NULL , |
||
char * | fmt = NULL , |
||
char * | unit = NULL , |
||
unsigned long | response = 0 , |
||
nmea_value_type_t | type = NMEA_SIMPLE_FLOAT |
||
) |
Initialize the contents of a data value table entry.
idx | The data index for the value to be initialized |
label | Pointer to a label string that describes the value |
fmt | Pointer to a sprintf format to use for the value, e.g. "%6.2f" |
unit | Pointer to a string for the units, e.g. "Deg Mag" |
response | Time constant for smoothing in ms. The longer the time constant, the more slowly the smoothed value will move towards a new value. |
type | The type of data contained in the value. simple float 0, angle 0-360 1, angle +/-180 2, angle with history centered +/- around the latest angle 3, lat/lon DDMM.mm 10, time HHMMSS 20. |
nmea_history_t * Adafruit_GPS::initHistory | ( | nmea_index_t | idx, |
nmea_float_t | scale = 10.0 , |
||
nmea_float_t | offset = 0.0 , |
||
unsigned | historyInterval = 20 , |
||
unsigned | historyN = 192 |
||
) |
Attempt to add history to a data value table entry. If it fails to malloc the space, history will not be added. Test the pointer for a check if needed. Select scale and offset values carefully so that operations and results will fit inside 16 bit integer limits. For example a scale of 1.0 and an offset of 100000.0 would be a good choice for atmospheric pressure in Pa with values ranging ~ +/- 3500, while a scale of 10.0 would be pushing the integer limits.
idx | The data index for the value to have history recorded |
scale | Value for scaling the integer history list |
offset | Value for scaling the integer history list |
historyInterval | Approximate Time in seconds between historical values. |
historyN | Set size of data buffer. |
void Adafruit_GPS::removeHistory | ( | nmea_index_t | idx | ) |
Remove history from a data value table entry, if it has been added.
idx | The data index for the value to have history removed |
void Adafruit_GPS::showDataValue | ( | nmea_index_t | idx, |
int | n = 7 |
||
) |
Print out the current state of a data value. Primarily useful as a debugging aid.
idx | The index for the data value |
n | The number of history values to include |
bool Adafruit_GPS::isCompoundAngle | ( | nmea_index_t | idx | ) |
Check if it is a compound angle.
idx | The index for the data value |
nmea_float_t Adafruit_GPS::boatAngle | ( | nmea_float_t | s, |
nmea_float_t | c | ||
) |
Estimate a direction in -180 to 180 degree range from the values of the sine and cosine of the compound angle, which could be noisy.
s | The sin of the angle |
c | The cosine of the angle |
nmea_float_t Adafruit_GPS::compassAngle | ( | nmea_float_t | s, |
nmea_float_t | c | ||
) |
Estimate a direction in 0 to 360 degree range from the values of the sine and cosine of the compound angle, which could be noisy.
s | The sin of the angle |
c | The cosine of the angle |
char Adafruit_GPS::thisSource[NMEA_MAX_SOURCE_ID] |
the first two letters of the current sentence, e.g. WI, GP
char Adafruit_GPS::thisSentence[NMEA_MAX_SENTENCE_ID] |
the next three letters of the current sentence, e.g. GLL, RMC
char Adafruit_GPS::lastSource[NMEA_MAX_SOURCE_ID] |
the results of the check on the most recent successfully parsed sentence
char Adafruit_GPS::lastSentence[NMEA_MAX_SENTENCE_ID] |
the next three letters of the most recent successfully parsed sentence, e.g. GLL, RMC
nmea_float_t Adafruit_GPS::latitude |
Floating point latitude value in degrees/minutes as received from the GPS (DDMM.MMMM)
nmea_float_t Adafruit_GPS::longitude |
Floating point longitude value in degrees/minutes as received from the GPS (DDDMM.MMMM)
int32_t Adafruit_GPS::latitude_fixed |
Fixed point latitude and longitude value with degrees stored in units of 1/10000000 of a degree. See pull #13 for more details: https://github.com/adafruit/Adafruit-GPS-Library/pull/13 Fixed point latitude in decimal degrees. Divide by 10000000.0 to get a double.
int32_t Adafruit_GPS::longitude_fixed |
Fixed point longitude in decimal degrees Divide by 10000000.0 to get a double.
nmea_float_t Adafruit_GPS::HDOP |
Horizontal Dilution of Precision - relative accuracy of horizontal position
nmea_float_t Adafruit_GPS::VDOP |
Vertical Dilution of Precision - relative accuracy of vertical position
nmea_float_t Adafruit_GPS::PDOP |
Position Dilution of Precision - Complex maths derives a simple, single number for each kind of DOP
nmea_datavalue_t Adafruit_GPS::val[NMEA_MAX_INDEX] |
an array of data value structs, val[0] = most recent HDOP so that ockam indexing works
nmea_float_t Adafruit_GPS::depthToKeel |
depth from surface to bottom of keel in metres
nmea_float_t Adafruit_GPS::depthToTransducer |
depth of transducer below the surface in metres
char Adafruit_GPS::toID[NMEA_MAX_WP_ID] |
id of waypoint going to on this segment of the route
char Adafruit_GPS::fromID[NMEA_MAX_WP_ID] |
id of waypoint coming from on this segment of the route