CellLocate getting started

Introduction

A Global Navigation Satellite System (GNSS) receiver cannot determine a position when satellite signals are unavailable, such as in urban canyons, indoors, parking garages, or when GNSS jamming signals are present. For fleet asset tracking and supply chain management, it’s unacceptable. On the other hand, cellular network cells and Wi-Fi access points are widely available, even in areas where GNSS signals are poor or absent. Network-based location using cellular and short-range radio attributes provides an alternative to no position fix at all.

CellLocate is a robust network-based location service that delivers location data where you need it, in the cloud, even in areas where GNSS is poor or absent, by using cellular and Wi‑Fi network attributes. It is ready to use since it is embedded in u-blox cellular and short-range modems. You can manage entire fleets with our easy-to-use IoT platform and flexible predictable plans. This end-to-end solution is proven, scalable, and ready to virtually eliminate any “no position” scenario.

In a nutshell

CellLocate provides an estimated location based on visible network cell information reported by the cellular module. When CellLocate is activated, a data connection to the CellLocate server is established and the network cell information is passed to the server which provides an estimation of the device position based on the cell information.

CellLocate is fully integrated into u-blox GSM/GPRS, HSPA/UMTS, LTE-M, and LTE Cat 1 cellular modules and works in parallel to normal module functionality. The technology enables stand-alone location data based on surrounding mobile network information as well as hybrid technology that works in conjunction with GNSS. Through the single AT command interface, it is possible to define all the location settings for optimized performance.

When using CellLocate, the position accuracy is not predictable and is determined by the availability in the database of previous observations within the same area. CellLocate does not require a GNSS receiver to be present or active.

Service configuration - obtain a token

To use the service you need a valid token (an alphanumeric string)  generated by the  Thingstream platform. The token needs to be configured on each module as explained  in a later section, to grant the access to the service. 

To get a token:

• Sign-in to the Thingstream platform

• Go to Location services > Location Things and click on the Add Location Thing button

• Select CellLocate > Generate Token and follow the wizard

For further information check the token management section for more information on creating and managing your tokens.

NOTE: the token is used to authorize your device to access to the service and it's valid for the entire fleet. During the wizard, you are requested to associate to the token a price plan (it can be a developer or a paid plan).

Device configuration

Configuring the device and use the service is extremely simple. You just need

• to set the server URL and the authentication token

• to set the cell scan mode as normal or deep

This configuration is persistent and need only be done once.

Configuring server settings

To configure the service endpoints and the token use this AT command

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

where:

• primary and secondary server shall be set as cell-live1.services.u-blox.com and cell-live2.services.u-blox.com unless you need to work in Server to Server mode as explained in one of the following section

• your_auth_token is the authentication token that you generated on the Thingstream platform

AT+UGSRV="cell-live1.services.u-blox.com","cell-live2.services.u-blox.com","abcdefg123456"

• For LENA-R8 use lscellapi.services.ublox.com  as primary server and ignore the secondary server.

Configuring the cell scan mode

There are two modes to choose from:

• normal scan: the cellular module reports the serving cell and the neighboring visible cells designated by the network operator, which are normally collected by the module during its “network” activity. This configuration is suggested for a quick update of location

• deep scan: the cellular module scans and reports all visible cells providing in addition to serving and neighboring cells by the serving network operator, also the cells of all other available (visible) network operators,  thus increasing the probability of obtaining a successful position estimation. Although this takes a bit longer (approximately 30 sec to 2 minutes is needed to perform a deep scan), uses more data (each reported cell requires a few bytes), and more power, coverage and reliability are potentially better in corner cases.

Note: Deep scan configuration is generally recommended only for corner cases that must be individually considered and tested

Scan mode can be configured using the AT+ULOCCELL= <value> where:

• <value> = 0 for normal scan

• <value> = 1 for deep scan

Note: deep scan is not supported by all the modules. Refer to the module AT manual to verify compatibility

Note: Both settings AT+UGSRV and AT+ULOCCELL are persistent.

The scan mode influences the time needed to complete the scan, so the timeout value (explained in the next section) should be set accordingly. Be aware that the cell information is sent to the server only when the scan is completed, so setting a small value for the timeout means that the scan information may not be used.

Using the service

The AT+ULOC command is used every time that the device application wants to get a position using CellLocate. The command syntax is:

AT+ULOC=<mode>,<sensor>,<response_type>,<timeout>,<accuracy>

Where recommended settings are:

• <mode> = 2 (single-shot position)

• <sensor> = 2, (CellLocate) 

• <response_type>  (see section below)

  • 0  - standard response type

  • 1 - detailed response

  • 2 - multi-hypothesis response

• <timeout> = 30 (normal scan).  The timeout value defines the maximum amount of time in seconds allocated for the cell scan operation. 

  • If timeout is  exceeded, the module sends the list of cells that it was able to collect before the timeout is reached. The timer is particularly important for deep scan mode because, as described previously, setting a short value does not allow a complete collection of cell ID of other operators than the serving one. 

  • In the event that the timeout is reached before the scan is complete, the output of normal scan will be sent to service endpoint to fulfill the request. 

  • most of the time, the scan is completed in few seconds; in such case the request is sent to the service without waiting the timeout expiration

• <accuracy> = 30. This parameter (expressed in meters) specifies the target accuracy when using hybrid positioning (CellLocate + GNSS).  

If you are not using hybrid positioning (that is only Cellular positioning without GNSS) you shall set a low value (1-30) so that at any location request sent in the AT interface corresponds to a request to the service and thus a cloud position estimation. 

If you setting an high value of <accuracy> (for example 150), the logic inside the modem, evaluates if it is possible to provide a solution without contacting the server to minimize the data and energy consumption.

Note: to know more about the logic implemented in the CellLocate client inside the u-blox cellular module, send a request to services-support@u-blox.com providing also the cellular model that you are using.

Here below the typical location request

 AT+ULOC=2,2,0,30,30

Note: Please check the AT command manual for your module type in the product documentation section of the u-blox website to find the full set of available parameters.

Once the device application has sent the command to the module, the module autonomously:

• collects all the information required to get the position

• request the position estimation to the service, using a proprietary protocol

• waits for the response from the server

• provides back to the application, date, time and location information

An example of response (when response_type=0) is:

+UULOC: 13/04/2011,09:54:51.000,45.6334520,13.0618620,35,115

that complies to this format

+UULOC: <date>,<time>,<lat>,<long>,<alt>,<uncertainty>

where :

• <date> is a String that represents UTC date(DD/MM/YY) of the estimated position coming from the CellLocate server

• <time> is a String that represents UTC time (hh:mm:ss.sss) of the estimated position coming from the CellLocate server

• <lat> and <lon> are strings representing the estimated latitude and longitude 

• <alt>  is a number reporting the estimated altitude, in meters. This is available only for hybrid positioning using GNSS and thus it is set to 0 when using CellLocate as the sensor

• <uncertainty> is a number that represents the estimated 50% confidence level error, in meters (0 - 20000000). For a higher confidence level, read the relevant section below

Extended responses

There is the possibility to get an extended response to obtain additional useful parameters, by setting it properly in the request. 

AT+ULOC=<mode>,<sensor>,<response_type>,<timeout>,<accuracy>

Standard response type

The standard response type described above is obtained by using the value <response_type>=0. As explained above the response is provided in the following format

+UULOC: <date>,<time>,<lat>,<long>,<alt>,<uncertainty>

where  <uncertainty> provides the uncertainty of the position estimation at 50th percentile.

Detailed response

This is obtained by setting <response_type>=1.

The resposne is in the following format

+UULOC: <date>,<time>,<lat>,<long>,<alt>,<uncertainty>,<speed>,<direction>,<vertical_acc>,<response_source>,<SV_used>,<antenna_status>,<jamming_status>

Most of these additional parameters (compared to standard response) are relevant only in case of hybrid positioning (CellLocate + GNSS) , but the <response_source> parameter is useful to understand if the location response is provided by the server (response_source = 2) or by the module (response_source=0) becuse of the client logic in the module.

Multi-hypothesis response type

By setting <response_type>=2, as explained in the following "Confidence level" section,  you can obtain additional information like

• Sensor used

• uncertainty at 50th and 95th percentile (major50 and major95)

+UULOC: <sol>,<num>,<response_source>,<date>,<time>,<lat>,<long>,<alt>,<lat50>,<long50>,<major50>,<minor50>,<orientation50>,<confidence50>,<lat95>,<long95>,<major95>,<minor95>,<orientation95>,<confidence95>

It is worth noting that

•  the parameters  minor and orientation are not used in the current FW releases, and the reported value should not be considered

• the lat50, lon50, lat95 and lon95 will be used in future FW releases. In the current FW these values are always a replica of lat, lon parameters

• the sol and num parameters are useful to indicate respectively the solution index and the total number of hypothesis, in case you would have specified the optional  <num_hypothesis> as reported below. This feature allows you to receive from CellLocate  service multiple possible location estimation.  The default value of sol and num parameter is 1

AT+ULOC=<mode>,<sensor>,<response_type>,<timeout>,<accuracy>,<num_hypothesis>

Understanding errors

It's recommended to always activate the ULOC URCs to understand how the location request is progressing and if there is any issue. 

To activate the URC, you can use AT+ULOCIND=<mode> where mode can be  0 or 1 to disable or enable URCs. The response is in the format

+UULOCIND: <step>,<result>

where steps indicate which is the on-going task of the Cellular modem, while result represent the result of the task.

Wi-Fi location

CellLocate includes the capability to locate a device using the nearby Wi-Fi access points. Especially in urban environments, this greatly improves the accuracy of the solution provided.  To know more, visit the Wi-Fi location section.

Other ways to access the service

Service to Service access

Some use cases impose that the device communicates only with your application server. To address this requirement it is possible also to work in Service to Service mode where the device sends the raw data to the your application server that will then provide these raw data  to the CellLocate endpoints using a REST API; the service returns the position estimation directly to your server in JSON format.

Detailed information about this option are available in the Service to Service guide.

Location in the Cloud

This is the most straightforward and simple way to estimate the device location and get it directly on the cloud saving data, reducing latency and minimizing the battery drain. 

Detailed information about this option are available in the Location in the Cloud documentation.