Merge pull request #1 from sparkfun/Add_Config_Size_IDs

Add template methods for VALSET and VALGET

Author: PaulZC

.github/workflows/compile-sketch.yml

@@ -100,6 +100,7 @@ jobs:
             - source-path: ./
           sketch-paths: |
             - examples/Example1_PositionVelocityTime
+            - examples/VALGET_and_VALSET/Example6_multiSetVal_and_GetVal_Templates
           enable-warnings-report: true
           enable-deltas-report: true
           # verbose: true

README.md

@@ -54,9 +54,11 @@ Migrating to v3 is easy. There are two small changes all users will need to make
 v3 is _mostly_ backward-compatible with v2, but there have been some important changes. If in doubt, please look at the updated [examples](./examples).
 They have all been updated and tested with v3.
 
+### VAL_LAYER
+
 Because all module configuration is performed using the Configuration Interface, you will find that the **VAL_LAYER** has been added as
 a parameter in many methods. The set methods default to using ```VAL_LAYER_RAM_BBR``` - i.e. the configuration will be changed and stored in both
-RAM and Battery-Backed RAM. Options are: ```VAL_LAYER_RAM```, ```VAL_LAYER_BBR```, ```VAL_LAYER_FLASH``` (if your module has flash memory attached),
+RAM and Battery-Backed RAM but not flash. Options are: ```VAL_LAYER_RAM```, ```VAL_LAYER_BBR```, ```VAL_LAYER_FLASH``` (if your module has flash memory attached),
 ```VAL_LAYER_RAM_BBR``` and ```VAL_LAYER_ALL``` (all three).
 
 Please check your code. If you are using ```maxWait```, you will need to specify the LAYER too. E.g.:
@@ -84,6 +86,9 @@ Please check your code. If you are using ```maxWait```, you will need to specify
 ```
 
 Likewise, when reading (getting) the configuration, you can specify ```VAL_LAYER_RAM``` or ```VAL_LAYER_DEFAULT```. The methods default to ```VAL_LAYER_RAM```.
+(```VAL_LAYER_BBR``` and ```VAL_LAYER_FLASH``` are also supported - but earlier ZED-F9P's NACK'd reading those layers.)
+
+### VALSET and VALGET
 
 v3 provides a new way of reading (getting) values from the Configuration Interface: ```newCfgValget```, ```addCfgValget``` and ```sendCfgValget```.
 Please see the [VALSET and VALGET examples](./examples/VALGET_and_VALSET/) for more details.
@@ -106,6 +111,28 @@ To configure the ports, please use the methods:
   bool setSPIInput(uint8_t comSettings, uint8_t layer = VAL_LAYER_RAM_BBR, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
 ```
 
+### Template VALSET and VALGET
+
+Please also note that as of Jan 10th 2023 the u-blox Config Keys defined in [u-blox_config_keys.h](./src/u-blox_config_keys.h) now have their size encoded into them.
+We OR extra data into the unused bits in each key to define the size. This allows set and get template methods to cope with the different sizes. E.g.:
+
+```
+// CFG-ANA: AssistNow Autonomous and Offline configuration
+//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+const uint32_t UBLOX_CFG_ANA_USE_ANA = UBX_CFG_L | 0x10230001;    // Use AssistNow Autonomous
+const uint32_t UBLOX_CFG_ANA_ORBMAXERR = UBX_CFG_U2 | 0x30230002; // Maximum acceptable (modeled) orbit error in m. Range is from 5 to 1000.
+```
+
+```UBX_CFG_L``` is a logical boolean single bit, stored as 8-bit U1 (uint8_t). ```UBX_CFG_U2``` is 2-byte (16-bit) unsigned (uint16_t). Etc..
+
+If you are using the keys in your own code, you can restore the original key value by ANDing with the inverse of ```UBX_CFG_SIZE_MASK``` :
+
+```
+key &= ~UBX_CFG_SIZE_MASK; // Mask off the size identifer bits
+```
+
+The get and set template methods are based on an idea by Michael Ammann. Thank you @mazgch
+
 ## Compatibility
 
 v3 of the library provides support for generation F9 and M10 u-blox GNSS modules.

examples/Basics/Example22_PowerOff/Example22_PowerOff.ino

@@ -0,0 +1,88 @@
+/*
+  Powering off a ublox GNSS module
+  By: bjorn
+  unsurv.org
+  Date: July 20th, 2020
+  License: MIT. See license file for more information.
+
+  This example shows you how to turn off the ublox module to lower the power consumption.
+  There are two functions: one just specifies a duration in milliseconds the other also specifies a pin on the GNSS device to wake it up with.
+  By driving a voltage from LOW to HIGH or HIGH to LOW on the chosen module pin you wake the device back up.
+  Note: Doing so on the INT0 pin when using the regular powerOff(durationInMs) function will wake the device anyway. (tested on SAM-M8Q)
+  Note: While powered off, you should not query the device for data or it might wake up. This can be used to wake the device but is not recommended.
+        Works best when also putting your microcontroller to sleep.
+
+  Feel like supporting open source hardware?
+  Buy a board from SparkFun!
+  SparkFun GPS-RTK2 - ZED-F9P (GPS-15136)    https://www.sparkfun.com/products/15136
+  SparkFun GPS-RTK-SMA - ZED-F9P (GPS-16481) https://www.sparkfun.com/products/16481
+  SparkFun ZED-F9K Breakout (GPS-18719)      https://www.sparkfun.com/products/18719
+  SparkFun ZED-F9R Breakout (GPS-16344)      https://www.sparkfun.com/products/16344
+
+  Hardware Connections:
+  Plug a Qwiic cable into the GNSS and a BlackBoard.
+  To force the device to wake up you need to connect to a pin (for example INT0) seperately on the module.
+  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 <SparkFun_u-blox_GNSS_v3.h> //http://librarymanager/All#SparkFun_u-blox_GNSS_v3
+SFE_UBLOX_GNSS myGNSS;
+
+// define a digital pin capable of driving HIGH and LOW
+#define WAKEUP_PIN 5
+
+// Possible GNSS interrupt pins for powerOffWithInterrupt are:
+// VAL_RXM_PMREQ_WAKEUPSOURCE_UARTRX  = uartrx
+// VAL_RXM_PMREQ_WAKEUPSOURCE_EXTINT0 = extint0 (default)
+// VAL_RXM_PMREQ_WAKEUPSOURCE_EXTINT1 = extint1
+// VAL_RXM_PMREQ_WAKEUPSOURCE_SPICS   = spics
+// These values can be or'd (|) together to enable interrupts on multiple pins
+
+void wakeUp() {
+
+  Serial.print("-- waking up module via pin " + String(WAKEUP_PIN));
+  Serial.println(" on your microcontroller --");
+
+  digitalWrite(WAKEUP_PIN, LOW);
+  delay(1000);
+  digitalWrite(WAKEUP_PIN, HIGH);
+  delay(1000);
+  digitalWrite(WAKEUP_PIN, LOW);
+}
+
+
+void setup() {
+
+  pinMode(WAKEUP_PIN, OUTPUT);
+  digitalWrite(WAKEUP_PIN, LOW);
+
+  Serial.begin(115200);
+  while (!Serial); //Wait for user to open terminal
+  Serial.println("SparkFun u-blox Example");
+
+  Wire.begin();
+
+  //myGNSS.enableDebugging(); // Enable debug messages
+
+  if (myGNSS.begin() == false) //Connect to the u-blox module using Wire port
+  {
+    Serial.println(F("u-blox GNSS not detected at default I2C address. Please check wiring. Freezing."));
+    while (1);
+  }
+
+  // Powering off for 20s, you should see the power consumption drop.
+  Serial.println("-- Powering off module for 20s --");
+
+  myGNSS.powerOff(20000);
+  //myGNSS.powerOffWithInterrupt(20000, VAL_RXM_PMREQ_WAKEUPSOURCE_EXTINT0);
+
+  delay(10000);
+
+  // After 10 seconds wake the device via the specified pin on your microcontroller and module.
+  wakeUp();
+}
+
+void loop() {
+  //Do nothing
+}

examples/Callbacks/CallbackExample1_NAV_PVT/CallbackExample1_NAV_PVT.ino

@@ -3,17 +3,18 @@
   By: Paul Clark
   SparkFun Electronics
   Date: December 30th, 2020
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure the u-blox GNSS to send navigation reports automatically
   and access the data via a callback. No more polling!
 
   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
+  SparkFun GPS-RTK2 - ZED-F9P (GPS-15136)    https://www.sparkfun.com/products/15136
+  SparkFun GPS-RTK-SMA - ZED-F9P (GPS-16481) https://www.sparkfun.com/products/16481
+  SparkFun MAX-M10S Breakout (GPS-18037)     https://www.sparkfun.com/products/18037
+  SparkFun ZED-F9K Breakout (GPS-18719)      https://www.sparkfun.com/products/18719
+  SparkFun ZED-F9R Breakout (GPS-16344)      https://www.sparkfun.com/products/16344
 
   Hardware Connections:
   Plug a Qwiic cable into the GPS and a BlackBoard

examples/Callbacks/CallbackExample2_NAV_ODO/CallbackExample2_NAV_ODO.ino

@@ -3,17 +3,18 @@
   By: Paul Clark
   SparkFun Electronics
   Date: December 30th, 2020
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure the u-blox GNSS to send odometer reports automatically
   and display the data via a callback. No more polling!
 
   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
+  SparkFun GPS-RTK2 - ZED-F9P (GPS-15136)    https://www.sparkfun.com/products/15136
+  SparkFun GPS-RTK-SMA - ZED-F9P (GPS-16481) https://www.sparkfun.com/products/16481
+  SparkFun MAX-M10S Breakout (GPS-18037)     https://www.sparkfun.com/products/18037
+  SparkFun ZED-F9K Breakout (GPS-18719)      https://www.sparkfun.com/products/18719
+  SparkFun ZED-F9R Breakout (GPS-16344)      https://www.sparkfun.com/products/16344
 
   Hardware Connections:
   Plug a Qwiic cable into the GPS and a BlackBoard

examples/Callbacks/CallbackExample3_TIM_TM2/CallbackExample3_TIM_TM2.ino

@@ -3,8 +3,7 @@
   By: Paul Clark
   SparkFun Electronics
   Date: December 30th, 2020
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure the u-blox GNSS to send TIM TM2 reports automatically
   and display the data via a callback. No more polling!

examples/Callbacks/CallbackExample4_RAWX/CallbackExample4_RAWX.ino

@@ -3,8 +3,7 @@
   By: Paul Clark
   SparkFun Electronics
   Date: March 11th, 2021
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure the u-blox GNSS to send RXM RAWX reports automatically
   and access the data via a callback. No more polling!

examples/Callbacks/CallbackExample5_NAV_SAT/CallbackExample5_NAV_SAT.ino

@@ -3,8 +3,7 @@
   By: Paul Clark
   SparkFun Electronics
   Date: December 1st, 2021
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure the u-blox GNSS to send NAV SAT reports automatically
   and access the data via a callback. No more polling!

examples/Callbacks/CallbackExample6_UseCallbackDataInLoop/CallbackExample6_UseCallbackDataInLoop.ino

@@ -3,8 +3,7 @@
   By: Paul Clark
   SparkFun Electronics
   Date: April 15th, 2022
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to access the callback data from the main loop.
   The simple way to check if new data is available is to use a global flag: set it in the callback, check it and clear it in the main loop.
@@ -13,9 +12,11 @@
 
   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
+  SparkFun GPS-RTK2 - ZED-F9P (GPS-15136)    https://www.sparkfun.com/products/15136
+  SparkFun GPS-RTK-SMA - ZED-F9P (GPS-16481) https://www.sparkfun.com/products/16481
+  SparkFun MAX-M10S Breakout (GPS-18037)     https://www.sparkfun.com/products/18037
+  SparkFun ZED-F9K Breakout (GPS-18719)      https://www.sparkfun.com/products/18719
+  SparkFun ZED-F9R Breakout (GPS-16344)      https://www.sparkfun.com/products/16344
 
   Hardware Connections:
   Plug a Qwiic cable into the GPS and a BlackBoard

examples/NEO-D9S_and_NEO-D9C/Example5_QZSSL6_Corrections_with_NEO-D9C/Example5_QZSSL6_Corrections_with_NEO-D9C.ino

@@ -3,8 +3,7 @@
   By: SparkFun Electronics / Paul Clark
   Based on original code by: u-blox AG / Michael Ammann
   Date: September 23rd, 2022
-  License: MIT. See license file for more information but you can
-  basically do whatever you want with this code.
+  License: MIT. See license file for more information.
 
   This example shows how to configure a NEO-D9C QZSS-L6 receiver and have it send coorection data to a ZED-F9x via Serial (UART).
 

examples/VALGET_and_VALSET/Example1_GetVal/Example1_GetVal.ino

@@ -105,9 +105,9 @@ void setup()
   // The next line creates and initialises the packet information which wraps around the payload
   ubxPacket customCfg = {0, 0, 0, 0, 0, customPayload, 0, 0, SFE_UBLOX_PACKET_VALIDITY_NOT_DEFINED, SFE_UBLOX_PACKET_VALIDITY_NOT_DEFINED};
 
-  myGNSS.newCfgValget(&customCfg, VAL_LAYER_RAM); // Create a new VALGET construct. Read the data from the RAM layer.
+  myGNSS.newCfgValget(&customCfg, 9, VAL_LAYER_RAM); // Create a new VALGET construct. Read the data from the RAM layer.
 
-  myGNSS.addCfgValget8(&customCfg, UBLOX_CFG_I2C_ADDRESS); // Get the I2C address (see u-blox_config_keys.h for details)
+  myGNSS.addCfgValget(&customCfg, UBLOX_CFG_I2C_ADDRESS); // Get the I2C address (see u-blox_config_keys.h for details)
 
   if (myGNSS.sendCfgValget(&customCfg) == true) // Send the VALGET
   {
@@ -121,17 +121,33 @@ void setup()
 
     // We can also use the "extract" helper functions to read the data - useful for 16, 32 and 64-bit values
     // The full list is:
-    //   uint64_t extractLongLong(ubxPacket *msg, uint16_t spotToStart);  // Combine eight bytes from payload into uint64_t
-    //   uint32_t extractLong(ubxPacket *msg, uint16_t spotToStart);      // Combine four bytes from payload into long
-    //   int32_t extractSignedLong(ubxPacket *msg, uint16_t spotToStart); // Combine four bytes from payload into signed long (avoiding any ambiguity caused by casting)
-    //   uint16_t extractInt(ubxPacket *msg, uint16_t spotToStart);       // Combine two bytes from payload into int
+    //   uint64_t extractLongLong(ubxPacket *msg, uint16_t spotToStart);       // Combine eight bytes from payload into uint64_t
+    //   uint64_t extractSignedLongLong(ubxPacket *msg, uint16_t spotToStart); // Combine eight bytes from payload into int64_t
+    //   uint32_t extractLong(ubxPacket *msg, uint16_t spotToStart);           // Combine four bytes from payload into long
+    //   int32_t extractSignedLong(ubxPacket *msg, uint16_t spotToStart);      // Combine four bytes from payload into signed long (avoiding any ambiguity caused by casting)
+    //   uint16_t extractInt(ubxPacket *msg, uint16_t spotToStart);            // Combine two bytes from payload into int
     //   int16_t extractSignedInt(ubxPacket *msg, uint16_t spotToStart);
-    //   uint8_t extractByte(ubxPacket *msg, uint16_t spotToStart);      // Get byte from payload
-    //   int8_t extractSignedChar(ubxPacket *msg, uint16_t spotToStart); // Get signed 8-bit value from payload
+    //   uint8_t extractByte(ubxPacket *msg, uint16_t spotToStart);            // Get byte from payload
+    //   int8_t extractSignedChar(ubxPacket *msg, uint16_t spotToStart);       // Get signed 8-bit value from payload
+    //   float extractFloat(ubxPacket *msg, uint16_t spotToStart);             // Get 32-bit float from payload
+    //   double extractDouble(ubxPacket *msg, uint16_t spotToStart);           // Get 64-bit double from payload
 
     Serial.print("6: Current I2C address (should be 0x42): 0x");
     currentI2Caddress = myGNSS.extractByte(&customCfg, 8);
     Serial.println(currentI2Caddress >> 1, HEX); //u-blox module returns a shifted 8-bit address. Make it 7-bit unshifted.
+
+    // New in v3: we can use a template method to extract the value for us
+    
+    uint8_t i2cAddress; // We still need to know the type...
+    if (myGNSS.extractConfigValueByKey(&customCfg, UBLOX_CFG_I2C_ADDRESS, &i2cAddress, sizeof(i2cAddress))) // Get the I2C address - using the key
+    {
+      Serial.print(F("7: Current I2C address (should be 0x42): 0x"));
+      Serial.println(i2cAddress >> 1, HEX); //We have to shift by 1 to get the common '7-bit' I2C address format
+    }
+    else
+    {
+      Serial.println(F("extractConfigValueByKey failed!"));      
+    }
   }
   else
   {

examples/VALGET_and_VALSET/Example2_SetVal/Example2_SetVal.ino

@@ -57,7 +57,7 @@ void setup()
   //You can obtain them from the ZED-F9P interface description doc
   //or from u-center's Messages->CFG->VALSET window. Keys must be 32-bit.
 
-  setValueSuccess &= myGNSS.setVal8(UBLOX_CFG_NMEA_HIGHPREC, 0); //Enable high precision NMEA. UBLOX_CFG_NMEA_HIGHPREC is L (bool) but we use 8-bits (uint8_t)
+  setValueSuccess &= myGNSS.setVal8(UBLOX_CFG_NMEA_HIGHPREC, 1); //Enable high precision NMEA. UBLOX_CFG_NMEA_HIGHPREC is L (bool) but we use 8-bits (uint8_t)
 
   //setValueSuccess &= myGNSS.setVal16(UBLOX_CFG_RATE_MEAS, 100); //Set measurement rate to 100ms (10Hz update rate). UBLOX_CFG_RATE_MEAS is 16-bit U2 (uint16_t)
   setValueSuccess &= myGNSS.setVal16(UBLOX_CFG_RATE_MEAS, 1000); //Set measurement rate to 1000ms (1Hz update rate). UBLOX_CFG_RATE_MEAS is 16-bit U2 (uint16_t)

examples/VALGET_and_VALSET/Example4_multiSetVal/Example4_multiSetVal.ino

@@ -72,8 +72,8 @@ void setup()
   myGNSS.autoSendCfgValsetAtSpaceRemaining(16); // Trigger an auto-send when packetCfg has less than 16 bytes are remaining
 
   //Begin with newCfgValset
-  setValueSuccess &= myGNSS.newCfgValset(); // Defaults to configuring the setting in Flash, RAM and BBR
-  //setValueSuccess &= myGNSS.newCfgValset(VAL_LAYER_RAM); //Set this and the following settings in RAM only instead of Flash/RAM/BBR
+  setValueSuccess &= myGNSS.newCfgValset(); // Defaults to configuring the setting in RAM and BBR
+  //setValueSuccess &= myGNSS.newCfgValset(VAL_LAYER_RAM); //Set this and the following settings in RAM only
 
   // Add KeyIDs and Values
   setValueSuccess &= myGNSS.addCfgValset8(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1005_I2C, 1); //Set output rate of msg 1005 over the I2C port to once per measurement (value is 8-bit (U1))
@@ -92,6 +92,33 @@ void setup()
   }
   else
     Serial.println("Value set failed");
+
+  delay(1000);
+
+  // New in v3 : we can use the template method addCfgValset to deduce the data size automatically
+
+  //Begin with newCfgValset
+  setValueSuccess = myGNSS.newCfgValset(); // Defaults to configuring the setting in RAM and BBR
+  //setValueSuccess &= myGNSS.newCfgValset(VAL_LAYER_RAM); //Set this and the following settings in RAM only
+
+  // Add KeyIDs and Values
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1005_I2C, 1); //Set output rate of msg 1005 over the I2C port to once per measurement (value is 8-bit (U1))
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1077_I2C, 1); //Set output rate of msg 1077 over the I2C port to once per measurement (value is 8-bit (U1))
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1087_I2C, 1); //Set output rate of msg 1087 over the I2C port to once per measurement (value is 8-bit (U1))
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1127_I2C, 1); //Set output rate of msg 1127 over the I2C port to once per measurement (value is 8-bit (U1))
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1097_I2C, 1); //Set output rate of msg 1097 over the I2C port to once per measurement (value is 8-bit (U1))
+  setValueSuccess &= myGNSS.addCfgValset(UBLOX_CFG_MSGOUT_RTCM_3X_TYPE1230_I2C, 10); //Set output rate of msg 1230 over the I2C port to once every 10 measurements (value is 8-bit (U1))
+
+  // Send the packet using sendCfgValset
+  setValueSuccess &= myGNSS.sendCfgValset();
+
+  if (setValueSuccess == true)
+  {
+    Serial.println("Values were successfully set");
+  }
+  else
+    Serial.println("Value set failed");
+
 }
 
 void loop()