Skip to main content

Getting Started With Your Devices

This guide provides the steps to take to get your devices up and running on nRF Cloud. The bulk of the content is centered around device security and credentials, which is a complex though essential topic. See also the Authentication sections of the MQTT API or the REST API.

Guides for nRF9160 DK and Thingy:91#

If you are using an nRF9160 DK or Thingy:91, see the Other Docs and Tools page for links to Getting Started Guides specifically designed for these products. The information below complements those guides.

Getting started#

  1. Create a free account on nRFCloud.com.
  2. Read the documentation on device provisioning and adding and removing devices. This will give you an understanding of the various ways you can get your devices connected to your nRF Cloud account. Refer to the steps below for generating device credentials depending upon your use case.
  3. Read the documentation on our APIs to decide upon your next steps.
  4. Install nRF Connect for Desktop and the LTE Link Monitor modem client application.

Securely generating credentials on the nRF9160#

note

Make sure you have modem firmware v1.3.x or later.

The modem can securely generate credentials using the KEYGEN AT command. This method can be considered more secure because the private key is not exposed and never leaves the modem.

  1. To ensure the modem is deactivated, send the following AT command:

    AT+CFUN=4

    In the output, <sec_tag> is the slot in the modem where the credentials will be stored. The default <sec_tag> for nRF Cloud credentials is 16842753. In most cases, this slot already contains the credentials. You must delete these to flash new credentials in the steps that follow. Otherwise, you may use a different slot.

    To see which slots are currently used, use the CMNG AT command:

    AT%CMNG=1

  2. If you intend to use slot 16842753, you most likely have to delete the existing certificate and private key by sending these AT commands one at a time:

    AT%CMNG=3,16842753,1

    When you see OK in the terminal, issue the following command:

    AT%CMNG=3,16842753,2

    If you resend AT%CMNG=1, you see a value only for type 0 (CA certificate). This is expected, as you are not flashing a new CA certificate.

  3. To generate a private key in the modem and receive the associated certificate signing request (CSR), execute the following AT command:

    AT%KEYGEN=16842753,2,0

    If you are not using the slot 16842753, substitute the correct value.

    note

    The KEYGEN command uses the default value, the nRF9160's UUID, for the CN in the credential. If you are using a different device ID or MQTT client ID, update your KEYGEN command to use the ID as the CN value.

    The output of a successful KEYGEN command is a base64-encoded CBOR object.

  4. Convert the CBOR object to a Certificate Signing Request (CSR) in PEM format using the modem_credentials_parser.py script. See the README for additional details.

    note

    If you are manually copying and pasting the KEYGEN output, make sure to copy all characters of the base64 string that is enclosed in double quotes.

  5. Use the CSR PEM file to create a device certificate with the create_device_credentials.py script. See the README for additional details.

    This step requires a CA certificate (and its private key). If you do not already have one, use the create_ca_cert.py script to create a CA and a key that you can use to sign all your device certificates.

  6. If the device uses MQTT to connect to nRF Cloud, write the device certificate to the device using the same <sec_tag> you used for the KEYGEN command. See Managing and Flashing Credentials for details.

    After flashing the credentials, your device contains the private key in the <sec_tag> provided to the KEYGEN command, as well as a device certificate.

    To communicate with nRF Cloud your device also needs an AWS Root CA certificate.

  7. Write the AWS Root CA certificate to your device, using the same <sec_tag> you used for the KEYGEN command.

    The device now has the credentials it needs to use all of the nRF Cloud APIs:

    • a AWS CA certificate
    • a private key
    • a device certificate for MQTT

  8. Tell nRF Cloud about the certificate or public key, depending upon your broad use case:

  • Devices that use MQTT or the nRF Cloud FOTA service must be provisioned. If this applies, use the ProvisionDevices endpoint to upload the device certificate, provision the device on nRF Cloud, and add it to your nRF Cloud account.

  • If the device does not need to be provisioned but uses nRF Cloud REST APIs that require JWTs, you must register its public key through the RegisterPublicKeys endpoint.

    note

    For default or prebuilt Asset Tracker applications, provision your device using the nrf-[IMEI] device ID. Otherwise, configure these applications to use the device UUID.

Assuming your device has an active SIM card installed, you should see the device in your account and connected after a restart.

Generating credentials on a computer#

You can create credentials created off-device and later load them into the device. This method can be considered less secure, because it exposes the private key.

  1. To create a device certificate and a key pair (public key and private key), use the create_device_credentials.py script. See the README for additional details. For the -cn parameter (Common Name) to create_device_credentials.py use your device's nRF Cloud device ID. If you wish to use the device's internal UUID, see How to obtain the nRF9160's UUID.

    This step requires a CA certificate (and its private key). If you do not already have one, use the create_ca_cert.py script to create a CA and key that you can use to sign all your device certificates.

  2. Provision the device certificate to the ProvisionDevices endpoint.

    A successful call to ProvisionDevices will result in a device which is both provisioned and associated with your nRF Cloud account. Devices that use MQTT or the nRF Cloud FOTA service must be provisioned and associated. If the device does not need to be provisioned but needs to use certain nRF Cloud REST APIs, provide the public key generated above to the RegisterPublicKeys endpoint.

  3. Write the private key to your device so that it can communicate with nRF Cloud through MQTT (for mTLS) or REST (for signing JWTs). Use the the desired <sec_tag>; typically 16842753 for nRF Cloud. See Managing and Flashing Credentials for details.

  4. If the device uses MQTT to connect to nRF Cloud then it needs the device certificate generated above. Write the device certificate to your device, using the same <sec_tag> as above.

  5. To communicate with nRF Cloud it also needs the AWS CA certificate. Write the CA certificate to your device, using the same <sec_tag> as above.

The device now has:

  • an AWS CA certificate
  • a private key,
  • a device certificate for MQTT

It is ready to interact with nRF Cloud through REST or MQTT.

Managing and flashing credentials#

Manage the credentials using the CMNG AT command, either through the AT command directly or the LTE Link Monitor Certificate Manager.

Using the LTE Link Monitor certificate manager#

To use the Certificate Manager, perform the following steps:

  1. Type your <sec_tag> into the Security tag field.

  2. Copy and paste the CA certificate into the top box, labeled CA certificate.

  3. Copy and paste the device certificate into the middle box, labeled Client certificate.

  4. Copy and paste the private key into the bottom box, labeled Private key.

    info

    If you used KEYGEN to generate a private key, do not input any data into the Private Key box. This would overwrite the key created by KEYGEN and you would need to start the process over.

Example of flashing a new device certificate#

This screenshot of the LTE Link Monitor Certificate Manager depicts flashing a new client (device) certificate to sec_tag 16842753:

Using the LTE Link Monitor Certificate Manager

Click Update certificates. The terminal returns the following:

Using the LTE Link Monitor terminal after flashing the certificate

Using AT commands#

note

These commands are difficult to use with the LTE Link Monitor Terminal, because it does not properly format the line breaks. If you are using the LTE Link Monitor, use its Certificate Manager.

Writing a CA certificate#

To write a CA certificate to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,0,"<CA_cert_text>"

Writing a device certificate#

To write a device certificate to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,1,"<device_cert_text>"

Writing a private key#

To write a private key to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,2,"<private_key_text>"

Additional information#

See background information on device security.