Merge pull request #1 from sparkfun/main

merge in SparkFun's main

Author: nabelekt

Diff for: .github/workflows/compile-sketch.yml

@@ -87,27 +87,21 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v2
+        
+      - name: Branch name
+        run: echo running on branch ${GITHUB_REF##*/}
 
       - name: Compile Sketch
         uses: arduino/compile-sketches@v1
         with:
           platforms: ${{ matrix.board.platforms }}
           fqbn: ${{ matrix.board.fqbn }}
           libraries: |
-            - source-url: https://github.com/${{github.repository}}.git
+            - source-path: ./
           sketch-paths: |
-            - examples/Example10_AltitudeMSL
-            - examples/Example11_ResetModule/Example1_FactoryDefaultviaI2C
-            - examples/Example13_PVT/Example1_AutoPVT
-            - examples/Example13_PVT/Example2_AutoPVT_ExplicitUpdate
-            - examples/Example14_DebugOutput
-            - examples/Example15_GetDateTime
-            - examples/Example16_Nanosecond_MaxOutput
-            - examples/Example16_PartialSecond_MaxOutput
-            - examples/Example18_PowerSaveMode
-            - examples/Example19_DynamicModel
             - examples/Example20_SendCustomCommand
           enable-warnings-report: true
+          enable-deltas-report: true
           # verbose: true
 
     # outputs:

Diff for: Adding_New_Messages.md

@@ -0,0 +1,168 @@
+## How to add new messages to the SparkFun u-blox GNSS Arduino Library
+
+Based on [this issue](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/issues/97), here is a summary of how to add new messages to the SparkFun u-blox GNSS Arduino Library with full "auto" support (for callbacks, logging, etc.).
+
+Looking at the issue, we see that the library is not supporting the UBX-NAV-PVAT (Navigation Position Velocity Attitude Time solution).
+PVAT is a new message added in version 1.21 of the HPS (High Precision Fusion) firmware and version 33.21 of the F9 Interface Description.
+This makes us wonder if more new messages have been added which should also be included?
+
+### Step 1: Check the Interface Description for new keys
+
+* Download the latest [interface description](https://www.u-blox.com/sites/default/files/F9-HPS-1.21_InterfaceDescription_UBX-21019746.pdf) from the [u-blox website](https://www.u-blox.com/en/product/zed-f9r-module#tab-documentation-resources)
+* Open the interface description in Adobe Acrobat Reader DC (the free version)
+* Do a ```File \ Save as Text...```
+* Save the file in ```Text (Accessible) (*.txt)``` format
+* Go make a cup of tea - this takes a while
+* Open the txt file in Notepad++ or another editor which supports Regular Expressions
+* The keys will have been saved as individual lines in the format: 0xnnnnnnnn space CR LF
+* So all we need to do is use a regex to delete everything else
+* Open Search \ Replace
+* Click the Search Mode - Regular Expression button
+* In the "Find what :" box enter: ```^(?!.*0x[\dabcdefABCDEF]{8}\s\r\n).*```
+* Clear the "Replace with :" box
+* Click "Replace All"
+* You are left with just the keys - and a bunch of empty lines, some of which contain form feeds (\f)
+* Delete the empty lines (\r\n) by replacing \r\n with nothing - don't panic, this takes a few seconds
+* Delete the form feeds by replacing \f with nothing
+* Finally replace the remaining spaces (\s) with \r\n
+* Delete any spurious lines left at the start of the file. E.g. ROM and BASE and 0x118B2060. These came from the General information section
+* The following line (0x10340014) is the first key from the "Configuration Reference" section
+* Search for that key number and you will find it again half way through the file. This second copy came from "Configuration Defaults"
+* Delete the duplicate keys from that line onwards
+* Save the file
+* Open it in a spreadsheet, e.g. LibreOffice Calc
+* Select the "A" column and click "Sort Ascending A-Z"
+* Save the file (as Text CSV)
+* Use KDiff3 or another diff package to see the new additions
+
+You can find the keys in the [keys folder](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/tree/main/keys), saved as sorted text files.
+There are separate files for the P, R and T interfaces, plus a combined list (also sorted in ascending order).
+
+Comparing HPS 1.21 to HPS 1.20, we can see that the following keys have been added:
+
+* 0x10340014 CFG-BDS-USE_GEO_PRN
+* 0x10710005 CFG-I2CINPROT-SPARTN
+* 0x10730005 CFG-UART1INPROT-SPARTN
+* 0x10750005 CFG-UART2INPROT-SPARTN
+* 0x10770005 CFG-USBINPROT-SPARTN
+* 0x10790005 CFG-SPIINPROT-SPARTN
+* 0x20050035 CFG-TP-DRSTR_TP1
+* 0x20910605 CFG-MSGOUT-UBX_RXM_SPARTN_I2C
+* 0x20910606 CFG-MSGOUT-UBX_RXM_SPARTN_UART1
+* 0x20910607 CFG-MSGOUT-UBX_RXM_SPARTN_UART2
+* 0x20910608 CFG-MSGOUT-UBX_RXM_SPARTN_USB
+* 0x20910609 CFG-MSGOUT-UBX_RXM_SPARTN_SPI
+* 0x2091062a CFG-MSGOUT-UBX_NAV_PVAT_I2C
+* 0x2091062b CFG-MSGOUT-UBX_NAV_PVAT_UART1
+* 0x2091062c CFG-MSGOUT-UBX_NAV_PVAT_UART2
+* 0x2091062d CFG-MSGOUT-UBX_NAV_PVAT_USB
+* 0x2091062e CFG-MSGOUT-UBX_NAV_PVAT_SPI
+* 0x20910634 CFG-MSGOUT-UBX_SEC_SIG_I2C
+* 0x20910635 CFG-MSGOUT-UBX_SEC_SIG_UART1
+* 0x20910636 CFG-MSGOUT-UBX_SEC_SIG_UART2
+* 0x20910637 CFG-MSGOUT-UBX_SEC_SIG_USB
+* 0x20910638 CFG-MSGOUT-UBX_SEC_SIG_SPI
+
+Interestingly, we can also see that one key has been deleted:
+
+* 0x10530006 CFG-UART2-REMAP
+
+From this we can confirm - as documented by u-blox in the [Release Notes](https://www.u-blox.com/sites/default/files/ZED-F9R-02B_FW1.00HPS1.21_RN_UBX-21035491_1.3.pdf) -
+that HPS 1.21:
+
+* adds support for SPARTN (Safe Position Augmentation for Real-Time Navigation) correction messages
+* enables the use of BeiDou geostationary satellites (previously, this configuration item had a different name)
+* enables UBX-SEC-SIG message (signal security measures) as output across the different interfaces
+* enables UBX_NAV_PVAT message (navigation and altitude position) as output across the different interfaces
+
+There are also two new dynamic models, robotic lawn mower (11) and e-scooter model (12), which we need to add to the library.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/805aab18b6656513bfee473487a437754cd3965d) for the changes.
+
+### Step 2: Update the combined keys file
+
+Update [u-blox_config_keys_sorted.txt](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/blob/main/keys/u-blox_config_keys_sorted.txt)
+to include the new keys.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/8895764f237ae494dcd0fa1ae942d487d2e1557f) for the changes.
+
+### Step 3: Update u-blox_config_keys.h
+
+Update [u-blox_config_keys.h](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/blob/main/src/u-blox_config_keys.h) to include the new keys.
+Include the descriptions as defined in the Interface Description.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/3609da15f90a7a66b41524e77c6dc3dd76cd362c) for the changes.
+
+### Step 4: Add the new message struct to u-blox_struct.h
+
+The next step is to add the new struct for UBX-NAV-PVAT to u-blox_struct.h.
+
+The messages are in ascending class and ID order. So we add UBX-NAV-PVAT (0x01 0x17) after UBX-NAV-HPPOSLLH (0x01 0x14).
+
+The names and widths of the fields are taken directly from the interface definition.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/a4ba440c6240e0974c27f40b976a5ddf0fbdb9b6) for the changes.
+
+### Step 5: Update SparkFun_u-blox_GNSS_Arduino_Library.h
+
+Add the new message ID: ```const uint8_t UBX_NAV_PVAT = 0x17;```
+
+Add the new functions to provide "auto" support for UBX-NAV-PVAT: ```getNAVPVAT```, ```setAutoNAVPVAT```, ..., ```logNAVPVAT```
+
+Add new helper functions to access the most important fields: ```getVehicleRoll```, ..., ```getMotionHeading```
+
+Add the pointer to the struct storage: ```UBX_NAV_PVAT_t *packetUBXNAVPVAT = NULL;```
+
+Add the private init function: ```bool initPacketUBXNAVPVAT();```
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/423a1e2ccd418dd679257edc6edeec0bd3029052) for the changes.
+
+### Step 6: Update SparkFun_u-blox_GNSS_Arduino_Library.cpp
+
+Now we need to update SparkFun_u-blox_GNSS_Arduino_Library.cpp:
+
+#### Step 6.1: Update end()
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/35d225e3f1abb316eda3becb7f8e2eb04ff1d17c) for the changes.
+
+#### Step 6.2: Update checkAutomatic()
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/b746d8e2742961ede95e2d06d5db3a3a557e571d) for the changes.
+
+#### Step 6.3: Update getMaxPayloadSize()
+
+#### Step 6.4: Update processUBXpacket()
+
+Take time to double-check that you have used the correct data width, signed/unsigned and position for each field.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/8eecdd5044f810b0e2b567150ff63a17c219fe8e) for the changes.
+
+#### Step 6.5: Update checkCallbacks()
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/b53bffaa3ae12482cfb268f23796963d0b8519c9) for the changes.
+
+#### Step 6.6: Add the "auto" functions
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/e394ae003ad38117d150598774d0552059416473) for the changes.
+
+#### Step 6.7: Add the helper functions (if any)
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/318e76383e96d6676bbb57294c25e665c0d4a31f) for the changes.
+
+### Step 7: Add an example
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/06014dc95f1b9ffae4876fbacfb9390541d7c31d) for the changes.
+
+### Step 8: Update keywords.txt
+
+Add the new "auto" and helper functions to keywords.txt.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/4f0a0ca3c5e6420be9064b91702947c23104bd1b) for the changes.
+
+### Step 9: Update Theory.md
+
+Add the new message to the list of "auto" messages.
+
+See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/57f133259245d8071c73797e4be2ff630c2720ab) for the changes.
+
+That's all folks!

Diff for: README.md

@@ -21,12 +21,35 @@ u-blox makes some incredible GNSS receivers covering everything from low-cost, h
 
 This library can be installed via the Arduino Library manager. Search for **SparkFun u-blox GNSS**.
 
-## v2.0
+## Automatic support for correction services like PointPerfect (u-blox), RTK2go, Emlid Caster and Skylark (Swift Navigation)
+
+u-blox's PointPerfect GNSS augmentation service uses the secure MQTT protocol to download SPARTN format correction data, providing "3-6 cm accuracy and convergence within seconds". Please see the new [PointPerfect Client example](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/tree/main/examples/ZED-F9P/Example18_PointPerfectClient) for more details.
+
+v2.2.1 also supports L-band correction services using the new u-blox NEO-D9S correction data receiver. Please see the new [L-band Corrections example](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/tree/main/examples/ZED-F9P/Example19_LBand_Corrections_with_NEO-D9S) for more details.
+
+Other RTK NTRIP corrections services often require you to send them your location in NMEA GPGGA format. v2.2 of the library makes this easy by providing get functions and automatic callbacks
+for both GPGGA and GNGGA messages. You can now instruct your module to output GPGGA (e.g.) every 10 seconds and then push it to the correction server directly from the callback. No more polling, no more parsing!
+
+v2.2 also includes two new functions useful for correction services:
+
+* ```setMainTalkerID``` : lets you change the NMEA Talker ID (prefix) from "GN" to "GP" - just in case your correction service really does need GPGGA, not GNGGA
+* ```setHighPrecisionMode``` : adds extra decimal places in the GGA messages, increasing the resolution of latitude, longitude and altitude
+
+Please see the new [Automatic_NMEA examples](./examples/Automatic_NMEA) for more details.
+
+We've also added a new [NTRIP Caster Client example](./examples/ZED-F9P/Example17_NTRIPClient_With_GGA_Callback) showing how to use these new features to full effect.
+
+## AssistNow<sup>TM</sup>
+
+v2.1 of the library adds support for u-blox AssistNow<sup>TM</sup> Assisted GNSS (A-GNSS) which can dramatically reduce the time-to-first-fix. You can find further details in the [AssistNow Examples folder](./examples/AssistNow).
+
+## v2 vs. v1
 
 This library is the new and improved version of the very popular SparkFun u-blox GNSS Arduino Library. v2.0 contains some big changes and improvements:
 
 * Seamless support for "automatic" message delivery:
-  * In v1.8, you could ask for the NAV PVT (Navigation Position Velocity Time) message to be delivered _automatically_, without polling. v2.0 adds automatic support for [**23 messages**](./Theory.md#auto-messages), covering the full range of: standard and High Precision position, velocity and time information; relative positioning; event capture with nanosecond time resolution; raw GNSS signal data including carrier phase; Sensor Fusion; and High Navigation Rate data.
+  * In v1.8, you could ask for the NAV PVT (Navigation Position Velocity Time) message to be delivered _automatically_, without polling. v2.0 adds automatic support for [**26 messages**](./Theory.md#auto-messages), covering the full range of: standard and High Precision position, velocity, attitude and time information; relative positioning; event capture with nanosecond time resolution; raw GNSS signal data including carrier phase; Sensor Fusion; and High Navigation Rate data.
+  * Don't see the message you really need? [Adding_New_Messages](./Adding_New_Messages.md) provides details on how to add "auto" support for your favourite message.
 * Dynamic memory allocation with clearly-defined data storage structs for each message:
   * There are no static 'global' variables to eat up your RAM. v2.0 automatically allocates memory for the automatic messages when they are enabled. You may find your total RAM use is lower with v2.0 than with v1.8.
   * Each "auto" message has a clearly-defined [data storage struct](./src/u-blox_structs.h) which follows the u-blox protocol specification precisely.
@@ -53,6 +76,8 @@ Migrating to v2.0 is easy. There are two small changes all users will need to ma
 
 If you are using the Dead Reckoning Sensor Fusion or High Dynamic Rate messages, you will need to make more small changes to your code. Please see the [dead reckoning examples](./examples/Dead_Reckoning) for more details. There is more detail available in [Theory.md](./Theory.md#migrating-your-code-to-v20) if you need it.
 
+There is a [new example](./examples/Dead_Reckoning/Example8_getNAVPVAT) showing how to read the UBX-NAV-PVAT (Position, Velocity, Attitude, Time) with a single function call. UBX-NAV-PVAT has full "auto" callback and data-logging support too!
+
 ## Memory Usage
 
 The u-blox GNSS library has grown considerably over the years and v2.0.8 came very close to completely filling the program memory on platforms like the ATmega328 (Arduino Uno).
@@ -79,9 +104,13 @@ The SPI examples have their [own folder](./examples/SPI).
 
 Please check the module datasheets for details on what clock speeds and data rates each module supports. The maximum clock speed is typically 5.5MHz and the maximum transfer rate is typically 125kBytes/s.
 
-## Max (400kHz) I<sup>2</sup>C Support
+## I<sup>2</sup>C Support
+
+For I<sup>2</sup>C communication, please be sure to remove all additional pull-ups on the I<sup>2</sup>C bus. u-blox modules include internal pull-ups on the I<sup>2</sup>C lines (sometimes called DDC in their manuals). Cut all I<sup>2</sup>C pull-up jumpers and/or remove them from peripheral boards. Otherwise, various data glitches can occur. See issues [38](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/38) and [40](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/40) for more information. We recommend running the I<sup>2</sup>C bus at 100kHz.
+
+## Compatibility
 
-To achieve 400kHz I<sup>2</sup>C speed please be sure to remove all pull-ups on the I<sup>2</sup>C bus. Most, if not all, u-blox modules include internal pull ups on the I<sup>2</sup>C lines (sometimes called DDC in their manuals). Cut all I<sup>2</sup>C pull up jumpers and/or remove them from peripheral boards. Otherwise, various data glitches can occur. See issues [38](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/38) and [40](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/40) for more information. If possible, run the I<sup>2</sup>C bus at 100kHz.
+v2 of the library provides support for generation 8, 9 and 10 u-blox GNSS modules. For generation 6 and 7, please see [this example (depricated)](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/tree/master/examples/Series_6_7/Example1_GetPositionAndTime_Series_6_7).
 
 ## Contributing
 

Diff for: 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.
 
@@ -55,9 +54,11 @@ In v2.0, the full list of messages which can be processed and logged automatical
 - UBX-NAV-VELNED (0x01 0x12): Velocity solution in NED frame
 - UBX-NAV-HPPOSECEF (0x01 0x13): High precision position solution in ECEF
 - UBX-NAV-HPPOSLLH (0x01 0x14): High precision geodetic position solution
+- UBX-NAV-PVAT (0x01 0x17): Navigation position velocity attitude time solution (**only with ADR or UDR products**)
 - 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
@@ -70,6 +71,8 @@ In v2.0, the full list of messages which can be processed and logged automatical
 - UBX-HNR-ATT (0x28 0x01): Attitude solution (**only with ADR or UDR products**)
 - UBX-HNR-INS (0x28 0x02): Vehicle dynamics information (**only with ADR or UDR products**)
 
+Please see [Adding_New_Messages](./Adding_New_Messages.md) for details on how to add "auto" support for new messages.
+
 Notes:
 - UBX-NAV-POSLLH is not supported as UBX-NAV-PVT contains the same information
 - UBX-NAV-TIMEUTC is not supported as UBX-NAV-PVT contains the same information