PointPerfect Zero Touch Provisioning
Overview of Credentials Provisioning
To access the PointPerfect service from a device, the basic steps include creating a PointPerfect Thing on our Thingstream platform and using the credentials provided in the PointPerfect Thing to provision the service onto the device.
Your device can be provisioned to use any available delivery methods provided by the PointPerfect plan (NTRIP, MQTT, L-band) with the corresponding client credentials for the device. See all of these steps explained in the PointPerfect Getting Started Guide.
As your fleet grows, performing these steps on individual devices can add time and other related costs to your organization. To reduce these costs, u-blox has developed Zero Touch Provisioning (ZTP) allowing customers to deploy devices that can provision themselves. This happens automatically the first time they access our PointPerfect service in the field.
Implementing Zero Touch Provisioning
PointPerfect ZTP is based on two elements:
A token to authenticate any provisioning request, corresponding to a Location Service Device Profile that defines the characteristics of the PointPerfect Thing(s) that will be created .
A request via REST API, where devices send an HTTPS POST request to create and provision a new PointPerfect Thing. The response to this POST request will contain the credentials required by the newly created device to access the PointPerfect service.
Creating a Device Profile
Select 'Device Profiles' from the Location Services menu on the sidebar and click on 'Create Profile' in the top right corner.
In this section
Still need help?
If you need more help or have any questions, please send an email to support@thingstream.io.
You can now set the following Device Profile attributes:
Device Profile Name - This is a label to help you identify the device profile in the portal
Device Type - Defines which service the profile relates to (PointPerfect)
Auto Activate Devices - After provisioning the new PointPerfect Thing can be left in an allocated state, or automatically activated for immediate use
Select a Plan - Set the PointPerfect price plan, which will apply to Things created with this profile. This is mandatory if you have selected to auto activate devices. You can find more details about the available plans on our pricing page
Client Protocol – Set the IP delivery method to return the appropriate credentials in the REST API response
Region – Reduce the number of subscriptions (topics) or mountpoints in the response to include only those applicable to a specific region.
Device Tags – Apply tags automatically to all devices created with this profile (can also be done individually in the REST API command)
Mandatory Hardware Code - When a device calls the provisioning API on bootstrap there is an option for it to provide an additional unique hardware code e.g. IMEI for additional security. There is also the option to use a whitelist to ensure only devices with a known hardware code can be provisioned. If you chose to make the hardware code mandatory, you have the option on what action to take if a device tries to call the provisioning API with an existing hardware code, either return an error, or return the existing device credentials.
Calling the REST API
Once the Device Profile is created with the desired plan and preferences, you will find on the Device Profile page the ZTP endpoint URL and the provisioning token to be used for creating/provisioning devices using this Device Profile.
The swagger docs for the API can be found here.
The body of the request shall be in the following format:
{"tags": ["string"],"token": "string", "givenName": "string", "hardwareId": "string" }
where:
tags refer to a list of tags to be applied to the Location Thing as it is created. This parameter is optional, and can be set either here or within the Device Profile.
token is specific to each Device Profile and mandatory for authentication
givenName, you can choose a friendly name for the device which is displayed in the portal. The name does not need to be unique.
hardwareId is a unique identifier of the device e.g. IMEI and this parameter is required when your identified Device Profile has included the "Hardware Code Mandatory" check box.
Upon a successful request the response body will include JSON code with content needed by the device to use the service, including device authentication parameters and specifics for using the selected plan and delivery methods defined in the Device Profile. The device can parse the JSON content to collect and store client authentication and connection requirements for PointPerfect after provisioning.
Note: Authentication parameters in the JSON (credentials such as certificates and private keys, username and passwords) are unique, and the device can store and use them as such.
An example of the an MQTT request response in JSON format is shown below.
{
"certificate": "string",
"clientId": "f5xexxxxxxxxxxxxxxxxxxxxxxx",
"privateKey": "string",
"brokerHost": "pp.services.u-blox.com",
"supportsMqtt": true,
"supportsLband": false,
"subscriptions": [
{
"description": "IP key distribution topic",
"path": "/pp/key/ip"
},
{
"description": "IP correction topic for EU region",
"path": "/pp/ip/eu"
},
{
"description": "IP correction topic for US region",
"path": "/pp/ip/us"
}
],
"subscriptionsTitle": "Subscriptions",
"rotatingKeyTitle": "IP Dynamic Keys",
"dynamickeys": {
"next": {
"duration": 2419199999,
"start": 1647043182000,
"value": "95axxxxxxxxxxxxxxxxxxxxxxxx"
},
"current": {
"duration": 2419199999,
"start": 1644623982000,
"value": "82xxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
An example of an NTRIP request response in JSON format is shown below.
{
"brokerPort": 0,
"ntripCredentials": {
"userName": "d2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"password": "xxxxxxxxxx",
"endpoint": "ppntrip.services.u-blox.com",
"httpPort": "2101",
"httpsPort": "2102",
"mountPoints": [
{
"path": "/EU",
"region": "Europe",
"displayName": "Europe"
},
{
"path": "/US",
"region": "United States",
"displayName": "United States"
},
{
"path": "/AU",
"region": "Australia",
"displayName": "Australia"
},
{
"path": "/KR",
"region": "Korea",
"displayName": "Korea"
}
]
},
"supportsMqtt": true,
"supportsLband": false,
"subscriptions": []
}
The PointPerfect Thing for your device (auto-created as a result of your successful ZTP request) can be seen in the Location Things section on the Thingstream platform. You can search your device using the name, the unique "hardwareId" parameters used in the provisioning request, or the tags defined in the device profile.
