Skip to main content

Shelly smart home integration, free and open source

Shelly integration for Gladys Assistant

Connect your Shelly devices (relays, plugs, meters, shutters, lights) to Gladys, locally.

View on GitHubAll integrations

This integration connects your Shelly devices to Gladys Assistant: relays, smart plugs, energy meters, roller shutters, dimmers and colour lights, inputs and buttons.

It talks directly to your devices on your local network (the Gen2+ RPC protocol) and lets them push their changes in real time, so a relay flipped on the wall appears in Gladys in about a second. It can fall back to the MQTT, then to the Shelly Cloud, when a device cannot be reached locally. Nothing is mandatory: a fully local setup works with an entirely empty form.

Supported generations: Gen2 and later — Shelly Plus, Pro, Mini, Gen3, Gen4 — and Gen1 (Shelly 1, 1PM, 2.5, Plug S "SHPLG-S", EM, 3EM…).

Gen1 speaks a completely different API (REST instead of JSON-RPC, Basic auth instead of Digest), but the integration normalizes it into the same model: a Gen1 Shelly 3EM exposes exactly the same features, under the same names, as a Gen2 Pro 3EM. Your dashboards and scenes cannot tell them apart.

One limit worth knowing: locally, Gen1 devices have no real-time channel. Their push protocol (CoIoT) is multicast, which never reaches a Docker container, so their values follow the refresh interval. Over MQTT they do, exactly like Gen2+.

Requirements​

  • Gladys Assistant 5.1.0 or newer (dashboard widgets, scene triggers and scene actions).
  • Your Shelly devices are powered and joined to your Wi-Fi (set up from the Shelly app or the device web interface).
  • Gladys and your Shelly devices are on the same local network — or you know the IP addresses of the devices sitting on another VLAN.

Step 1 — Install the integration​

In Gladys: Integrations → Install an integration → Shelly, then Install. Gladys pulls the Docker image and starts the container.

There is nothing to configure for a simple local setup: go straight to step 3.

Step 2 — Configure (only if you need to)​

Open the integration Configuration screen. Every field is optional.

Local connection​

FieldWhen to fill it in
Additional device addressesYour Shelly devices are not found automatically (another VLAN, mDNS disabled on the device or filtered by the router). Enter the IPs, comma-separated.
Device usernameLeave it as admin: it is the only username Gen2+ devices accept.
Device passwordYou enabled authentication on your Shelly devices. The password shared by your devices (the others go in the next field).
Per-device passwordsSome devices have a different password: device=password entries separated by ; (Shelly id, MAC or IP address).

🔑 Different passwords? Keep the most common one in Device password, and list the others in Per-device passwords, as device=password entries separated by ;: the device is its Shelly id (shellyplus1-a8032ab12345), its MAC address or its IP address. A device that refuses its password shows an orange dot on its badge, and the Configuration screen names it.

Shelly Cloud (fallback)​

Fill this in only if you want Gladys to keep controlling a device that is unreachable locally (Gladys hosted elsewhere, device on another network, temporary Wi-Fi drop).

  1. Open the Shelly app (or https://control.shelly.cloud/).
  2. Settings → User settings → Authorization cloud key.
  3. Click Get key: the app shows the authorization key and the server address (something like shelly-53-eu.shelly.cloud).
  4. Copy both values into Gladys and turn on Enable the Shelly Cloud fallback.

🔐 This key grants full control over every device of your Shelly account. Treat it like a password. Gladys stores it encrypted and never shows it in clear text.

The integration reads the whole account in one request per refresh cycle and spaces its calls one second apart, the limit of the Shelly Cloud API: a fleet on the cloud never trips it.

When both channels are configured, Gladys shows a standard "Prefer the local connection" toggle (on by default). It is a preference: the integration applies it when it can, and reports the per-device reality through the transport badges (see below).

Fill this in if some devices are never discovered, or if you want real time on Gen1 hardware.

On each Shelly: device web interface → Settings → MQTT →

SettingValue
Enableticked
Serveryour broker address, e.g. 10.5.0.50:1883
Username / Passwordyour broker credentials, if it is protected
Enable 'MQTT Control'ticked — this is what lets Gladys control the device over MQTT
RPC status notifications over MQTTticked — this is what sends the values in real time
MQTT prefixleave the default (the device id)

In Gladys: tick Enable MQTT and enter the same broker address, plus the credentials if needed.

The prefix is free-form, slashes included: the integration does not rely on it. It identifies each device by the src field of its messages, which is the hardware id — so renaming a prefix breaks nothing.

💡 Gen1 too. They publish in a completely different dialect (shellies/<id>/emeter/0/power, one value per topic, no JSON anywhere), which the integration also understands. A Gen1 3EM on MQTT therefore reports in real time, unlike the same device locally.

Advanced​

Feature names: the language of the feature names given to the devices you create from now on (English, French, German or Spanish). A device already created keeps its names — rename its features in Gladys if you wish; their ids, history and scenes never depend on the name.

Refresh interval: how often Gladys reads the state of every device. 30 seconds by default.

A shorter interval means fresher values but more requests. Gladys rate-limits an integration to 300 states per minute: the integration only publishes values that actually changed (with a forced refresh every 30 minutes so a frozen value does not look dead), so a short interval only hurts when many values move constantly. A single Shelly Pro 3EM carries ~25 measurements: past three or four energy meters, stay at 30 seconds or more.

Step 3 — Discover your devices​

Go to the integration Discovery tab and click Scan.

Gladys queries four sources and merges them:

  1. mDNS — your Shelly devices announce themselves on the network (_shelly._tcp for Gen2+, _http._tcp for Gen1). The Gladys core listens on behalf of the integration: containers run on a bridge network and never receive multicast traffic.
  2. Your MQTT broker, if you configured one — see below.
  3. The addresses you typed in step 2.
  4. Every address already seen, whether the device was created in Gladys or merely spotted during an earlier scan. An address that answered once is re-probed on every scan: a device found once is never lost again.

Each address is then queried over unicast (which does cross the bridge network). Click Create to add a device to Gladys.

⚠️ A device is missing? Use MQTT​

This is the most important part of this page if you have more than a handful of devices.

mDNS works in short multicast bursts. On an installation with about fifteen Shelly devices, one scan reports 19 announcements, the next 27, and some devices are never announced at all — while working perfectly and answering HTTP the moment you know their address. It is not a signal problem, nor a device setting.

Three ways out, most effective first:

  1. Configure MQTT (next section). A device publishing to your broker announces itself continuously: there is no window left to miss. It is discovered, it reports in real time, and it stays controllable even when it is unreachable on the local network. Past a handful of devices this is the only reliable inventory.
  2. Enable the Shelly Cloud. It does not discover devices, but it keeps the ones Gladys already knows readable and controllable when the local network fails.
  3. Type the IP addresses by hand in "Additional device addresses". Immediate and effective, but you have to redo it if a DHCP lease changes — reserve a fixed IP on your router in that case.

One Shelly = one Gladys device​

A Shelly Pro 4PM becomes one single Gladys device carrying four On/Off features, plus their measurements. This is the Gladys convention, and it keeps the external ids stable when you rename a channel.

If you named your channels in the Shelly app ("Bathroom", "Toilet"…), those names are picked up: you get "Bathroom — On/Off" rather than four identical "On/Off". Name your channels in the Shelly app before running the discovery: it is the fastest way to get a readable result.

Supported devices and measurements​

Features are derived from what the device actually reports, never from a hard-coded model table: a Shelly Pro 1 (no metering) only exposes an On/Off, a Pro 1PM also exposes power, voltage, current and energy — and a Shelly released after this version works as long as it speaks the same vocabulary.

Shelly componentWhat you get in Gladys
switch:NOn/Off (controllable), power (W), voltage (V), current (A), total energy (kWh), internal temperature (°C)
cover:NShutter open / stop / close (controllable), position (%) once calibrated, power, voltage, current, energy, temperature
light:NLight on/off and brightness (controllable), power and energy
rgb:N / rgbw:NSame as light:N, plus the colour (controllable)
cct:NSame as light:N, plus the colour temperature (controllable)
input:NSwitch mode: an input (on/off). Button mode: a button and the "Button pressed" scene trigger. Count mode: a counter
em:N (three-phase)Per L1/L2/L3 phase: active power (W), apparent power (VA), voltage (V), current (A) — plus the totals and the neutral current
emdata:NTotal and returned energy, per phase and total (kWh)
em1:N / em1data:NSingle-phase equivalents (Shelly Pro EM, 1PM Mini Gen3)
pm1:NPower, voltage, current and energy of a standalone meter (PM Mini)
temperature:N, humidity:NTemperature (°C), humidity (%)
devicepower:NBattery level (%)
flood:N, smoke:NWater leak, smoke (Gen1 Flood and Smoke, Gen2+ equivalents)
contact:N, illuminance:NDoor/window opening (closed / open) and illuminance (lux) of a Gen1 Door/Window
number:N / boolean:NVirtual components of "Powered by Shelly" devices (LinkedGo ST1820…): thermostat setpoint (controllable, clamped to the device range and step), room temperature (°C), humidity (%), on/off options such as "Enable thermostat" or "Child lock" (controllable when the device allows it), relay status

Hardware validated against real payloads: Shelly Pro 3EM, Shelly Pro 4PM, Shelly Pro 3, Shelly Plus 2PM, Shelly Plus Plug S and the Gen1 3EM. Shutters, lights and inputs follow the documented Shelly API and are waiting for your feedback on real hardware: if you own one, please report how it behaves (see Diagnostic).

Virtual components are named and typed from the device's own description (Shelly.GetComponents, read at every scan): the semantic role the device declares when there is one (target_temperature → thermostat setpoint), the name, unit and access otherwise. enum:N components are not mapped yet. Writing a virtual component needs the local network or MQTT — the Shelly Cloud cannot relay it.

On Gen1, the same model applies: a Shelly 2.5 in roller mode becomes a shutter, a Dimmer, a Bulb or a Duo a light, an RGBW2 in colour mode a colour light, the inputs of an i3 inputs and buttons (single, double, triple and long presses, from the press counter of each reading, or instantly over MQTT), a Flood a water leak sensor, a Smoke a smoke detector, a Door/Window an opening sensor with its illuminance.

Battery-powered devices sleep (H&T, Flood, Door/Window, Smoke, Button, Plus/Gen3 H&T…): asleep, they answer nothing, which is their normal state. The integration therefore keeps them local as long as they reported in the last 26 hours, never parks them and never fires "Shelly reachability changed" while they sleep. Their values arrive when they wake up: configure MQTT on them to receive each report as it is sent, a sleeping device is almost never awake when a poll comes.

Roller shutters​

A cover exposes the standard Gladys shutter control: Open, Stop, Close, and a position slider. The position (100 % = fully open, the same convention in Shelly and in Gladys) only exists once the cover is calibrated in the Shelly app: an uncalibrated cover has no position feature at all rather than one that never moves. Calibrate it, then run a discovery again and click Update on the device.

While the shutter moves, Gladys shows its direction (opening / closing); once it stops, the state reads "stopped" and the position is the real one.

Lights​

Dimmers and colour outputs become Gladys lights: on/off, brightness (0 to 100 %), colour for rgb / rgbw, colour temperature for cct (2700 K warm to 6500 K cold). Changing the brightness does not switch the light on or off. An RGBW output also exposes its white LEDs (0 to 100 %). Analog inputs are not exposed yet.

Inputs and buttons​

What an input becomes depends on its mode in the Shelly app:

  • Switch (a wall switch, a dry contact): an input feature, on or off, published in real time;
  • Button (a push button): a button feature, plus the Button pressed on a Shelly scene trigger, fired on every single, double, triple or long press — in real time, over the WebSocket or MQTT. A Shelly i4 thus gives four buttons ready for your scenes;
  • Count: a counter.

Changed the mode of an input in the Shelly app? Run a discovery again and click Update on the device.

The neutral current​

On a Pro 3EM, n_current is only measured when you wired the neutral clamp. Without it the device returns null: the feature is then not created at all rather than showing a permanently empty chart. If you add the clamp later, run a discovery again to make the measurement appear.

Transport badges​

Every device shows a badge in Gladys telling you which channel actually reaches it:

BadgeMeaning
LocalNominal. Gladys talks directly to the device on your network.
CloudGladys goes through the Shelly Cloud (you turned off "Prefer the local connection").
Cloud + orange dotDegraded: the device was not reachable locally, Gladys fell back to the cloud. Hover the badge for the reason.
UnreachableNeither the local network nor the cloud answered.

A Cloud badge with an orange dot is the one to watch: your setup works, but not in its nominal mode. The tooltip gives the cause — device powered off, IP changed, or password refused.

Scenes​

In the scene editor, category Integrations:

Triggers

  • Button pressed on a Shelly — choose the device, optionally the input (0 to 3) and the presses (single, double, triple, long). The variables device_name, input and event are available to the following actions.
  • Shelly reachability changed — a device became unreachable on every transport (local, MQTT and cloud), or answers again. Handy for a notification when the meter of the main board stops reporting.

Actions

  • Turn on for a duration — switches a relay or a light on, and the Shelly itself switches it off after the duration (1 second to 1 day). The timer lives in the device: a Gladys restart in between never leaves the pump, the heater or the garden watering running. Output number 0 is the first relay or light of the device, 1 the second, and so on.
  • Restart a Shelly — the usual cure for a device that stopped pushing after a Wi-Fi change.

The usual actions (switch on, off, set a position, a brightness...) remain the standard Gladys device actions.

Dashboard widgets​

Add them from the dashboard editor, Integrations column:

  • Shelly energy meter — for a metering Shelly (Pro 3EM, Pro EM, PM Mini, a plug or a relay with metering): a live power gauge (below zero when you export), one tile per phase or per channel, the total energy, the power chart over the period of your choice, then the voltages, currents, apparent power, power factor and frequency of the last reading, and the source. Set the gauge maximum to your subscribed power.
  • Shelly switches — the relays and lights of a room or of the whole house (leave the selection empty for all): state and power of each output, the number switched on, the total power, and All on / All off buttons (with a confirmation).
  • Shelly shutters — a group of shutters: state and position of each, the average position, and Open, Stop, Close and Position buttons for the whole group (the position form is pre-filled with the current average).
  • Shelly network health — how many devices push in real time, fall back, or are unreachable, then the list of what deserves attention (unreachable, degraded, weak Wi-Fi signal, firmware update available), and the share of the Gladys budget of 300 states per minute in use.

Diagnostic​

The Configuration screen of the integration has two read-only buttons, made for a GitHub issue or a forum post:

  • Diagnostic of the devices — a text report of the whole installation: configuration (never a password nor the cloud key), WebSocket and MQTT channels, states published over the last minute and the real-time lane cadence, then for each device its transport and whether it is degraded, the age of its last data, the local circuit breaker, its components, Wi-Fi signal, uptime, available firmware update and the state of its outputs. Pick a device to diagnose it alone.
  • Test a device — reads one device now, at the address the integration uses: /shelly identity and answer time, then the full status read (with the password), the components and the features the integration maps, the Wi-Fi signal, and whether it pushes in real time. On failure, the exact error and what to try. It also works for a device not created in Gladys: type its IP address — the fastest way to understand why a scan does not find it. It never writes anything to the device.

By default the MAC part of the device ids is shortened and the local addresses are hidden, so the report can be pasted publicly as is. Tick Show device ids and local addresses for a private exchange. The reports are also written to the integration logs, always in their masked form.

Updating the integration​

Gladys shows available updates in Integrations. Click Update: the container is recreated with the new image, and your configuration and devices are preserved. The notes of each version are on the GitHub releases page.

A Shelly that changed profile (a Plus 2PM from relays to cover, a dimmer from light to switch) keeps its old features in Gladys, empty. The scan names them in the logs and Diagnostic of the devices lists them: click Update for the new ones, then delete the old ones in Gladys.

New features of an existing device (a shutter calibrated since, a newly supported component) appear after a discovery: click Update on the device marked "Already added". Its existing features, history, scenes and dashboards are kept.

Troubleshooting​

No device found during the scan​

  1. Check that the device answers. From a browser on the same network, open http://<shelly-ip>/shelly. You should see JSON containing "gen": 2 (or 3, or 4). If there is no gen field but a "type" field, this is a Gen1 device: supported too, over polling.
  2. mDNS does not cross VLANs, nor some Wi-Fi access points. Enter the IP addresses by hand in Additional device addresses, then save: the discovery re-runs automatically.
  3. Use "Test a device" in the Configuration screen with the device IP: it says whether the device answers, refuses the password, or is not a Shelly.
  4. Read the container logs (docker logs <container>). The integration logs how many candidate addresses it has, where each came from, and the exact reason an address was discarded.

"The device refused the password"​

You enabled authentication on that Shelly, and the password entered in Gladys does not match. On Gen2+ the username is always admin: only the password matters. Fix it and save — the correction takes effect immediately, without restarting the container.

If only this device has another password, add it to Per-device passwords (its-shelly-id=its-password) instead of changing the shared one. The Configuration screen names the devices that refuse their password, and Test a device says which password it tried.

A device keeps falling back to Cloud (orange badge)​

Its IP address most likely changed (DHCP lease). Run a discovery again: the address is re-learned and remembered. To avoid a repeat, reserve a static IP for your Shelly devices in your router.

The Shelly Cloud rejected the authorization key​

Copy the key and the server address from the Shelly app: they go together, and the server address depends on your account region. A valid key on the wrong server is rejected.

Values do not update as fast as expected​

On/off states are near-instant (about a second): your devices push them to Gladys over a WebSocket, without waiting for the next refresh.

Every instantaneous power — a meter's total power, the power of each phase of a three-phase meter, each relay's power — rides a dedicated real-time lane, published every 5 seconds by default (adjustable from 1 s to 30 s, or disabled). That is what a scene needs to react: steering a battery, shedding a load.

Every other measurement (voltages, currents, apparent power, energy counters, temperatures) follows the refresh interval you configured. That is deliberate, and it is a hard constraint rather than a choice: Gladys limits an integration to 300 states per minute, while a single Pro 3EM pushes about one update per second across ~25 measurements. Forwarding all of it verbatim would be roughly 900 states per minute — three times over the cap. So measurements are coalesced: Gladys gets the freshest value at your configured cadence, without an HTTP round trip.

The integration also only publishes values that changed; a stable value is republished every 30 minutes so it does not look dead.

What happens when your fleet is too big for your cadence. The cost of the lane comes from the fleet, not from the setting: a value that never moves is free, a value that always moves costs a slot in every window. So the integration measures what it actually publishes and stretches its own interval once it passes 240 states per minute — and it says so:

Real-time lane slowed to 10s (you asked for 5s): the fleet is publishing
612 states/min, and the limit is 300/min. It speeds back up on its own; create
fewer devices, or raise the refresh interval, to stay at 5s.

Your setting is a floor: the lane returns to it on its own as soon as the budget allows. A slower lane is visible; a state Gladys refuses would not be.

The controller is deliberately slow to change its mind: it slows down in proportion (a big installation reaches its cadence in one or two steps) but it speeds back up one second at a time, only once the rate has fallen well under the threshold, and never more than once a minute. The rate is measured over a rolling minute, so deciding faster would mean deciding on a number that still describes the previous cadence — and oscillating.

If Gladys refuses states anyway, it says so by name, and the lane slows down immediately without waiting:

Gladys refused 38 state(s): over the 300/min limit. They are retried on the
next cycle, and the real-time lane slows down.

Once a minute, one line tells you where you stand:

Real-time lane: 54 state(s) published in the last minute (every 5s, from
4 WebSocket and 15 MQTT device(s)); 61/300 states/min of the Gladys budget used

Checking that real time is actually working. Two distinct lines per device in the container logs:

shellypro4pm-ece334ea4d10: real-time WebSocket connected
shellypro4pm-ece334ea4d10: real-time updates flowing

The first one means the connection is established and the device answered us; the second appears with the first notification received. If the first line never shows up, the device is refusing the connection (password? old Gen2 firmware?): its values then simply follow the refresh interval, nothing is lost.

Migrating from an existing MQTT / Node-RED setup​

This integration creates its own devices with its own external ids (ext:shelly:device:...). It does not carry over the history of devices created through MQTT: both can coexist during the transition, then you delete the old ones.

Going further​

Configuration settings​

These are the settings Shelly asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Local connection (recommended)sectionNoGladys talks to your Shelly devices directly on your network, with no cloud in between: faster, and it keeps working when the Internet is down. Devices announce themselves over mDNS and are found automatically when you run a scan — nothing to fill in here unless your devices are password-protected or invisible to mDNS. Every generation is supported: Gen1, Gen2, Plus, Pro, Mini, Gen3 and Gen4.
Additional device addressesstringNoOptional. Comma-separated IP addresses or hostnames of Shelly devices that mDNS does not find (different VLAN, mDNS disabled on the device, static setup). Example: 10.5.0.171, 10.5.0.172, shellypro4pm-ece334ea4d10.local
Device usernamestringNoOnly if you enabled authentication on your Shelly devices. On Gen2+ the username is always 'admin' — leave it as is.
Device passwordsecretNoOnly if you enabled authentication on your Shelly devices. Used for every device, except those listed in Per-device passwords below.
Per-device passwordssecretNoOptional, for the devices whose password differs from the one above: device=password entries separated by semicolons. The device is its Shelly id, its MAC address or its IP address. Example: shellyplus1-a8032ab12345=first; 10.5.0.42=second
Shelly Cloud (fallback)sectionNoOptional. When a device cannot be reached locally (away from home, another VLAN, Wi-Fi drop), Gladys can fall back to the Shelly Cloud. Get the authorization key and the server address in the Shelly app: Settings, then User settings, then Authorization cloud key. Leave this section empty for a local-only setup.
Enable the Shelly Cloud fallbackbooleanNoUse the Shelly Cloud when a device is unreachable on the local network. Requires the server address and the authorization key below.
Shelly Cloud serverstringNoThe server your account is hosted on, shown next to the authorization key in the Shelly app. Example: shelly-53-eu.shelly.cloud
Shelly Cloud authorization keysecretNoThe authorization cloud key of your Shelly account. It grants full control over every device of the account — treat it like a password.
MQTT (recommended for large installations)sectionNoOptional, and the most reliable way to reach a large fleet. Shelly devices announce themselves over mDNS in short multicast bursts that are easily missed, so on an installation with many devices some are simply never discovered. A device configured to publish to your MQTT broker announces itself continuously instead: it is discovered, it reports in real time, and it can still be controlled when it is unreachable on the local network. Configure the broker in each Shelly: Settings, then MQTT, then tick Enable, Enable MQTT Control and RPC status notifications over MQTT.
Enable MQTTbooleanNoListen to your MQTT broker to discover, read and control the Shelly devices that publish to it.
MQTT broker addressstringNoHost and port of your broker, exactly as entered in the Server field of your Shelly devices. The port defaults to 1883.
MQTT usernamestringNoOnly if your broker requires authentication. Use the same credentials you set in your Shelly devices.
MQTT passwordsecretNoOnly if your broker requires authentication.
AdvancedsectionNoSensible defaults are already set — change these only if you know why. A shorter refresh interval means fresher values but more requests on your network and against the Gladys state rate limit.
Feature namesselectNoLanguage of the feature names given to newly discovered devices. A device already created keeps its names: rename its features in Gladys if needed.
Refresh intervalselectNoHow often Gladys reads the state of every device.
Real-time interval (power and on/off)selectNoHow fast the values a scene reacts to are published: every instantaneous power (total, per phase, per relay), every on/off state, shutter and light state. Everything else (voltages, currents, energy counters, temperatures) follows the refresh interval above. This is a floor, not a promise: Gladys accepts 300 states per minute in total, so on a large fleet the integration slows this lane down on its own and says so in the logs, then returns here as soon as the budget allows.

How to install Shelly in Gladys​

  1. In Gladys, open Integrations: Shelly appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/terdious/gladys-shelly:1.4.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/Terdious/gladys-shelly.

Shelly requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Shelly is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by Terdious, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on