Shelly Integration Setup

Shelly Wi-Fi devices connect to Home Assistant through the built-in Shelly integration. It talks to each device on the local network, so no Shelly cloud account and no MQTT broker are needed. Once a device is on Wi-Fi, Home Assistant usually discovers it on its own.

Before You Start

1. Reserve an address for each Shelly in the router’s DHCP settings (MAC address to fixed IP). Do not set a static IP on the device itself unless that address is outside the DHCP pool.
2. Put the Shelly devices on the same network and subnet as Home Assistant. Discovery relies on mDNS, which does not cross VLANs unless the network has an mDNS relay.
3. Keep the device firmware up to date. Home Assistant offers firmware updates for mains-powered devices once they are added.

Step 1: Connect the Device to Wi-Fi

Use either method:

• Shelly Smart Control app: the app finds the new device over Bluetooth and sends it the Wi-Fi credentials.
• The device’s own access point: a new device opens an open Wi-Fi network named after its model and MAC address, such as ShellyPlus2PM-A8032AB636EC.
  1. Join that network and open http://192.168.33.1.
  2. Go to Settings > Wi-Fi, choose the home network, and enter its password.

If Home Assistant already lists the new device under Discovered with Provision Wi-Fi via Bluetooth, it can send the Wi-Fi credentials itself: select the network, and Home Assistant adds the device once it joins.

The access point turns itself off after 15 minutes, or after 3 minutes on battery devices. How to open it again depends on the model: on the 1 Mini Gen4, for example, hold the button for 5 seconds (holding it for 10 seconds factory resets the device). Check the device’s manual for other models.

Once the device is on Wi-Fi, turn its access point off in Settings > Access Point. Home Assistant raises a repair for any Shelly that still has an open access point. If the home runs fully local, you can also turn off Settings > Cloud.

Step 2: Add the Device to Home Assistant

1. Go to Settings > Devices & Services.
2. The device appears under Discovered as Shelly. Select it and confirm.
3. If the device has a password set (Settings > Device settings > Authentication), enter it. Gen2 and later devices only ask for the password.

If the device is not discovered, select Add Integration, search for Shelly, and enter its IP address.

Each Shelly is its own integration entry. A device with several channels, such as a Pro 4PM, shows each channel as a sub-device under that entry.

Battery-Powered Devices

Battery devices, such as the H&T Gen3 and the Wi-Fi Flood sensor, sleep most of the time.

1. Press the device button to wake it before adding it. A device without a password is added the next time it wakes; a password-protected device must be awake while you confirm.
2. Home Assistant configures the device’s Outbound WebSocket so that it reports each time it wakes up. You only set it by hand if Home Assistant cannot work out its own address, or if the device was used with another Home Assistant before: in the device’s web page, go to Settings > Connectivity > Outbound WebSocket, enable it, and enter ws://<home-assistant-address>:<port>/api/shelly/ws, using the address and port of the Home Assistant instance. Use wss:// if Home Assistant is served over HTTPS.

Home Assistant shows when a battery device has new firmware but cannot install it. Update battery devices from the Shelly app or their web page.

Shelly BLU Devices

Shelly BLU buttons and sensors (BLU Button, BLU Door/Window, BLU Motion, BLU H&T, and others) are Bluetooth devices. They do not use the Shelly integration: Home Assistant picks them up through the BTHome integration as soon as it receives their Bluetooth broadcasts.

• Range: any mains-powered Gen2 or later Shelly can relay Bluetooth to Home Assistant. Open that device’s Shelly integration entry, select Configure, and set Bluetooth scanner mode to Auto. A Shelly running Zigbee firmware cannot do this.
• Encryption: if a BLU device is encrypted in the Shelly app, BTHome asks for its 32-character encryption key when you add it.
• BLU TRV: the radiator valve is the exception. It pairs with a BLU Gateway Gen3, or with another Shelly that has built-in BLU TRV support, and Home Assistant controls it through that device’s Shelly integration entry. Reboot the valve once it is mounted, so it calibrates.

Gen4 Devices: Wi-Fi, Matter, or Zigbee

Gen4 devices ship with Wi-Fi and Matter enabled, and the Shelly integration works with that firmware. They can switch to Zigbee firmware instead, either from Settings > Firmware > Alternative Firmware or by pressing the device button 5 times. A device runs one or the other, not both.

Keep Gen4 devices on Wi-Fi with the Shelly integration unless the home is built around Zigbee. On Zigbee firmware, pair them as described in Pairing Zigbee Devices .

Gen1 Devices

Older Gen1 devices are still supported but use a different protocol, CoIoT. In the device’s web page, go to Internet & Security > Advanced - Developer Settings, enable CoIoT, set the CoIoT peer to <home-assistant-ip>:5683, and restart the device. Battery-powered Gen1 devices need this to report at all.

Troubleshooting

1. The device is not discovered. Add it by IP address. If Home Assistant and the device are on different VLANs, set up an mDNS relay or keep them on the same network.
2. A Gen1 device reports a push update failure. Check the CoIoT peer setting, and allow UDP port 5683 between the device and Home Assistant.
3. A battery device shows no entities. Press its button to wake it. It reports on the next wake.
4. Home Assistant reports a MAC address mismatch. Reboot the device and try again.
5. A BLU device does not appear. Check that a Shelly or another Bluetooth adapter near it is relaying Bluetooth to Home Assistant, and that its encryption key is correct.