nRF Cloud location

The nRF Cloud location library enables applications to submit cellular network and/or nearby Wi-Fi network information to nRF Cloud over MQTT to obtain device location. This library is an enhancement to the nRF Cloud library.

Note

To use the nRF Cloud location service, you need an nRF Cloud account, and the device needs to be associated with your account.

Configuration

Configure the CONFIG_NRF_CLOUD_LOCATION Kconfig option to enable or disable the use of this library.

Request and process location data

The nrf_cloud_location_request() function is used to submit network information to the cloud. If specified in the request, nRF Cloud responds with the location data. If the application provided a callback with the request, the library sends the location data to the application’s callback. Otherwise, the library sends the location data to the application’s nRF Cloud event handler as an NRF_CLOUD_EVT_RX_DATA_LOCATION event.

The nrf_cloud_location_process() function processes the received location data. The function parses the data and returns the location if it is found.

API documentation

Header file: include/net/nrf_cloud_location.h, include/net/wifi_location_common.h
Source files: subsys/net/lib/nrf_cloud/src/
group nrf_cloud_location

Defines

NRF_CLOUD_LOCATION_WIFI_OMIT_RSSI

Omit the RSSI value when submitting a location request

NRF_CLOUD_LOCATION_WIFI_OMIT_CHAN

Omit the channel value when submitting a location request

NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN

Minimum number of access points required by nRF Cloud

NRF_CLOUD_LOCATION_CELL_OMIT_TIME_ADV

Omit the timing advance value when submitting a location request

NRF_CLOUD_LOCATION_CELL_OMIT_RSRQ

Omit the RSRQ value when submitting a location request

NRF_CLOUD_LOCATION_CELL_OMIT_RSRP

Omit the RSRP value when submitting a location request

NRF_CLOUD_LOCATION_CELL_OMIT_EARFCN

Omit the EARFN value when submitting a location request

NRF_CLOUD_LOCATION_CELL_TIME_ADV_MAX

Maximum value for timing advance parameter

Typedefs

typedef void (*nrf_cloud_location_response_t)(const struct nrf_cloud_location_result *const pos)

Cloud location result handler function type.

Param pos

Location result.

Enums

enum nrf_cloud_location_type

Location request type.

Values:

enumerator LOCATION_TYPE_SINGLE_CELL
enumerator LOCATION_TYPE_MULTI_CELL
enumerator LOCATION_TYPE_WIFI
enumerator LOCATION_TYPE__INVALID

Functions

int nrf_cloud_location_request(const struct lte_lc_cells_info *const cells_inf, const struct wifi_scan_info *const wifi_inf, const bool request_loc, nrf_cloud_location_response_t cb)

Perform an nRF Cloud location request over MQTT.

Parameters

  • cells_inf – Cell info. The required network parameters are cell identifier, mcc, mnc and tac. The required neighboring cell parameters are E-ARFCN and physical cell identity. The parameters for time diff and measurement time are not used. The remaining parameters are optional; including them may improve location accuracy. To omit a request parameter, use the appropriate NRF_CLOUD_LOCATION_CELL_OMIT_ define. Can be NULL if Wi-Fi info is provided.

  • wifi_inf – Wi-Fi info. The MAC address is the only required parameter for each item. To omit a request parameter, use the appropriate NRF_CLOUD_LOCATION_WIFI_OMIT_ define. Can be NULL if cell info is provided.

  • request_loc – If true, cloud will send location to the device. If false, cloud will not send location to the device.

  • cb – Callback function to receive parsed location result. Only used when request_loc is true. If NULL, JSON result will be sent to the cloud event handler as an NRF_CLOUD_EVT_RX_DATA_LOCATION event.

Return values

  • 0 – Request sent successfully.

  • -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

  • -EDOM – The number of access points in the Wi-Fi-only request was smaller than the minimum required value NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN.

Returns

A negative value indicates an error.

int nrf_cloud_location_request_json_get(const struct lte_lc_cells_info *const cells_inf, const struct wifi_scan_info *const wifi_inf, const bool request_loc, cJSON **req_obj_out)

Get the reference to a cJSON object containing a location request.

Parameters

  • cells_inf – Cell info; can be NULL if Wi-Fi info is provided.

  • wifi_inf – Wi-Fi info; can be NULL if cell info is provided.

  • request_loc – If true, cloud will send location to the device. If false, cloud will not send location to the device.

  • req_obj_out – The reference to the generated cJSON object.

Return values

  • 0 – If successful.

  • -EDOM – The number of access points in the Wi-Fi-only request was smaller than the minimum required value NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN.

Returns

A negative value indicates an error.

int nrf_cloud_location_process(const char *buf, struct nrf_cloud_location_result *result)

Process location data received from nRF Cloud over MQTT or REST.

Parameters

  • buf – Data received from nRF Cloud.

  • result – Parsed results.

Return values

  • 0 – If processed successfully and location found.

  • 1 – If processed successfully but no location data found. This indicates that the data is not a location response.

  • -EFAULT – An nRF Cloud error code was processed.

Returns

A negative value indicates an error.

int nrf_cloud_location_scell_data_get(struct lte_lc_cell *const cell_inf)

Get the cellular network information from the modem that is required for a single-cell location request.

Parameters

  • cell_inf – Cellular information obtained from the modem.

Return values

0 – If cellular informat was obtained successfully.

Returns

A negative value indicates an error.

struct nrf_cloud_location_result
#include <nrf_cloud_location.h>

Location request result.

Public Members

enum nrf_cloud_location_type type

The service used to fulfill the location request

double lat

Latitude

double lon

Longitude

uint32_t unc

The radius of the uncertainty circle around the location in meters. Also known as Horizontal Positioning Error (HPE).

enum nrf_cloud_error err

Error value received from nRF Cloud. NRF_CLOUD_ERROR_NONE on success.

group wifi_location_common

Common components for Wi-Fi location.

Defines

WIFI_MAC_ADDR_STR_LEN

Size of Wi-Fi MAC address string: 2 chars per byte, colon separated

WIFI_MAC_ADDR_TEMPLATE

Print template for creating a MAC address string from a byte array

struct wifi_scan_info
#include <wifi_location_common.h>

Access points found during a Wi-Fi scan.

Public Members

struct wifi_scan_result *ap_info

Array of access points found during scan.

uint16_t cnt

The number of access points found during scan.