Credentials provisioning

To use CloudLocate service accessing to the endpoint directly from the device (and not in Service to Service mode) you need two fundamental steps:

1. Create manually a Location thing for each device in the Thingstream platform and obtain the configuration parameters to access to the service:

   • hostname

   • client id (different for each device)

   • username and password (different for each device)

2. configure this information in the device.

When your fleet grows, these steps can result in an operational burden that can be resolved using the CloudLocate Zero Touch Provisioning procedure; this solution can be used when

• the device is already in the field and you want to activate the service for the first time or you need to renew the credentials;

• the device is provisioned in the production line by an automated system with internet access (while usually a device does not)

How to use ZTP

CloudLocate Zero Touch Provisioning (ZTP) is based on two elements:

1. a REST API to request to the Thingstream platform the creation of a new Location thing. The request contains in the body the parameters that are used by platform to authenticate the request an create the logical object

2. a token, created through the platform, that is shared by all your devices (or a just a group) and it is used authenticate the request and identify the group to which the new Thing shall belong. Once the procedure has been completed, the token can be removed by the device.

The request can be issued by the device in the field (or whenever it has access to Internet) or by a provisioning system in you r production line.

The platform provides in the body of the response all the parameters required to configure the MQTT client to access to CloudLocate service. In the next sections a detailed explanation is provided

Location device profile

The first step is to create a device profile for Location Things. Select the item 'Device profile' in the Location services section of the menu. Click on the button 'Create profile' and fill the fields:

• Profile name is a mnemonic string that should help you to remember a specific scenario or group of devices

• Device Type: select CloudLocate

• Flag the 'Auto Activate Devices' option if you want that the active immediately the Thing. Remember that id does not have impact on the billing until that device makes a CloudLocate request. On the other side if you do not select this option, you will need to manually activate each device from the platform

• Select then the plan to which the device shall be linked. Price plan are available also in the CloudLocate section on the pricing page. If you do not see your desired plan, access to the Plan section on the right side menù and add the desired plan, then go back in the wizard for profile selection and select it. Just remind that you can have:

  • multiple tokens linked to the same pricing plan, if you need for example to allocate different group of devices with similar usage

  • multiple tokens linked to different pricing plan

• Select the 'Hardware Code Mandatory' options if you want to accept only devices with an HW id (for example the IMEI)

Once created, you can modify the device profile, assign default tags, change the default price plan and modify the previously selected options

Setup the REST API

From the device profile page you can get:

• the API URL: https://api.thingstream.io/ztp/cloudlocate/credentials

  • API is also documented the the Service platform API documentation (Zero touch API Webservice)

• the token

The body of the request shall be in the 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 and corresponds to the parameter provided in the profile

• givenName is not mandatory but highly suggested, since it corresponds to the name of the Location Thing in the Thingstream platform

• hardwareId is mandatory only if you have selected the check box during profile creation. This parameter can be used to accept only incoming request that have a this parameter in the request

Credentials renewal

ZTP procedure can be used also anytime that you want to renew the MQTT credentials and device ID. In case of credential renewal, remember to deactivate the old Thing in the Thingstream platform, once you have completed the renewal.

It's suggest to avoid the hardcoding of the token, so that you can modify in the device without the need to do a firmware update