Shelly

Local control of Shelly Gen2 Wi-Fi devices — relays, dimmers, and input modules — over the device's own HTTP control API on your LAN. No Shelly cloud account and no third-party hub sit in the middle: GEM talks straight to the device's IP address.

One Shelly device in GEM maps to one physical Shelly unit. Each channel on that unit — a relay output, a dimmer output, or a digital input — becomes a zone you add under the device. A single-channel Shelly 1 is one zone; a 4-channel Shelly Pro 4PM is four zones.

Typical uses:

• Lights — switch a Shelly relay channel on/off, or dim a Shelly Dimmer / Pro Dimmer channel.
• Garage doors and gates — wire a relay channel to the operator's trigger input and fire a momentary pulse to open/close.
• Power / appliances — switch or power-cycle (reboot) a load.
• Inputs — read the state of a Shelly input (button, switch, or dry-contact sensor) and use it in automations.

Gen2 firmware only

This driver speaks the Gen2 RPC API (/rpc/…). The older Gen1 HTTP API (/relay/0, /light/0) is not supported. Plus and Pro models ship with Gen2 firmware; older Gen1 hardware must be re-flashed to Gen2 firmware where that is available, otherwise it cannot be used here.

Prerequisites

• Put the Shelly on the same LAN GEM can reach and give it a static IP or a DHCP reservation. The integration addresses the device by IP, so a moving lease takes it offline.
• The device must answer HTTP on port 80 (the default). GEM calls the Gen2 RPC endpoint at http://<device-ip>/rpc/….
• Disable Shelly Cloud and confirm local network / LAN control is enabled in the Shelly app. The driver only uses the local HTTP API.
• If you turned on the device's built-in HTTP authentication, have the username and password ready — otherwise no credentials are needed.

Setup

1. Open Devices and add a new device. Pick the Shelly driver.
2. In Shelly IP Address enter the device's LAN IP (e.g. 192.168.1.50). Fill in HTTP Username / HTTP Password only if you enabled auth on the Shelly; leave them blank otherwise.
3. Enable the device. The driver immediately starts polling the channels you give it zones for.
4. Open Zones and add one zone per channel you want to control. Set each zone's address to the channel id (see Channel addressing below) and choose the subsystem and control type that match what the channel drives.
5. For a garage door or gate wired to a relay's trigger, set the zone (or its subsystem) to momentary so open/close fire a pulse — see Garage doors and gates.

Channel addressing

A Shelly unit numbers its channels starting at 0. The zone address tells the driver which channel to act on and, optionally, which kind of channel it is:

Address you enter	Channel it targets	Reported state
0, 1, 2, …	Bare channel id — the driver tries the relay/dimmer output first, then the input	on / off
output_0, output_1, …	A relay or dimmer output channel	on / off
relay_0, relay_1, …	A relay output reported as a dry contact	closed / open
input_0, input_1, …	A digital input channel (read-only)	on / off

The number after the prefix is the Shelly component id. So a 2-channel relay's outputs are output_0 and output_1; its inputs are input_0 and input_1.

Use a bare number when you have a simple single-output device and want the driver to figure out the channel type. Use the explicit output_ / input_ / relay_ prefix on multi-channel devices, or whenever you want to force how the state is read and reported.

Subsystem and control type

Pick the subsystem for each zone based on what the channel physically drives — the driver suggests Lights, Garage, Gates, and Power. The subsystem and the zone's control type together decide how the channel behaves and which on-screen control the user gets.

• A switched light or appliance — Lights or Power subsystem, Light Switch control. on / off energize and de-energize the relay.
• A dimmable light (Shelly Dimmer / Pro Dimmer) — Lights subsystem, Light Dimmer control. See Dimming.
• A garage door or gate — Garage / Gates subsystem; usually set momentary so open/close become a pulse. See Garage doors and gates.

Dimming

For a Shelly Dimmer or Pro Dimmer channel, set the zone's control type to Light Dimmer (light_dimmer). With that control type:

• The level command sets brightness directly (0–100). A level of 0 also turns the channel off; any level above 0 turns it on.
• State polling reports both on/off and the current brightness back to the zone, so a slider follows changes made at the wall or in the Shelly app.

If the channel is a plain relay configured as Light Switch (light_switch), the level command is treated as on/off instead — any level above 0 turns the relay on, 0 turns it off. Use Light Dimmer only on hardware that actually dims.

Garage doors and gates

Most garage and gate operators expect a momentary contact closure on their trigger input, not a relay that latches on. To get that:

1. Put the relay zone on the Garage (or Gates) subsystem.
2. Mark the zone — or the whole Garage subsystem — as momentary.

With momentary set, the driver rewrites open and close into a pulse: it closes the contact, waits the zone's Pulse Delay (delay, default 1000 ms), then re-opens it. One press triggers the operator and the relay returns to rest.

Because a momentary relay can't tell you whether the door is actually open or closed, wire a separate input (a reed/limit switch on a Shelly input channel) to report real position, add it as its own input zone, and point the relay zone's status_zone attribute at that input zone's id. The relay zone then mirrors the live open/closed state from the contact instead of guessing.

Status polling

While the device is enabled, the driver polls each of its zones in turn and writes the result back to the zone's state (and, for dimmers, level). The poll cadence is the device's Status Poll Interval (status_interval, default 1000 ms); zones are queried about 200 ms apart so a multi-channel device isn't hit all at once. If a busy device struggles, raise status_interval.

Attributes

Add these in the Attribute editor for the device or zone (most have a labeled field in the device/zone forms).

Device

Attribute	Type	Required	Default	Description
ip	string	yes	—	LAN IP of the Shelly. Shown as Shelly IP Address.
username	string	no	—	HTTP Username — only if HTTP auth is enabled on the device.
password	string (secure)	no	—	HTTP Password. Stored encrypted.
status_interval	int	no	1000	Status Poll Interval (ms) — how often each zone is polled.
relay	bool	no	—	Relay Mode toggle in the form. In practice the driver decides closed/open reporting from the per-channel relay_ address prefix (above), so prefer that on the zone address.

Zone

Attribute	Type	Required	Default	Description
address	string	yes	—	Channel id — 0, output_0, input_0, or relay_0. See Channel addressing.
delay	int	no	1000	Pulse Delay (ms) — pulse length for momentary open/close (gate/garage).
status_zone	int	no	—	Id of another zone whose state this zone should mirror (the garage reed-switch pattern above).

The zone's control type (Light Dimmer / Light Switch, etc.) is set from the zone's control picker, not as a typed attribute.

Commands

These are the commands the driver exposes. They are written and kept current by the driver, so they appear automatically on the device's Commands and can be tested there.

Command	Args	What it does
on	address	Turn the channel on (closes the relay / energizes the output).
off	address	Turn the channel off.
close	address	Energize the output (same as on).
open	address	De-energize the output (same as off).
pulse	address, delay	Momentary trigger: close the contact, wait delay ms (default 1000), then open. Used for gate/garage strikes.
reboot	address, delay	Power-cycle a load: turn the channel off, wait delay ms (default 5000), then on.
level	address, level	Set dimmer brightness (0–100); 0 also turns off. On a Light Switch channel it maps to on/off instead.
get_state	address	Read the channel's current state now and reconcile the zone.
get_config	address	Listed for completeness but not implemented in this driver — leave it unused.

Driver-managed commands

The rows above are rewritten by the driver every time the system starts. Add your own commands if you need them, but don't hand-edit the templates or args of these — your changes are overwritten on the next restart.

When a zone is set to momentary on the Garage subsystem, open and close are automatically converted to pulse before they run — see Garage doors and gates.

Troubleshooting

Symptom	Check
Device never connects; log shows shelly missing ip	The Shelly IP Address (ip) attribute is blank. Set it to the device's LAN IP.
A zone shows invalid zone address	The address polled doesn't match any zone. Confirm a zone exists for that channel and its address matches the channel id (0, output_0, input_0, …).
State never updates / responses never arrive	Disable Shelly Cloud and confirm local LAN HTTP is enabled. If a busy device is being flooded, raise Status Poll Interval (status_interval) above the 1 s default.
open/close latch the relay instead of pulsing	The zone isn't momentary. Put it on the Garage (or Gates) subsystem and mark the zone or subsystem momentary.
A dimmer's brightness never tracks	Set the zone's control type to Light Dimmer. A Light Switch channel only reports on/off.
Auth errors against a locked-down device	The Shelly has HTTP auth enabled. Fill in HTTP Username and HTTP Password to match it.

Related documentation

• Devices — add the Shelly device and set its IP / auth.
• Zones — create one zone per channel and set its address and control type.
• Subsystems — pick Lights / Garage / Gates / Power, and set momentary for gate/garage relays.
• Commands — where on / off / pulse / reboot / level appear and can be tested.
• Relay semantics — how relay open/closed states map to on/off across the system.