Skip to main content

Getting Started with Location Services

This guide is intended for developers and explains how to use nRF Cloud Location Services on the nRF9160 DK through MQTT or our REST API:

  • Find device location from single or multiple cell towers (CELL_POS).
  • Provide a device with current (assisted GPS or A-GPS) or predicted (P-GPS) satellite locations for a faster time-to-first-fix (TTFF).
  • View device location history.

Requirements#

This guide is written for devices using the nRF9160 SiP. Location Services are not usable by nRF52 series devices.

CELL_POS services require that your device has an active SIM card.

Additionally, devices consuming the nRF Cloud Location Services via the REST API must also use modem firmware v1.3.x, which has its own hardware requirements as described in the release notes.

Devices using Location Services over MQTT may use modem firmware v1.2.0 and above unless using MCELL, which requires modem firmware v1.3.x.

Steps for Getting Started#

Devices may consume Location Services either via MQTT or REST.

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#

MQTT requires your device(s) to have the proper X.509 certificates and be provisioned on nRF Cloud.

  1. Create and flash 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 our 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 Account.
  4. Under REST API Authentication Management, find Service Evaluation Token.
  5. Click Generate Token. A window opens asking for confirmation.
  6. Click OK to generate the token.
  7. The token appears in the text field to the left of the Generate Token button. You can copy and paste it using your mouse or keyboard, or copy it by clicking the clipboard button next to the text field. 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.

The following steps assume 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 flash 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 JSON Web Tokens, see the AT%JWT command and related library in the nRF91 AT Commands documentation.

Troubleshooting#

I can't get a GPS fix#

Some older DKs might have difficulty getting a GPS fix. Check that your device meets the requirements. If it doesn't have an internal GPS antenna, attach an external antenna, or query the device location using Cell.

If your device has a newer nRF9160 SiP and you are still having trouble getting a GPS 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 using CELL_POS.

I can't get cell location data#

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

  • Check with your cellular network provider to make sure there's coverage in your area.
  • Check that your device's SIM 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 if necessary.