Merge pull request sparkfun#4 from tve/autoPVT

Add support for auto-reporting of navigation solutions using UBX_NAV_PVT

Author: nseidle

README.md

@@ -38,6 +38,39 @@ Documentation
 
 * **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
 
+Polling vs. auto-reporting
+--------------------------
+
+This library supports two modes of operation for getting navigation information with the `getPVT`
+function (based on the `UBX_NAV_PVT` protocol packet): polling and auto-reporting.
+
+The standard method is for the sketch to call `getPVT` (or one of the `getLatitude`, `getLongitude`,
+etc. methods) when it needs a fresh navigation solution. At that point the library sends a request
+to the GPS to produce a fresh solution. The GPS then waits until the next measurement occurs (e.g.
+once per second or as set using `setNavigationFrequency`) and then sends the fresh data.
+The advantage of this method is that the data received is always fresh, the downside is that getPVT
+can block until the next measurement is made by the GPS, e.g. up to 1 second if the nav frequency is
+set to one second.
+
+An alternate method can be chosen using `setAutoPVT(true)` which instructs the GPS to send the
+navigation information (`UBX_NAV_PVT` packet) as soon as it is produced. This is the way the older
+NMEA navigation data has been used for years. The sketch continues to call `getPVT` as before but
+under the hood the library returns the data of the last solution received from the GPS, which may be
+a bit out of date (how much depends on the `setNavigationFrequency` value).
+
+The advantage of this method is that getPVT does not block: it returns true if new data is available
+and false otherwise. The disadvantages are that the data may be a bit old and that buffering for
+these spontaneus `UBX_NAV_PVT` packets is required (100 bytes each). When using Serial the buffering
+is an issue because the std serial buffer is 32 or 64 bytes long depending on Arduino version. When
+using I2C the buffering is not an issue because the GPS device has at least 1KB of internal buffering
+(possibly as large as 4KB).
+
+As an example, assume that the GPS is set to produce 5 navigation
+solutions per second and that the sketch only calls getPVT once a second, then the GPS will queue 5
+packets in its internal buffer (about 500 bytes) and the library will read those when getPVT is
+called, update its internal copy of the nav data 5 times, and return `true` to the sketch. The
+skecth calls `getLatitude`, etc. and retrieve the data of the most recent of those 5 packets.
+
 Products That Use This Library 
 ---------------------------------
 

examples/Example12_FactoryDefault2/Example12_FactoryDefault2.ino

@@ -0,0 +1,60 @@
+/*
+ Test baud rate changes on serial, factory reset, and hard reset.
+ By: Thorsten von Eicken
+ Date: January 29rd, 2019
+ License: MIT. See license file for more information but you can
+ basically do whatever you want with this code.
+
+ This example shows how to reset the U-Blox module to factory defaults.
+
+ Feel like supporting open source hardware?
+ Buy a board from SparkFun!
+ ZED-F9P RTK2: https://www.sparkfun.com/products/15136
+ NEO-M8P RTK: https://www.sparkfun.com/products/15005
+ SAM-M8Q: https://www.sparkfun.com/products/15106
+
+ Hardware Connections:
+ Connect the U-Blox serial port to Serial1
+ If you're using an Uno or don't have a 2nd serial port (Serial1), consider using software serial
+ Open the serial monitor at 115200 baud to see the output
+*/
+
+#include <SparkFun_Ublox_Arduino_Library.h> //http://librarymanager/All#SparkFun_Ublox_GPS
+SFE_UBLOX_GPS myGPS;
+
+int state = 0; // steps through auto-baud, reset, etc states
+
+void setup()
+{
+ Serial.begin(115200);
+ while (!Serial); //Wait for user to open terminal
+ Serial.println("SparkFun Ublox Example");
+
+ Wire.begin();
+
+ if (myGPS.begin() == false) //Connect to the Ublox module using Wire port
+ {
+ Serial.println(F("Ublox GPS not detected at default I2C address. Please check wiring. Freezing."));
+ while (1);
+ }
+
+ while (Serial.available()) Serial.read(); //Trash any incoming chars
+ Serial.println("Press a key to reset module to factory defaults");
+ while (Serial.available() == false) ; //Wait for user to send character
+
+ myGPS.factoryReset();
+
+ if (myGPS.begin() == false) //Attempt to re-connect
+ {
+ Serial.println(F("Ublox GPS not detected at default I2C address. Please check wiring. Freezing."));
+ while (1);
+ }
+
+ Serial.println("Unit has now been factory reset. Freezing...");
+ while(1);
+}
+
+void loop()
+{
+
+}

examples/Example13_AutoPVT/Example13_AutoPVT.ino

@@ -0,0 +1,83 @@
+/*
+ Configuring the GPS to automatically send position reports over I2C
+ By: Nathan Seidle
+ SparkFun Electronics
+ Date: January 3rd, 2019
+ License: MIT. See license file for more information but you can
+ basically do whatever you want with this code.
+
+ This example shows how to configure the U-Blox GPS the send navigation reports automatically
+ and retrieving the latest one via getPVT. This eliminates the blocking in getPVT while the GPS
+ produces a fresh navigation solution at the expense of returning a slighly old solution.
+
+ This can be used over serial or over I2C, this example shows the I2C use. With serial the GPS
+ simply outputs the UBX_NAV_PVT packet. With I2C it queues it into its internal I2C buffer (4KB in
+ size?) where it can be retrieved in the next I2C poll.
+
+ Feel like supporting open source hardware?
+ Buy a board from SparkFun!
+ ZED-F9P RTK2: https://www.sparkfun.com/products/15136
+ NEO-M8P RTK: https://www.sparkfun.com/products/15005
+ SAM-M8Q: https://www.sparkfun.com/products/15106
+
+ Hardware Connections:
+ Plug a Qwiic cable into the GPS and a BlackBoard
+ If you don't have a platform with a Qwiic connection use the SparkFun Qwiic Breadboard Jumper (https://www.sparkfun.com/products/14425)
+ Open the serial monitor at 115200 baud to see the output
+*/
+
+#include <Wire.h> //Needed for I2C to GPS
+
+#include <SparkFun_Ublox_Arduino_Library.h> //http://librarymanager/All#SparkFun_Ublox_GPS
+SFE_UBLOX_GPS myGPS;
+
+void setup()
+{
+ Serial.begin(115200);
+ while (!Serial); //Wait for user to open terminal
+ Serial.println("SparkFun Ublox Example");
+
+ Wire.begin();
+
+ if (myGPS.begin() == false) //Connect to the Ublox module using Wire port
+ {
+ Serial.println(F("Ublox GPS not detected at default I2C address. Please check wiring. Freezing."));
+ while (1);
+ }
+
+ myGPS.setI2COutput(COM_TYPE_UBX); //Set the I2C port to output UBX only (turn off NMEA noise)
+ myGPS.setNavigationFrequency(2); //Produce two solutions per second
+ myGPS.setAutoPVT(true); //Tell the GPS to "send" each solution
+ myGPS.saveConfiguration(); //Save the current settings to flash and BBR
+}
+
+void loop()
+{
+ // Calling getPVT returns true if there actually is a fresh navigation solution available.
+ if (myGPS.getPVT())
+ {
+ Serial.println();
+ long latitude = myGPS.getLatitude();
+ Serial.print(F("Lat: "));
+ Serial.print(latitude);
+
+ long longitude = myGPS.getLongitude();
+ Serial.print(F(" Long: "));
+ Serial.print(longitude);
+ Serial.print(F(" (degrees * 10^-7)"));
+
+ long altitude = myGPS.getAltitude();
+ Serial.print(F(" Alt: "));
+ Serial.print(altitude);
+ Serial.print(F(" (mm)"));
+
+ byte SIV = myGPS.getSIV();
+ Serial.print(F(" SIV: "));
+ Serial.print(SIV);
+
+ Serial.println();
+ } else {
+ Serial.print(".");
+ delay(50);
+ }
+}

keywords.txt

@@ -76,7 +76,10 @@ getPositionAccuracy	KEYWORD2
 
 getProtocolVersionHigh	KEYWORD2
 getProtocolVersionLow	KEYWORD2
-getProtocolVersion	KEYWORD2
+getProtocolVersion KEYWORD2
+
+factoryReset KEYWORD2
+setAutoPVT KEYWORD2
 
 #######################################
 # Constants (LITERAL1)