Shelly relays and plugs are among the easiest Wi-Fi devices to use with Home Assistant without a cloud. The official Shelly integration talks to each device directly over the local network, and the device pushes its state changes to Home Assistant instead of waiting to be asked. A light switched from the wall shows up in Home Assistant almost immediately, and it keeps working when the internet connection is down.

Out of the box, though, a Shelly is set up for the Shelly app: it has an open setup access point, a cloud connection and no password on its web panel. This guide covers setting one up so that Home Assistant is in charge, the device is protected on the network, and the button presses and energy readings end up where you can use them.

Which generation you have

Shelly has released four generations of devices, and the integration supports all of them. The difference matters for setup:

  • Generation 1 (older Shelly 1, 2.5, Plug S and similar) uses a protocol called CoIoT for push updates. It needs a small manual setting on each device.
  • Generation 2 and newer (Plus, Pro, Gen3 and Gen4 models) uses an RPC protocol. Mains-powered devices need no extra configuration.
  • Shelly BLU devices are Bluetooth sensors and buttons. They are not added through the Shelly integration, but through the BTHome integration.

The web panel footer shows the model and firmware version. The integration requires firmware 1.9 or later on Gen1 and 1.0 or later on Gen2, so update very old devices first.

Step 1: get the device onto your Wi-Fi without the app

A new or reset Shelly starts its own access point with a name like ShellyPlus1-XXXXXXXXXXXX, where the last part is the device ID. Connect a phone or laptop to it and open http://192.168.33.1 in a browser. That is the local web panel, and it works without an account or an internet connection.

In Settings > Wi-Fi, choose your network and enter its password. Newer models, such as the Gen3 devices, can store two networks and switch to the second one if the first one is unavailable. After a few seconds the panel shows the new address on your network. Open that address and continue from there.

Two things are worth doing right away:

  1. Fix the IP address. Set a static IP in the Wi-Fi settings or, better, create a DHCP reservation on your router. A stable address makes troubleshooting easier, and some features, such as the Shelly range extender, only work with a static or reserved address.
  2. Close the access point. Shelly's own documentation says the device's access point is an open network by default. Once the device is on your Wi-Fi, disable it under the access point settings, or at least set a password. Otherwise anyone within range can join it and reach the web panel.

Step 2: set a password on the device

Gen2 and newer devices support authentication on the local API and web panel. It is off by default. Turn it on in the device's web panel under the authentication settings (in Settings > Authentication on Gen3 models) and choose a password.

A few details from the Shelly API documentation:

  • The username is always admin. You only choose the password.
  • The protection uses HTTP digest authentication with SHA-256. It covers the web panel and the RPC interface over HTTP and WebSocket, but not MQTT or the outbound WebSocket, which are outgoing connections from the device.
  • A small amount of information, such as basic device info, stays readable without a password so that discovery still works.
  • Firmware 2.0.0 and newer slows down repeated wrong passwords. After 11 failed attempts the device makes the client wait before trying again, the wait grows with more failures, and from 40 failures it is 5 minutes. Blocked requests get an HTTP 429 response.

Do not confuse this with the PIN lock in the Shelly app. That PIN only protects the device inside the app. It does nothing for someone on your network.

Home Assistant asks for the username and password when it adds a protected device. If you set a password on a device that is already added, the integration asks you to re-authenticate.

Step 3: add it to Home Assistant

In most networks Home Assistant discovers the device by itself and shows it under Settings > Devices & services as discovered. Select Add, confirm, and enter the credentials if prompted.

If discovery does not find it (common when the Shelly sits on a different VLAN), add it manually: Settings > Devices & services > Add integration > Shelly, then enter the device's IP address. The port field is only needed for devices reached through a Shelly range extender.

Battery-powered devices, such as a Shelly H&T, sleep most of the time. Press the button on the device to wake it up right before you add it.

Generation 1: enable CoIoT

Gen1 devices only push updates to Home Assistant if CoIoT is configured. In the device's web panel, open Internet & Security > ADVANCED - DEVELOPER SETTINGS, check Enable CoIoT, and enter the Home Assistant address with port 5683 in the CoIoT peer field, for example 192.168.1.10:5683. Save and restart the device.

Home Assistant documentation recommends this unicast setup in general and says it is mandatory for battery devices. If push updates do not arrive, Home Assistant shows a repair issue for the device. If you cannot find the CoIoT peer field, the firmware is too old.

Generation 2+: battery devices and outbound WebSocket

Mains-powered Gen2+ devices need nothing else. Battery-powered ones send their data through an outbound WebSocket, which the integration normally configures by itself. If Home Assistant cannot work out its own internal URL, or the device was previously used with another Home Assistant instance, set it manually in the device's web panel under Settings > Connectivity > Outbound WebSocket: enable it and enter ws://<Home Assistant IP>:8123/api/shelly/ws. If Home Assistant uses HTTPS, use wss:// instead.

Devices on a separate VLAN

The integration needs two-way traffic between Home Assistant and the devices:

  • Home Assistant must reach each Shelly over HTTP (port 80) or HTTPS (port 443, see below).
  • Gen1 devices must reach Home Assistant on UDP port 5683 for CoIoT.
  • Battery-powered Gen2+ devices must reach Home Assistant on its web port, usually 8123, for the outbound WebSocket.

Mains-powered Gen2+ devices only need the first rule.

Step 4: turn off the cloud (or decide not to)

Once Home Assistant controls the device, the Shelly Cloud connection is optional. It is enabled by default and can be switched off in the web panel under Settings > Cloud (or Connectivity > Cloud on some models). Shelly's documentation is clear about the effect: with the cloud disabled, the Shelly app can no longer reach the device from outside the local network.

If you reach Home Assistant remotely anyway, you lose nothing. If someone in the household relies on the Shelly app away from home, leave the cloud on and still use the local integration. They work side by side.

Step 5: make the entities match the wiring

By default, each relay becomes a switch entity. Two device settings change what Home Assistant creates, and both are easier to set before you build automations.

Consumption type. If a relay drives a light, set the output's external consumption type to light in the web panel. The integration then creates a light entity instead of a switch, so the relay appears with the other lights in the area and works with light actions.

Input mode. The wall switch connected to the Shelly can be configured as Switch or Button:

  • With Switch (a classic toggle switch), Home Assistant gets a binary sensor showing the input state.
  • With Button (a momentary push button), Home Assistant gets an event entity instead, and the device reports single, double, triple and long presses. This makes one physical button do several things.

If the button should only send events to Home Assistant and not switch the relay directly, set the output type to Detached. Then the relay can be controlled independently by automations.

A double press on a detached button can turn off every light on the floor:

alias: "Hallway button: double press turns off downstairs"
triggers:
  - trigger: state
    entity_id: event.hallway_button_input_0
conditions:
  - condition: template
    value_template: "{{ trigger.to_state.attributes.event_type == 'double_push' }}"
actions:
  - action: light.turn_off
    target:
      area_id: downstairs

The entity ID depends on your device name. The state of an event entity is the time of the last event, so it changes with every press, even if the press type repeats. Gen2 and newer devices report btn_down, btn_up, single_push, double_push, triple_push and long_push. Gen1 devices use single, double, triple, long, single_long and long_single.

It is also worth checking Action on power on for each output. It decides whether the relay turns on, stays off or restores its last state after a power cut. For lights, "restore last state" usually makes the most sense. For a heater or a pump, think about what should happen if power returns while nobody is home.

Energy readings

On models with power metering, the integration creates a power sensor in watts and an energy sensor that counts consumption in kWh. The energy sensor is a total that only increases, which is what the Home Assistant Energy dashboard expects. Add it under Individual devices in the Energy dashboard settings. Our article on the Energy dashboard covers the rest of that setup.

The Home Assistant documentation points out one dependency here: Shelly devices need working time synchronization (SNTP) for features such as power measurement. If readings look wrong, check in the web panel that the configured time server is reachable, especially on a VLAN without internet access, where you may have to point the device to an NTP server on your local network.

Some devices also have built-in protection settings, such as maximum power, current and voltage. The relay turns off if a limit is exceeded. This happens on the device itself, without Home Assistant, which is exactly where a safety limit belongs.

Firmware updates and HTTPS

The integration creates a firmware update entity for each device, so Shelly updates appear next to other updates in Home Assistant and can be installed from there. Battery devices are the exception: Home Assistant shows that an update is available, but cannot start it, because the device is asleep most of the time.

Firmware 2.0.0 introduced Enhanced Security for Gen2+ devices, related to the EU Radio Equipment Directive. Devices shipped with 2.0.0 or newer already use HTTPS. Devices updated from older firmware keep working as before until you enable Enhanced Security yourself. The integration detects HTTPS and connects on port 443 automatically. The Verify SSL option should only be enabled if the device uses a certificate signed by an authority that Home Assistant trusts. If you have not installed such a certificate yourself, leave it off.

Bonus: a Bluetooth proxy in every relay

Mains-powered Gen2+ devices can also forward Bluetooth advertisements to Home Assistant. In the integration options, choose a Bluetooth scanner mode. The documentation recommends Auto, which listens passively and only scans actively when needed, saving around 95% of the scan-related battery drain on Bluetooth sensors. A Shelly cannot handle active connections, so it suits temperature sensors and BLU buttons, not devices that need pairing.

Common mistakes

  • Leaving the setup access point open. It is the first thing to close after the device joins your Wi-Fi.
  • Assuming the app PIN protects the device. Only the authentication password protects local access.
  • Forgetting the CoIoT peer on Gen1 devices. The device still works, but Home Assistant gets no push updates from it and shows a repair issue.
  • Blocking the return path between VLANs. Control from Home Assistant works, but battery devices and Gen1 devices stop reporting.
  • A detached button with no automation. If Home Assistant is down, the button does nothing. Decide whether that is acceptable for the room. For the main light, a non-detached input is usually safer.