diff --git a/Adding_New_Messages.md b/Adding_New_Messages.md new file mode 100644 index 0000000..3205e01 --- /dev/null +++ b/Adding_New_Messages.md @@ -0,0 +1,167 @@ +## 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/ZED-F9R_ProductSummary_UBX-19048775.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 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.4: Update checkCallbacks() + +See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/b53bffaa3ae12482cfb268f23796963d0b8519c9) for the changes. + +#### Step 6.5: Add the "auto" functions + +See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/e394ae003ad38117d150598774d0552059416473) for the changes. + +#### Step 6.6: 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! \ No newline at end of file