1. Overview

This application note describes how to determine the device location using the nRF9151 GNSS module.

2. Device Preparations

1. Set up the hardware platform with LTE and GNSS antennas as described in Setting Up Emcraft SOM-NRF9151 Hardware Platform.

2. Install the modem and application firmware onto the hardware platform as described in Installing SOM-NRF9151 Images.

3. Complete certificate provisioning and verify that the hardware platform connects to nRF Cloud as described in Performing IoT Provisioning and Connecting to nRF Cloud.

3. nRF Connect SDK Location Library

The Location library provides functionality for retrieving the location of a device using different positioning methods such as:

• GNSS satellite positioning including Assisted GNSS (A-GNSS) and Predicted GPS (P-GPS) data.

• Cellular positioning.

• Wi-Fi^® positioning.

This library provides an API for applications to request the location of a device. The application can determine the preferred order of the location methods to be used along with other configuration information. If a method fails to provide the location, the library performs a fallback to the next preferred method.

Both cellular and Wi-Fi positioning detect the base stations and use web services for retrieving the location. GNSS positioning uses satellites to compute the location of the device. This library can use the assistance data (A-GNSS and P-GPS) to find the satellites faster.

3.1. Location Library Implementation

The Location library has a compact API and a location core that handles the functionality that is independent of the location method, such as fallback to the next preferred method and timeouts. The customized Asset Tracker v2 application makes use of the GNSS and Cellular positioning methods:

• GNSS positioning

  • Uses GNSS interface for getting the location.

  • A-GNSS and P-GPS are managed with nRF Cloud A-GNSS and nRF Cloud P-GPS.

  • The application may also use some other source for the data and use location_agnss_data_process() and location_pgps_data_process() to pass the data to the Location library.

  • The data format of A-GNSS or P-GPS must be as received from nRF Cloud A-GNSS.

  • The data transport method for nRF Cloud A-GNSS and nRF Cloud P-GPS can be configured to be either MQTT (CONFIG_NRF_CLOUD_MQTT) or REST (CONFIG_NRF_CLOUD_REST). If different transport is desired for different location methods, (CONFIG_NRF_CLOUD_MQTT) and (CONFIG_NRF_CLOUD_REST) can be enabled simultaneously. In such a case, MQTT takes precedence as the transport method of GNSS assistance data.

  • Note that acquiring GNSS fix only starts when LTE connection, more specifically Radio Resource Control (RRC) connection, is idle. Also, if A-GNSS is not used and Power Saving Mode (PSM) is enabled, the Location library will wait for the modem to enter PSM.

  • Selectable location accuracy (low/normal/high).

  • Obstructed visibility detection enables a fast fallback to another positioning method if the device is detected to be indoors.

• Cellular positioning

  • Uses LTE link control for getting a list of nearby cellular base stations.

  • Neighbor cell measurement is performed with LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_LIGHT search type. If more than one cell is requested, a GCI search with LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT search type is performed to find the cells based on the history information. If a sufficient number of cells still has not been found, a GCI search with LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_LIGHT search type is performed. For more details on GCI search, see location_cellular_config.cell_count.

  • The cloud location method handles sending cell information to the selected location service and getting the calculated location back to the device.

3.2. nRF Cloud A-GNSS

The nRF Cloud A-GNSS library enables applications to request and process Assisted GNSS (A-GNSS) data from nRF Cloud to be used with the nRF91 Series SiP. This library is an enhancement to the nRF Cloud library.

Using A-GNSS reduces the time for a Global Navigation Satellite System (GNSS) module to estimate its position, which is also called Time to First Fix (TTFF). To get a position fix, a GNSS module needs information such as the satellite orbital data broadcasted by the satellites. If nRF Cloud A-GNSS service is used, the broadcasted information can be downloaded at a faster rate from nRF Cloud.

In addition to reducing the time to fix, A-GNSS also provides ionospheric correction data to the device. Ionospheric corrections enable GNSS to estimate the ionospheric delay for each satellite, making the position data more accurate. While ionospheric corrections can also be downloaded from the satellite broadcast, this is often not practical because the whole GPS navigation message takes 12.5 minutes.

By default, the A-GNSS library is enabled in the customized Asset Tracker v2 application by setting the CONFIG_NRF_CLOUD_AGNSS and CONFIG_NRF_CLOUD_MQTT options in the prj.conf file.

4. Determining Device Location

4.1. Determining Device Location using GNSS Shell

The application implements a set of location shell commands, which can be used to trigger or cancel location requests from the serial console.

Perform the following steps to obtain the GPS data.

1. From the serial console, initiate the GNSS request:

   uart$ location get -m gnss

2. Observe the GPS readings in the following format:

   Started to get current location... Unknown event from location library, id 8 Location: used method: GNSS (2) latitude: XX.XXXXXX longitude: -YYY.YYYYYY accuracy: 48.9 m date: 2024-07-09 time: 11:28:31.321 UTC

3. Observe the C/N0 (Carrier-to-Noise Density Ratio) for each satellite in the fix, one satellite per line:

   PRN: 12, C/N0: 23.1, in fix: 1, unhealthy: 0 PRN: 30, C/N0: 0.0, in fix: 0, unhealthy: 0 PRN: 19, C/N0: 24.8, in fix: 1, unhealthy: 0 PRN: 15, C/N0: 28.4, in fix: 1, unhealthy: 0 PRN: 13, C/N0: 23.8, in fix: 1, unhealthy: 0

4.2. Determining Device Location using Location Module

The location module controls the GNSS, cellular, and Wi-Fi^® positioning functionality. It can be used to retrieve the location of the device in the form of events containing a position, velocity and time (PVT) structure.

The module uses the Location library to communicate with the nRF91 Series modem and control its GNSS and LTE neighbor cell measurement functionalities as well as with the nRF7002 Wi-Fi positioning functionality. A location request starts when the module receives an APP_EVT_DATA_GET event and the APP_DATA_LOCATION type is listed in the event’s data_list member containing the data types that shall be sampled.

The default configuration for the location request is set as follows:

• GNSS, Wi-Fi and cellular positioning are set in priority order of the location methods. Wi-Fi is omitted if it is not built into the application. If GNSS fails, both Wi-Fi and cellular positioning are tried. The priority order of the methods can be changed through Location library Kconfig options. Methods that should not be used can be configured by adding them into No Data List. See Real-time configurations for more information.

• Timeout, which can be configured as part of Real-time configurations with Location timeout.

The location module receives configuration updates as payload in the following two events:

• DATA_EVT_CONFIG_INIT - The event contains the value configured at build time or received from cloud and stored to flash. The event is distributed from the data module as part of the application initialization.

• DATA_EVT_CONFIG_READY - The event is received when the data module has processed an incoming message from cloud with a configuration update.

The module sends the following events based on the outcome of the location request:

• LOCATION_MODULE_EVT_GNSS_DATA_READY: GNSS position has been acquired

• LOCATION_MODULE_EVT_CLOUD_LOCATION_DATA_READY: Neighbor cell measurements or Wi-Fi access points (or both) have been obtained

• LOCATION_MODULE_EVT_DATA_NOT_READY: Location request failed

• LOCATION_MODULE_EVT_TIMEOUT: Timeout occurred

• LOCATION_MODULE_EVT_AGNSS_NEEDED: A-GNSS request should be sent to cloud

• LOCATION_MODULE_EVT_PGPS_NEEDED: P-GPS request should be sent to cloud

5. Validating GNSS Operations

1. Check the board uuid from the nRF9151 console (it is assumed that the nRF Device provisioning procedure has been performed earlier):

   uart:~$ nrf_provisioning uuid 50343959-3733-4c71-806b-202470cee0bf

2. Check that the board has successfully connected to the cloud over LTE:

   [00:00:02.824,615] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTING [00:00:04.110,168] <inf> app_event_manager: MODEM_EVT_LTE_CELL_UPDATE [00:00:15.095,916] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTED [00:00:15.234,283] <inf> cloud_module: DEVICE CERTIFICATE IS PRESENT [00:00:15.236,907] <inf> app_event_manager: CLOUD_EVT_CONNECTING [00:00:15.237,426] <inf> app_event_manager: MODEM_EVT_LTE_PSM_UPDATE [00:00:15.237,915] <inf> app_event_manager: DATA_EVT_DATE_TIME_OBTAINED [00:00:22.080,871] <inf> net_mqtt: Connect completed

3. Login to the nRF Cloud and go to the DEVICE MANAGEMENT / Devices page. Find the board by the uuid ID and open the board page:

   Open

   

4. Click the Manage Cards button and check the Device Data checkbox so that the Device Data card is displayed on the board page.

5. In the Device Data card, check the Last connected attribute to make sure that the board has recently connected to the cloud:

   Open

   

6. From the nRF9151 console, confirm that the location module is active:

   [00:00:16.094,635] <inf> app_event_manager: LOCATION_MODULE_EVT_ACTIVE [00:00:16.112,396] <inf> app_event_manager: LOCATION_MODULE_EVT_AGNSS_NEEDED

7. Wait up to 300 seconds for the application to receive GNSS data. The default timeout of 300 seconds can be reduced or increased if necessary: click the View Config button, then Edit Configuration. Location request timeout is no greater than locationTimeout.

   Open

   

8. From the nRF9151 console, confirm that the device have received GNSS data:

   [00:03:19.068,115] <inf> app_event_manager: LOCATION_MODULE_EVT_GNSS_DATA_READY [00:03:19.068,847] <inf> app_event_manager: LOCATION_MODULE_EVT_INACTIVE

9. Wait 110 seconds for the device data to be updated on the cloud. The default timeout of 110 seconds can be reduced for convenience: click the View Config button, then Edit Configuration. If activeMode is false then the timeout is no greater than movementResolution, otherwise, it is no greater than activeWaitTime.

10. From the nRF9151 console, confirm that the device data have been sent to the cloud:

    [00:03:19.069,335] <inf> app_event_manager: DATA_EVT_DATA_READY [00:03:19.073,059] <inf> app_event_manager: DATA_EVT_DATA_SEND_BATCH [00:03:19.073,974] <inf> app_event_manager: CLOUD_EVT_DATA_SEND_QOS

11. In the Device Data card on the nRF Cloud, verify that the Location attribute has been updated recently and has a proper value:

    Open

    

12. Click the Show Location card icon to see the graphical representation of the device location:

    Open

    

13. Click the View historical data icon and select appropriate time interval to see device location history:

    Open