Skip to content

Commit

Permalink
Update corrections documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@nseidle
nseidle committed May 8, 2024
1 parent 91e2952 commit 7bac895
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 162 deletions.
58 changes: 47 additions & 11 deletions docs/correction_sources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,54 @@ Torch: ![Feature Supported](img/Icons/GreenDot.png)

*RTK Corrections Priorities Menu*

To achieve an RTK Fix, SparkFun RTK products must be provided with a [correction source](https://docs.sparkfun.com/SparkFun_RTK_Everywhere_Firmware/correction_sources/). An RTK device can obtain corrections from a variety of sources. Below is the list of possible sources (not all platforms support all sources) and their default priorities:
To get millimeter accuracy we need to provide the RTK unit with correction values. Corrections, often called RTCM, help the RTK unit refine its position calculations. RTCM (Radio Technical Commission for Maritime Services) can be obtained from a variety of sources but they fall into three buckets: Commercial, Public, and Civilian Reference Stations.

* Bluetooth
* IP (PointPerfect/MQTT)
* TCP (NTRIP)
* L-Band
* External Radio
* LoRa Radio
* ESP-Now
## Commercial Reference Networks

The *Corrections Sources* menu allows a user to specify which correction source should be given priority. For example, if corrections are provided over Bluetooth and L-Band simultaneously, the corrections from L-Band will be blocked because the Bluetooth source has a higher priority. This prevents the RTK engine from receiving potentially mixed correction signals.
These companies set up a large number of reference stations that cover entire regions and countries, but charge a monthly fee. They are often easy to use but can be expensive.

* [PointPerfect](https://docs.sparkfun.com/SparkFun_RTK_Everywhere_Firmware/quickstart-torch/#pointperfect-corrections) ($8/month) - US, EU, as well as parts of Australia, Brazil, and South Korea. Note: This is an SSR service.
* [PointOneNav](https://app.pointonenav.com/trial?src=sparkfun) ($50/month) - US, EU, Australia, South Korea
* [Skylark](https://www.swiftnav.com/skylark) ($29 to $69/month) - US, EU, Japan, Australia
* [SensorCloud RTK](https://rtk.sensorcloud.com/pricing/) ($100/month) partial US, EU
* [Premium Positioning](https://www.premium-positioning.com) (~$315/month) partial EU
* [KeyNetGPS](https://www.keypre.com/KeynetGPS) ($375/month) North Eastern US
* [Hexagon/Leica](https://hxgnsmartnet.com/en-US) ($500/month) - partial US, EU

## Public Reference Stations

![Wisconsin network of CORS](<img/Corrections/SparkFun NTRIP 7 - Wisconsin Map.png>)

*State Wide Network of Continuously Operating Reference Stations (CORS)*

Be sure to check if your state or country provides corrections for free. Many do! Currently, there are 21 states in the USA that provide this for free as a department of transportation service. Search ‘Wisconsin CORS’ as an example. Similarly, in France, check out [CentipedeRTK](https://docs.centipede.fr/). There are several public networks across the globe, be sure to google around!

## Civilian Reference Stations

![SparkFun Base Station Enclosure](img/Corrections/Roof_Enclosure.jpg)

*The base station at SparkFun*

You can set up your own correction source. This is done with a 2nd GNSS receiver that is stationary, often called a Base Station. There is just the one-time upfront cost of the Base Station hardware. See the [Creating a Permanent Base](https://docs.sparkfun.com/SparkFun_RTK_Everywhere_Firmware/permanent_base/) document for more information.

## OSR vs SSR

Not all companies providing correction services use the same type of corrections. There are two types: OSR and SSR.

![Wisconsin network of CORS](<img/Corrections/SparkFun NTRIP 7 - Wisconsin Map.png>)

*State Wide Network of Continuously Operating Reference Stations (CORS)*

Observation Space Representation (OSR) is the classic type of corrections network. This is a collection of base stations located across a geographic area. Corrections coming from this type of network provide the highest RTK accuracy (14mm or less is common when located within 10km of a base station) with the minimum convergence time (the time you have to wait before the GNSS receiver can achieve RTK Fix). Normal convergence time for an OSR is a few seconds. However, because a CORS has to be placed every few 10km, these type of networks are expensive to install and maintain. An OSR network is prone to holes or gaps in the network where a base station is not sufficiently close to maintain RTK Fix. Imagine an autonomous semi-trailer truck driving down a highway; an OSR network is extremely difficult to setup that has full coverage needed for highly kinetic applications.

[PointOne Nav](https://app.pointonenav.com/trial?src=sparkfun), and [Skylark Nx RTK](https://www.swiftnav.com/products/skylark) are examples of an OSR.

[![PointPerfect Coverage map including L-Band and IP delivery methods](<img/PointPerfect/SparkFun RTK Everywhere - PointPerfect Coverage Map Small.png>)](https://www.u-blox.com/en/pointperfect-service-coverage)

*PointPerfect Coverage map including L-Band and IP delivery methods*

State Space Representation (SSR) covers huge areas, sometimes entire continents. SSR combines the readings from a handful of base stations and creates a model for the region. This model extrapolates the needed corrections for a given area. These corrections are 'good enough' for many applications. Because SSR requires far fewer base stations, they are often a much lower-cost service. The RTK Fix accuracy is lower (20mm is possible but 40mm is common), and the convergence time increases considerably. Convergence time for an SSR can be 180 seconds or more.

The [PointPerfect](https://www.u-blox.com/en/pointperfect-service-coverage) and [Skylark Cx](https://www.swiftnav.com/products/skylark) are examples of an SSR.

![RTK Corrections Priorities Menu](<img/Terminal/SparkFun RTK Everywhere - Corrections Priorities Menu.png>)

In the serial terminal menu, pressing a letter will increase or decrease the position of a priority. For example, in the image above, pressing **D** will raise the `L-Band` priority above `TCP (NTRIP)`.
165 changes: 15 additions & 150 deletions docs/menu_corrections_priorities.md
View file
Original file line number Diff line number Diff line change
@@ -1,160 +1,25 @@
# Corrections Priorities

Torch: ![Feature Supported](img/Icons/GreenDot.png)
Torch: ![Feature Supported](img/Icons/GreenDot.png)

![Message rate configuration](<img/Terminal/SparkFun RTK Everywhere - Messages Menu.png>)
![RTK Corrections Priorities Menu](<img/Terminal/SparkFun RTK Everywhere - Corrections Priorities Menu.png>)

*The messages configuration menu*
*RTK Corrections Priorities Menu*

From this menu, a user can control the output of various NMEA, RTCM, and other messages. Any enabled message will be broadcast over Bluetooth *and* recorded to SD (if available).
To achieve an RTK Fix, SparkFun RTK products must be provided with a correction source. An RTK device can obtain corrections from a variety of sources. Below is the list of possible sources (not all platforms support all sources) and their default priorities:

Because of the large number of configurations possible, we provide a few common settings:
* Bluetooth
* IP (PointPerfect/MQTT)
* TCP (NTRIP)
* L-Band
* External Radio
* LoRa Radio
* ESP-Now

* Reset to Defaults
The *Corrections Priorities* menu allows a user to specify which correction source should be given priority. For example, if corrections are provided through Bluetooth and L-Band simultaneously, the corrections from L-Band will be discarded because the Bluetooth source has a higher priority. This prevents the RTK engine from receiving potentially mixed correction signals.

RTCM can also be enabled in both Rover and Base modes.
![RTK Corrections Priorities Menu](<img/Terminal/SparkFun RTK Everywhere - Corrections Priorities Menu.png>)

## Reset to Defaults
In the serial terminal menu, pressing a letter will increase or decrease the position of a priority. For example, in the image above, pressing **D** will raise the `L-Band` priority above `TCP (NTRIP)`.

This will turn off all messages and enable the following messages:

* NMEA-GGA, NMEA-GSA, NMEA-GST, NMEA-GSV, NMEA-RMC

These five NMEA sentences are commonly used with SW Maps for general surveying.

## Individual Messages

![Configuring the NMEA messages](<img/Terminal/SparkFun RTK Everywhere - Messages Menu NMEA.png>)

*Configuring the NMEA messages*

There are a large number of messages supported (listed below). Each message sub-menu will present the user with the ability to set the message report rate.

Each message rate input controls which messages are disabled (0) and how often the message is reported (1 = one message reported per 1 fix, 5 = one report every 5 fixes). The message rate range is 0 to 20.

**Note:** The message report rate is the *number of fixes* between message reports. In the image above, with GSV set to 4, the NMEA GSV message will be produced once every 4 fixes. Because the device defaults to a 4Hz fix rate, the GSV message will appear once per second.

The following messages are supported for Bluetooth output and logging (if available):

<table class="table">
<table>
<COLGROUP><COL WIDTH=200><COL WIDTH=200><COL WIDTH=200></COLGROUP>
<tr>
<td>&#8226; NMEA-DTM</td>
<td>&#8226; NMEA-GBS</td>
<td>&#8226; NMEA-GGA</td>
</tr>
<tr>
<td>&#8226; NMEA-GLL</td>
<td>&#8226; NMEA-GNS</td>
<td>&#8226; NMEA-GRS</td>
</tr>
<tr>
<td>&#8226; NMEA-GSA</td>
<td>&#8226; NMEA-GST</td>
<td>&#8226; NMEA-GSV</td>
</tr>
<tr>
<td>&#8226; NMEA-RMC</td>
<td>&#8226; NMEA-ROT</td>
<td>&#8226; NMEA-THS</td>
</tr>
<tr>
<td>&#8226; NMEA-VTG</td>
<td>&#8226; NMEA-ZDA</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1001</td>
<td>&#8226; RTCM3x-1002</td>
<td>&#8226; RTCM3x-1003</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1004</td>
<td>&#8226; RTCM3x-1005</td>
<td>&#8226; RTCM3x-1006</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1007</td>
<td>&#8226; RTCM3x-1009</td>
<td>&#8226; RTCM3x-1010</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1011</td>
<td>&#8226; RTCM3x-1012</td>
<td>&#8226; RTCM3x-1013</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1019</td>
<td>&#8226; RTCM3x-1020</td>
<td>&#8226; RTCM3x-1033</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1042</td>
<td>&#8226; RTCM3x-1044</td>
<td>&#8226; RTCM3x-1045</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1046</td>
<td>&#8226; RTCM3x-1071</td>
<td>&#8226; RTCM3x-1072</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1073</td>
<td>&#8226; RTCM3x-1074</td>
<td>&#8226; RTCM3x-1075</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1076</td>
<td>&#8226; RTCM3x-1077</td>
<td>&#8226; RTCM3x-1081</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1082</td>
<td>&#8226; RTCM3x-1083</td>
<td>&#8226; RTCM3x-1084</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1085</td>
<td>&#8226; RTCM3x-1086</td>
<td>&#8226; RTCM3x-1087</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1091</td>
<td>&#8226; RTCM3x-1092</td>
<td>&#8226; RTCM3x-1093</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1094</td>
<td>&#8226; RTCM3x-1095</td>
<td>&#8226; RTCM3x-1096</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1097</td>
<td>&#8226; RTCM3x-1104</td>
<td>&#8226; RTCM3x-1111</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1112</td>
<td>&#8226; RTCM3x-1113</td>
<td>&#8226; RTCM3x-1114</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1115</td>
<td>&#8226; RTCM3x-1116</td>
<td>&#8226; RTCM3x-1117</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1121</td>
<td>&#8226; RTCM3x-1122</td>
<td>&#8226; RTCM3x-1123</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1124</td>
<td>&#8226; RTCM3x-1125</td>
<td>&#8226; RTCM3x-1126</td>
</tr>
<tr>
<td>&#8226; RTCM3x-1127</td>
</tr>

</table></table>
Please see [Correction Sources](correction_sources.md) for a description of where to obtain corrections.
2 changes: 1 addition & 1 deletion docs/quickstart-torch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,6 @@ RTK Fix will be maintained as long as there is a clear view of the sky and corre

* High-precision GNSS works best with a clear view of the sky; it does not work indoors or near a window. GNSS performance is generally *not* affected by clouds or storms. Trees and buildings *can* degrade performance but usually only in very thick canopies or very near tall building walls. GNSS reception is very possible in dense urban centers with skyscrapers but high-precision RTK may be impossible.

* The location reported by the RTK device is the location of the antenna element; it's *not* the location of the pointy end of the stick. Lat and Long are fairly easy to obtain but if you're capturing altitude be sure to do additional reading on ARPs (antenna reference points) and how to account for the antenna height in your data collection software. Note: This rule does not apply when tilt compensation is activated. Go here for more information.
* The location reported by the RTK device is the location of the antenna element; it's *not* the location of the pointy end of the stick. Lat and Long are fairly easy to obtain but if you're capturing altitude be sure to do additional reading on ARPs (antenna reference points) and how to account for the antenna height in your data collection software. The Torch ARP is [here](https://docs.sparkfun.com/SparkFun_RTK_Torch/hardware_overview/#antenna-reference-point). Note: This rule does not apply when tilt compensation is activated. See the [Tilt Compensation Menu](menu_tilt.md) for more information.

* An internet connection is required for most types of RTK. RTCM corrections can be transmitted over other types of connections (such as serial telemetry radios). See [Correction Transport](correction_transport.md) for more details.

0 comments on commit 7bac895

Please sign in to comment.