Getting started with devices on nRF Cloud
This guide explains how to connect devices to nRF Cloud.
For further information on background concepts, see device security and credentials. See also the Authentication sections of the MQTT API or the REST API.
Guides for nRF9160 DK and Thingy:91
See the guides to getting started with the nRF9160 DK or Thingy:91 for information on working with these specific devices.
Getting started
- Create a free account on nRFCloud.com.
- Read the documentation on device provisioning and adding and removing devices to decide how to connect your devices to your nRF Cloud account. Refer to the steps in Securely generating credentials on the nRF9160 depending upon your use case.
- Read the nRF Cloud API documentation to decide how you or your device communicate with nRF Cloud.
- Install nRF Connect for Desktop and the LTE Link Monitor modem client application.
Securely generating credentials on the nRF9160
The steps in this section require modem firmware v1.3.x or later.
You can securely generate credentials with the modem using the KEYGEN
AT command. Using this method, the private key is not exposed and never leaves the modem.
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 credentials are stored. The default<sec_tag>
for nRF Cloud credentials is16842753
. In most cases, this slot already contains credentials. You must delete these to provision 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
If you intend to use the default slot
16842753
, delete the existing certificate and private key by first sending the following AT command:AT%CMNG=3,16842753,1
When you see
OK
in the terminal, issue the next 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 provisioning a new CA certificate.To generate a private key in the modem and receive the associated certificate signing request (CSR), execute the following AT command. If you are not using the slot
16842753
, substitute the correct value.:AT%KEYGEN=16842753,2,0
The
KEYGEN
command uses the default value of the nRF9160's UUID as theCN
in the credential. If you are using a different device ID or MQTT client ID, update yourKEYGEN
command to use that ID as theCN
value.The output of a successful
KEYGEN
command is a base64-encoded CBOR object.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.
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.
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 theKEYGEN
command. See Managing and provisioning credentials for details. After provisioning the credentials, your device contains the private key in the<sec_tag>
provided to theKEYGEN
command, as well as a device certificate. To communicate with nRF Cloud, your device also needs an AWS Root CA certificate.Write the AWS Root CA certificate to your device using the same
<sec_tag>
you used for theKEYGEN
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
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 a JSON Web Token (JWT), you must register the device's public key through the
RegisterPublicKeys
endpoint.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.
If your device already has an active SIM card installed, you can see the device in your account and connected after a restart.
Generating credentials on a computer
You can create credentials off-device and load them into the device later. This method is less secure, because it exposes the private key.
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) tocreate_device_credentials.py
use your device's nRF Cloud device ID. 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.
Provision the device certificate to nRF Cloud using the
ProvisionDevices
endpoint.A successful call to
ProvisionDevices
provisions the device and associates it 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 requiring a JWT, provide the public key generated above to nRF Cloud using theRegisterPublicKeys
endpoint.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>
; typically16842753
for nRF Cloud. See Managing and provisioning credentials for details.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 in previous steps.To communicate with nRF Cloud, the device also needs an AWS CA certificate. Write the CA certificate to your device, using the same
<sec_tag>
.
The device now has:
- An AWS CA certificate.
- A private key.
- A device certificate for MQTT.
The device is ready to interact with nRF Cloud through REST or MQTT.
Managing and provisioning 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:
Type your
<sec_tag>
into the Security tag field.Copy and paste the CA certificate into the CA certificate field.
Copy and paste the device certificate into the Client certificate field.
Copy and paste the private key into the Private key field.
note
If you use
KEYGEN
to generate a private key, do not enter any data into thePrivate key
field. If you enter data into this field, it will overwrite the key created byKEYGEN
and you will need to start the process again.
Example of provisioning a new device certificate
This screenshot of the LTE Link Monitor Certificate manager depicts provisioning a new client (device) certificate to sec_tag
16842753:
Click Update Certificates. The terminal returns the following:
Using AT commands
The LTE Link Monitor terminal does not properly format line breaks. If you are using the LTE Link Monitor application, 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>"