CellLocate Service-to-Service access

Introduction

Service-to-Service access allows to access to the service requesting the location estimation directly from your application platform instead of from your devices. This approach is preferred, for example,  whenever you need the position information directly on server side  and not in the device or when your fleet does not have access to the public internet and cannot reach directly the CellLocate end-points reported in the Getting started guide.

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

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. If not, we invite you to start with this step that takes few minutes and it's free.

2. you have registered a credit card in the portal or you have a credit line active, just in case you want to use a paid plan. But you can start even with the developer plan that is free of charge.

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 CellLocate S2S Thing, just one for all your fleet. 

2. Select the preferred pricing plan or the developer plan

3. Get the credentials for REST API access

4. Setup your application platform to receive the measurements from the device, used for location estimation

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

Create a CellLocate S2S Thing

The first step is to create a CellLocate S2S things that provides you all the parameters to issue 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 CellLocate section from where you can select the wizard to create CellLocate 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. 

Module configuration

The module can be configured using  the same AT command reported in the Getting started guide

AT+UGSRV="primaryServer","secondaryServer","optional_device_ID"

where:

• primary server is the url of your application server

• secondary server is optional and can be a fallback url of your application server

• optional_device_ID  can be a custom alphanumeric string, used to identify the device  (for example it can be the IMEI) when your application server receives the HTTP request explained in the next section. It's an alphanumeric string  of maximum 22 characters:

  • numbers

  • capital and small

  • underscore ( _ ) and dash ( _ ) special characters

This ID is for your internal use and you do not need to forward it to CellLocate endpoint

Setup your application platform

The picture below displays the flow of data to obtain a position estimation:

1. The CEL module is triggered through the ULOC command (see Getting started guide) to generate a raw measurement containing all the information required for position estimation

2. Once the raw measurement is ready, the CEL module automatically sends the payload through a HTTP request to the server configured above (your application platform). The request is:

/CellGetOnlineData.ashx?celltype=gsm;token=XXXXXXXXXXXXXXXXXX;datatype=pos;format=mga;

where the token parameter is the information configured through the UGSRV command  described in the previous section and can represent a device identifier

3. The application on your server shall

   • Get the request through an http server and extract the payload

   • Convert the binary payload in base64 format and create a JSON body payload for the API as described in the specifications  and get the estimated position back. 

   • You have two options for the response you need to send back to the device because loop should be closed otherwise cellular module will wait for the response:

     1. If you don't want position in the device then you can send the dummy response to the module in the format specified in the next section to close the loop

     2. To send the position on the device you can send the UBXResponse received in the API response to the module.  UBXResponse  is base64 encoded string so before sending back to the device you need to decode the string in bytes and send the binary payload to device