CloudLocate Service-to-Service access using REST API

Introduction

Service-to-Service access enables you to leverage the power of CloudLocate sending the GNSS measurements from your application platform, instead of directly using your IoT device.

This documentation will guide you through the process of setting up your Thingstream account for service-to-service access using the REST API

As an alternative option, you can publish the data using an MQTT client as described in this guide.

Prerequisites

The prerequisites to complete the procedure are:

  1. you have access to the u-blox Thingstream portal and you have already created a domain

  2. you have registered a credit card in the portal or you have a credit line active.

  3. you have knowledge and tools about how to send an API request

Procedure overview

The mains steps of this procedure are

  1. Create a CloudLocate S2S Thing, just one for all your fleet.

  2. Select the preferred pricing plan

  3. Get the credentials for REST API access

  4. Send the measurements using the API and get the location back


Create a CloudLocate S2S Thing

The first step is to create a CloudLocate S2S things that provides you all the parameters to send the API:

  • username and password

  • service endpoint

The Thing let also you to:

  • modify the pricing plan

  • deactivate/ reactivate the access

  • monitor the usage of the service

  • and look at the the events

Sign-in into the Thingstream portal and select the Location Things item from the Location Services section. Click the button to create a new Location Thing and browse to the CloudLocate section from where you can select the wizard to create CloudLocate S2S Thing.

During the creation steps you are suggested to assign a price plan. If you skip this step the Thing will not be automatically activated and cannot be used. When you are ready to assign a plan, open the Thing panel and assign the preferred one.

Get the position estimation

To obtain the position estimation, send the raw measurement generated by the GNSS in the device to CloudLocate service endpoint using a REST API.

Note: the endpoint is specified in the details panel of the just created CloudLocate S2S thing

API specifications are available at https://clapi.services.u-blox.com/.

You can send the raw measurement in one of the two allowed format:

  1. as a binary payload. Additional information about binary format are available at this page

  2. as a base64 encoded hex string;

As explained in the API documentation, in case of delayed message, date and time shall be added in the header of the request.

Get the position estimation with a known coarse position

As described in the API specification, using the UBX-RXM-MEAS12 there are 2 options available:

  • Option 1: capture from the GNSS both the UBX-RXM-MEAS12C and UBX-RXM-MEAS12D raw measurements (respectively Codephase and Doppler) and send both to CloudLocate S2S interface. Each of them is 12 bytes long.

{

"Constellation": "GPS",

"Doppler": "AuVPRZoYW7MON8pS",

"CodePhase": "bJ9ZdHY8GxDE+kc7"

}

  • Option 2: if the device is located in an area around 100 km radius from a known position, you can capture only the UBX-RXM-MEAS12C measurements from the M10 GNSS and send it to your application platform, that will issue the position estimation request (through the API) by adding the known position information (CoarsePosition parameter).

{

"Constellation": "GPS",

"CoarsePosition": "tWIBARQAiHSTC0CLVhfbMvj/wg3pHUwAAAAN6w==",

"CodePhase": "aaF3+7PMbliRXxl8"

}

This option is very useful whenever you want to minimize the transmitted payload and your fleet is located in a known area.

The CoarsePosition parameter format is reported in the following and it is according to the Earth-Centered, Earth-Fixed (ECEF) coordinate system. As shown above, the parameter shall be Base64 encoded.

Note: you do not need necessary a u-blox GNSS to generate the Coarse position information, just a payload formatted as below

Checksum field generation

The checksum is calculated over the message, starting and including the class field up until, but excluding, the checksum fields (see the figure UBX frame structure). The checksum algorithm used is the 8-bit Fletcher algorithm, which is used in the TCP standard RFC 1145). This algorithm works as follows:

  • Buffer[N] is an array of bytes that contains the data over which the checksum is to be calculated.

  • The two CK_A and CK_A values are 8-bit unsigned integers, only! If implementing with larger sized integer values, make sure to mask both CK_A and CK_B with the value 0xff after both operations in the loop.

  • After the loop, the two U1 values contain the checksum, transmitted after the message payload, which concludes the frame.

CK_A = 0, CK_B = 0

For (I = 0; I < N; I++)

{

CK_A = CK_A + Buffer[I]

CK_B = CK_B + CK_A

}