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
info

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

info

Possible values for action:

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

Note: step_up, step_down and dim_up, dim_down actions are used for driving cover and dimming lights by keep button pressed or rotate scroller. Currently supported on BLU Remote Control events rotate_left and rotate_right. Since version 1.0.23 BLU devices with 4 buttons like Wall EU Wall US supports actions on hold_press event.

BTHomeControl.StartLearning​

Starts process of adding mapping. Requires one of the parameters input_id or component_key. If Bluetooth on Shelly WiFi device is disabled will be enabled. When mapping is added successfully, Bluetooth will stay enabled, otherwise will be disabled

Request​

Parameters:

PropertyTypeDescription

input_id

number

Id of the Input component

component_key

string

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

Response​

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

BTHomeControl.StopLearning​

Stops process of learning.

Request​

The method takes no parameters.

Response​

The result from calling this method is null on success

BTHomeControl.SetConfig​

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

BTHomeControl.GetConfig​

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

Find the BTHomeControl.GetConfig response properties in config section

BTHomeControl.GetStatus​

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

Find more about the status response properties in status section

BTHomeControl.Create​

Creates BTHomeControl component with given output key and maps Shelly BLU devices inputs to outputs of Shelly WiFi device.

Request​

Parameters:

PropertyTypeDescription

output

string

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

inputs

array of objects

See - BTHomeControl.List inputs attribute. Required

Response​

The result from calling this method is a JSON object, with an id on success, otherwise it will return an error.

BTHomeControl.Update​

Updates BTHomeControl with given id with output key and maps Shelly BLU devices inputs to outputs of Shelly WiFi device.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance. Required

output

string

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

inputs

array of objects

See - BTHomeControl.List inputs attribute. Required

Response​

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

BTHomeControl.DeleteAll​

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

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

Response​

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

BTHomeControl.Enumerate​

Shows which outputs could be controlled with BTHomeControl. When there are no BTHomeControl components result will be null

Request​

The method takes no parameters.

Response​

PropertyTypeDescription

<type>:<cid>

string

Key is component key in the format <type>:<cid>. Value is BTHomeControl component id.

Configuration​

The configuration of the BTHomeControl component contains information about how cover is controlled by BLU Remote. To Get/Set the configuration of the BTHomeControl component its id must be specified.

Parameters:

PropertyTypeDescription

id

number

Id of the component instance

blu_remote_cover_mode

number

Cover control mode by BLU Remote. Applicable only when BTHomeControl has output_key of type Cover


0 - Cover moves until scroll wheel of remote is rotated.


1 Move based on steps received by rotating scroll wheel 24steps = 3 sec movement.

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 BTHomeControl component its id must be specified.

Parameters:

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
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
9Event received from wrong device
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.SetConfig example​

http://192.168.33.1/rpc/BTHomeControl.SetConfig?id=200&config={"blu_remote_cover_mode":0}

Response

{
  "restart_required": false
}

BTHomeControl.GetConfig example​

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

Response

{
  "id": 200,
  "blu_remote_cover_mode": "0"
}

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.Create example​

http://192.168.33.1/rpc/BTHomeControl.Create?output="switch:0"&inputs=[{"bthomedevice:200":{"58:0":{"single_push":{"action":"on"}},"58:1":{"single_push":{"action":"off"}}}}]

Response

{
  "id": 200
}

BTHomeControl.Update example​

http://192.168.33.1/rpc/BTHomeControl.Update?id=200&output="switch:1"&inputs=[{"bthomedevice:200":{"58:0":{"single_push":{"action":"off"}}}}]

Response

null

BTHomeControl.DeleteAll example​

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

Response

null

BTHomeControl.Enumerate example​

http://192.168.33.1/rpc/BTHomeControl.Enumerate

Response

{
  "light:0": 200,
  "light:1": 201,
  "light:2": 202
}