BTHome components

What this is for

A BLU sensor and a Shelly relay, bound directly to each other. The sensor reports, the relay acts, and nothing else is involved — no Wi-Fi, no internet, no cloud account, and no script.

That is the whole appeal, and it matters most in two situations.

For a customer installation: the automation keeps working during an internet outage, a router reboot, or a broadband fault. A motion sensor that switches a light does not care that the internet is down.

For an installer: you can bind the devices on the bench before you drive out. A stand-alone solution, configured and tested, that needs no network at the customer’s address to function.

Despite living in the Scripting section, this needs no code at all. Scripts can read the same components, which is covered at the end — but the binding itself is done entirely in the web interface.

Requirements

• A Gen3 device on firmware 1.3 or newer, or a Pro device on firmware 1.4 or newer. Gen2 and Plus devices cannot do this
• Any Shelly BLU sensor — H&T, Door/Window, Motion, Button, TRV
• Both within Bluetooth range, roughly 10 metres indoors

On firmware older than 1.5.0 the Bluetooth observer had to be switched on manually. From 1.5.0 onwards it enables itself when you add a BTHome device.

Pairing the device

Everything happens in the host device’s web interface — the relay or dimmer that will act on the sensor.

1. Open the web interface. Either at the device’s IP address, or by joining its access point and opening http://192.168.33.1. See the web interface
2. Go to Components and press + next to BTHome devices
3. Press Start to scan, then pick the sensor from the list

Adding the sensors

Pairing the device is not the end. A BLU H&T reports temperature, humidity and battery, and each of those is a separate sensor you add individually.

Press Configure next to the paired device, then + beside each sensor you want. You can rename them here too, which is worth doing — Bathroom humidity beats Sensor 201.

If a sensor is missing from the list, wake the device by pressing its button and look again. A sleeping sensor has not told the host what it can report.

If the device is encrypted, enter its key in the same screen. Get it from the Shelly BLE Debug app. Without the key the host sees the device but cannot read anything from it — which looks exactly like a sensor that is not reporting.

Each sensor becomes a component with an id from 200 to 299. Note the ids if you intend to use them in a script.

Creating the action

The binding exists; now make it do something. Go to the Actions tab and create an action: when the sensor reports a value, the relay switches.

That is the whole automation. Motion detected, light on. Door opened, light on. Humidity above a threshold, fan on.

The host device does not have to be the light. It can act on a sensor and send an HTTP request to a different Shelly, which is how one relay becomes the brain for a group of them — see webhooks and HTTP requests.

Reading a sensor from a script

Where an action is not enough — several conditions, a timer, a calculation — a script on the host device can read the same components.

A BTHome sensor reports its value as a status change, identified by its component id:

Shelly.addStatusHandler(function (status) {
  if (status.component !== "bthomesensor:201") return;
  if (typeof status.delta.value === "undefined") return;

  print("Sensor 201 is now " + status.delta.value);
});

See how to add a script for installing it.

Tips & best practices

• Bind before you install. A stand-alone solution configured on the bench needs nothing at the customer’s address, and testing it there is far easier than in a ceiling.
• Update the BLU device first, using the Shelly BLE Debug app. Sensor support has changed across firmware versions.
• Raise the RSSI threshold when pairing near other devices. It is the only thing standing between you and the wrong sensor.
• The host does not have to be the gateway. A device can host BTHome components for a sensor that another device relays — though in practice the nearest mains device is usually both.
• This does not replace the app. A sensor bound this way still works in Shelly Smart Control and can still be read by Home Assistant. Binding adds a local path; it does not close the others.

Related guides