Shelly devices are some of the easiest local-first hardware to add to Home Assistant. They use the core Shelly integration, which finds them on your network. You don’t need a Shelly Cloud account or an MQTT broker. Here’s how to set one up and get the most from it.
Short answer
Connect the Shelly to your 2.4 GHz Wi-Fi using the Shelly app or its web page. Then, in Home Assistant, accept the discovered device, or add it by IP address under Settings > Devices & services.
Before you start
- Use 2.4 GHz Wi-Fi. Shelly setup works only on 2.4 GHz.
- Give each Shelly a DHCP reservation, so its IP address stays the same.
- Plan the wiring first. For mains-connected devices, read the safety section at the end before you touch any wires.
Connect the Shelly to Wi-Fi
Most Shelly devices create their own access point during setup, at 192.168.33.1. Use the Shelly app or that web page to join your Wi-Fi network. Once the device is online, it appears on your network.
Add it to Home Assistant
- Go to Settings > Devices & services. If Home Assistant discovers the Shelly, it appears under Discovered. Accept it.
- If it doesn’t appear, select Add integration, search for Shelly, and enter the device’s IP address.
- For Gen2 and newer devices with a password set, sign in with the username
adminand the password you chose.
Gen1 and Gen2+ work differently
- Gen1 devices use HTTP, plus CoIoT push messages over UDP port 5683. For battery-powered Gen1 devices, set the CoIoT peer to Home Assistant’s IP address and port 5683 so the device can send updates.
- Gen2 and newer (Plus, Pro, Gen3 and Gen4) use RPC over WebSocket. For battery-powered models, Home Assistant configures the device to connect when it wakes up.
Battery-powered Shellys report when they wake up, not on a polling schedule. Expect updates to arrive at those times.
Input modes and smart bulbs
Each input on a Shelly can run in one of four modes: momentary, toggle, edge or detached.
Detached mode separates the physical switch from the relay. That’s the mode to use with smart bulbs. The bulbs stay powered, and the wall switch sends a signal to Home Assistant instead of cutting power. If you use a normal toggle mode with smart bulbs, cutting the switch leaves the bulbs unreachable.
Power monitoring and the Energy dashboard
Models with power metering, often labeled PM, report power in watts and energy in kWh. Energy totals can feed the Energy dashboard, which needs the energy sensor requirements covered in adding and managing devices in Home Assistant. To split energy totals into daily or monthly figures, see the Home Assistant utility meter guide.
Relay ratings vary by model. The Shelly 1 Gen3, for example, is rated around 16 A. Check the spec sheet for your exact model before you connect a load.
Shelly 1 and 1 Plus relays are dry contact. The 1PM isn’t. That difference matters if you want to use a Shelly to trigger a garage door’s wall button. See what garage door opener works with Home Assistant.
Bluetooth and proxies
Shelly BLU devices join Home Assistant through BTHome. Gen2 and newer Shellys can act as Bluetooth proxies for Home Assistant, with passive or active scanning. Set the scanning option on the device to match what you need.
Newer models
Some Gen3 and Gen4 models add Matter support, and Gen4 models add Zigbee. Check the spec for the exact model before you plan around either feature.
Scripts, schedules and updates
Gen2 and newer devices can run scripts, written in mJS, and schedules on the device itself. These keep working even if Home Assistant is down.
Firmware updates appear as update entities in Home Assistant. On Gen1 devices, enabling MQTT disables the Shelly Cloud connection. Gen2 and newer devices can run both.
You don’t need Shelly Cloud or MQTT for Home Assistant to work with Shelly devices.
Safety
- Wire mains voltage (110 to 240 V) only with the breaker switched off. Use a licensed electrician where local rules require one.
- Don’t exceed the rated amps of the relay, and derate for motors and other inductive loads.
For the general model of integrations and devices, see adding and managing devices in Home Assistant.