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
}