PointPerfect MQTT Distribution
Overview
Introduction
The u-blox PointPerfect service offers GNSS correction data services that enable high-precision positioning. This data is provided in SPARTN format, which is fully supported by u-blox F9 GNSS receiver modules. The SPARTN format is designed to be compact and optimized for bandwidth usage. By using u-blox F9 GNSS receiver modules along with the PointPerfect service, customers can achieve optimal performance. Customers can choose between NTRIP or MQTT as the distribution protocol.
This document specifically describes the MQTT protocol delivery option. If you wish to use another distribution method such as NTRIP or L-Band, please refer to our PointPerfect Service Description page for more information about these options and see other distribution-specific steps in our PointPerfect Getting Started guide.
Benefits of MQTT
MQTT is a lightweight binary protocol that can carry smaller payloads, reducing the amount of data transmitted over the network. It is a common and well-tested language used for IoT systems. Accessing PointPerfect corrections data via the MQTT protocol is delivered as topics to provide a low bandwidth option to save power in IoT devices.
MQTT Delivery Architecture
PointPerfect corrections are distributed via MQTT version 3.1.1, using an MQTT broker to provide data via MQTT topics to filter only the data you need. Topics used will be specific to the plan you have activated, the region you are located, and the distribution method you have chosen. Data Topics provide the PointPerfect data in SPARTN format, and Key Topics needed to decrypt the data received using our Continental distribution method.
PointPerfect Topics in MQTT
When using MQTT, your device must be configured to subscribe to the appropriate topics needed to access the service. The device will need these topics to receive the correct stream for PointPerfect data and to obtain the decryption keys that may be needed for the encrypted SPARTN messages.
A list of topics specific to your PointPerfect plan can be found under the Topics tab of your Thing. Note: If you have multiple Things with different plans in your domain, please pay attention to the differences and apply the proper data topics as you configure your device.
MQTT Topic Structure
The MQTT topic structure follows the service distribution model for the MQTT delivery option and supports all solution combinations. Currently, we support these distributions:
Continental IP
Localized IP
L-band+IP
L-band (for key collection only)
The following table shows the topics used by the PointPerfect system.
NOTE: Data topics for the L-band+IP distribution are only applicable when the IP option is used.
MQTT PointPerfect Data Topics
When connecting using the MQTT protocol, PointPerfect corrections are provided through service data topics. These topics will vary between selected plans and applicable regions.
Below is a screenshot of the Topics tab in Thingstream, showing the service data topics for an IP plan with the EU region (using the Filter by Region button.) The IP correction topic for <region> includes all of the data needed for PointPerfect. Deserialized data topics (/gad, /hpac, /ocb, /clk) are also available if needed for your application.
Once you configure the topics for the PointPerfect data streams, the device is ready to access and consume the service.
MQTT Key Topics
About Dynamic Keys and MQTT Key Topics
Dynamic Keys are provided to decrypt only our Continental-wide correction streams, which are used only with our L-band or IP delivery plans when a Continental distribution is selected for an MQTT client. Clients using the Localized distribution via MQTT or NTRIP do not need these dynamic keys.
Encryption keys change every month. Your device is required to use the current encryption key to decrypt the data. “Current” and “Next” keys are provided with valid to/from start dates to provision two keys simultaneously.
You can acquire these dynamic keys in multiple ways:
Your device can subscribe to the MQTT key distribution topic associated with its plan. By subscribing to the key distribution topic, updated keys will be continuously received by your device regardless of the time it was originally published.
Keys can be manually collected from the Thingstream platform under the Credentials tab of your Thing.
In the ‘MQTT Credentials’ section, you will find the u-center config file (downloads in JSON format) that includes the Current and Next Keys along with their start date and duration.
Within the ‘L-band + IP Dynamic keys’ section the current and Next Keys are displayed with their expiration date.
See the Dynamic Keys Lease section of the PointPerfect Service Description document for an example of dynamic key messages in .JSON format.
Dynamic Key Topics in UBX format
For u-blox receivers, users can subscribe to the key distribution topic for their plan and collect the keys in UBX format. The data generated by the topic is in binary format and not encapsulated in any envelope, so it can be transferred to the receiver as it is.
/pp/ubx/0236/ip (Topic for IP dynamic keys in UBX format)
/pp/ubx/0236/Lb (Topic for L-band + IP dynamic keys in UBX format)
Below is a screenshot of the Topics tab on Thingstream showing the IP key distribution topic for an IP plan (previously selected as our example.)
Configuration
MQTT Client Authorization (Key and Certificate)
To provision a device, you will need the Client Key and Client Certificate associated with the location Thing with a PointPerfect plan. This information is found under the Credentials tab > MQTT Credentials section and can be downloaded separately or together within the u-center config (JSON) file. Once the keys and certificates are stored on your host, you can transfer them to your system to authorize its connection to the service.
Evaluate PointPerfect using u-center
For u-center connectivity, the u-center config (JSON) file is all you need to provide MQTT client authorizations. Simply open u-center, connect to your receiver’s serial port and open the MQTT client settings dialog from the Receiver menu. Select the JSON file for your device and choose the correction type either Continental or Localized. Choosing the Continental distribution method will require you to select the key and data topics, please see more about each distribution method and how to configure them in these pages:
Additional Features
AssistNow MQTT Topics with PointPerfect
Devices using PointPerfect via MQTT can subscribe to the AssistNow topics over the PointPerfect broker, with no additional charges!
AssistNow significantly reduces the time to first fix (TTFF) after a cold start by providing the latest ephemerides data (with updates) from satellite constellations. This saves time by not downloading this data from the satellites.
To get started, simply subscribe to the /pp/ubx/mga topic to receive ephemerides data for all constellations. With a message size of around 8 kB, you'll have access to all the data you need to get started.
Once you've received this data, it's time to unsubscribe and subscribe to the /pp/ubx/mga/updates topic to get incremental ephemerides updates with a message size of around 80 bytes for each satellite as they are updated.
With this bandwidth-optimized approach, your device will have the latest ephemerides data available, even during poor sky visibility and signal loss such as in urban canyons.
It is true incremental updates can reduce the amount of bandwidth required, but we should keep in mind these updates still have an impact on overall data traffic. Unless the assistance data is crucial for operations in challenging environments (such as urban canyons) we suggest avoiding subscribing to the aforementioned topics. This way you can effectively conserve valuable data traffic and reduce operational costs.
The table below shows the two different topics and their respective message size and update frequency.
Python sample script: PointPerfect MQTT Client
If you are interested to evaluate PointPerfect with an MQTT Client built-in your host application, you may please refer to PointPerfect MQTT Client sample python script available in the Thingstream Downloads PointPerfect section to get started. The script demonstrates on how to authenticate the MQTT client with the broker and subscribe to the MQTT topics.
MQTT Deserialized Topics for PointPerfect
The SPARTN correction data IP topics (e.g. /pp/ip/eu) provide the SPARTN messages in a sequential order, where clock corrections come every 5 seconds and GAD, HPAC and OCB messages come every 30 seconds. The GAD, HPAC and OCB messages are required by the receiver to achieve a PointPerfect solution.
To reduce the time the receiver takes to start using the correction data and achieve a PointPerfect solution, the device can subscribe to each of the SPARTN message topics individually. This enables the device to get the required data right away, rather than waiting for 30 seconds while subscribed to the assembled SPARTN topic.
The device needs to subscribe to the individual topics in the required order to utilize them. Once the receiver has a fix (position information), the device shall first subscribe to the GAD topic. The device shall then subscribe to the HPAC topic, and finally to the OCB topic. After the data from these three topics have been received, the device shall subscribe to the CLK topic to receive the clock corrections. Please refer to the message sequence diagram shared below.
The individual topics used by PointPerfect for SPARTN messages for IP based plan are described in the table below.
Reference Documentation
[1] ZED-F9P Integration manual, UBX-18010802
[2] u-center User guide, UBX-13005250
[3] u-blox F9 HPG 1.32 Interface description, UBX-22008968
[4] C099-F9P application board User guide, UBX- 18063024
[5] EVK-F9P-01 evaluation kit User guide, UBX-22038408
[6] Thingstream Knowledge Base – Services Support