Skip to main content
Version: 1.0

BTHome Components

caution

Available as preview since 1.3.0-beta1. The API is subject to change.

note

Available only for Gen3 and Gen2 Pro* devices.

BTHome components are a subset of dynamic components for managing Bluetooth devices that emit data in BTHome format.

Both Bluetooth and the observer are required to be enabled. If either of them is disabled, an error will be displayed in the component's status.

The management is accomplished through RPC methods within the BTHome namespace:

Available BTHome components:

Methods​

Request​

BTHome.GetConfig​

Does not own configuration at the moment.

BTHome.SetConfig​

Does not own configuration at the moment.

BTHome.GetStatus​

Find more about the status response properties in status section

BTHome.AddDevice​

Properties:

PropertyTypeDescription

config

object

Configuration to be used for the new component. Find the config properties in the config section

id

number

Id for the new component. Accepted range: [200..299]. Optional. If omitted, the first free ID will be used. If the desired ID is not available, an error will be returned.

Response​

The result from calling this method is a JSON object, with the newly generated component key upon success, otherwise it will return an error.

Received attributes:

PropertyTypeDescription

key

string

Key of the newly created component. (in format <type>:<cid>, for example bthomedevice:200)

BTHome.DeleteDevice​

Request​

Properties:

PropertyTypeDescription

id

number

The id of existing BTHomeDevice component Required

Response​

The result from calling this method is null on success, otherwise it will return an error.

BTHome.AddSensor​

Request​

Properties:

PropertyTypeDescription

config

object

Configuration to be used for the new component. Find the config properties in the config section

id

number

Id for the new component. Accepted range: [200..299]. Optional. If omitted, the first free ID will be used. If the desired ID is not available, an error will be returned.

Response​

The result from calling this method is a JSON object, with the newly generated component key upon success, otherwise it will return an error.

Received attributes:

PropertyTypeDescription

key

string

Key of the newly created component. (in format <type>:<cid>, for example bthomesensor:200)

BTHome.DeleteSensor​

Request​

Properties:

PropertyTypeDescription

id

number

The id of existing BTHomeSensor component Required

Response​

The result from calling this method is null on success, otherwise it will return an error.

BTHome.StartDeviceDiscovery​

Request​

Starts active scan for discovery of BTHome devices

Properties:

PropertyTypeDescription

duration

number

duration for the scan in seconds, default value is 30s

info

During the scanning process, device_discovered events are emitted, providing information about the discovered device, see example at device_discovered section. Upon completion of the scanning process, a discovery_done event is dispatched, see example at discovery_done.

Response​

The result from calling this method is null on success, otherwise it will return an error.

BTHome.GetObjectInfos​

Request​

Retrieve info for BTHome objects This method support the same paging mechanism as Shelly.GetComponents method.

Properties:

PropertyTypeDescription

offset

number

Index of the component from which to start generating the result Optional

Response​

The result from calling this method is null on success, otherwise it will return an error.

Status​

The BTHome component status provides details regarding the availability of a scanning process and errors.

Properties:

PropertyTypeDescription

discovery

object

Available only when scan process is in progress

PropertyTypeDescription

started_at

number

The initiation of the scanning process in UNIX timestamp

duration

number

Duration of the scan process

errors

array of type string

Component error conditions. May contain observer_disabled or bluetooth_disabled.

Examples​

BTHome.GetConfig example​

http://192.168.33.1/rpc/BTHome.GetConfig

Response

{}

BTHome.SetConfig example​

http://192.168.33.1/rpc/BTHome.SetConfig

Response

null

BTHome.GetStatus example​

http://192.168.33.1/rpc/BTHome.GetStatus

Response

{
  "errors": [
    "observer_disabled"
  ]
}

BTHome.AddDevice example​

http://192.168.33.1/rpc/BTHome.AddDevice?config={"addr":"3c:2e:f5:71:d5:2a"}

Response

{
  "added": "bthomedevice:201"
}

BTHome.DeleteDevice example​

http://192.168.33.1/rpc/BTHome.DeleteDevice?id=200

Response

null

BTHome.AddSensor example​

http://192.168.33.1/rpc/BTHome.AddSensor?config={"addr":"3c:2e:f5:71:d5:2a","obj_id":2,"obj_idx":3}

Response

{
  "added": "bthomesensor:200"
}

BTHome.DeleteSensor example​

http://192.168.33.1/rpc/BTHome.DeleteSensor?id=200

Response

null

BTHome.StartDeviceDiscovery example​

http://192.168.33.1/rpc/BTHome.StartDeviceDiscovery?duration=25

Response

null

BTHome.GetObjectInfos example​

http://192.168.33.1/rpc/BTHome.GetObjectInfos?obj_ids=[2,3,4]

Response

{
  "objects": [
    {
      "obj_id": 2,
      "obj_name": "temperature",
      "type": "sensor",
      "unit": "° C"
    },
    {
      "obj_id": 3,
      "obj_name": "humidity",
      "type": "sensor",
      "unit": "%"
    },
    {
      "obj_id": 4,
      "obj_name": "pressure",
      "type": "sensor",
      "unit": "hPa"
    }
  ],
  "offset": 0,
  "count": 3,
  "total": 3
}

Events​

device_discovered example​

{
  "component": "bthome",
  "event": "device_discovered",
  "device": {
    "addr": "3c:2e:f5:71:d5:2a",
    "local_name": "SBBT-002C",
    "rssi": -59,
    "encrypted": false,
    "shelly_mfdata": {
      "flags": 25,
      "model_id": 1,
      "mac": "3c:2e:f5:71:d5:2a"
    }
  },
  "ts": 1706593991.91
}

discovery_done example​

{
  "component": "bthome",
  "event": "discovery_done",
  "device_count": 1,
  "ts": 1706593991.91
}