Skip to main content
Version: 1.0

BTHomeControl

The BTHomeControl component maintains mapping between Shelly BLU devices and outputs of Shelly WiFi device.

BTHomeControl.StartLearning with input_id parameter starts process of adding BLU device and maps its buttons to outputs like Switch, Cover or Light components. Other way of starting process is triggering 4 times desired Input which corresponds to Output.

During process of creating mapping Shelly WiFi device has following indication of outputs:

  • 1 blink/movement - Learn mode is enabled.
  • 2 times blink/movement - a BLU device has been added or it already exists and it is seen that it is in pair mode. Now it is possible to add or remove mapping by pressing button on BLU device.
  • 3 times blink/movement - mapping has been successfully added.

There might be device specific sequence of pressing Input or indicating.

BTHomeControl component uses BTHomeControl as RPC namespace and has the following methods:

Devices which supports BTHomecontrol:

With Switch component

With Cover component

With Light component

Methods​

BTHomeControl.List​

This method returns a list with mappings between BLU device buttons and device output.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

Response​

Attributes in the result:

PropertyTypeDescription

id

number

Id of the component instance

output

string

Output component key in the format <type> <cid> (for example, cover:0)

inputs

array of objects

Each entry is a object

PropertyTypeDescription

bthomedevice

string

BTHomeDevice component key in the format <type> <cid> (for example, bthomedevice:200). Contains one or more ObjectID:idx.

obj_id

string

Object ID in decimal and index of button - ObjectID:idx. Contains one or more events.

event

string

Blu device event which will be mapped

action

string

Action of Shelly WiFi device output.

offset

number

Index of the first BTHomeDevice component key in inputs array

total

number

Total number of BTHomeDevice component keys in inputs array

Possible values for event:

  • single_push
  • double_push
  • triple_push
  • rotate_left
  • rotate_right
  • hold_press

Note: for BLU Devices with channel support event will be single_push@2 for channel 2.

Possible values for action:

  • close, open, cycle, step_up, step_down For output of type Cover
  • on, off, toggle For output of type Switch
  • dim_up, dim_down, toggle For output of type Light

BTHomeControl.StartLearning​

Properties:

PropertyTypeDescription

input_id

number

Id of the Input component

Starts process of adding mapping. If Bluetooth on Shelly WiFi device is disabled will be enabled. When mapping is added successfully, Bluetooth will stay enabled, otherwise will be disabled

BTHomeControl.StopLearning​

Stops process of learning.

BTHomeControl.GetStatus​

Properties:

PropertyTypeDescription

id

number

Id of the component instance

Find more about the status response properties in status section

BTHomeControl.DeleteAll​

PropertyTypeDescription

id

number

Id of the component instance

When id is given BTHomeControl component with given id is removed. Without id all BTHomeControl components will be deleted.

Status​

The status of the BTHomeControl component contains information about learn progress when procedure of creating mapping between Shelly BLU devices and outputs of Shelly WiFi device has been started. To obtain the status of the BTHomeDevice component its id must be specified.

Properties:

PropertyTypeDescription

id

number

Id of the component instance

learning

object

Information about the learning progress, only presented when Learn procedure is started with BTHomeControl.StartLearning or by physical input, if applicable.

PropertyTypeDescription

stage

string

Current stage

err

string or null

Error object containig info about any issues

PropertyTypeDescription

code

number

Code of error

msg

string or null

Human readable message if applicable

ts

number

Unix timestamp (in UTC)

duration

number or null

Duration (Timeout) of current stage

info

learning.stage could be one of following: pairing, press, done, remove, and error.

  • pairing - when Shelly WiFi device is looking for BLU device
  • press - after Shelly WiFi device found and added BLU device and it is ready to accept user press on button of BLU device
  • done - when successfull mapping is created between Shelly WiFi device and BLU device
  • remove - when mapping is removed
  • error - when there is an error
info
learning.err.codelearning.err.msg
0General Error
1Internal Error
2Pairing timeout
3Press timeout
4Stopped by input
5Stopped by RPC
6Bluetooth is disabled
7BLU device is not button type
8No BLU devices found
any otherUnknown error

Examples​

BTHomeControl.List example​

http://192.168.33.1/rpc/BTHomeControl.List?id=200

Response

{
  "id": 200,
  "output": "switch:0",
  "inputs": [
    {
      "bthomedevice:200": {
        "58:0": {
          "single_push": {
            "action": "on"
          }
        },
        "58:1": {
          "single_push": {
            "action": "off"
          }
        }
      }
    },
    {
      "bthomedevice:201": {
        "58:0": {
          "single_push": {
            "action": "toggle"
          }
        }
      }
    }
  ],
  "offset": 0,
  "total": 2
}

BTHomeControl.StartLearning example​

http://192.168.33.1/rpc/BTHomeControl.StartLearning?input_id=2

Response

null

BTHomeControl.StopLearning example​

http://192.168.33.1/rpc/BTHomeControl.StopLearning

Response

null

BTHomeControl.GetStatus example​

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

Response

{
  "learning": {
    "stage": "pairing",
    "err": null,
    "ts": 1751280234.92,
    "duration": 60
  }
}

BTHomeControl.DeleteAll example​

http://192.168.33.1/rpc/BTHomeControl.DeleteAll?id=200

Response

null