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_ANCHOR_NAME_MAX

Maximum string length of an anchor name

NRF_CLOUD_ANCHOR_LIST_BUF_MIN_SZ

Minimum size of the anchor buffer required to hold one maximum length anchor name. Multiply this value by your desired number anchor names to obtain your buffer size.

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 struct nrf_cloud_location_config *const config, 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.

  • config – Optional configuration of request. If NULL, fall back to default which is do_reply = true, hi_conf = false, and fallback = true.

  • cb – Callback function to receive parsed location result. Only used when config->do_reply is true or config is NULL. If CONFIG_NRF_CLOUD_LOCATION_ANCHOR_LIST is enabled, the application should not access the anchor list data after exiting the callback as it may become invalid. If cb is 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_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 information was obtained successfully.

Returns:

A negative value indicates an error.

struct nrf_cloud_anchor_list_node
#include <nrf_cloud_location.h>

Anchor name list node, to be used with sys_slist_t APIs.

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.

uint32_t anchor_cnt

The number of anchors received

sys_slist_t anchor_list

List of received anchor names contained as nrf_cloud_anchor_list_node. If all anchor names cannot fit in the list, the number of items in the list will be less than anchor_cnt.

char *anchor_buf

User provided buffer to contain the anchor_list. CONFIG_NRF_CLOUD_LOCATION_PARSE_ANCHORS must be enabled for anchor data to be parsed. This buffer must point to valid memory or be set to NULL. A valid buffer should have a size of at least NRF_CLOUD_ANCHOR_LIST_BUF_MIN_SZ.

size_t anchor_buf_sz

Size of provided buffer

struct nrf_cloud_location_config
#include <nrf_cloud_location.h>

Location request config.

Public Members

bool do_reply

If true, nRF Cloud will send the location to the device.

bool hi_conf

If true, uncertainty of result will be 95%, otherwise 68%.

bool fallback

If true, and location cannot be found, result will fall back to rough estimate based on the cell tower tracking area code. If false, will return an error if the cloud cannot provide a higher accuracy response.

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.