Have Home Assistant at home? Shelly devices connect to it easily, and there are four ways to do it: the built-in Shelly integration, Matter, or Zigbee through ZHA or Zigbee2MQTT. This guide compares the options, explains how to connect with each one and helps you choose.
In short
For most homes, the built-in integration is the right choice. It runs locally on your home network, with no cloud, and gets every capability of the device: power metering, shutters with position control, push buttons, BLU sensors and firmware updates. Matter and Zigbee suit special cases, which are covered below.
1. The four options in one table
| Built-in integration | Matter | Zigbee: ZHA | Zigbee: Zigbee2MQTT | |
|---|---|---|---|---|
| How it connects | Wi-Fi or Ethernet (Pro) | Matter over Wi-Fi | Zigbee, through a Zigbee coordinator | Zigbee, through a Zigbee coordinator |
| What you get | Everything: metering, shutters, buttons, BLU, updates, scripts | Basic control: on, off, shutter, dimming | Basic. Shelly support is still partial | Broader: includes power metering and shutter mode on the 2PM |
| Needs the cloud? | No | No | No | No |
| Extra hardware | None | None (just the Home Assistant app on your phone) | Zigbee coordinator | Zigbee coordinator |
| Best for | Almost everyone | Anyone who also wants the device in Apple Home or Google Home | Anyone already running ZHA | Anyone with a large Zigbee network or a congested Wi-Fi |
| Models | All generations, the Pro series, Wall Display | Gen4 and some Gen3 models | Gen4 and BLU ZB | Gen4 and BLU ZB |
2. The built-in Shelly integration
The recommended route. Part of Home Assistant itself, with nothing extra to install.
This is an official Home Assistant integration at its highest quality tier (Platinum). It works with Local Push: the device sends an update the moment something changes, directly over your home network, without going through the Shelly cloud. You can keep using the Shelly app alongside it, and schedules set on the device itself keep working too.
How to connect
1
Connect the device to your home Wi-Fi network, following the guide to adding a new Shelly device to the app. It’s a good idea to update the firmware at this stage.
2
In Home Assistant, go to Settings → Devices & services. In most cases the device already appears under Discovered. Click Add.
3
Not there? Click Add integration, choose Shelly and enter the device’s IP address. You’ll find the address in the Shelly app, in the device details.
4
If you’ve set a password on the device, Home Assistant will ask for it. Then assign the device to a room, and you’re done.
Tip
A fixed IP address for each device (an address reservation in the router, DHCP reservation) saves a lot of trouble. See also the home network guide.
What you get
- Relays and lighting: a switch for each channel, dimming on dimmers.
- Shutters: a cover entity with position control. Calibration is done on the device, as in the device setup guide.
- Power metering on PM devices and energy meters: power, energy, voltage and current. You can add them straight to the Home Assistant Energy dashboard.
- Wall push buttons: every press (single, double, long) shows up as an event you can trigger an automation from. That way one button can run a whole scene.
- Firmware updates directly from Home Assistant.
- Advanced: scripts and virtual components on the device show up as entities.
- Wall Display: the relay, the sensors and the speaker (as a media player, on firmware 2.2 and later).
Battery-powered devices
Battery-powered sensors (for example the H&T or the flood sensor) “sleep” most of the time to save battery. To add one, wake the sensor by pressing its button, then add it in Home Assistant right away. On Gen2 and later, if updates don’t come through, set Outbound WebSocket on the device to ws://<HA-address>:8123/api/shelly/ws (in the device’s web interface, under Settings → Connectivity).
Older Gen1 devices
Older Gen1 devices (for example the original Shelly 1, 1PM or 2.5, before the Plus series) use a different protocol, CoIoT. If Home Assistant warns that updates aren’t coming through, open the device’s web interface and, under Internet & Security → Advanced – Developer Settings, enable CoIoT and set CoIoT peer to the Home Assistant address with port 5683. Then restart the device.
BLU sensors and remotes
Shelly’s Bluetooth sensors (BLU) broadcast using an open standard called BTHome, and Home Assistant detects them through the BTHome integration. To get the signal to Home Assistant from distant rooms too, any mains-powered Shelly Gen2 or later device can act as a Bluetooth proxy: turn it on in the device’s integration options. That way the devices already installed in your walls become a receiver network for your sensors.
- BLU H&T temperature and humidity sensor
- BLU Motion sensor
- BLU Door/Window ZB sensor
- BLU ZB Remote and BLU RC Button 4 ZB
3. Matter
One standard for every system. Simple, but basic.
Shelly Gen4 devices ship with Matter enabled out of the box, and some Gen3 models get it through a firmware update. On Shelly, Matter runs over your home Wi-Fi, so you don’t need a Thread border router. All the details (which models support it, where to find the code and how to connect to each system) are in the Shelly and Matter guide.
How to connect
1
In Home Assistant, install the Matter Server: Settings → Apps (before version 2026.2 this section was called Add-ons). On a standard Home Assistant OS installation this happens almost automatically when you add the Matter integration.
2
On your phone, open the Home Assistant app (Companion) and choose Add Matter device. The phone needs to be on the same Wi-Fi network, and on Android you need to give the app location access.
3
Scan the Matter QR code on the device or the box, or enter its numeric code. The device joins in about a minute.
The advantage of Matter
Matter lets you connect the same device to several systems at once (Multi-Admin): to Home Assistant and also to Apple Home or Google Home. Connecting to Apple Home is explained in the guide to connecting Shelly devices to smart assistants.
What you lose compared with the built-in integration
Home Assistant treats Matter as basic control. You get on, off, dimming and shutters, but not what’s specific to Shelly: device settings, firmware updates, scripts, Bluetooth proxy and sometimes part of the power metering data (depending on the model). So if Home Assistant is the main system in your home, it’s better to connect the device with the built-in integration and use Matter only for the additional system.
4. Zigbee: ZHA or Zigbee2MQTT
No Wi-Fi at all. For large networks.
Gen4 devices can also run on Zigbee instead of Wi-Fi and Matter. In this mode the device joins your home Zigbee network, and mains-powered devices also act as a router that strengthens the network. In addition, BLU products marked ZB (remotes and door sensors) work over both Bluetooth and Zigbee.
What you need
- A Zigbee coordinator connected to Home Assistant, for example the Home Assistant Connect ZBT-2 or another supported USB adapter.
- One of two options: ZHA, Home Assistant’s built-in integration (simple, nothing to install), or Zigbee2MQTT (Z2M), which is installed as an app and works with MQTT.
Switching a Gen4 device to Zigbee mode
1
Press the button on the device 5 times in a row (or the switch wired to its input, depending on the model’s instructions). The device switches from Wi-Fi/Matter mode to Zigbee mode. You can also make the switch from the device’s web interface.
2
In Home Assistant, open the pairing window: in ZHA Add device, and in Z2M Permit join.
3
Press the button 3 times so the device searches for a network. Pairing takes up to 2 to 3 minutes.
Note
The buttons on a device in a wall box sit behind the switch. It’s best to do these presses before the device goes into the wall, or to ask the electrician. In Zigbee mode the device is managed through Home Assistant, and some features of the Shelly app and cloud aren’t available.
ZHA or Zigbee2MQTT?
As of late 2026, Zigbee2MQTT is ahead in Shelly support. Z2M has support pages for the 2PM Gen4 (as a switch and as a cover, with power metering per channel), the Dimmer Gen4, the i4 Gen4 and the BLU ZB remotes. In ZHA the devices connect and work with basic control, but some of the special features aren’t supported yet. If you’re starting a new Zigbee network for Shelly, Z2M is the safer choice.
5. What about MQTT and the cloud?
- MQTT: Shelly devices support MQTT, but without automatic discovery in Home Assistant. You have to set up each entity yourself or use a community script. For a typical home it isn’t worth the effort: the built-in integration gives you more, and it’s just as local. Just don’t connect the same device through both the built-in integration and MQTT.
- The Shelly cloud: Home Assistant has no official Shelly cloud integration, and it doesn’t need one. The cloud is still useful for the app when you’re away from home, for voice assistants and for Shelly scenes.
6. Which option is right for me?
- I have Home Assistant and it’s the hub of my home → built-in integration.
- I also want my devices in Apple Home or Google Home → the built-in integration for Home Assistant, and Matter for the additional system.
- I already have a Zigbee network with lots of devices, or my home Wi-Fi is congested → Gen4 devices in Zigbee mode, preferably with Zigbee2MQTT.
- An electrical panel with lots of channels → the Pro series with Ethernet and the built-in integration. The most reliable setup.
- I don’t have Home Assistant yet → the Shelly app is enough for most homes. Buy Gen4 devices and keep your options open: they support every route in this guide.
Before you buy
Gen4 devices are the only ones that support all four routes: the built-in integration, Matter and Zigbee. If you’re building a smart home today, it’s the choice that keeps every door open.
7. Suitable products
- Shelly 1PM Gen4: for a water heater, lighting or an outlet, with power metering.
- Shelly 2PM Gen4: for a shutter or two lights.
- Shelly 1PM Mini Gen4 and Shelly 1 Mini Gen4: for crowded wall boxes.
- Shelly Dimmer Gen4: light dimming.
- Shelly Pro 4PM and Pro 2PM: for the electrical panel, with Ethernet.
- Shelly Wall Display and Wall Display XL: a wall control screen that also works with Home Assistant.
FAQ
Does Shelly need an internet connection to work with Home Assistant?
No. The built-in integration, Matter and Zigbee all work inside your home network. The internet is only needed for the Shelly app away from home, for voice assistants and for scenes in the Shelly cloud.
Can I keep using the Shelly app after connecting to Home Assistant?
Yes, with the built-in integration and with Matter. Both work alongside the app. In Zigbee mode the device is managed through Home Assistant.
My devices are Gen3. Will they work?
Yes, with the built-in integration, with every feature. Some Gen3 models also support Matter after a firmware update. Zigbee is available on Gen4 only.
Which devices support Zigbee?
Gen4 devices (for example the 1PM Gen4, 2PM Gen4, Mini Gen4 and Dimmer Gen4) and BLU products marked ZB.
The device doesn’t appear under Discovered. What do I do?
Check that Home Assistant and the device are on the same network (not a guest network), and add it manually by IP address. If it still doesn’t work, see the home network guide.
Which is better, Matter or the built-in integration?
For Home Assistant, the built-in integration. It gives you everything, while Matter gives basic control. Matter is better only when you also want to connect the device to another system.
Will the Shabbat schedules I set on the device keep working?
Yes. Schedules stored on the device itself run even without Home Assistant and without internet. See smart homes for Shabbat observers.
Need help with the installation? Book an electrician who knows Shelly. Want to start from the basics? The complete guide to installing a Shelly smart home. This guide was prepared by OZZI, the official distributor of Shelly smart home products in Israel.