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:

•  Real time location:

  • Option 1:   UBXM-RXM-MEAS* payload, header and checksum excluded, with Base64 encoding . The content type of the API shall be set to plain/text. This option is not applicable to UBX-RXM-MEASX. This option is the best one to minimize the data transmission and so the base64 encoding should be done in the cloud application before issuing the API request

  • Option 2.: UBXM-RXM-MEAS* entire message, including header and checksum. The message shall be encoded in Base64 and added to the payload parameter. In this case the application/JSON content type shall be set in the API and the JSON format shall be used. Since it's a real-time location,  Date/time information is not mandatory

• Not real-time location:  as Option 2 of real-time location, but the JSON object shall include the Date/time information.

Get the position estimation with a known coarse position

If the use case allows you to know in advance a coarse position of the device with an accuracy of 100 Kms, it can be beneficial for the position estimation because:

• it help to increase the fix rate when sky view is limited

• in case of MEAS12 message, you can just send 12 bytes (UBX-RXM-MEAS12C) instead od 2x12 (UBX-RXM-MEAS12C and UBX-RXM-MEAS12D)

You can provide the coarse position in 2 formats:

• by specifying latitude and longitude or

• providing the UBX-NAV-POS-ECEF message that you can get by every u-blox GNSS receiver. Usually this information is extracted by a GNSS that is part of the network infrastructure with a u-blox receiver on-board.

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

}