Skip to main content

Using GNSS and GPS assistance

This page explains how to use nRF Cloud GNSS and GPS assistance over REST using samples for the nRF9160 DK.

Hardware requirements

This guide uses the nRF9160 DK. Cloud assistance requires an LTE modem and valid activated SIM card to download assistance data.

Prerequisites

See the common prerequisites for Location Services. All services require an nRF Cloud account.

Samples

The Location sample supports A-GPS and P-GPS, and provides a lightweight demo of core location functionality.

Modem Shell supports A-GPS and P-GPS, and adds further configuration options to the Location sample structure.

These samples use the GNSS interface, as well as the Location library.

note

If your application or sample can pass device data to nRF Cloud, the real-time location map on the device page in the nRF Cloud portal shows a GNSS data point after a successful operation. A-GPS operations also include an SCELL request. The historical location map also includes this SCELL data point.

This SCELL request is excluded from metrics data and billing.

Tutorial options

This guide covers two options for using nRF Cloud GPS assistance with samples, as well as an explanation of related API operations:

  • Using the Location sample: Suitable for a lightweight demo of core functionality with the most recent libraries.
  • Using Modem Shell: Suitable for development using integration with the most recent libraries.
  • GPS assistance API operations: Directly calling REST or MQTT endpoints is separate from using the other samples or applications. It is not dependent on using a particular application, and the applications in this guide do these operations automatically.
note

The instructions for each sample contain references to the nRF Connect for VS Code documentation that cover the general steps. This guide includes additional information relevant to each specific setup, so read through the relevant sample or application's steps before you begin.

Tools

This guide uses nRF Connect for VS Code to build and flash samples, and nRF Terminal (part of the nRF Connect for VS Code extension package) to send commands to the device.

Using the Location sample

This option uses the Location sample to demonstrate core GNSS location functionality and is compatible with GPS assistance from nRF Cloud.

The Location sample uses REST to communicate with nRF Cloud.

Create the sample:

  1. Open Visual Studio Code with the nRF Connect extension installed.
  2. Click the nRF Connect for VS Code icon in the left sidebar.
  3. Create the Location sample using the nrf/samples/nrf9160/location application template.

Create a build configuration according to your device and specify the necessary overlays:

  1. Select your Board from the drop-down menu. Choose the _ns option for the nRF9160 DK.
  2. Under Kconfig fragments, click Add fragment.
    • Select overlay-pgps.conf if you want to enable P-GPS. A-GPS is enabled by default without an overlay.
  3. Click OK.
  4. Deselect the checkbox marked Build after generating configuration.
  5. Click Generate configuration.

Check that the configuration options are correct:

  1. Under the Applications panel, make sure the Location sample is selected.
  2. Under the Location build panel, expand Input files.
  3. Check that the correct configuration options are set in prj.conf and overlay-pgps.conf:
    • A-GPS is enabled by default and requires no additional changes. Change the value of CONFIG_NRF_CLOUD_AGPS=y to =n or use # to comment the option out if you want to disable it.
    • Optional: Add CONFIG_MODEM_ANTENNA_GNSS_EXTERNAL=y if you are using an external GNSS antenna.
  4. Make sure you save any changes to the configuration files.

Build the sample and flash it to your device:

  1. Build the sample.

  2. Connect your device:

    1. Expand the Connected Devices panel.

    2. If your device is not visible, mouse over the panel and click the circular arrow to refresh the device list.

      Your device appears in the panel.

  3. Flash the sample to your device.

Run the sample in nRF Terminal:

  1. Under the Connected Devices panel, mouse over or click on the desired COM port.

  2. Click the plug icon to connect to the device in nRF Terminal. The terminal opens to the side.

    If the sample does not run, press the RESET (SW5) button on the nRF9160 DK.

  3. The Location sample requests assistance data from nRF Cloud and returns the device's location automatically. View the output to see latitude, longitude, and uncertainty.

Using Modem Shell

This method is intended for developers who need a customizable positioning setup. Modem Shell is compatible with GPS assistance from nRF Cloud.

Modem Shell can use either REST or MQTT to communicate with Cloud, depending on how you configure it.

note

If you are using an nRF9160 DK for the first time and want to use Modem Shell, see Getting nRF9160 DK out-of-the-box and to nRF Cloud for important information on AT commands and provisioning. You must follow these steps to provision a device running Modem Shell, otherwise, nRF Cloud cannot process location requests.

Create the sample:

  1. Open Visual Studio Code with the nRF Connect extension installed.
  2. Click the nRF Connect for VS Code icon in the left sidebar.
  3. Create the Modem Shell sample according to your device, SDK version, and toolchain. Select the nrf/samples/nrf9160/modem_shell application template.

Create a build configuration and specify the necessary overlays:

  1. Select your Board from the drop-down menu. Choose the _ns option for the nRF9160 DK.
  2. For GPS assistance: under Kconfig fragments, click Add fragment.
    • Select overlay-pgps.conf to enable P-GPS. A-GPS is enabled by default as part of the sample.
    • Select cloud_mqtt.conf to disable REST and use MQTT instead.
  3. Click OK.
  4. Deselect the checkbox marked Build after generating configuration.
  5. Click Generate configuration.

Once your build configuration is generated, check that the configuration options are correct:

  1. Under the Applications panel, make sure the Modem Shell sample is selected.
  2. Under the Modem Shell build panel, expand Input files.
  3. Open prj.conf and set the following configurations as needed:
    • Uncomment CONFIG_LTE_NETWORK_MODE_LTE_M_GPS=y to enable the GNSS receiver.
    • Optional: Add CONFIG_LOCATION_LOG_LEVEL_DBG=y to enable verbose logging for location operations. This generates a large amount of text as the device finds satellites.
  4. Make sure you save changes to your configuration files.

Build the sample and flash it to your device:

  1. Build the sample.

  2. Connect your device:

    1. Expand the Connected Devices panel.

    2. If your device is not visible, mouse over the panel and click the circular arrow to refresh the device list.

      Your device appears in the panel.

  3. Flash the sample to your device.

Run the sample in nRF Terminal:

  1. Under the Connected Devices panel, mouse over or click on the desired COM port.

  2. Click the plug icon to connect to the device in nRF Terminal. The terminal opens to the side.

    If the terminal does not show the $mosh prompt, press the RESET (SW5) button on the nRF9160 DK.

  3. Run the command location get. Add --method gnss --gnss_cloud_nmea to also send the result to nRF Cloud.

    • If you are using MQTT, run the command cloud connect before location get.

    The server fetches and applies assistance data. The device calculates its own location.

  4. The sample responds with location data in the output:

    Started to get current location...
    Location:
    used method: GNSS (2)
    latitude: 65.064386
    longitude: 25.878653
    accuracy: 19.7 m
    date: 2022-04-11
    time: 08:47:18.857 UTC
    Google maps URL: https://maps.google.com/?q=65.064386,25.878653

GPS assistance API operations

You can call the nRF Cloud REST API directly to get GPS assistance data.

This process is handled automatically by the Location and Modem Shell samples, so you do not typically need to do this separately.

Call GetAssistanceData to download current A-GPS data.

Call GetPredictedAssistanceData to download P-GPS data.