LwM2M location assistance

The LwM2M location assistance library provides a proprietary mechanism to fetch location assistance data from nRF Cloud by proxying it through the LwM2M server.

Overview

Location Assistance object is a proprietary LwM2M object used to deliver information required by various location services through LwM2M. This feature is currently under development and considered experimental. As of now, only AVSystem’s Coiote LwM2M server can be used for utilizing the location assistance data from nRF Cloud.

The library adds support for four objects related to location assistance:

• GNSS Assistance object (ID 33625) for requesting and handling A-GPS and P-GPS assistance data.

• Ground Fix Location object (ID 33626) for requesting and storing estimated cell and Wi-Fi based location.

• Visible Wi-Fi Access Point object (ID 33627) for storing nearby Wi-Fi Access Point information.

• ECID-Signal Measurement Information object (ID 10256) for storing the cell neighborhood information.

The Ground Fix Location object works in co-operation with the Visible Wi-Fi Access Point object and the ECID-Signal Measurement Information object. When using ground fix, the library always sends as much information about the location to be estimated as it can.

Note

The old Location Assistance object (ID 50001) has been removed.

Supported features

There are four different supported methods of obtaining the location assistance:

• Location based on cell information - The device sends information about the current cell and possibly about the neighboring cells to the LwM2M server. The LwM2M server then sends the location request to nRF Cloud, which responds with the location data.

• Location based on Wi-Fi access points - The device sends information about the nearby Wi-Fi access points to the LwM2M server. The LwM2M server then sends the location request to nRF Cloud, which responds with the location data.

• Query of A-GPS assistance data - The A-GPS assistance data is queried from nRF Cloud and provided back to the device through the LwM2M server. The A-GPS assistance data is then provided to the GNSS module for obtaining the position fix faster.

• Query of P-GPS predictions - The P-GPS predictions are queried from nRF Cloud and provided back to the device through the LwM2M server. The predictions are stored in the device flash and injected to the GNSS module when needed.

API usage

This section describes API usage in different scenarios.

Cell-based location

Cell-based location uses only current cell or current and neighboring cells. To get information about the current cell, use the Connectivity Monitor object (ID 4). When you enable the Kconfig option CONFIG_LWM2M_CLIENT_UTILS_CONN_MON_OBJ_SUPPORT, the connectivity monitor is populated with data about the current cell.

To get information about the neighboring cells, use a collection of ECID-Signal Measurement Information objects (ID 10256). To populate the objects, call the lwm2m_ncell_handler_register() function to register the listener for the neighborhood measurements and lwm2m_ncell_schedule_measurement() to schedule a measurement.

The Ground Fix Location object needs to address the report_back resource before sending a location request. Back reporting tells the server whether it needs to send the acquired location back to the device. If the location is sent back to the device, the location is stored only in the Ground Fix Location object.

To send the location request for the cell-based location, call the location_assistance_ground_fix_request_send() function.

Wi-Fi based location

Wi-Fi based location uses the nearby Wi-Fi access points for estimating location. The library uses a collection of Visible Wi-Fi Access Point objects (ID 33627) for storing the information about nearby Wi-Fi access points. To populate the objects, first enable the Kconfig option for the access point scanner CONFIG_LWM2M_CLIENT_UTILS_WIFI_AP_SCANNER and call the lwm2m_wifi_request_scan() function to request the access point scan.

The Ground Fix Location object is used in the same manner as it is used in the cell-based location when sending the location request.

Note

Cell-based location and Wi-Fi based location can be combined. When combined, the ground fix assistance request contains data from both, the nearby cells and nearby Wi-Fi access points.

A-GPS assistance

When using A-GPS assistance, the device requests A-GPS assistance data from the server. You can query the GNSS module for the data needed. A device can request for all data at once or split the request to reduce the memory usage. The request also contains information about the current cell the device is connected to and the information is similarly available on Connectivity Monitor object as in the cell-based location.

When requesting for A-GPS assistance data, the device must first set the mask for the data it is requesting by calling the location_assistance_agps_set_mask() function. When the mask has been set, the location_assistance_agps_request_send() function sends the request with all necessary data to the server and responds with the A-GPS assistance data. The assistance data is written to the GNSS module automatically by the library.

Filtered A-GPS

With filtered A-GPS, the satellites below the given angle above the ground are filtered out. You can set the the angle to a degree [0 - 90] using the location_assist_agps_set_elevation_mask() function. Setting the degree to -1 disables filtering, which is the default setting.

P-GPS assistance

When using P-GPS assistance, the device requests predictions for the satellites for a near future. P-GPS does not use information about current cell at all. It stores the information about satellites and injects the data to the GNSS module when needed. When using P-GPS, external flash is necessary as each prediction needs 2 kB of memory.

When requesting for P-GPS assistance data, the device can set the P-GPS resources. If default values are used in the resources, predictions are requested for one week (42 predictions, 7 days, 4 hours between predictions). When the resources have been set, the location_assistance_pgps_request_send() function sends the request to the server.

Result codes and automatic resend

The location assistance objects have a resource called result_code. This resource contains information about the request handling in the server side. It can have three different values:

• 0 - The request was handled successfully.

• -1 - A permanent error in the server needs fixing. The library will reject further requests and the device must be rebooted after the issue has been resolved in the server.

• 1 - Due to a temporary error in the server, the device needs to retry sending the request after a while.

The library has a resend handler for the temporary error code. You can initialize it with the location_assistance_init_resend_handler() function. It uses an exponential backoff for scheduling the resends. You can also set your own callbacks for the result code for better control of the application.

Using A-GPS and P-GPS simultaneously

A-GPS and P-GPS can be used simultaneously. However, only one active request at a time for the object is allowed. The functions location_assistance_agps_set_mask(), location_assistance_agps_request_send() and location_assistance_pgps_request_send() return -EAGAIN if there is an active request. In such case, the device must resend the request after the previous request has been handled.

Configuration

To enable location assistance, configure either or both of the following Kconfig options:

• CONFIG_LWM2M_CLIENT_UTILS_GNSS_ASSIST_OBJ_SUPPORT

• CONFIG_LWM2M_CLIENT_UTILS_GROUND_FIX_OBJ_SUPPORT

Following are the other important library options:

• CONFIG_LWM2M_CLIENT_UTILS_LOCATION_ASSIST_AGPS - nRF Cloud provides A-GPS assistance data and the GNSS-module in the device uses the data for obtaining a GNSS fix, which is reported back to the LwM2M server.

• CONFIG_LWM2M_CLIENT_UTILS_LOCATION_ASSIST_PGPS - nRF Cloud provides P-GPS predictions and the GNSS-module in the device uses the data for obtaining a GNSS fix, which is reported back to the LwM2M server.

• CONFIG_LWM2M_CLIENT_UTILS_LOCATION_ASSIST_CELL - nRF Cloud provides estimated location based on currently attached cell and its neighborhood.

• CONFIG_LWM2M_CLIENT_UTILS_CONN_MON_OBJ_SUPPORT - Enable support for connectivity monitoring utilities. Provides data about the current cell and network the device has connected to.

• CONFIG_LWM2M_CLIENT_UTILS_VISIBLE_WIFI_AP_OBJ_SUPPORT - Enable support for the Visible Wi-Fi Access Point objects (ID 33627).

• CONFIG_LWM2M_CLIENT_UTILS_WIFI_AP_SCANNER - Enable support for scanning Wi-Fi access points and populating Visible Wi-Fi Access Point objects.

API documentation

Header file: include/net/lwm2m_client_utils_location.h

Source file: subsys/net/lib/lwm2m_client_utils/location/location_assistance.c

group lwm2m_client_utils_location

API for the LwM2M based LOCATION.

Defines

LOCATION_ASSIST_NEEDS_UTC

LOCATION_ASSIST_NEEDS_EPHEMERIES

LOCATION_ASSIST_NEEDS_ALMANAC

LOCATION_ASSIST_NEEDS_KLOBUCHAR

LOCATION_ASSIST_NEEDS_NEQUICK

LOCATION_ASSIST_NEEDS_TOW

LOCATION_ASSIST_NEEDS_CLOCK

LOCATION_ASSIST_NEEDS_LOCATION

LOCATION_ASSIST_NEEDS_INTEGRITY

LOCATION_ASSIST_RESULT_CODE_OK

LOCATION_ASSIST_RESULT_CODE_PERMANENT_ERR

LOCATION_ASSIST_RESULT_CODE_TEMP_ERR

GNSS_ASSIST_OBJECT_ID

GROUND_FIX_OBJECT_ID

VISIBLE_WIFI_AP_OBJECT_ID

ECID_SIGNAL_MEASUREMENT_INFO_OBJECT_ID

Functions

int location_assistance_agps_set_mask(const struct nrf_modem_gnss_agps_data_frame *agps_req)

Set the A-GPS request mask.

Parameters

• agps_req – The A-GPS request coming from the GNSS module.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_assistance_agps_request_send(struct lwm2m_ctx *ctx, bool confirmable)

Send the A-GPS assistance request to LwM2M server.

Parameters

• ctx – LwM2M client context for sending the data.

• confirmable – Boolean value to indicate should the server return confirmation.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_assistance_ground_fix_request_send(struct lwm2m_ctx *ctx, bool confirmable)

Send the Ground Fix request to LwM2M server.

Parameters

• ctx – LwM2M client context for sending the data.

• confirmable – Boolean value to indicate should the server return confirmation.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_assistance_pgps_request_send(struct lwm2m_ctx *ctx, bool confirmable)

Send the P-GPS assistance request to LwM2M server.

Parameters

• ctx – LwM2M client context for sending the data.

• confirmable – Boolean value to indicate should the server return confirmation.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_assistance_init_resend_handler(void)

Initialize the location assistance library resend handler. Handler will handle the result code from server and schedule resending in case of temporary error in server using an exponential backoff.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_event_handler_init(struct lwm2m_ctx *ctx)

Initialize the location assistance event handler.

Parameters

• ctx – LwM2M client context for sending the data.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

void location_assist_agps_request_set(uint32_t request_mask)

Set an A-GPS assistance request mask for the object.

Parameters

• request_mask – A bitmask containing the requested parameters from the server

void location_assist_agps_set_elevation_mask(int32_t elevation_mask)

Set the satellite elevation mask angle above the ground. Satellites below the angle will be filtered in the response.

Parameters

• elevation_mask – Elevation mask angle in degrees above the ground level

int32_t location_assist_agps_get_elevation_mask(void)

Get the satellite elevation mask currently stored in the resource.

Returns

Returns the currently stored elevation mask as degrees above the ground level.

int location_assist_pgps_set_prediction_count(int32_t predictions)

Set prediction count for the P-GPS query.

Parameters

• predictions – Number of predictions requested

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int location_assist_pgps_set_prediction_interval(int32_t interval)

Set prediction interval as minutes for the P-GPS query.

Parameters

• interval – Time in minutes between each query

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

void location_assist_pgps_set_start_gps_day(int32_t gps_day)

Set starting GPS day as days since GPS epoch. Setting the day as 0, will use the default value for the request which will be current GPS day.

Parameters

• gps_day – Day as a GPS days since GPS epoch.

int32_t location_assist_pgps_get_start_gps_day(void)

Get the GPS start day stored currently in the resource.

Returns

Returns the currently stored value for GPS start day.

int location_assist_pgps_set_start_time(int32_t start_time)

Set the GPS start time in seconds.

Parameters

• start_time – Time of day in seconds.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int32_t location_assist_gnss_get_result_code(void)

Get the result code of the location request.

Returns

int32_t Returns a result code from the LwM2M server.

void ground_fix_set_report_back(bool report_back)

Set if the server should report the location back to the object after it has attained it.

Parameters

• report_back – Boolean value showing if the server should report the location back.

int32_t ground_fix_get_result_code(void)

Get the result code of the location request.

Returns

int32_t Returns a result code from the LwM2M server.

int lwm2m_signal_meas_info_inst_id_to_index(uint16_t obj_inst_id)

int lwm2m_signal_meas_info_index_to_inst_id(int index)

int lwm2m_update_signal_meas_objects(const struct lte_lc_cells_info *const cells)

Update the ECID-Signal Measurement Info objects with the recent neighbor cell data.

Parameters

• cells – Struct containing all the cell neighbors.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

int lwm2m_ncell_handler_register(void)

Register the handler for the Neighbor cell scanning.

Returns

Returns a negative error code (errno.h) indicating reason of failure or 0 for success.

void lwm2m_ncell_schedule_measurement(void)

int lwm2m_wifi_request_scan(void)

Request a Wi-Fi scan for nearby access points.

The Wi-Fi access points are added to the Visible Wi-Fi Access Point objects (ID 33627) and used for the Wi-Fi based location when sending a ground fix request.

Returns

Returns a negative error code (errno.h) indicating the reason for failure or 0 for success.