Skip to main content

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

Toolchain and applications

The tutorials use the following tools and applications:

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.

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.

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.

ProtocolAuthenticationKey Differences
MQTTMutual TLSRequires certificate and cloud provisioning.
RESTJSON Web Token (JWT)Does not require certificate and cloud provisioning. Can be used by proxy servers on behalf of devices they serve (requires commercial account). If you want to try this service for 30 days over REST, you can create a temporary evaluation token.

Using MQTT

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.

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.

Evaluation token

An evaluation token lets you use nRF Cloud Location Services free for thirty days. The trial period starts once you generate the token.

You can create and view an evaluation token through the nRF Cloud portal or directly through the APIs.

To generate an evaluation token in the portal:

  1. Log in to the nRF Cloud portal.
  2. Click the drop-down menu in the top right corner.
  3. Click Team.
  4. In the Service Evaluation Token section, click Generate Token. A window opens asking for confirmation.
  5. Click OK to generate the token.
  6. Copy the token that appears in the text field to the left of the Generate Token button. The token no longer appears once it has expired.

To generate an evaluation token using the REST API:

  1. Call the GenerateServiceEvaluationToken endpoint.
  2. View the token and its expiration date at any time using the GetServiceEvaluationToken endpoint.

Contact Nordic Semiconductor Sales to renew an expired token, or for more information about nRF Cloud services.

Service key

If you are using nRF Cloud through a proxy server beyond the trial period, a service key is required to generate and sign your own JWTs. Cloud-to-cloud use of nRF Cloud requires a commercial account. For more information, contact Nordic Semiconductor Sales.

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:

Troubleshooting

This section provides possible solutions to Location Services issues.

I cannot get a GNSS fix

Some older DKs might have difficulty getting a GNSS fix. Check that your device meets the prerequisites. If it does not have an internal GNSS antenna, attach an external antenna, or query the device location using cellular.

If your device has a newer nRF9160 SiP and you are still having trouble getting a GNSS fix, try the following:

  • Place the device near a window with a clear view of the sky.
  • Ensure that the device connection is stable.
  • Query the device location with an alternative method that does not require the GNSS receiver, such as cell location.

I cannot get cell location data

If your device is otherwise functioning normally, try the following to correct cellular issues:

  • If you have physical access to the device, open the LTE Link Monitor application of nRF Connect for Desktop to check the connection status:
    • Check that the correct COM port is selected.
    • Check which network the device is connected to and signal strength in the left panel.
    • There is occasionally a delay in establishing a connection after the device starts up or resets. See if the device functions as expected after two or three minutes. If it still does not connect, push the RESET button on the device.
  • Check with your cellular network provider to make sure there is coverage in your area.
  • Check that your device's SIM card still has data:
    1. Sign in to the nRF Cloud portal.
    2. Click SIM cards in the navigation bar on the left.
    3. Buy more data for your SIM card if necessary.