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 (NTRIP is for either SPARTN/NTRIP or RTCM over NTRIP), 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
Login to the Thingstream Portal & select 'ZTP -> Device Profiles' from the Location Services menu on the sidebar then click on 'Create Profile' in the top right corner of the screen.
In the following screen you can set the following Device Profile attributes (an example screen shot is included below):
-
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
For example; PointPerfect.
Selecting PointPerfect will display other attributes that can be set (see below for
more information)
-
Auto Activate Devices - After provisioning, the new PointPerfect Thing can be left in an allocated state or automatically activated for immediate use.
-
Device Tags – Apply tags automatically to all devices created with this profile (can also be done individually in the REST API command)
-
Hardware Code Mandatory - 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 improved security. There is also the option to use a allowlist 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.
When the PointPerfect Device Type is selected, the screen will update to include other attributes – see amended screen shot below.
-
Format - Either SPARTN or RTCM. Depending on the Format & Plan chosen further attributes will be shown.
-
Select a Plan (Optional) – Set the PointPerfect price plan, which will apply to Things created with this profile
Selecting a Plan is mandatory if you have chosen to auto activate your devices. You can find more details about the available plans on our pricing page.
Once the Device Profile is created, it is available in your domain.
The Device Profile screen displays the current attributes of the device, for example:
-
The current plan – if set
-
The token
-
The status of the device (Enabled / Disabled)
Many of the attributes can be updated using the Add, Edit, Change, Enable or Disable options. This includes changing the plan or setting the Status of the Thing, for example, disabling it to stop new devices from registering on it.
Calling the REST API
On the Device Profile page, you will find 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 SPARTN/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": []
}
An example of an RTCM over NTRIP request response in JSON format is shown below.
{
"rtcmCredentials": {
"userName": "BACPFqXgxrE6",
"password": "36stcUX5yD7C",
"mountPoint": "NEAR-RTCM",
"endPoints": [
{
"endpoint": "pp2ntrip-eu-dev.services.u-blox.com",
"httpPort": "2101",
"httpsPort": "2102",
"region": "Europe"
},
{
"endpoint": "ppntrip-na-dev.services.u-blox.com",
"httpPort": "2101",
"httpsPort": "2102",
"region": "North America"
},
{
"endpoint": "ppntrip-sa-dev.services.u-blox.com",
"httpPort": "2101",
"httpsPort": "2102",
"region": "South America"
}
]
},
"brokerPort": 0,
"supportsMqtt": false,
"supportsLband": false,
"subscriptions": []
}
The PointPerfect Thing for your device, that was auto created because 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. An example Location Things screen is shown below.
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com.
Comments
0 comments
Article is closed for comments.