BLE Example

The BLE Device Service example demonstrates how to onboard a BLE device.

This example uses a Texas Instruments CC2650 Sensor Tag.

Preconfiguration

Prior to starting the device service, update your local docker-compose.yml to include the following environment variables:

version: '3.7'

services:
  device-ble:
    environment:
      DEVICE_DISCOVERY_ENABLED: 'true'
      BLE_INTERFACE: hci0

DEVICE_DISCOVERY_ENABLED: 'true' is necessary for automatic device onboarding.

Start the BLE Device Service

To start the BLE Device Service, enter the following command:

edgexpert up device-ble

Device Onboarding

Once the BLE Device Service has been started, BLE devices can be onboarded to Edge Xpert automatically through discovery or manually by using either the Edge Xpert Manager UI or through Edge Xpert REST API commands. Instructions on how to use both methods are described below.

Automatic Device Onboarding with BLE Discovery

When enabled, discovery starts on initialization of the device service. To add a BLE device through BLE discovery, follow the steps below:

1. Ensure discovery is enabled with the following environment variables in the docker-compose.yml

   DEVICE_DISCOVERY_ENABLED: 'true'
   BLE_INTERFACE: hci0
   

   If this is not enabled, update your local docker-compose.yml by following the instructions in Using a Local Docker Compose and restart the device service.

2. Turn on the CC2650 device

3. Add the device profile using the below command:

   curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/ble/sensor-tag-cc2650.yaml"
   

4. Add a provision watcher to search for a matching device:

   curl --request POST 'http://localhost:59881/api/v2/provisionwatcher' \
   --header 'Content-Type: application/json' \
   --data-raw '[
      {
         "provisionwatcher":{
            "apiVersion":"v2",
            "name":"Provision-Watcher-BLE",
            "adminState":"UNLOCKED",
            "labels":[
               "ble"
            ],
            "identifiers":{
               "Alias":"^CC2650+(.*)$"
            },
            "serviceName":"device-ble",
            "profileName": "sensor-tag-cc2650",
            "protocolName":"ble",
            "deviceDescription":"ble device {{MAC}}"
         },
         "apiVersion":"v2"
      }
   ]'
   

   This will search for BLE devices that fit the above criteria. The ^CC2650+(.*)$ is a regular expression to filter the discovered devices.

All matching devices will be added to Edge Xpert.

Manual Device Onboarding with the Edge Xpert Manager UI

1. Ensure the Edge Xpert Manager UI is started, for example:

   edgexpert up xpert-manager
   

2. Open a browser and go to localhost:9090. The default username and password is admin

3. Using the device profile upload capability, upload the provided BLE example device profile at /usr/share/edgexpert/examples/device-services/ble/sensor-tag-cc2650.yaml

4. Onboard the BLE device using the device onboarding capability. The following values can be used to provision the example BLE device:

   Field	Example Value	Description	Required
   Name	sensor-tag	The unique name used to identify the device	Required
   Description	CC2650 sensor tag	Any additional information about the device	Optional
   Label	BLE	Any additional information about the device	Optional
   MAC Address	00:00:00:00:00:00	MAC address of the BLE device. Replace 00:00:00:00:00:00 with the MAC address for your own device.	Required
   Device Profile	sensor-tag-cc2650	The name of the device profile uploaded above	Required
   Device Service	device-ble	The name of the appropriate device service	Required

Device Onboarding with the Edge Xpert REST API

1. Upload the provided BLE example device profile:

   curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/ble/sensor-tag-cc2650.yaml"
   

2. Onboard the device using similar values as explained in the above table:

   curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
     -d '[ {
               "apiVersion": "v2",
                "device": {
                  "name" :"sensor-tag",
                  "description": "CC2650 sensor tag",
                  "labels":[
                     "ble"
                  ],
                  "serviceName": "device-ble",
                  "profileName": "sensor-tag-cc2650",
                  "protocolName":"ble",
                  "protocols":{
                     "BLE": {
                       "MAC": "00:00:00:00:00:00"
                     }
                  },
                  "adminState":"UNLOCKED",
                  "operatingState":"UP"
               }
           }
       ]'
   

   Note

   Replace "MAC": "00:00:00:00:00:00" with the MAC address for your own device.

Device Data Flow

Once the device is onboarded to Edge Xpert, data flow between the Device Service and the connected device can be verified in a number of ways.

The Edge Xpert Manager UI supports Read and Write functionality for each device. Readings can also be viewed and queried within the Edge Xpert Manager UI Data Center.

Alternatively, you can read and write data with cURL commands or through REST API applications, such as Postman.

Both the GET and PUT requests can be made to the following address:

http://localhost:59882/api/v2/device/name/{deviceName}/{commandName}

Using the example above, a GET request to this device service could be:

curl http://localhost:59882/api/v2/device/name/sensor-tag/HumidityData

For more information on this, see the Core Command Microservice. A list of available API commands can be found under Edge Xpert API.

Any data collected by the Device Service can then be processed like all other Edge Xpert sensor data. The data readings can be exported for data processing in a number of other applications and services. See the Supporting Services and Application Services documentation for more details.