AssistNow device registration

Introduction

The GNSS receiver registration through the AssistNow Zero Touch Provisioning procedure is a mandatory step to use the service, and it is required to:

• Set the type of A-GNSS data required (AssistNow Live Orbits or AssistNow Predictive Orbits)

• Register the device in the Thingstream platform and automatically create the AssistNow Thing

• Obtain the credentials (Chipcode) used to request the AssistNow. 

The procedure is needed only once, although it can also be repeated to:

• Retrieve the Chipcode again

• Get a new Chipcode in case of suspicious activity or compromised credentials

• Get access to additional data

The Chipcode is generated server-side and is based on the GNSS receiver's unique chip identifier, provided in 'Input' during the procedure.

ZTP streamlines device setup, eliminating the need for manual configuration for each device. With ZTP, adding devices to your fleet is simplified, making it ideal for large-scale deployments. The Chipcode provides secure authentication, protecting your devices and data from unauthorized access.

ZTP is required for both Predictive Orbits and Live Orbits, with one common Chipcode used across both.

How to use ZTP 

The AssistNow ZTP is based on two elements:

• A device profile, created through the Thingstream platform, which sets up the parameters to use the service, including the AssistNow data types and the commercial plan that the devices will use once provisioned.

• A REST API that the device shall call to provision itself and receive the credentials (Chipcode) required to access the AssistNow service.

The ZTP procedure can be implemented either in the host (as part of the device firmware) or during the production line. Implementing it in the host is recommended, as it allows handling compromised credentials and supporting automatic renewal.

Thingstream portal sign-up

If not yet done, sign-up to Thingstream platform. It's free of charge, and it takes just a couple of minutes. This is a mandatory step to get access to all u-blox location services. You can also find documentation and reference implementations to accelerate your development.

With sign-up, you obtain your own domain, and you can grant access to other persons for service management

Device profile creation

The next step is to create a device profile that is used to identify all the devices that you want to enable to get access to AssistNow. This is a one-time manual step in the Thingstream platform.

In your Thingstream account, go to 'Services' > 'ZTP' > 'Device Profiles', then click on the 'Create Profile' button in the top-right corner to get access to the wizard that will guide you through the device profile creation. You will be asked to:

• Select a device type/service.

• Select Module type.

• Choose which type of AssitNow data you need (Live or Predictive Orbits)

• Select Profile Type:

  • Select the Commercial (Scale) plan to enable pay-as-you-go pricing, or if you have already purchased a bundle that includes a GNSS receiver with AssistNow Live Orbits access.

  • Select the Evaluation plan to do the initial testing. You can find more info in the next section

At the end of the wizard, you will obtain a token (alphanumeric string) to be used only for the device registration procedure (ZTP).

Note: Do not share this token outside your organization or with unauthorized individuals.

Evaluation plan 

As reported in the user guide, the number of request per device are limited to 2/day for Predictive Orbits and 10/day for Live Orbits.

The Evaluation plan allows you to increase this limit for up to 3 devices to provide up to 300 requests/month for Predictive and/or Live Orbits to enable performance testing

Please consider that

• You can have only 3 active Things per domain using the Evaluation plan.

• You cannot move a device between the evaluation plan and the commercial plan.  You need to delete the AssistNow Thing and repeat the device registration procedure with a commercial ZTP profile.

• You can have more than one Device Profile with an Evaluation plan attached, but the limit of 3 active Things is applicable per domain. You can delete or deactivate a Thing used for evaluation directly in the Thingstream Platform.

• It's not allowed to delete a Thing used with the commercial plan, but it can be deactivated if you need to block the service access to this Thing.

• If you need to delete things from your commercial device profile, please contact us at services-support@u-blox.com. 

Monitoring the device registration

By accessing the just-created device profile, you can:

• Activate/deactivate the profile by changing the 'Status' in the 'Details' section.

• Access to the profile details (ZTP endpoint, ZTP token, etc).

• Monitor how many devices are registered and how many are active in the 'Things' section (by default, after registration, the device is immediately activated).

• View the 'Events' section to verify the activation events and check for any failures.

Device registration

Now it's time to register the device by calling from the device firmware the ZTP REST API. The outcomes of this step are:

• A new AssistNow Thing: Created in your domain in the Thingstream platform and added automatically to the device profile, where you can monitor the service usage, view other details, and see the related events.

• The Chipcode: Returned in response to the API so that you can use it to access the service.

Below is a list of what is needed to implement the ZTP REST API

• Endpoint URL: You can find it in the 'Details' tab of the device profile you created (https://api.thingstream.io/ztp/assistnow/credentials)

• Provisioning Token (ZTP Token): The ZTP token can be found in the 'Details' tab of the device profile you created. It must be provided as an input parameter in the ZTP API request, as described below. The same token applies to all devices added to the same device profile.

  •  Note that the token must be sent in lowercase, for example: bxxxxxx8-0123-4567-abcde-bd12345657ab. Uppercase letters are not supported.
    Be aware that the example above is for illustration purposes only and does not represent a valid token.

• The unique GNSS identifier, retrievable using the UBX-SEC-UNIQID  message

• The GNSS HW and FW version, retrievable using the UBX-MON-VER message

• Request type: a POST shall be used

Note: if you need help on how to poll the UBX-SEC-UNIQID and UBX-MON-VER from the receiver, go to the 'GNSS unique identifier and version' section below.

{
"token": "abcdefg-xxxx-yyyy-zzzz-123456789123", 
"messages": { 
     "UBX-SEC-UNIQID": "B56227030A0002000000XXXXXXXXXXXXA03D", 
     "UBX-MON-VER": "B5620A04BE00524F4D2053504720352E31302028376232303265290000000000000000003030304130303030000046575645523D53504720352E31300000000000000000000000000000000050524F545645523D33342E313000000000000000000000000000000000004D4F443D45564B4D313031430000000000000000000000000000000000004750533B474C4F3B47414C3B424453000000000000000000000000000000534241533B515A53530000000000000000000000000000000000000000003A36" 
    } 
}

curl -X POST https://api.thingstream.io/ztp/assistnow/credentials ^
  -H "Content-Type: application/json" ^
  -d "{\"token\":\"xxxx\",\"messages\":{\"UBX-SEC-UNIQID\":\"B5xxx3\",\"UBX-MON-VER\":\"B5xxxB\"}}"

The API response should look like this:

{ 
"chipcode": "QkRCRjU0MEYxxxxxxxDMTlBQUE0", 
"serviceUrl": "https://assistnow.services.u-blox.com/GetAssistNowData.ashx"
"allowedData": "ualm, uporb_1, uporb_3, uporb_7, uporb_14, ulorb_l1, ukion, usvht, utime"
} 

and contains:

• The chipcode: a 28-character string (base64 encoding), and should be stored in a secure area of the device.

• The URL of the service endpoint to be used to request the AssistNow data

• The allowedData parameter reports the data that the device can get based on the subscription. In the example above, the device can access all Predictive Orbits and Live Orbits data. You can find the description of each parameter both in the Service Integration guide and in the REST API specifications.

Note: At the end of the device registration process, you can find the just-created Thing added automatically to the device profile, with a name equal to the GNSS receiver Unique ID. 

• For example, if the UBX-SEC-UNIQID Sent is "B56227030A0002000000XXXXXXXXXXXXA03D": the name of the Thing will be XXXXXXXXXXXX.

GNSS unique identifier and version

UBX-MON-VER

To poll the GNSS HW and FW version from the receiver:

1. Connect to the GNSS receiver

2. Poll the UBX-MON-VER message by sending the message B5620A0400000E34 to the receiver. (A Python example script can be found here: AssistNow Downloads | Thingstream)

   • B5 62 → UBX sync bytes

   • 0A 04 → Class = 0A (MON), ID = 04 (VER)

   • 00 00 → Payload length = 0 (no payload)

   • 0E 34 → Checksum ( computed according to the guidance provided in the Integration manual of the GNSS receiver)

3. Read the response: The receiver returns a UBX-MON-VER message containing the version information. You must include the binary payload exactly as received, including the sync bytes and checksum, in the JSON payload. (Check the example in the 'Device registration' section).

UBX-SEC-UNIQID

Follow the same logic to poll the Device ID from the receiver:

1. Connect to the GNSS receiver

2. Poll UBX-SEC-UNIQID message by sending the message B562270300002AA5 to the receiver. (A Python example script can be found here: AssistNow Downloads | Thingstream)

   • B5 62 → UBX sync bytes

   • 27 03 → Class = 0x27 (SEC), ID = 0x03 (UNIQID)

   • 00 00 → Payload length = 0 (no payload)

   • 2A A5→ Checksum (computed according to the guidance provided in the Integration manual of the GNSS receiver)

3. Read the response: The receiver returns a UBX-SEC-UNIQID message containing the unique GNSS receiver identifier. You must include the binary payload exactly as received, including the sync bytes and checksum, in the JSON payload. (Check the example in the 'Device registration' section).

Getting AssistNow data

Now the device is ready to get access to the AssistNow service, as explained in the User Guide, by using the Service REST API. Please do not confuse the ZTP REST API used to register the device and retrieve the credentials with the Service REST API used to get the AssistNow data. Be aware that the endpoints are also different. 

Chipcode renewal

• Device reset: The device credentials may need to be obtained again after a factory reset. In such cases, ensure that the device profile can be provisioned remotely.

• Chipcode renewal: The Chipcode may need to be renewed if it is suspected to be compromised. In this case:

  • Contact u-blox service support and provide the unique chip identifier (UBX-SEC-UNIQID) along with your Thingstream portal domain.

  • Repeat the ZTP procedure by calling the ZTP REST API to obtain a new (“fresh”) Chipcode in the response.

Troubleshooting & Error Handling

The device firmware must be robust enough to handle the following error codes: 

Next readings

• Host software

• Service integration

• Service specifications

• Service API specification

Other readings

• AssistNow testing with u-center 2