Using the REST API with a Bluetooth® Low Energy device
This guide shows how to use endpoints in the nRF Cloud REST API to interact with a device running a Bluetooth® Low Energy (LE) application.
To complete all the steps in this guide, you need:
An nRF9160 DK programmed with the nRF Cloud demo application.
This application demonstrates the Bluetooth LE capabilities of the nRF9160 DK. See Building and programming an application in the nRF Connect SDK documentation for how to program the application to the DK.
An iOS or Android phone running the nRF Cloud gateway phone application.
An nRF Cloud account.
The examples in this tutorial use cURL to construct API requests. You can also use a separate application for API calls, such as Postman or Insomnia.
Connecting nRF Cloud Demo to nRF Cloud
Complete these steps to connect nRF Cloud Demo:
Open the nRF Cloud gateway on your phone.
In the phone app, log in using your nRF Cloud account.
In a browser, log in to the nRF Cloud portal.
Click Device Management on the left, select Gateways, and select your gateway.
If you are not sure which option is your current gateway, check the name and gateway ID in the Account section of the phone app.
Note the gateway ID.
You need the gateway ID for the cURL examples.
On the gateway's page, click the green + button in the Devices card.
Click Bluetooth Device.
This starts the gateway's Bluetooth LE scan process.
Select nRF Cloud Demo.
When prompted about device groups, click No:
The nRF Cloud Demo device page opens, with the Tutorial card visible.
If you do not see the Tutorial card, refresh the page.
Note the device ID.
The device ID is in parentheses after nRF Cloud Demo at the top. You need the device ID for the API calls in the examples.
To enable Bluetooth LE notifications, expand the options in the nRF Connect card, then click the play icon:
REST API call examples
This section contains examples for operating Bluetooth LE devices using the nRF Cloud REST API. The examples include fetching device data, toggling LED lights on the device, and refreshing the stored state of the device. When performing the operations, you can see gateway events processing in the Device Log card in the device's page on nRF Cloud portal.
Before you can use the cURL examples, you must retrieve and set some environment variables.
Setting the environment variables
Complete these steps to retrieve your API key, and set the API key, device ID, and gateway ID as environmental variables:
Log in to the nRF Cloud portal.
Click the three-line menu in the upper right corner and select User Account.
Note the API key from the Team Details card. Regenerate the API key if it is no longer valid.
See REST API authentication for more information on API key.
Set the environment variables:
Fetching Bluetooth LE device data
To view the state of your Bluetooth LE device, call the
curl https://api.nrfcloud.com/v1/devices/$DEVICE_ID -H "Authorization:Bearer $API_KEY"
Below is an example JSON response. When using the
FetchDevice endpoint, hex values for lights are converted to integer arrays, so
0A 00 is equivalent to
The JSON response can be large. If you want a smaller response, read Transforming JSON responses. Note that
tags in the response means device groups.
value field for characteristic
086022228277EF8E1523785788778193 in this example is
[10, 0], indicating that LEDs 2 and 4 are on. This value is also visible in the Tutorial Lights section of the nRF Connect card in the device's page on the nRF Cloud portal.
Toggling LED lights
Each LED light on the nRF9160 DK has a corresponding hex value: LED1
01 00, LED2
02 00, LED3
04 00, LED4
08 00. To toggle LED lights, use the
UpdateCharacteristicValue endpoint to send a new characteristic value in the request body as an array.
When using the endpoint, the hex values are converted to integer arrays. For example, to turn on LED3 and LED4, send
[12,0]. The current array is visible in the Tutorial Lights section of the nRF Connect card in the device's page on the nRF Cloud portal.
Note the characteristic ID fetched from the device. In the above example, it is
086022228277EF8E1523785788778193. Set the characteristic ID as an environment variable:
Send the integer array corresponding to the lights you want to turn on. For example, this turns on LED3 and LED4:
curl --request PUT \
--url https://api.nrfcloud.com/v1/devices/$DEVICE_ID/characteristics/$CHARACTERISTIC_ID \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
For comparison, you can also toggle the LED lights in the nRF Cloud portal, without using the REST API:
- You can click any of the four buttons on the nRF9160 DK to toggle the LED lights. You can see them turn on and off in the Web image in the Tutorial card.
- You can click the Web image in the Tutorial card to toggle the lights.
- You can directly edit the integer array value in the Tutorial Lights section of the nRF Connect card.
Refreshing the stored state of the Bluetooth LE device
To refresh the stored state of a connected Bluetooth LE peripheral, issue a discover request:
curl --request POST \
--url https://api.nrfcloud.com/v1/devices/$GATEWAY_ID/discover/$DEVICE_ID \
--header 'Authorization: Bearer $API_KEY'
This causes the gateway to which the Bluetooth LE device is connected to rediscover all of its Bluetooth services. This can take a few seconds. Once the rediscovery has completed, you can fetch the updated state.