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.

Requirements¶

To complete all the steps in this guide, you need:

An nRF52832 DK programmed with the nRF Cloud demo application.

This application demonstrates the Bluetooth LE capabilities of the nRF52832 DK. See 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 guide 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 environment 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 the API key. 1. Set the environment variables:

export API_KEY=<YOUR_API_KEY>
export DEVICE_ID=<YOUR_DEVICE_ID>
export GATEWAY_ID=<YOUR_GATEWAY_ID>

Fetching Bluetooth LE device data¶

To view the state of your Bluetooth LE device, call the FetchDevice endpoint:

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 [10, 0]:

{
  "id": "BB254ECF-106F-58E2-100C-C171EFF98315",
  "gatewayId": "sgw-c7a1f715-i-660bc947581c7b09",
  "name": "BB254ECF-106F-58E2-100C-C171EFF98315",
  "tags": [],
  "type": "BLE",
  "tenantId": "55b8005c-7705-4487-8392-e034ee6d9270",
  "subType": "unknown",
  "state": {
    "086011118277EF8E1523785788778193": {
      "characteristics": {
        "086022228277EF8E1523785788778193": {
          "path": "086011118277EF8E1523785788778193/086022228277EF8E1523785788778193",
          "descriptors": {
            "2902": {
              "path": "086011118277EF8E1523785788778193/086022228277EF8E1523785788778193/2902",
              "uuid": "2902",
              "value": [
                0
              ]
            }
          },
          "uuid": "086022228277EF8E1523785788778193",
          "value": [
            10,
            0
          ],
          "properties": {
            "read": true,
            "write": true,
            "notify": true
          }
        }
      },
      "uuid": "086011118277EF8E1523785788778193"
    }
  },
  "firmware": {
    "supports": []
  },
  "$meta": {
    "version": "18.0",
    "createdAt": "2021-08-10T23:24:33.087Z",
    "updatedAt": "2021-08-11T22:23:03.541Z"
  }
}

The JSON response can be large. If you want a smaller response, read Transforming JSON responses. Note that tags in the response refers to device groups.

The 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 nRF52832 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:

export CHARACTERISTIC_ID=<YOUR_CHARACTERISTIC_ID>

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' \
  --data '[
  12,0
]'

Other methods¶

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 nRF52832 DK 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, send 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.