Add readNavigationDatabase. Update the AssistNow Autonomous example.

Author: PaulZC

Theory.md

@@ -5,7 +5,6 @@ When the user calls one of the methods the library will poll the u-blox module f
 * Wait for a minimum of 25 ms between polls (configured dynamically when update rate is set)
 * Write 0xFD to module
 * Read two bytes (0xFD and 0xFE) for bytes available
-* If 0x7F or 0xFF then no bytes are available
 * Otherwise, read number of bytes and process into NMEA, UBX, or RTCM frame.
 * If checksum is valid, flag frame as complete.
 
@@ -58,6 +57,7 @@ In v2.0, the full list of messages which can be processed and logged automatical
 - UBX-NAV-CLOCK (0x01 0x22): Clock solution
 - UBX-NAV-SVIN (0x01 0x3B): Survey-in data (**only with High Precision GNSS products**)
 - UBX-NAV-RELPOSNED (0x01 0x3C): Relative positioning information in NED frame (**only with High Precision GNSS products**)
+- UBX-NAV-AOPSTATUS (0x01 0x60): AssistNow Autonomous status
 - UBX-RXM-SFRBX (0x02 0x13): Broadcast navigation data subframe
 - UBX-RXM-RAWX (0x02 0x15): Multi-GNSS raw measurement data (**only with ADR or High Precision GNSS or Time Sync products**)
 - UBX-TIM-TM2 (0x0D 0x03): Time mark data

examples/AssistNow/AssistNow_Autonomous/Example1_AssistNowAutonomous_Read/Example1_AssistNowAutonomous_Read.ino

@@ -7,6 +7,10 @@
 
   This example shows how to enable, check the status of, and read the AssistNow Autonomous data from the module.
 
+  Note: this example will only work on boards which have plenty of RAM available.
+        The database can be several kBytes in length and needs to be stored twice:
+        once inside the library (by readNavigationDatabase); and again in this example code.
+
   Feel like supporting open source hardware?
   Buy a board from SparkFun!
   SparkFun Thing Plus - ESP32 WROOM:        https://www.sparkfun.com/products/15663
@@ -49,6 +53,8 @@ void setup()
 
   myGNSS.setI2COutput(COM_TYPE_UBX); //Turn off NMEA noise
 
+  //myGNSS.enableDebugging(Serial, true); // Uncomment this line to see helpful debug messages on Serial
+
   //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   // Enable AssistNow Autonomous data collection.
 
@@ -63,35 +69,85 @@ void setup()
   }
 
   //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-  // Keep calling getAOPSTATUSstatus until it returns zero (indicating AssistNow Autonomous data collection si complete)
+  // Keep calling getAOPSTATUSstatus until it returns zero (indicating AssistNow Autonomous data collection is complete)
   // or the user presses a key
 
   Serial.println(F("AssistNow Autonomous data collection is in progress. Press any key to quit."));
+  Serial.println(F("NAV AOPSTATUS status indicates when the AssistNow Autonomous subsystem is idle (0) or running (not 0)."));
 
   bool keepGoing = true;
+  int zerosSeen = 0; // Keep track of how many times aopStatus has been zero
   while (Serial.available()) Serial.read(); // Empty the serial buffer
 
-  while (keepGoing && !Serial.available()); // Wait keepGoing to go false, or for the arrival of a keypress
+  while (keepGoing && !Serial.available()) // Wait for keepGoing to go false, or for the arrival of a keypress
   {
     delay(1000);
-    Serial.print(F("NAV AOPSTATUS status is: "));
     uint8_t aopStatus = myGNSS.getAOPSTATUSstatus();
-    Serial.print(aopStatus);
-    Serial.println(F(". (Don't worry! This could take a _long_ time...)"));
+    Serial.print(F("NAV AOPSTATUS status is: "));
+    Serial.println(aopStatus);
     if (aopStatus == 0) // aopStatus will be zero when the AssistNow Autonomous subsystem is idle - i.e. data collection is complete
-      keepGoing = false;
+    {
+      zerosSeen++; // Keep track of how long aopStatus has been zero
+      if (zerosSeen >= 30)
+        keepGoing = false; // Stop after seeing 30 consecutive zeros
+    }
+    else
+    {
+      zerosSeen = 0; // Reset the number of zeros seen
+    }
   }
 
   if (!keepGoing)
-        Serial.print(F("AssistNow Autonomous data collection is complete!"));
+    Serial.println(F("AssistNow Autonomous data collection is complete!"));
 
   //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-  // Read the AssistNow Autonomous data from the module and pretty-print it (so it can be copied and pasted into Example2)        
+  // Read the AssistNow Autonomous data from the module and pretty-print it (so it can be copied and pasted into Example2)
+
+  #define MAX_DATABASE_LENGTH 32768 // Allocate 32kBytes to store the navigation database
+  size_t maxDatabaseLen = MAX_DATABASE_LENGTH;
+  uint8_t *database = new uint8_t[MAX_DATABASE_LENGTH]; // The database will be stored here
+
+  Serial.println(F("Storage has been allocated for the database.")); Serial.flush();
+
+  size_t actualDatabaseLen = myGNSS.readNavigationDatabase(database, maxDatabaseLen); // Read the database
+
+  Serial.print(F("The Navigation Database length was "));
+  Serial.println(actualDatabaseLen);
+
+  if (actualDatabaseLen == maxDatabaseLen)
+    Serial.println(F("There was not enough memory to store the entire database. Some data will have been lost!"));
+
+  // Pretty-print the database so it can be copied into Example2
+  Serial.println(F("Copy and paste the following into Example2, so you can write it back to the module:"));
+  Serial.println();
+  Serial.print(F("size_t databaseLen = "));
+  Serial.print(actualDatabaseLen);
+  Serial.println(F(";"));
+  Serial.print(F("const uint8_t database["));
+  Serial.print(actualDatabaseLen);
+  Serial.println(F("] = {"));
+  size_t i;
+  for(i = 0; i < actualDatabaseLen; i++)
+  {
+    if ((i % 32) == 0)
+      Serial.print(F("  0x"));
+    if (*(database + i) < 0x10) // Print leading zero
+      Serial.print(F("0"));
+    Serial.print(*(database + i), HEX);
+    if (i == (actualDatabaseLen - 1))
+      Serial.println();
+    else if ((i % 32) == 31)
+      Serial.println(F(","));
+    else
+      Serial.print(F(", 0x"));
+  }
+  Serial.println(F("};"));
 
 }
 
 //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 void loop()
 {
-}
+  // Nothing to do here
+}

examples/AssistNow/README.md

@@ -174,3 +174,33 @@ AssistNow Autonomous is disabled by default. You can enable it by calling ```set
 
 * set ```aopCfg``` to 1 to enable AssistNow Autonomous, or 0 to disable it
 * ```aopOrbMaxErr``` is used to set the 'lifetime' of the AssistNow data. It is recommended to set aopOrbMaxErr to 0 (the default value). This instructs the module to use the firmware default value that corresponds to a default orbit data validity of approximately three days (for GPS satellites observed once) and up to six days (for GPS and GLONASS satellites observed multiple times over a period of at least half a day).
+
+Once AssistNow Autonomous is enabled, you can monitor its progress via the ```status``` field in the UBX-NAV-AOPSTATUS message. You can read the ```status``` by calling ```getAOPSTATUSstatus```. It will return zero when the AssistNow Autonomous data collection is complete. Non-zero values indicate that data collection is still in progress.
+
+* <b>uint8_t getAOPSTATUSstatus(uint16_t maxWait);</b>
+* <b>uint8_t getAOPSTATUSuseAOP(uint16_t maxWait);</b>
+
+We have included full 'auto' support for UBX-NAV-AOPSTATUS, so you can have the message delivered periodically, add a callback for it, and/or log it to the file buffer:
+
+* <b>bool getAOPSTATUS(uint16_t maxWait);</b>
+* <b>bool setAutoAOPSTATUS(bool enabled, uint16_t maxWait);</b>
+* <b>bool setAutoAOPSTATUS(bool enabled, bool implicitUpdate, uint16_t maxWait);</b>
+* <b>bool setAutoAOPSTATUSrate(uint8_t rate, bool implicitUpdate, uint16_t maxWait);</b>
+* <b>bool setAutoAOPSTATUScallback(void (*callbackPointer)(UBX_NAV_AOPSTATUS_data_t), uint16_t maxWait);</b>
+* <b>bool assumeAutoAOPSTATUS(bool enabled, bool implicitUpdate);</b>
+* <b>void flushAOPSTATUS();</b>
+* <b>void logNAVAOPSTATUS(bool enabled);</b>
+
+The AssistNow Autonomous data is stored in the module's RAM memory. If that RAM is Battery-Backed - all SparkFun GNSS boards include battery back-up - then the data will be available after the module is powered down and powered back up again. However, you can also read (poll) the navigation database and store the contents in processor memory. ```readNavigationDatabase``` allows you to do that:
+
+* <b>size_t readNavigationDatabase(uint8_t *dataBytes, size_t maxNumDataBytes, uint16_t maxWait);</b>
+
+Data is written to ```dataBytes```. Set ```maxNumDataBytes``` to the (maximum) size of dataBytes. If the database exceeds maxNumDataBytes, the excess bytes will be lost.
+
+```readNavigationDatabase``` returns the number of database bytes written to ```dataBytes```. The return value will be equal to ```maxNumDataBytes``` if excess data was received.
+
+```readNavigationDatabase```  will timeout after ```maxWait``` milliseconds - in case the final UBX-MGA-ACK was missed.
+
+You can then write the database back into the module using ```pushAssistNowData```. Don't forget to call ```setUTCTimeAssistance``` _before_ ```pushAssistNowData```.
+
+Note: UBX-MGA-DBD messages are only intended to be sent back to the same receiver that generated them. They are firmware-specific.

keywords.txt

@@ -95,6 +95,7 @@ setUTCTimeAssistance	KEYWORD2
 setPositionAssistanceXYZ	KEYWORD2
 setPositionAssistanceLLH	KEYWORD2
 findMGAANOForDate	KEYWORD2
+readNavigationDatabase	KEYWORD2
 
 setFileBufferSize	KEYWORD2
 getFileBufferSize	KEYWORD2