AssistNow device registration

Introduction

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

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

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

• obtain the credentials (Chipcode) used to request the A-GNSS data to AssistNow service. 

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

• retrieve again the Chipcode

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

• get access to additional data

The Chipcode is generated server-side, and it is based on the unique chip identifier of the GNSS receiver provided in input by the receiver 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 both for Predictive Orbits and Live Orbits but the same Chipcode is used.

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 themselves and receive the credentials (Chipcode) required for access to the AssistNow service.

The ZTP procedure can be implemented in the Host as part of the device Firmware or in the production line. It's suggested the first option because you can handle also the case of compromised credentials and 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

To get access to the AssistNow service the next step is to create a device profile that is used to identify all the devices that you want to enable to the same service. This step is done manually, just once, in the Thingstream platform . 

Select Location services > ZTP > Device profile to get access to the wizard that will guide you in the device profile creation. You will be asked to define:

• which type of A-GNSS data you need (Live or Predictive Orbits)

• which  pricing to apply:

  • if you have purchased a bundle that includes the GNSS receiver and the AssistNow Live Orbits service access, just select the appropriate one from the drop down menu

  • otherwise select the Commercial plan (Scale plan) to apply the pay-as-you-go pricing

  • you can also 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.

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 to 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 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 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

Monitoring the device registration

By accessing to the just created device profile you can:

• activate/deactivate the profile and access to the profile details (ZTP endpoint, ZTP token, etc)

• monitor how many devices are registered and how many are active (by default after the registration the device is immediately activated)

• verify the activation events to check any failure

Device registration

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

• an AssistNow Thing is created in your domain in the Thingstream platform, where you can see the usage, access to other details, and see the related events

• the Chipcode is returned  in response to the API so that you can use it to access to the service 

Here below some useful information to implement the ZTP REST API

• Endpoint URL: you can find it in the Details tab of the device profile just created. It's also reported here for your convenience: https://api.thingstream.io/ztp/assistnow/credentials

• input Token: you need to provide in input, according to the format below the token above generate (the same one for all devices) during the Device profile creation step. Note that it shall be sent lowercase, for example: bxxxxxx8-0123-4567-abcde-bd12345657ab
  Be aware that the current example does not provide a valid token and it is reported here only as an example. Uppercase letters are not accepted.
  
  

• 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 section at the end of this guide.

The input data shall be arranged in JSON format and sent to the ZTP endpoint (the GNSS identifier , the HW and SW version are in HEX format)

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

The API response is in the format 

{ 
"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 that   is a 28-characters 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 A-GNSS data

• the allowedData parameter that reports the data that device can get based on the subscription. In the example above, the device can access to 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 procedure, you can find the just created Thing, with a name equal to the GNSS receiver Unique ID. For example, if you have sent in input the following information

"UBX-SEC-UNIQID": "B56227030A0002000000XXXXXXXXXXXXA03D" 

The name of the Thing will be XXXXXXXXXXXX.

Getting A-GNSS data

Now the device is ready to get access to AssistNow service as explained in the main 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 A-GNSS data. Be aware that also the endpoints are different. 

Chipcode renewal

It's highly suggested to design the firmware in such a way that it can repeat the ZTP procedure for two reasons:

• you might need to obtain again the device credential after a device factory reset for example. In such case remind to have a way to provision remotely the device profile.

• you might need to renew the Chipcode because you believe that it is compromised. In this case, you should:

  • contact  the u-blox service services support providing the unique chip identifier (UBX-SEC-UNIQID) and your Thingstream portal domain.

  • repeat the ZTP procedure by calling the ZTP REST API, and obtaining thus in response the "fresh" Chipcode. 

GNSS unique identifier and version

UBX-MON-VER

There 3 simple steps

1. Connect to the GNSS receiver

2. Poll the UBX-MON-VER message by sending to the receiver the message B5620A0400000E34

   • 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 responds with a UBX-MON-VER message containing the version details. You shall in the JSON payload, the binary payload as received by the receiver, including the sync bytes and the checksum

UBX-SEC-UNIQID

In the same way you can get the receiver ID:

1. Connect to the GNSS receiver

2. Poll UBX-SEC-UNIQID message by sending to the receiver the message B562270300002AA5

   • 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 responds with a UBX-SEC-UNIQID message containing the unique GNSS receiver identifier. You shall include in the JSON payload,  the binary payload as received by the receiver, including the sync bytes and the checksum

Error handling

The device firmware shall be robust enough to handle the following error codes.

The AssistNow Thing

In addition to the Chipcode, the ZTP procedure creates an AssistNow Thing in the Thingstream platform. A Thing is the logical representation of the  GNSS receiver and allows to:

• monitor the service usage

• view and renew the Chipcode

• set a device as Developer to allow deeper testing.

• monitor the events linked to the service usage

Next readings

• Host software

• Service integration

• Service specifications

• Service API specification

Other readings

• AssistNow testing with u-center 2