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

  1. The application on your server shall

    1. get the request through an http server and extract the payload

    2. send the dummy response to the module in the format specified in the next section to close the loop

    3. generate the API as described in the specifications and get the estimated position back. The API payload contains the raw measurement just extracted at step 1.

Dummy response format

A dummy response is required to close the loop, and acknowledge the CEL module request so that it stop listening for the answer.

The dummy response to be sent by your application server to the device (CEL module) , shall contain:

  • the status line HTTP /1.1 200 OK

  • no headers

  • the response body with a dummy payload in the format of a UBX-MGA-INI-TIME_UTC frame that has the structure reported below. You can use the standard dummy payload reported here:

B5 62 13 40 18 00 10 00 00 12 E5 07 05 1B 0C 1F 0F 00 C0 1E 6B 24 00 00 00 00 80 1A 06 00 E0 45

In this why the device stops the +ULOC procedure, used to request the position, and print out

+UULOC: 27/05/2021,14:42:38.000,0.0000000,0.0000000,0,20000000,0,0,0,0,0,0,0

NOTE: since it's a dummy response, it shall be ignored by the device application


UBX-MGA-INI-TIME_UTC frame structure

Send a measurement and get a position

As explained above, to trigger on the module the generation of the measurements used to get a position estimation you can use the +ULOC AT command exactly in the same way described in the Getting started guide.

Once you have received the measurement on your application server, to obtain a position you need to use the API

https://{endpoint}/v1/celllocate/s2s/location/get

as described in the CellLocate API documentation where:

  • the endpoint

  • username and password

can be retrieved in the credential section of your just created CellLocate S2S thing

The API response is in JSON format as reported below

{

"Location":

{

"Lat": 51.6387347,

"Lon": 0.1121669,

"Unc50": 20.1,

"Unc95": 70.1

},

"DateTime": "2020-08-17T20:18:12",

"DeviceID": "357861090015763",

"DeviceType": "SARA-R510S-00B-00/01.02,A00.01"

}