PointPerfect Flex S2S
For customers who wish to distribute correction data to their fleet themselves, we offer a service to service, or S2S option.
Our PointPerfect Flex S2S data stream uses the Apache Kafka distributed event streaming platform to provide a highly performant pipeline of data. This facilitates a scalable solution with greatly increased ease of implementation for our customers.
Our flexible deployment models enable starting simply before scaling to Edge location OTA, releasing our customers to focus on the optimal distribution of specific data based on their range of end devices.
Each S2S Service is allocated 6 topics defining the data format and continent:
SPARTN_eu delivering SPARTN data for Europe
SPARTN_na delivering SPARTN data for North America
SPARTN_sa delivering SPARTN data for South America
RTCM_eu delivering RTCM data for Europe
RTCM_na delivering RTCM data for North America
RTCM_sa delivering RTCM data for South America
Controlling Data
Correction data is further split into local nodes covering a 30km² area. Thingstream makes available a Webservice API that can be used to activate these nodes for delivery into the appropriate topic.
This Webservice supports the use of the NodeID or latitude & longitude in order to locate an appropriate node in addition to an option to get all Nodes for a region.
An example data consumer is available from the Downloads section within the Thingstream portal. Instructions on how to make use of the example data consumer are detailed below.
Note: This option requires a separate S2S agreement to be in place. Please contact services-support@u-blox.com to request access.
Create a PointPerfect Flex S2S Thing
Use the navigation bar on the left side of the page of the portal to select Services then 'Thing List' from the sub menu. You will be presented with a list of all your 'Things'. At the top right hand side of the displayed window is an "Add Location Thing" button, press this button.
The 'Add Thing' dialog will be displayed. Find the tab for PointPerfect, and select 'Add PointPerfect Flex S2S Thing'.
This will start a wizard process that will require you to enter a name for your new PointPerfect Flex S2S thing. The next step will be to select an appropriate plan from the list displayed after which an 'Activate' button will be enabled. Clicking 'Activate' will result in the creation and activation of a new PointPerfect Flex S2S thing. You will then be asked to select which Kafka topics you wish to use. Enable the ones relevant to the regiosns that you operate in and click 'Continue'. You will be offered the option to 'View details', 'View Thing credentials' or simply skip and see your new Thing listed.
Something to consider prior to connecting your Kafka client is the duration that the correction data will be required for. This period of time is referred to as the Time To Live or TTL for which there is a setting on the Thing details tab. Click the Edit link and set the preferred period using the slider provided in the dialog. Each time a node is activated, the TTL timer starts and data for that node is delivered to the appropriate Kafka topic for the duration of the TTL. If an already active node is activated again, the TTL timer is reset.
PointPerfect Flex S2S sample consumer
To verify the functionality of your newly created PointPerfect Flex S2S Thing a sample python script that will act as a data consumer is available from the Downloads Center. Select Downloads from the sidebar and then PointPerfect. The tools and scripts that can be used with the PointPerfect Flex service will now be listed. Select the 'Python sample script PointPerfect Flex S2S data consumer' for download.
Configuring the PointPerfect Flex S2S sample consumer
At the top of the downloaded script you will find some notes on the minimum version of python required in order to run the script (3.8) and also a list of the dependent libraries required. Ensure your python version is compliant and that all dependent libraries have been installed.
aiokafka
aws-msk-iam-sasl-signer-python
pyspartn
There is then a section that contains a list of variable that will hold the credentials from your PointPerfect Flex S2S Thing.
KAFKA_SERVER = os.getenv('KAFKA_SERVER', '[INSERT YOUR KAFKA ENDPOINT HERE]')
KAFKA_ACCESS_KEY = '[INSERT YOUR KAFKA ACCESS KEY HERE]'
KAFKA_SECRET = '[INSERT YOUR KAFTA SECRET HERE]'
KAFKA_GROUP_ID = os.getenv('KAFKA_GROUP_ID', '[INSERT YOUR KAFKA Group Prefix HERE]_mygroup')
KAFKA_TOPIC = os.getenv('KAFKA_TOPIC', '^[INSERT YOUR KAFKA Group Prefix HERE].*$')
The server, access key, secret and group_ID are all listed on the credentials tab of your thing. You will need to select the topic that best represents your general location from the list on the 'Topics' tab.
Once the dependent libraries have been installed and all the credentials copied into the script where indicated '[INSERT......]' the script is ready to be run.
The script is invoked at the terminal as follows:
python kafka-consumer-example.py
The initial output that will indicate success is: 'Running'. This indicates a connection has been made. All that remains is to activate the node(s) required for the correction data needed by your devices.
The next steps include
Identifying a node close to your device
Registering to receive corrections from the identified node using it's node ID.
These steps are carried out using Thingstream's Customer API which makes a swagger interface to the Correction_Data_API_Webservice available.
A number of endpoints are available to assist with selecting, registering and unregistering the nodes that you need. The NodeID is formatted like this 'N4529E00731', which can be broken down as:
N4529 = lat 45.29
E00731 = lon 007.31
Authentication for this Webservice makes use of the API Credentials listed on the credentials tab of your 'Thing' and NOT the domain_key/domain_secret at the top of the page.
Simply fill in the payload for your desired endpoint and click on 'Try me' and a modal Authentication input will be displayed by your browser. This will require the Key / Secret from the API Credentials for your Thing, as mentioned previously.
Identifying a node close to your device
/correctiondata/node/locate
This endpoint provides the means to identify a node using lat and lon values and will return the nearest node provided there is one in that region.
e.g.
{
"format": "SPARTN",
"latitude": 51.2,
"longitude": 1.3
}/correctiondata/node/list/all
This endpoint enables the listing of all nodes per region. A node can be selected by doing a manual scan of the list and finding a match to the location of your Thing based on breaking down the node ID in the manner described above.
e.g.
{
"region": "eu"
}
Registering to receive corrections from the identified node using its node ID.
/correctiondata/node/register/location
It is possible to provide a precise location and register that location and have a node identified for you automatically. Specify the required data format and a specific lat and lon and the servuce will obtain the ID of the nearest node.
e.g.
{
"format": "SPARTN",
"latitude": 51.128532,
"longitude": 1.323557
}returns
{
"region": "eu",
"nodeId": "N5122E00113",
"format": "SPARTN"
}/correctiondata/node/register
When registering to receive correction data from a node using a previously identified node ID, supply the required data format e.g. 'SPARTN' and the ID of the identified node e.g. 'N4529E00731'
{
"format": "SPARTN",
"nodeId": "N4529E00731"
}/correctiondata/node/register/list
It is possible to register with more than one node and this endpoint will accept more than one node ID in addition to the required data format.
e.g.
{
"format": "SPARTN",
"nodeIds": [
"N4529E00769", "N4529E00807"
]
}After registering one or more nodeID's you will start to see the correction data being displayed by the PointPerfect Flex S2S data consumer. This demonstrates how to register for correction data from a 'Node' near to your device.
You may wish to remind yourself at some point which nodes you have registered:
correctiondata/node/list
This is the endpoint to use if you wish to see which nodes are registered for a device. Supply the Data format to see a list of node ID's returned e.g.
{
"format": "SPARTN"
}As it is possible to register for data from nodes, it is also possible to un-register from one or more nodes:
correctiondata/node/unregister
This function will unregister a single node and the payload is the same as the register call. Supply the data format and the node ID e.g.
{
"format": "SPARTN",
"nodeId": "N4529E00731"
}correctiondata/node/unregister/all
This endpoint requires no inputs and will unregister all nodes.
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com.