Location module
The location module controls the positioning functionality of the nRF9160 including GNSS and cellular positioning. It can be used to retrieve the location of the device in the form of events containing a position, velocity and time (PVT) structure.
Features
This section documents the various features implemented by the module.
Location control
The module uses the Location library to communicate with the nRF9160 modem and control its GNSS and LTE neighbor cell measurement functionalities.
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 set as the first priority method and cellular positioning as the second priority. Fallback mode is used, which means that if GNSS fix cannot be acquired, cellular positioning is tried. 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_NEIGHBOR_CELLS_DATA_READY
: neighbor cell measurements have been obtained
* LOCATION_MODULE_EVT_DATA_NOT_READY
: Location request failed
* LOCATION_MODULE_EVT_TIMEOUT
: Timeout occurred
* LOCATION_MODULE_EVT_AGPS_NEEDED
: A-GPS request should be sent to cloud
* LOCATION_MODULE_EVT_PGPS_NEEDED
: P-GPS request should be sent to cloud
GNSS LNA configuration
Different devices have different GNSS antenna and LNA setups depending on the antenna type (onboard or external). The application uses the Modem antenna library for configuring the LNA. The library has Kconfig options to control the LNA using either the COEX0 or MAGPIO interface of the nRF9160. See the library documentation for more details on how to configure the antenna and LNA.
GPS assistance data
The location module receives requests for GPS assistance data from the Location library.
When the module receives an A-GPS request, it distributes it to the other modules as a LOCATION_MODULE_EVT_AGPS_NEEDED
event that contains information about the type of assistance data needed.
Providing the requested A-GPS data typically reduces significantly the time it takes to acquire a GNSS fix.
Module internals
The location module is a threadless module in terms of message processing. In this sense, it differs from many other modules.
All incoming events from other modules are handled in the context of the Application Event Manager callback, because they all complete fast enough to not require a separate thread.
Configuration options
- CONFIG_LOCATION_MODULE
Enables the location module.
Module states
The location module has an internal state machine with the following states:
STATE_INIT
- The initial state of the module in which it awaits the modem to be initialized and receive the location related configuration.
STATE_RUNNING
- The module has performed all required initialization and can respond to requests to start a location request. The running state has two sub-states:
SUB_STATE_SEARCH
- A location request is ongoing.
SUB_STATE_IDLE
- The module is idling and can respond to a request to start a location request.
STATE_SHUTDOWN
- The module has been shut down after receiving a request from the utility module.
State transitions take place based on input from other modules, such as the application module, data module, utility module and modem module.
Module events
The asset_tracker_v2/src/events/location_module_event.h
header file contains a list of events sent by the location module with associated payload.
Dependencies
The module uses the following nRF Connect SDK libraries:
API documentation
asset_tracker_v2/src/events/location_module_event.h
asset_tracker_v2/src/events/location_module_event.c
- group location_module_event
Location module event.
Enums
-
enum location_module_event_type
Location event types submitted by location module.
Values:
-
enumerator LOCATION_MODULE_EVT_GNSS_DATA_READY
A valid GNSS location has been obtained and the data is ready to be used. The event has associated payload of the type location_module_data in the event struct member
data.location
. All struct members withindata.location
contain valid data.
-
enumerator LOCATION_MODULE_EVT_DATA_NOT_READY
Location could not be obtained and will not be ready for this sampling interval. The event has no associated payload.
-
enumerator LOCATION_MODULE_EVT_NEIGHBOR_CELLS_DATA_READY
Neighbor cell measurements have been gathered and the data is ready. The event has associated payload of type location_module_neighbor_cells in the
data.neighbor_cells
member.
-
enumerator LOCATION_MODULE_EVT_TIMEOUT
The location search timed out without acquiring location. The event has associated payload of the type
struct location_module_data
in the event struct memberdata.location
. Thedata.location
struct membersearch_time
contains valid data andsatellites_tracked
contain valid data for GNSS.
-
enumerator LOCATION_MODULE_EVT_ACTIVE
An active location search has started.
-
enumerator LOCATION_MODULE_EVT_INACTIVE
A location search has stopped, either as a result of timeout, error or acquired location.
-
enumerator LOCATION_MODULE_EVT_SHUTDOWN_READY
The module has been shut down gracefully. The event has associated payload of the type
uint32
in the struct memberdata.id
that contains the module ID used when acknowledging a shutdown request from the util module.
-
enumerator LOCATION_MODULE_EVT_AGPS_NEEDED
The location library has reported that it needs GPS assistance data. The event has associated payload of the type
struct nrf_modem_gnss_agps_data_frame
in the event struct memberdata.agps_request
, which contains the types of A-GPS data that the modem needs.
-
enumerator LOCATION_MODULE_EVT_PGPS_NEEDED
The location library has reported that it needs GPS prediction data. The event has associated payload of the type
struct gps_pgps_request
in the event struct memberdata.pgps_request
, which specifies the P-GPS data need.
-
enumerator LOCATION_MODULE_EVT_ERROR_CODE
An error has occurred, and data may have been lost. The event has associated payload of the type
int
in the struct memberdata.err
, that contains the original error code that triggered the sending of this event.
-
enumerator LOCATION_MODULE_EVT_GNSS_DATA_READY
-
struct location_module_pvt
- #include <location_module_event.h>
Position, velocity and time (PVT) data.
-
struct location_module_neighbor_cells
- #include <location_module_event.h>
Location module data for associated payload for event of LOCATION_MODULE_EVT_NEIGHBOR_CELLS_DATA_READY types.
Public Members
-
struct lte_lc_cells_info cell_data
Information about the current cell.
-
struct lte_lc_ncell neighbor_cells[17]
Information about the neighbor cells.
-
int64_t timestamp
Uptime when the event was sent.
-
struct lte_lc_cells_info cell_data
-
struct location_module_data
- #include <location_module_event.h>
Location module data for associated payload for events of LOCATION_MODULE_EVT_TIMEOUT and LOCATION_MODULE_EVT_GNSS_DATA_READY types.
Public Members
-
struct location_module_pvt pvt
Location data in the form of a PVT structure.
-
uint8_t satellites_tracked
Number of satellites tracked.
-
uint32_t search_time
Time when the search was initiated until fix or timeout occurred.
-
int64_t timestamp
Uptime when location was sampled.
-
struct location_module_pvt pvt
-
struct location_module_event
- #include <location_module_event.h>
Location module event.
Public Members
-
struct app_event_header header
Location module application event header.
-
enum location_module_event_type type
Location module event type.
-
struct location_module_data location
Data for event LOCATION_MODULE_EVT_GNSS_DATA_READY.
-
struct location_module_neighbor_cells neighbor_cells
Data for event LOCATION_MODULE_EVT_NEIGHBOR_CELLS_DATA_READY.
-
struct nrf_modem_gnss_agps_data_frame agps_request
Data for event LOCATION_MODULE_EVT_AGPS_NEEDED.
-
int err
Cause of the error for event LOCATION_MODULE_EVT_ERROR_CODE.
-
struct app_event_header header
-
enum location_module_event_type