Shelly in Home Assistant

Why it works well

Home Assistant ships with a Shelly integration built in. Nothing to install, no custom component, and no Shelly account.

It is local. Home Assistant talks to the device directly over your network. No cloud in the path, response in milliseconds, and everything keeps working when the internet does not — which is the same argument the rest of this site makes about Shelly generally.

It is auto-discovered. A device on the network usually appears in Home Assistant within a few minutes, under Settings → Devices & services as a discovered integration.

Adding a device

The device must already be on your Wi-Fi — see add a device. It does not need to be claimed to a Shelly account.

If it was discovered: go to Settings → Devices & services, find it under Discovered, and press Configure.

If it was not: Settings → Devices & services → Add Integration → Shelly, then enter the device’s IP address or hostname. Find the address in your router or in the Shelly app.

Then assign it to an area and name the entities. Name them after what they control and where — “Kitchen counter light”, not “shelly1pm_a8032a”. Consistent naming is what makes automations readable a year later, and it is far more work to fix afterwards than to do now.

How each generation talks

The integration handles both automatically, but knowing which is which explains most of the problems people hit.

Gen1 — Shelly 1, 2.5, Plug, Dimmer 1 — uses CoIoT to push state, and REST for control. CoIoT has to be enabled in the device’s web interface and pointed at your Home Assistant server’s address.

Gen2 and newer — Plus, Pro, Gen3, Gen4 — use WebSocket and JSON-RPC. Nothing to configure; state arrives by itself.

If a device shows the right entities but the values never change, check CoIoT before anything else.

BLU sensors are different

This catches almost everyone, and it is not a fault.

Shelly BLU devices are not supported by the Shelly integration. BLU H&T, BLU Door/Window, BLU Motion and BLU Button speak Bluetooth, not Wi-Fi, so they never appear as Shelly devices in Home Assistant.

Use the BTHome integration instead. It reads the Bluetooth advertisements directly, and it needs something to receive them — a Bluetooth adapter on the Home Assistant machine, or a Shelly device acting as a BLU gateway. See BLE devices.

The exception is BLU TRV, which the Shelly integration does support — through a Shelly BLU Gateway Gen3.

The firmware 2.0.0 change

Firmware 2.0.0 introduced Enhanced Security on Gen2 and newer devices, required for compliance with the Radio Equipment Directive. When enabled, the device enforces HTTPS.

The consequence depends on where the firmware came from, and it is worth reading twice:

Devices shipped from the factory with 2.0.0 or newer already have certificates issued by Shelly, and HTTPS works out of the box.
Devices updated to 2.0.0 or newer have no factory certificate and serve plain HTTP by default. To use Enhanced Security on those, you must create and upload your own certificate.

So two identical devices can behave differently depending on when they were made. If one connects over HTTPS and another does not, this is why — not a network fault.

Leave Verify SSL/TLS certificate switched off unless the device uses a certificate your Home Assistant instance actually trusts.

When to use MQTT instead

The native integration is the right answer for almost everyone. It auto-discovers, needs no configuration, and covers every feature.

MQTT earns its place in one situation: an installation already running a broker for something else — Zigbee2MQTT is the usual reason — where keeping every device on one message bus is worth the extra setup.

It is not faster and not more capable. Enable MQTT in the device’s web interface if you need it; otherwise do not.

Tips & best practices

Update firmware before adding. The integration expects current firmware to expose the right APIs, and an old device can present fewer entities than it should.
Enable CoIoT on every Gen1 device, pointed at the Home Assistant server. It is the fix for most “the state never updates” reports.
Keep devices on the same subnet as Home Assistant, or discovery will not find them and manual entry becomes the only route.
Name entities on the day you add them. Twenty devices named after their model is a setup nobody wants to automate.
Thirty or more Shelly devices on one router is where Wi-Fi starts to matter more than Home Assistant does. See Wi-Fi and router setup.