Skip to content

Commit 081c9cb

Browse files
PaulZCPaulZC
authored
Merge pull request #99 from sparkfun/release_candidate
v2.2.0
2 parents d67c1e1 + 3cba4d1 commit 081c9cb

17 files changed

+2342
-49
lines changed

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

-9
Original file line numberDiff line numberDiff line change
@@ -99,15 +99,6 @@ jobs:
9999
libraries: |
100100
- source-path: ./
101101
sketch-paths: |
102-
- examples/Example10_AltitudeMSL
103-
- examples/Example11_ResetModule/Example1_FactoryDefaultviaI2C
104-
- examples/Example13_PVT/Example1_AutoPVT
105-
- examples/Example13_PVT/Example2_AutoPVT_ExplicitUpdate
106-
- examples/Example14_DebugOutput
107-
- examples/Example15_GetDateTime
108-
- examples/Example16_Nanosecond_MaxOutput
109-
- examples/Example18_PowerSaveMode
110-
- examples/Example19_DynamicModel
111102
- examples/Example20_SendCustomCommand
112103
enable-warnings-report: true
113104
enable-deltas-report: true

Diff for: ‎Adding_New_Messages.md

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
## How to add new messages to the SparkFun u-blox GNSS Arduino Library
2+
3+
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.).
4+
5+
Looking at the issue, we see that the library is not supporting the UBX-NAV-PVAT (Navigation Position Velocity Attitude Time solution).
6+
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.
7+
This makes us wonder if more new messages have been added which should also be included?
8+
9+
### Step 1: Check the Interface Description for new keys
10+
11+
* 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)
12+
* Open the interface description in Adobe Acrobat Reader DC (the free version)
13+
* Do a ```File \ Save as Text...```
14+
* Save the file in ```Text (Accessible) (*.txt)``` format
15+
* Go make a cup of tea - this takes a while
16+
* Open the txt file in Notepad++ or another editor which supports Regular Expressions
17+
* The keys will have been saved as individual lines in the format: 0xnnnnnnnn space CR LF
18+
* So all we need to do is use a regex to delete everything else
19+
* Open Search \ Replace
20+
* Click the Search Mode - Regular Expression button
21+
* In the "Find what :" box enter: ```^(?!.*0x[\dabcdefABCDEF]{8}\s\r\n).*```
22+
* Clear the "Replace with :" box
23+
* Click "Replace All"
24+
* You are left with just the keys - and a bunch of empty lines, some of which contain form feeds (\f)
25+
* Delete the empty lines (\r\n) by replacing \r\n with nothing - don't panic, this takes a few seconds
26+
* Delete the form feeds by replacing \f with nothing
27+
* Finally replace the remaining spaces (\s) with \r\n
28+
* 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
29+
* The following line (0x10340014) is the first key from the "Configuration Reference" section
30+
* Search for that key number and you will find it again half way through the file. This second copy came from "Configuration Defaults"
31+
* Delete the duplicate keys from that line onwards
32+
* Save the file
33+
* Open it in a spreadsheet, e.g. LibreOffice Calc
34+
* Select the "A" column and click "Sort Ascending A-Z"
35+
* Save the file (as Text CSV)
36+
* Use KDiff3 or another diff package to see the new additions
37+
38+
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.
39+
There are separate files for the P, R and T interfaces, plus a combined list (also sorted in ascending order).
40+
41+
Comparing HPS 1.21 to HPS 1.20, we can see that the following keys have been added:
42+
43+
* 0x10340014 CFG-BDS-USE_GEO_PRN
44+
* 0x10710005 CFG-I2CINPROT-SPARTN
45+
* 0x10730005 CFG-UART1INPROT-SPARTN
46+
* 0x10750005 CFG-UART2INPROT-SPARTN
47+
* 0x10770005 CFG-USBINPROT-SPARTN
48+
* 0x10790005 CFG-SPIINPROT-SPARTN
49+
* 0x20050035 CFG-TP-DRSTR_TP1
50+
* 0x20910605 CFG-MSGOUT-UBX_RXM_SPARTN_I2C
51+
* 0x20910606 CFG-MSGOUT-UBX_RXM_SPARTN_UART1
52+
* 0x20910607 CFG-MSGOUT-UBX_RXM_SPARTN_UART2
53+
* 0x20910608 CFG-MSGOUT-UBX_RXM_SPARTN_USB
54+
* 0x20910609 CFG-MSGOUT-UBX_RXM_SPARTN_SPI
55+
* 0x2091062a CFG-MSGOUT-UBX_NAV_PVAT_I2C
56+
* 0x2091062b CFG-MSGOUT-UBX_NAV_PVAT_UART1
57+
* 0x2091062c CFG-MSGOUT-UBX_NAV_PVAT_UART2
58+
* 0x2091062d CFG-MSGOUT-UBX_NAV_PVAT_USB
59+
* 0x2091062e CFG-MSGOUT-UBX_NAV_PVAT_SPI
60+
* 0x20910634 CFG-MSGOUT-UBX_SEC_SIG_I2C
61+
* 0x20910635 CFG-MSGOUT-UBX_SEC_SIG_UART1
62+
* 0x20910636 CFG-MSGOUT-UBX_SEC_SIG_UART2
63+
* 0x20910637 CFG-MSGOUT-UBX_SEC_SIG_USB
64+
* 0x20910638 CFG-MSGOUT-UBX_SEC_SIG_SPI
65+
66+
Interestingly, we can also see that one key has been deleted:
67+
68+
* 0x10530006 CFG-UART2-REMAP
69+
70+
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) -
71+
that HPS 1.21:
72+
73+
* adds support for SPARTN (Safe Position Augmentation for Real-Time Navigation) correction messages
74+
* enables the use of BeiDou geostationary satellites (previously, this configuration item had a different name)
75+
* enables UBX-SEC-SIG message (signal security measures) as output across the different interfaces
76+
* enables UBX_NAV_PVAT message (navigation and altitude position) as output across the different interfaces
77+
78+
There are also two new dynamic models, robotic lawn mower (11) and e-scooter model (12), which we need to add to the library.
79+
80+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/805aab18b6656513bfee473487a437754cd3965d) for the changes.
81+
82+
### Step 2: Update the combined keys file
83+
84+
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)
85+
to include the new keys.
86+
87+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/8895764f237ae494dcd0fa1ae942d487d2e1557f) for the changes.
88+
89+
### Step 3: Update u-blox_config_keys.h
90+
91+
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.
92+
Include the descriptions as defined in the Interface Description.
93+
94+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/3609da15f90a7a66b41524e77c6dc3dd76cd362c) for the changes.
95+
96+
### Step 4: Add the new message struct to u-blox_struct.h
97+
98+
The next step is to add the new struct for UBX-NAV-PVAT to u-blox_struct.h.
99+
100+
The messages are in ascending class and ID order. So we add UBX-NAV-PVAT (0x01 0x17) after UBX-NAV-HPPOSLLH (0x01 0x14).
101+
102+
The names and widths of the fields are taken directly from the interface definition.
103+
104+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/a4ba440c6240e0974c27f40b976a5ddf0fbdb9b6) for the changes.
105+
106+
### Step 5: Update SparkFun_u-blox_GNSS_Arduino_Library.h
107+
108+
Add the new message ID: ```const uint8_t UBX_NAV_PVAT = 0x17;```
109+
110+
Add the new functions to provide "auto" support for UBX-NAV-PVAT: ```getNAVPVAT```, ```setAutoNAVPVAT```, ..., ```logNAVPVAT```
111+
112+
Add new helper functions to access the most important fields: ```getVehicleRoll```, ..., ```getMotionHeading```
113+
114+
Add the pointer to the struct storage: ```UBX_NAV_PVAT_t *packetUBXNAVPVAT = NULL;```
115+
116+
Add the private init function: ```bool initPacketUBXNAVPVAT();```
117+
118+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/423a1e2ccd418dd679257edc6edeec0bd3029052) for the changes.
119+
120+
### Step 6: Update SparkFun_u-blox_GNSS_Arduino_Library.cpp
121+
122+
Now we need to update SparkFun_u-blox_GNSS_Arduino_Library.cpp:
123+
124+
#### Step 6.1: Update end()
125+
126+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/35d225e3f1abb316eda3becb7f8e2eb04ff1d17c) for the changes.
127+
128+
#### Step 6.2: Update checkAutomatic()
129+
130+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/b746d8e2742961ede95e2d06d5db3a3a557e571d) for the changes.
131+
132+
#### Step 6.3: Update processUBXpacket()
133+
134+
Take time to double-check that you have used the correct data width, signed/unsigned and position for each field.
135+
136+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/8eecdd5044f810b0e2b567150ff63a17c219fe8e) for the changes.
137+
138+
#### Step 6.4: Update checkCallbacks()
139+
140+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/b53bffaa3ae12482cfb268f23796963d0b8519c9) for the changes.
141+
142+
#### Step 6.5: Add the "auto" functions
143+
144+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/e394ae003ad38117d150598774d0552059416473) for the changes.
145+
146+
#### Step 6.6: Add the helper functions (if any)
147+
148+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/318e76383e96d6676bbb57294c25e665c0d4a31f) for the changes.
149+
150+
### Step 7: Add an example
151+
152+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/06014dc95f1b9ffae4876fbacfb9390541d7c31d) for the changes.
153+
154+
### Step 8: Update keywords.txt
155+
156+
Add the new "auto" and helper functions to keywords.txt.
157+
158+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/4f0a0ca3c5e6420be9064b91702947c23104bd1b) for the changes.
159+
160+
### Step 9: Update Theory.md
161+
162+
Add the new message to the list of "auto" messages.
163+
164+
See [this commit](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/commit/57f133259245d8071c73797e4be2ff630c2720ab) for the changes.
165+
166+
That's all folks!

Diff for: ‎README.md

+24-7
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,31 @@ u-blox makes some incredible GNSS receivers covering everything from low-cost, h
2121

2222
This library can be installed via the Arduino Library manager. Search for **SparkFun u-blox GNSS**.
2323

24-
## v2.0
24+
## Automatic support for correction services like RTK2go, Emlid Caster and Skylark (Swift Navigation)
25+
26+
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
27+
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!
28+
29+
v2.2 also includes two new functions useful for correction services:
30+
31+
* ```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
32+
* ```setHighPrecisionMode``` : adds extra decimal places in the GGA messages, increasing the resolution of latitude, longitude and altitude
33+
34+
Please see the new [Automatic_NMEA examples](./examples/Automatic_NMEA) for more details.
35+
36+
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.
37+
38+
## AssistNow<sup>TM</sup>
39+
40+
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).
41+
42+
## v2 vs. v1
2543

2644
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:
2745

2846
* Seamless support for "automatic" message delivery:
29-
* 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.
47+
* 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.
48+
* 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.
3049
* Dynamic memory allocation with clearly-defined data storage structs for each message:
3150
* 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.
3251
* Each "auto" message has a clearly-defined [data storage struct](./src/u-blox_structs.h) which follows the u-blox protocol specification precisely.
@@ -53,9 +72,7 @@ Migrating to v2.0 is easy. There are two small changes all users will need to ma
5372

5473
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.
5574

56-
## AssistNow<sup>TM</sup>
57-
58-
v2.1.0 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).
75+
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!
5976

6077
## Memory Usage
6178

@@ -83,9 +100,9 @@ The SPI examples have their [own folder](./examples/SPI).
83100

84101
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.
85102

86-
## Max (400kHz) I<sup>2</sup>C Support
103+
## I<sup>2</sup>C Support
87104

88-
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.
105+
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.
89106

90107
## Contributing
91108

Diff for: ‎Theory.md

+3
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ In v2.0, the full list of messages which can be processed and logged automatical
5454
- UBX-NAV-VELNED (0x01 0x12): Velocity solution in NED frame
5555
- UBX-NAV-HPPOSECEF (0x01 0x13): High precision position solution in ECEF
5656
- UBX-NAV-HPPOSLLH (0x01 0x14): High precision geodetic position solution
57+
- UBX-NAV-PVAT (0x01 0x17): Navigation position velocity attitude time solution (**only with ADR or UDR products**)
5758
- UBX-NAV-CLOCK (0x01 0x22): Clock solution
5859
- UBX-NAV-SVIN (0x01 0x3B): Survey-in data (**only with High Precision GNSS products**)
5960
- UBX-NAV-RELPOSNED (0x01 0x3C): Relative positioning information in NED frame (**only with High Precision GNSS products**)
@@ -70,6 +71,8 @@ In v2.0, the full list of messages which can be processed and logged automatical
7071
- UBX-HNR-ATT (0x28 0x01): Attitude solution (**only with ADR or UDR products**)
7172
- UBX-HNR-INS (0x28 0x02): Vehicle dynamics information (**only with ADR or UDR products**)
7273

74+
Please see [Adding_New_Messages](./Adding_New_Messages.md) for details on how to add "auto" support for new messages.
75+
7376
Notes:
7477
- UBX-NAV-POSLLH is not supported as UBX-NAV-PVT contains the same information
7578
- UBX-NAV-TIMEUTC is not supported as UBX-NAV-PVT contains the same information

0 commit comments

Comments
 (0)