nRF9160: Multicell location¶
The Multicell location sample demonstrates how to use Multicell location library to get a device’s position based on LTE cell measurements.
Requirements¶
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Build target |
---|---|---|---|
PCA20035 |
thingy91_nrf9160 |
|
|
PCA10090 |
|
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.
Overview¶
You can use this sample as a starting point to implement multicell location services in an application that needs the location of the device.
The sample acquires LTE cell information from LTE link controller. The cell information is passed on to the Multicell location library, where an HTTP request is generated and sent to the location service of choice. Responses from location services are parsed and returned to the sample, which displays the responses on a terminal.
Currently, the sample can be used with the location services supported by the Multicell location library, which are nRF Cloud Location Services, HERE Positioning and Skyhook Precision Location. Note that nRF Cloud currently is a single-cell location service, and does not make use of neighboring cells in location resolution. Before you use the services, see the Multicell location library documentation and the respective location service documentation for the required setup.
Trigger location requests¶
Location requests can be triggered in the following ways and can be controlled by Kconfig options:
Pressing Button 1.
Periodically, with a configurable interval.
Changing of the current LTE cell, indicating that the device has moved.
Cell measurements¶
Data from LTE cell measurements is used to resolve a device’s location. There are two types of cells for which properties can be measured:
Current cell to which the device is connected
Neighboring cells
The most detailed information is measured for the current cell.
See lte_lc_cells_info
in LTE link controller API for more details on the information that is available for the different cells.
LTE link controller library offers APIs to start and stop measurements, and the results are received in a callback.
Cell measurements are in general influenced by the following factors:
Network configuration
LTE connection state
Radio conditions
Cell measurement results might vary with the state of the LTE connection, and with the configurations of the LTE network that the device is connected to.
For instance, the timing advance
property, which can be used to estimate the distance between a device and the LTE cell, is only valid and available in RRC connected mode.
Based on the network configurations, neighbor cell measurements might not be available in RRC connected mode.
In this case, the device must enter RRC idle mode to perform neighbor cell measurements.
This means that in some networks and configurations, it might not be possible to obtain timing advance for the current cell and neighbor cell measurements at the same time.
Multicell location requests are based on cell measurements. While deciding on when to perform cell measurements, keep in mind the following factors:
Timing advance for the current cell is available in RRC connected mode and not in RRC idle mode.
Neighbor cell measurements might not be possible in RRC connected mode, depending on the network configuration.
Neighbor cell measurements can, with some exceptions, be done in RRC idle mode and PSM. The number of cells that can be found varies with network configuration.
Configuration¶
See Configuring your application for information about how to permanently or temporarily change the configuration.
Setup¶
To use one of the supported location services, you must have an account and a configured authorization method. Follow the documentation on nRF Cloud, HERE Positioning or Skyhook Precision Location for account creation and authorization method details.
Configuration options¶
Check and configure the following configuration options for the sample:
-
CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_PERIODIC
¶
(bool)
Request location periodically
Request cell measurements and location periodically.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_PERIODIC_INTERVAL
¶
(int)
Periodic search interval [sec]
Interval for periodic cell measurements and location requests.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_BUTTON
¶
(bool)
Request location pressing button 1
Request cell measurements and location when button 1 is pressed.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_CELL_CHANGE
¶
(bool)
Request location on cell change
Request cell measurements and location when the current LTE cell changes. This can be useful when testing on a moving device.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_PRINT_DATA
¶
(bool)
Print multicell data
Prints cell data when it’s reported from the link controller.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_PSM
¶
(bool)
Request PSM from the network
Request PSM from the LTE network.
-
CONFIG_MULTICELL_LOCATION_SAMPLE_EDRX
¶
(bool)
Request eDRX from the network
Request eDRX from the LTE network.
Additional configuration¶
Check and configure the following library options that are used by the sample:
For the location service that is used, the authorization method can be set with one of the following options:
See Multicell location for more information on the various configuration options that exist for the services.
Building and running¶
This sample can be found under samples/nrf9160/multicell_location
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.
Testing¶
After programming the sample to your development kit, test it by performing the following steps:
Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.
Observe that the sample starts:
*** Booting Zephyr OS build v2.4.99-ncs1-4938-g540567aae240 *** <inf> multicell_location_sample: Multicell location sample has started <inf> multicell_location: Provisioning certificate <inf> multicell_location_sample: Connecting to LTE network, this may take several minutes
Wait until an LTE connection is established. A successful LTE connection is indicated by the following entry in the log:
<inf> multicell_location_sample: Network registration status: Connected - roaming
Press Button 1 on the device to trigger a cell measurement and location request:
<inf> multicell_location_sample: Button 1 pressed, starting cell measurements
Observe that cell measurements are displayed on the terminal:
<inf> multicell_location_sample: Neighbor cell measurements received <inf> multicell_location_sample: Current cell: <inf> multicell_location_sample: MCC: 242 <inf> multicell_location_sample: MNC: 001 <inf> multicell_location_sample: Cell ID: 1654712 <inf> multicell_location_sample: TAC: 3410 <inf> multicell_location_sample: EARFCN: 1650 <inf> multicell_location_sample: Timing advance: 65535 <inf> multicell_location_sample: Measurement time: 645008 <inf> multicell_location_sample: Physical cell ID: 292 <inf> multicell_location_sample: RSRP: 57 <inf> multicell_location_sample: RSRQ: 30 <inf> multicell_location_sample: Neighbor cell 1 <inf> multicell_location_sample: EARFCN: 1650 <inf> multicell_location_sample: Time difference: -8960 <inf> multicell_location_sample: Physical cell ID: 447 <inf> multicell_location_sample: RSRP: 33 <inf> multicell_location_sample: RSRQ: -17 <inf>multicell_location_sample: Neighbor cell 2 <inf> multicell_location_sample: EARFCN: 100 <inf> multicell_location_sample: Time difference: 24 <inf> multicell_location_sample: Physical cell ID: 447 <inf> multicell_location_sample: RSRP: 19 <inf> multicell_location_sample: RSRQ: 4 <inf> multicell_location_sample: Neighbor cell 3 <inf> multicell_location_sample: EARFCN: 3551 <inf> multicell_location_sample: Time difference: 32 <inf> multicell_location_sample: Physical cell ID: 281 <inf> multicell_location_sample: RSRP: 41 <inf> multicell_location_sample: RSRQ: 13
Confirm that location request is sent, and that the response is received:
<inf> multicell_location_sample: Sending location request... <inf> multicell_location_sample: Location obtained: <inf> multicell_location_sample: Latitude: 63.4216744 <inf> multicell_location_sample: Longitude: 10.4373742 <inf> multicell_location_sample: Accuracy: 310
The request might take a while to complete.
Observe that cell measurement and location request happen after the periodic interval has passed:
<inf> multicell_location_sample: Periodical start of cell measurements
Observe that the sample continues with cell measurements and location requests as explained in the previous steps.
Dependencies¶
This sample uses the following nRF Connect SDK libraries and drivers:
It uses the following sdk-nrfxlib library:
It uses the following Zephyr libraries:
include/console.h
-
include/kernel.h
In addition, it uses the following samples: