Location Services tutorials

This page collects common prerequisites and tutorials for nRF Cloud Location Services.

Prerequisites

Make sure your setup first meets these prerequisites before you choose a tutorial. These are processes you need to complete, tools and applications you must install, or other information you need to know before getting started.

note

The prerequisites on this page apply to all Location Services tutorials. Each tutorial provides any additional information needed for that component or method.

Accounts and authentication

Complete the following steps before beginning a tutorial:

1. Create an nRF Cloud account.
2. Provision your device.
3. Connect your device to nRF Cloud.

Toolchain and applications

The tutorials use the following tools and applications:

• nRF Connect for Desktop.
• nRF Connect for VS Code.
• A tool to use the APIs. Examples in the API references use cURL but you can use another interface if you want. See REST client tools for more information on API tools.
• Asset Tracker v2.
• Location sample.
• Modem Shell sample.

Hardware requirements

The guides and tutorials in this section are written for devices using the nRF9160 SiP unless otherwise specified.

The reference hardware for the tutorials is the nRF9160 DK. Other devices might require additional configuration.

Cellular location

Your device must have an active SIM card and LTE module.

Using MCELL requires nRF Connect SDK v1.8.0 or later and modem firmware v1.3.0 or later.

A-GPS and P-GPS

Your device must have a GNSS module. The nRF9160 DK has an onboard GNSS receiver.

APIs

The following table summarizes requirements for using Location Services through either REST or MQTT, as well as an explanation of the authorization mechanisms for each.

Protocol	Authentication	Key Differences
MQTT	Mutual TLS	Requires certificate and cloud provisioning.
REST	JSON Web Token (JWT)	Does not require certificate and cloud provisioning. Can be used by proxy servers on behalf of devices they serve (requires a Pro or Enterprise plan). If you want to try this service for 30 days over REST, you can create a temporary evaluation token.

Click to expand the following sections for more information on specific requirements by protocol:

MQTT requirements for Location Services

To use MQTT, you must create X.509 device certificates and provision your device on nRF Cloud:

1. Create and provision the device certificates.
2. Provision the devices to your account.
3. Follow the steps in the docs for the relevant Location Service libraries in the nRF Connect SDK.

REST requirements for Location Services

Using REST

When using nRF Cloud REST-based Location Service endpoints, cloud provisioning is optional, as are device certificates.

JWTs are used for authentication. Include the token in the Authorization header in calls to Location Services REST endpoints. For example, using cURL: Authorization: Bearer <your_token>.

Authentication for proxy servers

If you are using Location Services over REST, you are likely using a proxy server in a cloud-to-cloud integration. You can use an evaluation token to temporarily evaluate the services and test your setup.

Service key

If you are using nRF Cloud through a proxy server beyond the trial period, a JWT signed with a service key is required for each component of Location Services.

Access

Cloud-to-cloud use of nRF Cloud requires a Pro or Enterprise plan.

See more information on generating a service key.

Authentication for devices

This is for device-to-cloud operations.

If you have successfully provisioned and connected your device to nRF Cloud, you do not need to do any additional steps for authentication.

The following steps apply if you are using the REST API without provisioning your devices on nRF Cloud and not using a proxy server:

1. Create a key pair and provision the private key.
2. Register the public key for each device using the RegisterPublicKeys endpoint.
3. Follow the steps in the docs for the relevant Location Service libraries in the nRF Connect SDK, including the REST library. For creating JWTs, see the AT%JWT command and related library in the nRF91 AT Commands documentation.

Tutorials

These tutorials explain specific operations using the different components of Location Services:

• Using the evaluation token and service key.
• Finding location through one or more cell towers using REST.
• Cloud-to-cloud cellular integration guide.
  • See also the requirements for a cloud-to-cloud setup.
• Finding location through Wi-Fi networks.
• GPS assistance.

See also Troubleshooting.