Skip to main content

Using the REST API with a Bluetooth® Low Energy Device

In this guide you will learn how to use endpoints in the nRF Cloud REST API to interact with a device running a Bluetooth LE application.

Hardware Prerequisites#

nRF9160 DK flashed with the nRF Cloud demo application. This is a demo application that leverages the Bluetooth Low Energy capabilities of the nRF9160 DK.

The nRF9160 DK supports J-Link, so you can just drag this application from your computer to an nRF9160 DK connected to it via USB.

Steps on nRF Cloud#

  1. If you have not already done so, create an account on nRFCloud.com and log in.
  2. Retrieve your API key from the Account page. (See the REST API Authentication section for more information.)
  3. Download one of the nRF Cloud gateway phone apps and log in using your nRF Cloud account credentials.
  4. Click Device Management > Gateways and select your gateway. If you are not sure which option is your current gateway, check for the gateway id in the Account section of the phone app.

Gateway Page with No Bluetooth LE Device Connected​

  1. In the Devices card, click the green "+" button, then click Bluetooth Device. This should start the gateway's Bluetooth LE scan process. When you see nRF Cloud Demo. When prompted about device groups, click No.

Scanning for and Selecting the nRF Cloud Demo

  1. You should now see a screen that looks like this. If you do not see the Tutorial card, refresh the page.

After Adding the nRF Cloud Demo Device

  1. Enable Bluetooth LE notifications by expanding the options in the nRF Connect card, and then clicking the play icon:

Enable Notifications

  1. You can now click any of the four buttons on the nRF9160 DK to toggle the LED lights. You should see them turn on and off in the Web image. You can also click the Web image to toggle the lights. In the nRF Connect card you will see the values being set; and in the Device Log card you will see the gateway events that are being processed.

Toggling LEDs

  1. If you expand the sections in the Tutorial card you will see the hex values corresponding to the lights: LED1 01 00, LED2 02 00, LED3 04 00, LED4 08 00. Light combinations will simply add these values. For example, if LED2 and LED4 are on you will see 0A 00. You can also directly edit this value by clicking on it in the Tutorial Lights section.

Editing Tutorial Lights

note

In the JSON response for the FetchDevice endpoint, below, hex values are converted to integer arrays, e.g., 0A 00 is [10, 0].

Let's now try working with this Bluetooth LE device using the nRF Cloud REST API.

Steps Using the REST API#

Set Environment Variables#

These steps also assume you are using cURL to make the REST API calls, but there are other recommended options. Here we'll set some environment variables to make it easier to use cURL.

export API_KEY=YOUR_API_KEY# This is the device id from the screenshots. Substitute your own device id.export DEVICE_ID=BB254ECF-106F-58E2-100C-C171EFF98315

Fetching Your Bluetooth LE Device Data#

You can now view the state of your Bluetooth LE device by calling the FetchDevice endpoint:

curl https://api.nrfcloud.com/v1/devices/$DEVICE_ID -H "Authorization:Bearer $API_KEY"

You should see something like this:

{  "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 rather large. If you want a smaller response, read the Transforming JSON Responses guide.

Note the value field for characteristic 086022228277EF8E1523785788778193. This indicates that LEDs 1 and 4 are on. This same value can be seen in Tutorial Lights section of the Tutorial card.

Toggling LED Lights#

To toggle LED lights, simply use the UpdateCharacteristicValue endpoint, sending a new characteristic value in the request body as an array. For example, to turn on LED3 and LED4, send [12,0]:

export CHARACTERISTIC_ID=086022228277EF8E1523785788778193curl --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]'

Refresh the Stored State of the Bluetooth LE Device#

You can also cause the stored state of a connected Bluetooth LE peripheral to be refreshed in its entirety by issuing a discover request:

# This is the gateway id from the screenshots.export GATEWAY_ID=sgw-c7a1f715-i-660bc947581c7b09curl --request POST \  --url https://api.nrfcloud.com/v1/devices/$GATEWAY_ID/discover/$DEVICE_ID \  --header 'Authorization: Bearer $API_KEY'

This will make the gateway to which the Bluetooth LE device is connected re-discover all of its Bluetooth services. (This can take a few seconds.) Once this is finished you can fetch the updated state.