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. To know more about the AVSystem integration with nRF Connect SDK, see AVSystem integration.

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

  • GNSS Assistance object (ID 33625) for requesting and handling A-GNSS 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-GNSS assistance data - The A-GNSS assistance data is queried from nRF Cloud and provided back to the device through the LwM2M server. The A-GNSS 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-GNSS assistance

When using A-GNSS assistance, the device requests A-GNSS 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-GNSS assistance data, the device must first set the mask for the data it is requesting by calling the location_assistance_agnss_set_mask() function. When the mask has been set, the location_assistance_agnss_request_send() function sends the request with all necessary data to the server and responds with the A-GNSS assistance data. The assistance data is written to the GNSS module automatically by the library.

Filtered A-GNSS

With filtered A-GNSS, the satellites below the given angle above the ground are filtered out. You can set the angle to a degree [0 - 90] using the location_assist_agnss_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.

The library has a callback handler for the result code. You can set your own callback with the location_assistance_set_result_code_cb() function. It is called whenever the request has been handled.

Using A-GNSS and P-GPS simultaneously

A-GNSS and P-GPS can be used simultaneously. However, only one active request at a time for the object is allowed. The functions location_assistance_agnss_set_mask(), location_assistance_agnss_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:

Following are the other important library options:

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

Typedefs

typedef void (*location_assistance_result_code_cb_t)(int32_t result_code)

Callback for location assistance result.

This callback is called whenever there is a new result in the location assistance and the location assistance resend handler has been initialized.

Param result_code:

Contains following possible result codes: LOCATION_ASSIST_RESULT_CODE_OK when there are no problems LOCATION_ASSIST_RESULT_CODE_PERMANENT_ERR when there is a permanent error between LwM2M-server and the nRF Cloud. Location assistance library will no longer send any requests. Device needs reboot for assistance library to resume operation. LOCATION_ASSIST_RESULT_CODE_TEMP_ERR when there is a temporary error between LwM2M-server and the nRF Cloud. The library automatically uses exponential backoff for the retries.

Functions

void location_assistance_set_result_code_cb(location_assistance_result_code_cb_t cb)

Set the location assistance result code calback.

Parameters:
  • cb – callback function to call when there is a new result from location assistance.

int location_assistance_agnss_set_mask(const struct nrf_modem_gnss_agnss_data_frame *agnss_req)

Set the A-GNSS request mask.

Parameters:
  • agnss_req – The A-GNSS 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_agnss_request_send(struct lwm2m_ctx *ctx)

Send the A-GNSS assistance request to LwM2M server.

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.

int location_assistance_ground_fix_request_send(struct lwm2m_ctx *ctx)

Send the Ground Fix request to LwM2M server.

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.

int location_assistance_pgps_request_send(struct lwm2m_ctx *ctx)

Send the P-GPS assistance request to LwM2M server.

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.

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_agnss_request_set(uint32_t request_mask)

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

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

void location_assist_agnss_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_agnss_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.