PointPerfect Zero Touch Provisioning
Credentials Provisioning
To access the PointPerfect service from a device there are two fundamental steps:
You can then subscribe to the various topics to access the service as explained in the PointPerfect Getting Started Guide. However, when your fleet grows, these steps can result in an operational burden.
Without an automated mechanism, the provisioning process involves installing the device credentials at manufacturing. This process is tedious and can slow down the production line increasing manufacturing costs. That's why u-blox has developed Zero Touch Provisioning (ZTP) which allows customers to deploy devices that can provision themselves automatically in the field, the first time they access PointPerfect service.
How to use ZTP
PointPerfect ZTP is based on two elements:
A token relating to a provisioning profile which defines the characteristics of the PointPerfect Things and is used to authenticate the provisioning request.
A REST API, where devices send an HTTPS POST request to create a PointPerfect Thing. The response to this POST request contains all of the credentials required by the device in order 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 Name - This is a label to help you identify the device profile in the portal
Device Type - Defines which service the profile relates to
Auto Activate Devices - After provisioning, should the new PointPerfect Thing be left in an allocated state or automatically activated for immediate use
Select a Plan - Set the PointPerfect price plan which Things using this profile should use. This is mandatory if you have selected to auto activate devices. You can find more details about the available plans on our pricing page
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 profile is created, you'll find the ZTP endpoint URL and the provisioning token to be used on all devices that will use the profile on the Thing Details page.
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 that can be applied to the Location Thing automatically created in the platform. This parameter is optional.
token is mandatory for authentication and you get it from the device profile as explained earlier.
givenName, you can choose a friendly name for the device which is diplsayed in the portal. The name does not need to be unique.
hardwareId is a unique identifier of the device e.g. IMEI, and is mandatory if you have selected the "Hardware Code Mandatory" check box while creating the device profile.
An example of the response of the request in JSON format is shown below. The JSON response is the similar to what you will get by downloading the config file from the Thingstream portal for your PointPerfect thing. The device needs to parse the JSON received to get and store the required data ( certificates, private keys, clientID, topics to subscribe) to be able to use the service after the provisioning.
Note: Each parameter is unique and the device can store it and use it as such, except for the correction topics. The JSON file will contains the topics for the service that are applicable to the selected price plan. This may include topics relating to regions other than the one the device is in. The device needs to select the appropriate topic for the region it is in.
{
"certificate": "string",
"clientId": "f5xexxxxxxxxxxxxxxxxxxxxxxx",
"privateKey": "string",
"brokerHost": "pp.services.u-blox.com",
"supportsMqtt": true,
"supportsLband": true,
"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"
}
}
}
The PointPerfect Thing for your device auto-created as a result of the ZTP request can be seen in the Location Things section on the Thingstream platform. You can search your device using the name, or unique "hardwareId" parameters used in the provisioning request or the tags defined in the device profile. The "hardwareId" value can also be seen in the Thing details in the "Sticker Ref" field.
