Cell-ID Guide

This user manual describes the geolocation agent (later referred to as “Cell-ID agent”) that enables geolocation via Cell-ID and WiFi.

Overview

The Cell-ID agent provides the following functionality:

Agent subscribes for changes in managed objects which have Mobile or Cell-ID fragment. If a change is detected the connected geolocation service is queried to determine the new device position. The supported external geolocation system is by default google-geolocation-api.

The determined position of the device will be shown in the device’s tracking history by creating a location update event. If enabled via configuration the device’s position in its own managed object will also be updated.

The amount of performed requests to the geolocation provider as well as the number of active devices are logged as statistics measurements. The agent will provide time range summaries over these measurements for a given tenant or its subtenants.

Exposed REST API

(De)activate devices

Using this REST end-point users can activate and deactivate the localization features for single devices. This end-point requires the operation mode “MANUAL” otherwise it will return 412​ PRECONDITION FAILED.

Usage:

POST
{{url}}/service/{application.name}/devices/{deviceId}
Content-Type:application/json
{
"active":{true|false}
}

Device must be a valid ID of a managed object. The activation parameter represents the targeted status of the device.

204 NO CONTENT

Note: A positive response has no Content in its body.

Get statistics summary

Using this REST end-point users can get the usage statistics for their tenant. The agent will retrieve the data in the specified period from the management tenant and build the summary. The role TENANT_STATISTICS_READ​ is required for using this endpoint​.

Usage:

GET
{{url}}/service/{cellid}/statistics/summary?dateFrom={dateFrom}&dateTo={dateTo}
Accept:application/json

Both query parameters are optional, but if they are set they must be of pattern YYYY-MM-DD. If dateFrom is not set, it is defaulted to 1970-01-01. If dateTo is not set, it is defaulted to exactly now on server time.

The timespan described by dateFrom and dateTo is interpreted as from the start of dateFrom to the start of dateTo. This means that data that happened during the course of the day referenced by dateTo will not be considered.

The dateTo parameter must always be after the dateFrom. This includes cases where one of the parameters is replaced with a default value. Otherwise 422 UNPROCESSABLE ENTITY is returned.

This represents the current tenant’s statistics with the sum of all requests during the timespan and the last amount of active devices.

Get all tenants summary

This endpoint behaves similarly to the single tenant statistics endpoint. It just retrieves statistics for all subtenants. The respective tenant must be allowed to have subtenants, otherwise 403 FORBIDDEN is returned.

Usage:

GET
{{url}}/service/{cellid}/allTenantsSummary?dateFrom={dateFrom}&dateTo={dateTo}
Accept: application/json

See Get statistics summary for the behavior of the query parameters dateFrom and dateTo.

200 OK

[
{
"tenant" : "tenant1" ,
"statistics" : {
"apiRequests" : 123 ,
"activeDevices" : 23
},
"currentlySubscribed" : true
},
{
"tenant" : "tenant2" ,
"statistics" : {
"apiRequests" : 123 ,
"activeDevices" : 23
},
"currentlySubscribed" : true
},
...
]

The response will contain a list of all subtenant’s statistics. This list will never contain the current tenant. In case of the management tenant this will contain a list of all tenants except management itself.

The summaries are created for all subtenants whether they are subscribed to the Cell-ID service or not. The currentlySubscribed parameter reflects this status at the time of the request.

Configuration

Configuring cell-id agent per tenant

There are several settings that must be configured to activate and use the Cell-ID agent for a given tenant.

Defining operation mode for tenant

The agent can run in three different operation modes for a subscribed tenant: AUTO​, ​ MANUAL​, and TYPES​. This mode defines how and when the agent searches for applicable devices in this​ tenant.

Create a tenant option as follows in the tenant:

POST {{url}}/tenant/options
{
"category": "{application.name}",
"key": "operation.mode",
"value": "{auto|manual|types}"
}

By default, the agent will run in AUTO​ mode.

Note: This option must be set before subscribing the​ tenant to the microservice. To change the mode at a later point the microservice must be unsubscribed and re-subscribed or the agent must be restarted.

AUTO mode

AUTO​ mode the agent will periodically scan for devices with the “c8y_Mobile” or the​ “c8y_CellInfo” fragments. All updates for those devices will be resolved via the geolocation provider automatically. For backwards compatibility reasons this is the default operation mode if nothing else is configured.

MANUAL mode

All devices must be manually activated to use the geolocation service for them. They can also be manually deactivated. There is no automatic scanning for applicable devices.

TYPES mode

All devices of a specified list of device types will be automatically activated. The agent will periodically scan for devices of the specified types and handle all updates for them automatically.

To specify the device type create a comma separated list in tenant options as follows:

POST {{url}}/tenant/options
{
"category": "{application.name}",
"key": "operation.types",
"value": "type1,type2,..."
}

Configuring Api key (optional)

This section is relevant if the tenant is not using global credential mode, meaning want to use own API-Key, otherwise it will be subscribed to the global credential mode (shared usage of API-Key of Google). There are two geolocation providers supported by the geolocation agent – Combain and Google where the required API-Key can be obtained from.

Set the API key for a tenant by creating a tenant option as follows:

POST {{url}}/tenant/options
{
"category": "{application.name}",
"key": "key",
"value": " {api key}"
}

Configuring URL (optional)

In order to change the geolocation provider, its URL must be configured. This step can be omitted if the URL is the same as configured in the agent properties file.

For different provider the URL must be set as follows:

POST {{url}}/tenant/options
{
"category": "{cellid}",
"key": "url",
"value": "{provider url} "
}

Requests

Voraussetzung: Gerät ist vorhanden und besitzt Fragment c8y_isDevice.

Grundsätzlich gibt verschiedene Arten von Cell-ID Requests. Pro Art sollten mind. 3 Requests bei einem “neuen” Gerät gesendet werden (mit unterschiedlichen Locations), um eine Tracking “Spur” mittels Zellendaten im entsprechenden Widget sichtbar zu machen. Hintergrund: wenn ein dem Agent unbekanntes Gerät einen 1. Cell ID Request sendet, muss eine Zeit von 10min vergehen. Hintergrund: der Agent fragt aktuell alle 10min neue Geräte ab & subscribt diese erst dann. Heißt: wenn weitere Requests innerhalb dieser 10min gesendet werden, werden diese nicht verarbeitet.

Cell-info Request 

PUT /inventory/managedObjects/<DEVICEID>
Authorization: <BASIC AUTH>
Content-Type: application/json
{
"c8y_CellInfo": {
"cellTowers": [
{
"mobileCountryCode": 262,
"mobileNetworkCode": 1,
"locationAreaCode": 14369,
"cellId": 48540
}]
}
}

Mobile request 

PUT /inventory/managedObjects/<DEVICEID>
Authorization: <BASIC AUTH>
Content-Type: application/json
{
"c8y_Mobile":
{
"imei": "[valid imei]",
"iccid": "[valid iccid]",
"imsi": "[valid imsi]",
"msidsn": "[valid msidsn]",
"cellId": "[valid cell id]",
"mcc": "[valid mcc]",
"mnc": "[valid mnc]",
"lac": "[valid lac]"
}
}

WIFI Request 

PUT /inventory/managedObjects/<DEVICEID>
Authorization: <BASIC AUTH>
Content-Type: application/json
{
"c8y_WlanSsidInformation": [
{
"macAddress": "e0:28:6d:92:12:fc",
"signalStrength": -90
},
{
"macAddress": "34:81:c4:0b:1c:ca",
"signalStrength": -88
}
]
}

Triangulation request

For triangulation could be used the same request with the follow fragments:

More information can be sought in the developer documentation of the geolocation service provider, in this case from Google: https://developers.google.com/maps/documentation/geolocation/intro) e.g.:

PUT /inventory/managedObjects/<DEVICEID>
Authorization: <BASIC AUTH>
Content-Type: application/json
{
"c8y_CellInfo": {
"homeMobileCountryCode": 262,
"homeMobileNetworkCode": 1,
"radioType": "lte",
"carrier": "Telekom",
"considerIp": "true",
"cellTowers": [
{
"cellId": 26494722,
"locationAreaCode": 18000,
"mobileCountryCode": 262,
"mobileNetworkCode": 1,
"age": 0,
"signalStrength": -75,
"timingAdvance": 0
},
{
"cellId": 213574,
"locationAreaCode": 35221,
"mobileCountryCode": 262,
"mobileNetworkCode": 1,
"age": 0,
"signalStrength": -101,
"timingAdvance": 0
},
{
"cellId": 227688,
"locationAreaCode": 35221,
"mobileCountryCode": 262,
"mobileNetworkCode": 1,
"age": 0,
"signalStrength": -71,
"timingAdvance": 0
}
]
}
}

More information and Troubleshooting