SUPL client and SUPL client OS integration

This section documents both the Secure User-Plane Location (SUPL) client library and the SUPL client OS integration library.

The Secure User-Plane Location (SUPL) client library is an OS-independent library that is distributed separately with a different license than the nRF Connect SDK. This library can be used to receive A-GNSS data from a SUPL server using the SUPL protocol.

The SUPL client OS integration library is a source code library distributed with the nRF Connect SDK. This library is used to integrate the SUPL client library with an nRF Connect SDK application.

The SUPL client is used with a 3rd party SUPL server. For example, Google hosts a SUPL server (supl.google.com), but for commercial use a license is required.

Secure User-Plane Location

SUPL enables the transfer of assistance and network-based positioning data of a SUPL Enabled Terminal (SET), such as an nRF9160 DK or a Thingy:91, over an IP User Plane bearer. See SUPL context model for more information on the SUPL architecture. SUPL is designed to support future positioning technologies. The SUPL version supported by the SUPL client library is 2.0.4.

SUPL uses A-GNSS for obtaining GPS satellite data, overcoming limitations of a standalone GNSS module.

A standalone GNSS module downloads orbital data (like Ephemeris and the Almanac) from satellites to calculate the current position of a device. It has the following limitations:

  • Typically, the data download from the satellites takes a long time and the first position is calculated in 30-40 seconds.

  • Any loss of signal requires the whole process to be restarted.

An A-GNSS server is a cached server that stores the orbital data. This information can be downloaded at a fast rate since an A-GNSS capable device supports mobile radio-network bearers with high data rate such as LTE.

SUPL payload

LTE Positioning Protocol (LPP) is the supported SUPL payload format.

LPP is a point-to-point protocol used between a location server (for example, a Secure Location Protocol (SLP) server) and a target device (for example, SET) to position the device using position-based information obtained from reference sources. A SET is a logical part of a device that supports communication with a SUPL network.

SUPL session and transaction type

A typical SUPL client session is SET-based, that is, the position is calculated based on SET. See SET-initiated SUPL collaboration for more information.

Each LPP session consists of one or more LPP transactions. Each LPP transaction corresponds to a single operation such as capability exchange, assistance data transfer, or location information transfer.

Note

The SUPL client library supports only assistance data transfer as the transaction type.

The following image shows the steps in the SUPL client connection session.

msc { hscale = "1.1"; SET,SLP; --- [label="Data connection setup"]; SET=>SLP [label="SUPL START (session-id, lid, SET capabilities)"]; SET<=SLP [label="SUPL RESPONSE (session-id, posmethod)"]; SET=>SLP [label="SUPL POS INIT (session-id, lid, SET capabilities)"]; SET..SLP [linecolor="#00a9ce", textcolor="#00a9ce", label="\nloop 1..N times"]; SET<=SLP [label="SUPL POS (session-id, LPP)"]; ...; SET..SLP [linecolor="#00a9ce"]; SET<<SLP [label="SUPL END (session-id)"]; --- [label="Data connection teardown"]; }

SUPL client library

The SUPL client library must be downloaded separately and integrated into the nRF Connect SDK by the user. Before you download the library, read through the license on the webpage. You must accept the license before you can download the library.

Downloading and installing

You can download the SUPL client library from the nRF9160 DK product page.

Download the nRF9160 SiP SUPL client library zip file and extract it into the nrf/ext/lib/bin/ folder. Make sure to maintain the folder structure that is used in the zip file.

Configuration

To enable the SUPL client library, set CONFIG_SUPL_CLIENT_LIB to y. See Configuring and building an application for information on how to change configuration options.

Note

The SUPL client library requires that the newlib C library is used. You can enable it using the CONFIG_NEWLIB_LIBC Kconfig option.

Resource initialization and ownership

Two buffers are used in the SUPL communication session. These buffers, namely the primary and secondary buffers, are owned by the user of the SUPL client library. The sizes of the buffers are defined by the LIBSUPL_PRI_BUF_SIZE and LIBSUPL_SEC_BUF_SIZE parameters. These parameters are defined in the supl_session.h header file.

The SUPL client library implements the following functionalities:

  • Send messages to the SUPL server

  • Receive messages from the SUPL server

  • Send A-GNSS data to the GNSS module

These functionalities are implemented using a set of callback functions. Both the buffers and the pointers to the callback functions are passed to the SUPL client library through the supl_client_init() function.

API callback functions

Callback functions are needed to achieve platform independence. If your application uses the SUPL client library, you must implement these callback functions. For an example of the implementation, see the Cellular: GNSS sample. The implementation is located in the samples/cellular/gnss/src/ directory. The various callback functions implemented in the SUPL client library and their purposes are listed below.

A-GNSS handler

Callback function to handle nRF assistance data types defined in A-GNSS data type enumerator. This callback writes the A-GNSS data to the GNSS module. The LTE Positioning Protocol (LPP) data contained within the SUPL payload is converted to nRF A-GNSS data structures defined in nrf_modem_gnss.h that can be written directly using the GNSS API.

SUPL logger

Callback function to output the SUPL client library debug messages. Callback implementation is optional. If the callback function is not implemented, the library does not display debug messages.

Millisecond counter

Callback function for millisecond counter. Callback implementation is optional. If the callback function is not implemented, the library assumes 1 second receive timeout and estimates SUPL level timeouts based on that.

SUPL read

Callback function for receiving incoming data from the SUPL server.

SUPL write

Callback function for sending outgoing data to the SUPL server.

SUPL session

The SUPL communication spans the following events and message transfers:

  • Receiving an event from the GNSS module requesting to update A-GNSS data

  • Executing subsequent message transfers until the completion of the A-GNSS session

  • Pushing data into the GNSS module

The following message sequence chart (MSC) describes the flow of communication in a SUPL session.

SUPL Session MSC

The various steps in the communication session are described below:

  1. The application receives a request from the GNSS to start a SUPL session. GNSS sends the NRF_MODEM_GNSS_EVT_AGNSS_REQ event when it needs fresh A-GNSS data.

  2. If the LTE modem is deactivated, the user must enable the LTE modem. When the modem is enabled, it initiates a TCP socket to connect to the SUPL server. In the SUPL session MSC above, the application opens a TCP socket to connect to the SUPL server.

  3. In order to start a SUPL session, the application must first initialize the SUPL client library. This is done by calling the supl_init() function of the SUPL client OS integration library. The function sets up the API and the buffers required for initializing the SUPL client library and invokes the supl_client_init() function with these parameters.

  4. The application can then begin the SUPL session by calling the supl_session() function with a copy of the nrf_modem_gnss_agnss_data_frame data that was received through the A-GNSS data request event from the GNSS module. The SUPL client OS integration library generates the following parameters that are necessary for the session:

    • supl_session_ctx_t structure from the A-GNSS request event data

    • lte_params_t structure from the data read from the LTE modem

    • device_id from device IP address

  5. The SUPL client OS integration library then starts the SUPL session by calling the supl_client_session() function from the SUPL client library with the supl_session_ctx_t parameter. The application does not return from this function until the SUPL session is finished or the supl_client_abort() function is called.

  6. The supl_client_session() function forms the entry point for the SUPL session. There is no specific limit on the number of subsequent SUPL sessions that can be executed from this entry point. See the documentation on the SET-Initiated Non-Roaming Successful Case (Proxy mode) for more information on the SUPL session. The callback functions used for data transfer are listed below:

    • SUPL write (supl_write_t): callback for sending outgoing data to the SUPL server

    • SUPL read (supl_read_t): callback for receiving incoming data from the SUPL server

  7. The decoded SUPL data is sent to the GNSS module using the A-GNSS handler (agps_handler_t()) callback function.

  8. After the application returns from the supl_client_session() function, the TCP socket is no longer used by the SUPL client library and can be closed.

SUPL client OS integration library

The SUPL client OS module integrates the SUPL client library into the nRF Connect SDK.

SUPL session

Before starting a SUPL session, the application must initialize the SUPL client library by calling the supl_init() function of the SUPL client OS integration library. Once the library is initialized, any number of subsequent SUPL sessions can be executed with the same set of initialized parameters.

To start the SUPL session, the application must call the supl_session() function of the SUPL client OS integration library. The library then creates the necessary parameters and starts the SUPL session in the SUPL client library. The SUPL client OS integration library abstracts the details of the SUPL client library away from the user.

See steps 3, 4 and 5 in the SUPL session MSC description for more information.

API documentation

Header file: include/supl_os_client.h
Source files: lib/supl/
group supl_os

Functions

int supl_session(const struct nrf_modem_gnss_agnss_data_frame *const agnss_request)

Start a SUPL session.

Parameters:

  • agnss_request – [in] This contain the information about the A-GNSS data that the GNSS module is requesting from the server.

Returns:

0 SUPL session was successful. <0 SUPL session failed.

int supl_init(const struct supl_api *const api)

Setup the API and the buffers required by the SUPL client library.

Parameters:

  • api – [in] Function pointers to the API required by SUPL client library to work.

Returns:

0 SUPL client library was initialized successfully. <0 Failed to initialize the SUPL client library.