BTHomeDevice

The BTHomeDevice component stands for an individual physical device identified by its MAC address. It uses BTHomeDevice as RPC namespace and has the following methods:

• BTHomeDevice.SetConfig to update the component's configuration
• BTHomeDevice.GetConfig to obtain the component's configuration
• BTHomeDevice.GetStatus to obtain the component's status
• BTHomeDevice.GetKnownObjects get a list of the known object ids from the device's packets

Methods

BTHomeDevice.SetConfig

Property	Type	Description
id	number	Id of the component instance
config	object	Configuration that the method takes

Find more about the config properties in config section

BTHomeDevice.GetConfig

Properties:

Property	Type	Description
id	number	Id of the component instance

Find the BTHomeDevice.GetConfig response properties in config section

BTHomeDevice.GetStatus

Properties:

Property	Type	Description
id	number	Id of the component instance

Find more about the status response properties in status section

BTHomeDevice.GetKnownObjects

Request

Parameters:

Property	Type	Description
id	number	Id of the component instance. Required

info

The new_objects event is triggered upon the discovery of a new sensor. See example event at new_objects example.

Response

Attributes in the result:

Property	Type	Description
id	number	Id of the component instance
objects	array of objects	Property Type Description obj_id number BTHome object id in decimal idx number BTHome object index component string or null Component key if the sensor is managed, otherwise null

Configuration

The configuration of the BTHomeDevice component contains information about its MAC address, display name, id, and meta data. To Get/Set the configuration of the BTHomeDevice component its id must be specified.

Properties:

Property	Type	Description
id	number	Id of the component instance
name	string or null	Name of the component instance
addr	string	MAC address of the physical device
key	string or null	AES encryption key as hexadecimal string for encrypted devices
meta	object	Object for storing meta data	ui	object	Properties of how the component will be rendered in the UI	icon	string or null	Allows setting custom icon for the component's card by providing an external hosted image via link.

Status

The status of the BTHomeDevice component contains information about its id, signal strength received with the latest packet, battery percentage of the device, the last packet id and a timestamp for when the packet is received. To obtain the status of the BTHomeDevice component its id must be specified.

Properties:

Property	Type	Description
id	number	Id of the component instance
rssi	number or null	Strength of the signal in dBms from the latest packet
battery	number or null	Device's battery percentage
packet_id	number or null	Id of the latest received packet
last_update_ts	number	Unix timestamp of the latest received packet
errors	array of type string	Component error conditions. May contain key_missing_or_bad, decrypt_failed, parse_failed and unencrypted_data.

Webhook Events

Available events from BTHomeDevice component that can trigger webhooks:

• bthomedevice.single_push - produced on single push event, supported for BTHomeDevice of type button.
• bthomedevice.double_push - produced on double push event, supported for BTHomeDevice of type button.
• bthomedevice.triple_push - produced on triple push event, supported for BTHomeDevice of type button.
• bthomedevice.long_push - produced on long push event, supported for BTHomeDevice of type button.
• bthomedevice.long_double_push - produced on long double push event, supported for BTHomeDevice of type button.
• bthomedevice.long_triple_push - produced on long triple push event, supported for BTHomeDevice of type button.
• bthomedevice.rotate_left - produced on rotate left event, supported for BTHomeDevice of type dimmer.
• bthomedevice.rotate_right - produced on rotate right event, supported for BTHomeDevice of type dimmer.

All events support attribute idx which is index of object type from which event is triggered.

Notifications

This section describes notifications for events specific to the BTHomeDevice component. For general information please see this page.

Instances of the BTHomeDevice component can send notifications for the following events:

• single_push
• double_push
• triple_push
• long_push
• long_double_push
• long_triple_push
• rotate_left
• rotate_right

Example for notification for event:

{"component":"bthomedevice:202","id":202,"event":"single_push", "idx":1,"ts":1731931521.19}

Where idx is object type index from which event is triggered.

Examples

BTHomeDevice.SetConfig example

BTHomeDevice.SetConfig HTTP GET Request

http://192.168.33.1/rpc/BTHomeDevice.SetConfig?id=200&config={"name":"Bathroom temperature"}

BTHomeDevice.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"BTHomeDevice.SetConfig","params":{"id":200,"config":{"name":"Bathroom temperature"}}}' http://${SHELLY}/rpc

BTHomeDevice.SetConfig Mos Request

mos --port ${PORT} call BTHomeDevice.SetConfig '{"id":200,"config":{"name":"Bathroom temperature"}}'

Response

BTHomeDevice.SetConfig HTTP GET Response

{
  "restart_required": false
}

BTHomeDevice.SetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": {
    "restart_required": false
  }
}

BTHomeDevice.SetConfig Mos Response

{
  "restart_required": false
}

BTHomeDevice.GetConfig example

BTHomeDevice.GetConfig HTTP GET Request

http://192.168.33.1/rpc/BTHomeDevice.GetConfig?id=200

BTHomeDevice.GetConfig Curl Request

curl -X POST -d '{"id":1,"method":"BTHomeDevice.GetConfig","params":{"id":200}}' http://${SHELLY}/rpc

BTHomeDevice.GetConfig Mos Request

mos --port ${PORT} call BTHomeDevice.GetConfig '{"id":200}'

Response

BTHomeDevice.GetConfig HTTP GET Response

{
  "id": 200,
  "addr": "3c:2e:f5:71:d5:2a",
  "name": "Bathroom temperature",
  "key": null,
  "meta": null
}

BTHomeDevice.GetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": {
    "id": 200,
    "addr": "3c:2e:f5:71:d5:2a",
    "name": "Bathroom temperature",
    "key": null,
    "meta": null
  }
}

BTHomeDevice.GetConfig Mos Response

{
  "id": 200,
  "addr": "3c:2e:f5:71:d5:2a",
  "name": "Bathroom temperature",
  "key": null,
  "meta": null
}

BTHomeDevice.GetStatus example

BTHomeDevice.GetStatus HTTP GET Request

http://192.168.33.1/rpc/BTHomeDevice.GetStatus?id=200

BTHomeDevice.GetStatus Curl Request

curl -X POST -d '{"id":1,"method":"BTHomeDevice.GetStatus","params":{"id":200}}' http://${SHELLY}/rpc

BTHomeDevice.GetStatus Mos Request

mos --port ${PORT} call BTHomeDevice.GetStatus '{"id":200}'

Response

BTHomeDevice.GetStatus HTTP GET Response

{
  "id": 200,
  "rssi": -55,
  "battery": 100,
  "packet_id": 1,
  "last_updated_ts": 1706593991.91
}

BTHomeDevice.GetStatus Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": {
    "id": 200,
    "rssi": -55,
    "battery": 100,
    "packet_id": 1,
    "last_updated_ts": 1706593991.91
  }
}

BTHomeDevice.GetStatus Mos Response

{
  "id": 200,
  "rssi": -55,
  "battery": 100,
  "packet_id": 1,
  "last_updated_ts": 1706593991.91
}

BTHomeDevice.GetKnownObjects example

BTHomeDevice.GetKnownObjects HTTP GET Request

http://192.168.33.1/rpc/BTHomeDevice.GetKnownObjects?id=200

BTHomeDevice.GetKnownObjects Curl Request

curl -X POST -d '{"id":1,"method":"BTHomeDevice.GetKnownObjects","params":{"id":200}}' http://${SHELLY}/rpc

BTHomeDevice.GetKnownObjects Mos Request

mos --port ${PORT} call BTHomeDevice.GetKnownObjects '{"id":200}'

Response

BTHomeDevice.GetKnownObjects HTTP GET Response

{
  "id": 200,
  "objects": [
    {
      "obj_id": 5,
      "idx": 3,
      "component": "bthomesensor:200"
    }
  ]
}

BTHomeDevice.GetKnownObjects Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": {
    "id": 200,
    "objects": [
      {
        "obj_id": 5,
        "idx": 3,
        "component": "bthomesensor:200"
      }
    ]
  }
}

BTHomeDevice.GetKnownObjects Mos Response

{
  "id": 200,
  "objects": [
    {
      "obj_id": 5,
      "idx": 3,
      "component": "bthomesensor:200"
    }
  ]
}

Events

new_objects example

{
  "component": "bthomedevice:200",
  "id": 200,
  "event": "new_objects",
  "ts": 1706593991.91
}