Multicell location
The Multicell location library provides a way to acquire the location of the device based on LTE cell measurements.
Overview
The library uses LTE cell information such as LTE link controller library to generate requests through nRF Cloud cellular positioning, nRF Cloud REST or REST client depending on the selected service and transport (REST or MQTT).
When the location service has resolved the location based on the cell measurements provided in the request, it sends back a response to the device. After receiving the response, the Multicell location library parses the response and returns the location to the caller.
The library supports the following location services:
HERE Positioning (v1 and v2)
The data transport method for the request to the service is mainly REST. However, either MQTT (CONFIG_NRF_CLOUD_MQTT
) or REST (CONFIG_NRF_CLOUD_REST
) can be configured for nRF Cloud Location Services.
To use the location services, see the respective documentation for account setup and for getting the required credentials for authentication.
Note
nRF9160 DK and Thingy:91 devices are shipped with RSA256 certificates. To start using the Multicell location library with nRF Cloud, you must perform either of the following actions:
Delete the device from nRF Cloud and reprovision it with a new ES256 device certificate. See Updating the nRF Cloud certificate for more information.
Register a separate key for JWT signing as described in Securely Generating Credentials on the nRF9160 and set
CONFIG_MULTICELL_LOCATION_NRF_CLOUD_JWT_SEC_TAG
accordingly.
The required credentials for the location services are configurable using Kconfig options. There is no difference in the API calls when using the services.
The library has an API to handle provisioning of the required TLS certificates for the location services, multicell_location_provision_certificate()
.
Note
Certificates must be provisioned while the modem’s functional mode is offline, or it is powered off.
The simplest way to achieve this is to call multicell_location_provision_certificate()
after booting the application, before connecting to the LTE network.
Configuration
To use the multicell location library, enable the CONFIG_MULTICELL_LOCATION
Kconfig option.
Select nRF Cloud, HERE, Skyhook and Polte location services using at least one of the following sets of options and configure corresponding authentication parameters:
CONFIG_MULTICELL_LOCATION_SERVICE_HERE
andCONFIG_MULTICELL_LOCATION_HERE_API_KEY
(see below other authentication options)CONFIG_MULTICELL_LOCATION_SERVICE_SKYHOOK
andCONFIG_MULTICELL_LOCATION_SKYHOOK_API_KEY
CONFIG_MULTICELL_LOCATION_SERVICE_POLTE
andCONFIG_MULTICELL_LOCATION_POLTE_CUSTOMER_ID
andCONFIG_MULTICELL_LOCATION_POLTE_API_TOKEN
API key is used for HERE, Skyhook and Polte (needs also customer ID) as default authentication method. A JSON Web Token (JWT) signed by the device’s private key is used for nRF Cloud.
The following options offer different version and authentication method for HERE location service:
The following options control the transport method used with nRF Cloud:
CONFIG_NRF_CLOUD_REST
- Uses REST APIs to communicate with nRF Cloud ifCONFIG_NRF_CLOUD_MQTT
is not set.CONFIG_NRF_CLOUD_MQTT
- Uses MQTT transport to communicate with nRF Cloud.
Following are the options that can usually have default values:
Other relevant options for configuring location retrieval can be found from nRF Cloud REST and REST client.
Limitations
Retrieving the device’s location is a blocking operation.
Dependencies
This library uses the following nRF Connect SDK libraries:
API documentation
include/net/multicell_location.h
lib/multicell_location/
- group multicell_location
Enums
-
enum multicell_service
Cellular positioning service.
Values:
-
enumerator MULTICELL_SERVICE_ANY
Use any location service that has been configured to be available.
This is especially useful when only one service is configured but can be used even if many are available, in which case selected service is undefined.
-
enumerator MULTICELL_SERVICE_NRF_CLOUD
nRF Cloud location service.
-
enumerator MULTICELL_SERVICE_HERE
Here location service.
-
enumerator MULTICELL_SERVICE_SKYHOOK
Skyhook location service.
-
enumerator MULTICELL_SERVICE_POLTE
Polte location service.
-
enumerator MULTICELL_SERVICE_ANY
Functions
-
int multicell_location_get(enum multicell_service service, const struct lte_lc_cells_info *cell_data, struct multicell_location *location)
Send a request for location based on cell measurements to the selected location service.
Note
This function will block the calling thread until a response is received from the location service.
Note
Certificate must be provisioned before a request can be sent, multicell_location_provision_certificate.
- Parameters
service – [in] Cellular positioning service to be used.
cell_data – [in] Pointer to neighbor cell data.
location – [out] Pointer to location.
- Return values
-ENOENT – No cellular cells found from cell_data. I.e., even current cell is not available and there is no cellular connectivity.
-ENOMEM – Out of memory.
-ENOMSG – Parsing response from the location service failed.
- Returns
0 on success, or negative error code on failure.
-
int multicell_location_provision_certificate(bool overwrite)
Provision TLS certificate that the selected location service requires for HTTPS connections. Certificate provisioning must be done before location requests can successfully be executed, either using this API or some other method.
Note
Certificate provisioning must happen when LTE is not active in the modem. This is typically achieved by calling this API prior to setting up the LTE link in an application, but it can also be done by setting the modem in offline mode before provisioning.
- Parameters
overwrite – [in] If this flag is set, any CA certificate currently provisioned to CONFIG_MULTICELL_LOCATION_TLS_SEC_TAG is overwritten.
- Returns
0 on success, or negative error code on failure.
-
struct multicell_location
- #include <multicell_location.h>
-
enum multicell_service