Shelly integration for Gladys Assistant
Connect your Shelly devices (relays, plugs, energy meters) to Gladys Assistant.
Published by Terdious
- Devices
- Version 1.0.0
- Requires Gladys >=4.83.0
- ★ 0
This integration connects your Shelly devices to Gladys Assistant: relays, smart plugs and energy meters.
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 4.83.0 or newer.
- 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
| Field | When to fill it in |
|---|---|
| Additional device addresses | Your Shelly devices are not found automatically (another VLAN, mDNS disabled on the device or filtered by the router). Enter the IPs, comma-separated. |
| Device username | Leave it as admin: it is the only username Gen2+ devices accept. |
| Device password | You enabled authentication on your Shelly devices. One single password is used for all of them. |
⚠️ If your Shelly devices have different passwords, the integration can only reach the ones sharing the password you entered. Unify the password, or disable authentication on your trusted local network.
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).
- Open the Shelly app (or https://control.shelly.cloud/).
- Settings → User settings → Authorization cloud key.
- Click Get key: the app shows the authorization key and the server
address (something like
shelly-53-eu.shelly.cloud). - 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.
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).
MQTT (recommended past a handful of devices)
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 →
| Setting | Value |
|---|---|
| Enable | ticked |
| Server | your broker address, e.g. 10.5.0.50:1883 |
| Username / Password | your broker credentials, if it is protected |
| Enable 'MQTT Control' | ticked — this is what lets Gladys control the device over MQTT |
| RPC status notifications over MQTT | ticked — this is what sends the values in real time |
| MQTT prefix | leave 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
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:
- mDNS — your Shelly devices announce themselves on the network
(
_shelly._tcpfor Gen2+,_http._tcpfor Gen1). The Gladys core listens on behalf of the integration: containers run on a bridge network and never receive multicast traffic. - Your MQTT broker, if you configured one — see below.
- The addresses you typed in step 2.
- 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:
- 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.
- 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.
- 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 component | What you get in Gladys |
|---|---|
switch:N | On/Off (controllable), power (W), voltage (V), current (A), total energy (kWh), internal temperature (°C) |
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:N | Total and returned energy, per phase and total (kWh) |
em1:N / em1data:N | Single-phase equivalents (Shelly Pro EM, 1PM Mini Gen3) |
pm1:N | Power, voltage, current and energy of a standalone meter (PM Mini) |
temperature:N | Temperature (°C) |
humidity:N | Humidity (%) |
devicepower:N | Battery level (%) |
Hardware validated by design against real payloads: Shelly Pro 3EM, Shelly Pro 4PM, Shelly Plus Plug S.
Not supported yet: roller shutters (
cover), dimmable lights (light), inputs (input). See the roadmap.
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:
| Badge | Meaning |
|---|---|
| Local | Nominal. Gladys talks directly to the device on your network. |
| Cloud | Gladys goes through the Shelly Cloud (you turned off "Prefer the local connection"). |
| Cloud + orange dot | Degraded: the device was not reachable locally, Gladys fell back to the cloud. Hover the badge for the reason. |
| Unreachable | Neither 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.
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.
Troubleshooting
No device found during the scan
- 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 nogenfield but a"type"field, this is a Gen1 device: supported too, over polling. - 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.
- 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.
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
- Project README — architecture and development
- Roadmap — what is done, what is coming
- Shelly Gen2+ API documentation
- Report an issue
Configuration settings
These are the settings Shelly asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Local connection (recommended) | section | No | Gladys 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. Gen2 and later are supported (Plus, Pro, Mini, Gen3, Gen4); Gen1 devices are not supported yet. |
| Additional device addresses | string | No | Optional. 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 username | string | No | Only if you enabled authentication on your Shelly devices. On Gen2+ the username is always 'admin' — leave it as is. |
| Device password | secret | No | Only if you enabled authentication on your Shelly devices. A single password is used for every device — set the same one on all of them, or leave this empty and disable authentication on your local network. |
| Shelly Cloud (fallback) | section | No | Optional. 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 fallback | boolean | No | Use the Shelly Cloud when a device is unreachable on the local network. Requires the server address and the authorization key below. |
| Shelly Cloud server | string | No | The 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 key | secret | No | The 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) | section | No | Optional, 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 MQTT | boolean | No | Listen to your MQTT broker to discover, read and control the Shelly devices that publish to it. |
| MQTT broker address | string | No | Host and port of your broker, exactly as entered in the Server field of your Shelly devices. The port defaults to 1883. |
| MQTT username | string | No | Only if your broker requires authentication. Use the same credentials you set in your Shelly devices. |
| MQTT password | secret | No | Only if your broker requires authentication. |
| Advanced | section | No | Sensible 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. |
| Refresh interval | select | No | How often Gladys reads the state of every device. |
| Real-time interval (power and on/off) | select | No | How fast the values a scene reacts to are published: every instantaneous power (total, per phase, per relay) and every on/off 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
- In Gladys, open Integrations: Shelly appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/terdious/gladys-shelly:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/Terdious/gladys-shelly.
Shelly requires Gladys >=4.83.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.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation