PointPerfect Service to Service (S2S) getting started

PointPerfect S2S

For customers who wish to distribute correction data to their fleet themselves, we offer a service to service, or S2S option.

Our PointPerfect 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 20km² 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 S2S Thing

Use the navigation bar on the left side of the page of the portal to select Location Services then 'Thing List' from the sub menu. You will be presented with a list of all your Location Service 'Things'. At the top right hand side of the displayed window is an "Add Location Thing" button, press this button.

The 'Add Location Thing' dialog will be displayed.  Find the tab for PointPerfect and select 'Add PointPerfect S2S Thing'.

This will start a wizard process that will require you to enter a name for your new PointPerfect 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 of a new PointPerfect S2S thing and you will be offered the option to 'View details',  'View Thing credentials' or simply skip and see your new Thing listed.

Once your new PointPerfect S2S Thing has been created you will need to consider the correction data that will be obtained by your Thing.  This will involve identifying an appropriately located node to activate after deciding which format of data best suits your needs. 

Something to consider prior to this 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 S2S sample consumer

To verify the functionality of your newly created PointPerfect S2S Thing a sample python script that will act as a data consumer is available from the Location Services Downloads Center.  Select Location Services from the Side bar and then Downloads from the Sub Menu.  Select PointPerfect next.

A list of tools and scripts for use with the PointPerfect service is listed.  Select the 'Python sample script PointPerfect S2S data consumer' for download.

Configuring the PointPerfect 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 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 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.