Add support for auto-reporting of navigation solutions using UBX_NAV_PVT

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)