nRF9160: GPS with SUPL client library

The GPS sample demonstrates how to retrieve GNSS data. If Secure User-Plane Location (SUPL) support is enabled, it also shows how to improve the fix accuracy and fix speed with A-GPS data from a SUPL server. See SUPL client and SUPL client OS integration for information on enabling SUPL support for the sample.

The sample first initializes the GNSS interface. Then it handles events from the interface, reads the associated data and outputs information to the console. Because NMEA data needs to be read as soon as an NMEA event is received, a Zephyr message queue is used for buffering the NMEA strings. The event handler function reads the received NMEA strings and puts those into the message queue. The consumer loop reads from the queue and outputs the strings to the console.

When SUPL support is enabled, a Zephyr workqueue is used for downloading the A-GPS data. Downloading the data can take some time and the workqueue ensures that the main thread is not blocked during the operation.

See GNSS interface for more information.

Overview

This sample operates in two different modes.

In the default mode, the sample displays information from both PVT (Position, Velocity, and Time) and NMEA strings. The sample can also be configured to run in NMEA-only mode, where only the NMEA strings are displayed in the console. The NMEA-only mode can be used to visualize the data from the GNSS using a third-party tool.

SUPL support can be enabled for both the default mode (PVT and NMEA) and the NMEA-only mode. When the SUPL support is enabled, the sample receives an A-GPS data request notification from the GNSS module, and it starts downloading the A-GPS data requested by the GNSS module. The sample then displays the information in the terminal about the download process. Finally, after the download completes, the sample switches back to the previous display mode.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160ns

The sample can be optionally used with the SUPL Client library (for details on download, see SUPL client and SUPL client OS integration).

The sample is configured to compile and run as a non-secure application on nRF91’s Cortex-M33. Therefore, it automatically includes the Secure Partition Manager that prepares the required peripherals to be available for the application.

You can also configure it to use TF-M instead of Secure Partition Manager.

Building and running

This sample can be found under samples/nrf9160/gps in the nRF Connect SDK folder structure.

The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160ns build target. Because of this, it automatically includes the Secure Partition Manager. You can also configure it to use TF-M instead of SPM.

See Building and programming a sample application for information about how to build and program the application.

Using the sample with the SUPL client library

If the sample is to be used with the SUPL client library, the library must be downloaded and enabled in the sample configuration. You can download it from the Nordic Semiconductor website. See SUPL client and SUPL client OS integration for information on installing and enabling the SUPL client library.

The SUPL client library is not required, and the sample will work without A-GPS support if the library is not available.

Testing

After programming the sample and all the prerequisites to the development kit, you can test the sample by performing the following steps:

  1. Connect your nRF9160 DK to the PC using a USB cable and power on or reset your nRF9160 DK.

  2. Open a terminal emulator.

  3. Test the sample by performing the following steps:

    If the default mode is enabled:

    1. Observe that the following information is displayed in the terminal emulator:

      Tracking: 0 Using: 0 Unhealthy: 0
---------------------------------
Seconds since last fix: 1
Searching [-]

NMEA strings:

$GPGGA,000000.00,,,,,0,,99.99,,M,0,,*37
$GPGLL,,,,,000000.00,V,A*45
$GPGSA,A,1,,,,,,,,,,,,,99.99,99.99,99.99,1*2D
$GPGSV,1,1,0,,,,,,,,,,,,,,,,,1*54
$GPRMC,000000.00,V,,,,,,,060180,,,N,V*08
---------------------------------

    2. Observe that the numbers associated with the displayed parameters Tracking and Using change.

    3. Observe that the sample displays the following information upon acquiring a fix:

      Tracking: 7 Using: 5 Unhealthy: 0
---------------------------------
Latitude:   61.491275
Longitude:  23.771611
Altitude:   116.3 m
Accuracy:   4.2 m
Speed:      0.0 m/s
Heading:    0.0 deg
Date:       2020-03-06
Time (UTC): 05:48:24

NMEA strings:

$GPGGA,054824.58,6128.77008,N,02351.48387,E,1,07,2.05,116.27,M,0,,*22
$GPGLL,6129.28608,N,02346.17887,E,054824.58,A,A*6B
$GPGSA,A,3,10,12,17,24,28,,,,,,,,3.05,2.05,2.25,1*13
$GPGSV,2,1,7,17,50,083,41,24,68,250,38,10,14,294,46,28,23,071,38,1*56
$GPGSV,2,2,7,12,29,240,36,19,00,000,32,1,00,000,33,1*50
$GPRMC,054824.58,A,6129.28608,N,02346.17887,E,0.08,0.00,030620,,,A,V*29
---------------------------------

    If NMEA-only mode is enabled:

    1. Observe that the following information is displayed in the terminal emulator:

      $GPGGA,000000.00,,,,,0,,99.99,,M,0,,*37
$GPGLL,,,,,000000.00,V,A*45
$GPGSA,A,1,,,,,,,,,,,,,99.99,99.99,99.99,1*2D
$GPGSV,1,1,0,,,,,,,,,,,,,,,,,1*54
$GPRMC,000000.00,V,,,,,,,060180,,,N,V*08
$GPGGA,000001.00,,,,,0,02,99.99,,M,0,,*34
$GPGLL,,,,,000001.00,V,A*44
$GPGSA,A,1,,,,,,,,,,,,,99.99,99.99,99.99,1*2D
$GPGSV,1,1,2,17,,,24,1,,,28,1*6D
$GPRMC,000001.00,V,,,,,,,060180,,,N,V*09
$GPGGA,000002.00,,,,,0,02,99.99,,M,0,,*37
$GPGLL,,,,,000002.00,V,A*47
$GPGSA,A,1,,,,,,,,,,,,,99.99,99.99,99.99,1*2D
$GPGSV,1,1,2,17,,,24,1,,,28,1*6D
$GPRMC,000002.00,V,,,,,,,060180,,,N,V*0A

    If SUPL client library support is enabled:

    1. Observe that the following message is displayed in the terminal emulator immediately after the device boots:

      New A-GPS data requested, contacting SUPL server, flags 59

    2. Observe the following actions in the terminal emulator:

      1. The sample switches to LTE and connects to a SUPL server.

      2. The A-GPS data gets downloaded.

      3. The sample continues after the SUPL session is complete.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr library: