How to add Shelly devices to Home Assistant

Home Assistant ships with a Shelly integration, so a Shelly relay, dimmer or plug goes in without installing anything. The integration talks to each device directly on your network, with no Shelly cloud in between, and state changes arrive the moment they happen. It supports every generation from Gen1 to Gen4. Gen1 devices and battery-powered ones each need one extra setting, covered below.

Before you start

• The Shelly is on your Wi-Fi. Home Assistant doesn't do this part. Use the Shelly app, as in our guide to adding a device to the Shelly app, or the device's own web page.
• It's on the same network as Home Assistant. Discovery doesn't cross from one network or VLAN to another.
• Its firmware is up to date. Older firmware can show fewer entities than it should.
• It has a name. Set a device name, and a channel name for each output, on the device first. Home Assistant builds its device and entity names from them, so a device named Kitchen downlights arrives as Kitchen downlights rather than its model and ID.

Add your Shelly to Home Assistant

Reserving each Shelly's IP address in your router is worth the minute it takes. If you use a Shelly as a Range Extender, that Shelly needs a fixed or reserved address for the devices behind it to work.

What you get once it's added

A relay arrives as a switch. If it runs a light, open the device's web page, go to Settings, select the output under Component settings, then Consumption type. Type light and select Save, and it arrives in Home Assistant as a light instead. On Gen1 the setting is called Appliance type. Power, energy and voltage readings come through as sensors on models that measure them, and they feed Home Assistant's energy dashboard.

How a wall switch wired to the input shows up depends on its input mode. On Plus and newer, Switch mode gives you a sensor that's on or off with the switch. Button mode gives you an event entity, and each press, double press or long press triggers automations through the shelly.click event. On Gen1, the Button type setting does the same job, and Momentary or Detached switch gives you the events. Our guide to Shelly switch modes explains which mode suits which switch.

Some entities are off by default. On Plus and newer they're Wi-Fi signal strength, uptime, the device's temperature, and a switch for each script on the device. Turn on the ones you want in the device's entity list. Virtual components you create on the device come through too, as switches, buttons, numbers, text, dropdowns or read-only sensors.

Firmware updates appear in Home Assistant as update entities, so you can update your mains-powered Shellys from one place. Battery-powered devices only show that an update is waiting.

Gen1 devices need CoIoT

Plus, Pro, Gen3 and Gen4 devices need nothing set on the device. Gen1 devices, such as the original Shelly 1, Shelly 2.5 and Dimmer 2, report their state over a protocol called CoIoT, and until it's on their entities don't update by themselves. Shelly's generations explains how to tell which you have.

The CoIoT peer is required on battery-powered Gen1 devices, even when they're on USB power. If Home Assistant runs somewhere other than Home Assistant OS, UDP port 5683 also needs to be open to it.

Battery-powered devices

Wake a battery-powered Shelly by pressing its button just before you add it, or Home Assistant can't reach it. Discovery often misses them, so adding one by its IP address while it's awake is usually quicker.

Plus and newer battery-powered devices send their readings to Home Assistant over a connection they open themselves, and Home Assistant normally sets that up when you add them. If readings never arrive, or the device was set up with a different Home Assistant before, tell it where Home Assistant is by hand. In the device's web page, go to Settings and, under Connectivity settings, select Outbound websocket. Tick Enable, enter this as the Server with your own Home Assistant address and port, and select Save. If your Home Assistant runs on HTTPS, start it with wss:// instead.

Shelly BLU sensors join through BTHome

Shelly BLU sensors, such as the BLU H&T, BLU Door/Window and BLU Motion, run on Bluetooth rather than Wi-Fi, and the Shelly integration doesn't support them. Add them through Home Assistant's BTHome integration instead. The BLU TRV is the exception: the Shelly integration supports it through a Shelly BLU Gateway Gen3, or another Shelly with built-in BLU TRV support.

BTHome needs something to hear the sensors. That can be Bluetooth on the Home Assistant machine, but a Shelly already on your network does the job too. Any Gen2 or newer Shelly that isn't battery powered can act as a Bluetooth proxy. Turn it on in the Shelly integration's options for that device and leave the scanner mode on Auto, which finds sensors quickly and saves the sensors' batteries. A relay in a room is usually closer to a sensor than the Home Assistant box is.

Firmware 2.0 and HTTPS

Firmware 2.0 added Enhanced Security to Gen2 and newer devices, which lets a device use HTTPS when it has a certificate. Home Assistant detects HTTPS and uses it by itself. A device shipped with firmware 2.0 or later has Shelly's own certificate already. One updated to 2.0 from older firmware stays on plain HTTP until you turn on Enhanced Security and upload your own certificate. So two of the same model can connect differently. Either way, leave Verify SSL off unless the certificate is one your Home Assistant trusts.

Do you need MQTT?

Probably not. The Shelly integration finds devices on its own and covers the controls and readings above. MQTT suits a home that already runs a broker, usually for Zigbee2MQTT, and wants every device on it. Ignore older guides that tell you to install ShellyForHASS. That custom component has been discontinued, and its features were folded into the Shelly integration.

If it doesn't show up

Most of the time it's the network, a device in Zigbee mode, or a password. Our guide to a Shelly not showing up in Home Assistant works through each one.