Skip to 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.

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.

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.

There are two options for using nRF Cloud GPS assistance with samples, as well as an explanation of related API operations.

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.

Using the Location sample

The Location sample is suitable for a lightweight demo of core functionality with the most recent libraries.

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.

Creating 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.

Creating a build configuration and specifying 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.

Checking configuration options

  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.

Building the sample and flashing 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.

Running the sample in nRF

  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

Modem Shell is suitable for development using integration with the most recent libraries.

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.

Creating 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.

Creating 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.

Checking 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.

Building 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.

Running 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

Directly calling REST or MQTT endpoints is separate from using the other samples or applications. It is not dependent on using a particular application. This process is handled automatically by the Location and Modem Shell samples, so you do not typically need to do this separately.

These endpoints do not calculate a GNSS-based location fix, but are for manually downloading prediction data: