BLE

The BLE Connector scans for Bluetooth Low Energy devices, reads data from their GATT characteristics, and forwards it to ThingsBoard as device attributes and telemetry. It can also write values to characteristics in response to shared attribute updates and RPC commands from ThingsBoard.

To enable this connector, add it to the connectors list in tb_gateway.json — see the General Configuration reference.

The BLE Connector requires system Bluetooth libraries and the bleak Python package.

sudo apt-get install -y libglib2.0-dev zlib1g-dev

sudo pip3 install bleak

sudo yum groupinstall -y "development tools"

sudo pip3 install bleak

The connector reads its settings from a JSON file. Below is a full example for a Xiaomi temperature and humidity sensor:

{
  "name": "BLE Connector",
  "passiveScanMode": true,
  "showMap": false,
  "scanner": {
    "timeout": 10000,
    "deviceName": "STH11"
  },
  "devices": [
    {
      "name": "Temperature and humidity sensor",
      "MACAddress": "4C:65:A8:DF:85:C0",
      "pollPeriod": 5000,
      "showMap": false,
      "timeout": 10000,
      "telemetry": [
        {
          "key": "temperature",
          "method": "notify",
          "characteristicUUID": "226CAA55-6476-4566-7562-66734470666D",
          "valueExpression": "[2]"
        },
        {
          "key": "humidity",
          "method": "notify",
          "characteristicUUID": "226CAA55-6476-4566-7562-66734470666D",
          "valueExpression": "[:]"
        }
      ],
      "attributes": [
        {
          "key": "name",
          "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB",
          "method": "read",
          "valueExpression": "[0:2]"
        }
      ],
      "attributeUpdates": [
        {
          "attributeOnThingsBoard": "sharedName",
          "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB"
        }
      ],
      "serverSideRpc": [
        {
          "methodRPC": "sharedName",
          "withResponse": true,
          "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB",
          "methodProcessing": "write"
        }
      ]
    }
  ]
}

Optional. When omitted, the connector discovers all available BLE devices in range. When set, only devices whose advertised name matches deviceName are reported.

"scanner": {
  "timeout": 10000,
  "deviceName": "NH11"
}

Finding a device’s MAC address:

If you do not know a device’s MAC address, use showMap to discover it. Two scenarios:

Scenario 1 — you don’t know the name or MAC address. Set showMap: true with no scanner. The gateway logs all visible devices:

{ "showMap": true }

Example gateway output:

24:71:89:cc:09:05 - NH11
54:bb:12:ff:09:01 - Unknown
23:cc:34:23:bb:56 - XYZ123

Scenario 2 — you know the name but not the MAC address. Set showMap: true and add scanner.deviceName to filter the output:

{
  "showMap": true,
  "scanner": {
    "timeout": 10000,
    "deviceName": "NH11"
  }
}

Example gateway output:

24:71:89:cc:09:05 - NH11

Once you have the MAC address, set showMap: false and add the device to devices.

An array of device configurations. Each entry represents one BLE peripheral.

Both sections use the same field structure. telemetry entries are forwarded to ThingsBoard as time-series data; attributes entries are forwarded as device attributes.

[
  {
    "key": "temperature",
    "method": "notify",
    "characteristicUUID": "226CAA55-6476-4566-7562-66734470666D",
    "valueExpression": "[2]"
  },
  {
    "key": "name",
    "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB",
    "method": "read",
    "valueExpression": "[0:2]"
  }
]

The raw payload from a BLE characteristic is a byte array. valueExpression is a Python slice pattern applied to that array to extract the value sent to ThingsBoard.

Example payload: device reports temperature and humidity as b'\x08\x22\x08\x00', which in integer form is [8, 34, 8, 0] (8 °C, 34 % RH).

Index positions in valueExpression follow standard Python slice rules:

• [n] — single element at position n
• [a:b] — elements from a (inclusive) to b (exclusive)
• [:] — all elements

When a ThingsBoard shared attribute changes, the gateway writes its value to the specified GATT characteristic.

{
  "attributeOnThingsBoard": "sharedName",
  "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB"
}

Maps ThingsBoard RPC commands to GATT read, write, or notify operations on the device.

{
  "methodRPC": "rpcMethod1",
  "withResponse": true,
  "characteristicUUID": "00002A00-0000-1000-8000-00805F9B34FB",
  "methodProcessing": "read"
}