homebridge-shelly-matter

Expose Shelly devices to Apple Home (and other Matter controllers) through Homebridge 2.x — including live power and cumulative energy metering, which Apple Home displays starting with iOS/tvOS 27.

HomeKit's own accessory protocol (HAP) has no energy characteristics; Matter has. Homebridge v2.2.0 added the Matter ElectricalPowerMeasurement and ElectricalEnergyMeasurement clusters to its plugin API, and this plugin bridges Shelly's native metering onto them.

This is a Matter-only plugin — it publishes no HAP accessories, so a Matter-enabled bridge is required: in the Homebridge UI, open the plugin's bridge settings and turn on "Enable Matter" (optionally turning off "Enable HAP", which this plugin does not use). If you want classic HAP exposure and don't need energy metering, use one of the HAP Shelly plugins instead.

Requirements

• Homebridge v2.3.0 or later with Matter enabled on the bridge. Earlier versions are missing the composed-accessory Matter fixes this plugin depends on — on them, Apple Home stops responding to controls ~30 seconds after pairing.
• Node.js 22.12+
• iOS/tvOS 27+ to see energy data in Apple Home (the accessories themselves work on earlier versions)

Pairing with Apple Home

Pair using the bridge's Matter pairing code — not the HAP QR code. A child bridge with HAP enabled advertises both, and since this plugin publishes no HAP accessories, pairing the HAP QR code adds an empty bridge with no devices. The Matter pairing code and QR are printed in the Homebridge log at startup. Turning off "Enable HAP" in the bridge settings removes the misleading HAP QR code entirely — recommended, since this plugin does not use HAP at all. Homebridge UI v5.28.0+ does all of this automatically: it recognizes this plugin as Matter-only and creates its child bridges with Matter on and HAP off.

Apple Home behaviours

• Tile wattage follows the Matter device type: only outlet-typed accessories show it. Power metering works for every accessory type this plugin exposes, but lights and switches — even though they publish identical power and energy data — show no consumption on their own tiles. To get live wattage, set the channel's accessory type to outlet. Prefer a light look? Use the Home app's "Show As" → Light on the outlet afterwards — the display override does not affect wattage (verified against certified hardware as well), and "Show As" is only offered on outlet-typed accessories in the first place.
• Apple's Energy view lists individual devices only for certified (native) Matter accessories. Bridged accessories' consumption is counted in the whole-home total, but they are not listed per-device — regardless of reporting shape, power topology, or endpoint structure (we verified by replicating a certified smart plug's exact Matter structure on this bridge). A Homebridge bridge cannot carry a device attestation certificate, so this is an Apple policy limitation, not a plugin gap.
• Commissioned controllers (fabrics) are shown in the Homebridge UI starting with v5.28.0 (plugin menu > Bridge Settings); this plugin also lists them in its own settings page ("Connected controllers").

Device support

Support comes in three tiers. "Tested" means validated against real devices on a live Apple Home installation; "untested" means the mapping is implemented by faithfully following the same protocol layer the tested devices use, but no real device of that kind has been on our bench yet. If you run an untested device, please report whether it works — one confirmation moves it to tested.

Supported and tested

• Shelly Gen 2/3 relays and plugs (Plus/Pro 1, 1PM, 2PM in switch profile, Pro 4PM, Plus Plug S, …)
  • On/off control (as light, outlet, or switch — configurable per channel)
  • Live power (W), voltage, current
  • Cumulative energy (kWh), including returned energy where the device measures it
• Multi-channel devices appear as independent accessories per channel by default, so each channel can live in its own room; set splitChannels: false to group them into a single accessory with a control per channel.
• Shelly Gen 1 relays and the Dimmer 2 (Shelly 1, 2.5 in relay mode, Dimmer 2 — confirmed by field testing, #4, #8): on/off, dimmer brightness, and live state updates from the wall switch over CoIoT (see the Gen 1 note below). Gen 1 power metering (1PM, 2.5, Plug S, Dimmer 2, EM/3EM meters) is mapped as of 0.8.0 - note that Gen 1 relay/dimmer energy counters reset when the device reboots (device behavior).
• Shelly 2.5 in roller mode — confirmed by field testing, #11: open/close/stop, target position, position and movement state, power metering.
• Battery sensors: Shelly H&T (SHHT-1) and Shelly Flood (SHWT-1) — confirmed by field testing, #6: temperature, humidity, water leak, and battery level. Battery sensors sleep between reports, so readings update when the device wakes (periodically or on change), not continuously. Newer sensor generations (Plus H&T, H&T Gen3, Flood Gen4) are implemented but not hardware-confirmed. The Shelly Door/Window 2 (contact, light level, temperature, battery) is confirmed by field testing as of 0.9.0 (#10); its vibration detection can be exposed as a motion sensor with vibrationAsMotion (confirmed too; raise the sensor's "Vibration sensitivity" in the Shelly app if impacts do not register, the factory default of 50 is often too low). The Shelly Gas has no Matter equivalent; its alarm is exposed as a smoke or CO alarm of your choice with gasAlarm, confirmed as a CO alarm by field testing (#10). Battery sensors that are asleep when Homebridge starts are restored from their last reported state (once the plugin has seen them awake once) and refresh when they next report. Gen 1 sensor models report over CoIoT — the note below applies.

Supported, not yet tested on real hardware

• Other covers / rollers (2PM in cover profile, Plus Shutter): same cover mapping as the confirmed Shelly 2.5 in roller mode, but no hardware confirmation yet.
• Gen 2+ dimmers (Plus Wall Dimmer, 0-10V Dimmer, Dimmer Gen3, Pro Dimmer): on/off and brightness.
• Other Gen 1 models (1L, 1PM, 2, 4Pro, Gen 1 plugs): same protocol paths as the tested Gen 1 devices, but no hardware confirmation yet.
• Smoke sensors (Plus Smoke, Shelly Smoke Gen 1): smoke alarm and battery level.

Gen 1 devices and CoIoT

Gen 1 devices report state changes (wall switch, Shelly app) over CoIoT, a multicast protocol that does not cross network boundaries. If your Shellys are on a different network or VLAN than Homebridge, commands from the Home app will work (those travel over routed HTTP) but state changes will not appear. Either keep Gen 1 devices on the same network as Homebridge, or set each device's CoIoT peer (device web page > Internet & Security > Advanced Developer Settings) to <homebridge-ip>:5683, which sends updates as routed unicast and works across networks (allow UDP port 5683 through any firewall between them). "Enable CoIoT" must be on either way.

Could be supported — ask for it

The vendored protocol layer already parses these; they need (and will get) a Matter mapping. Open an issue if you own one and want it prioritized — we can usually provide a beta build to test:

• RGB / RGBW / CCT lights (RGBW2, Plus RGBW PM, bulbs)
• Sensors: Motion, BLU sensors via a Shelly BLE gateway — including battery level
• Buttons and inputs (i3, i4, wall inputs) as stateless switches
• TRV / thermostats

Not mappable to Matter as what they are: gas detectors (no Matter device type; exposed as a smoke or CO alarm with gasAlarm), tilt.

Device table

The device id (shown in the plugin's log and settings page, e.g. shellyplus1-A1B2C3) identifies the model. Statuses: ✅ tested on real hardware · 🧪 in beta with a field tester · 🟡 implemented, awaiting a hardware confirmation · ⏳ planned, ask for it · ❌ not mappable to Matter.

| Device | Device id starts with | Exposed as | Status | |---|---|---|---| | Shelly 1 | shelly1 | light / outlet / switch | ✅ #4 | | Shelly Plus 1 | shellyplus1 | light / outlet / switch | ✅ | | Shelly Plus Plug S | shellyplusplugs | outlet + power/energy | ✅ | | Shelly Pro 2PM (switch profile) | shellypro2pm | 2× light / outlet / switch + power/energy | ✅ | | Shelly Pro 4PM | shellypro4pm | 4× light / outlet / switch + power/energy | ✅ #2 | | Shelly Dimmer 2 | shellydimmer2 | dimmable light + power/energy | ✅ #4 | | Shelly H&T (SHHT-1) | shellyht | temperature + humidity + battery | ✅ #6 | | Shelly Flood (SHWT-1) | shellyflood | water leak + temperature + battery | ✅ #6 | | Shelly 2.5 (relay mode) | shellyswitch25 | 2× light / outlet / switch | ✅ #8 | | Shelly 2.5 (roller mode) | shellyswitch25 | window covering + power/energy | ✅ #11 | | Other Gen 1 relays/plugs (1L, 1PM, 2, 4Pro, Plug, Plug S) | shelly1l, shelly1pm, shellyplug … | light / outlet / switch + power/energy where the device meters | 🟡 | | Gen 2+ relays (Plus 1PM, Plus 2PM switch, Pro 1/1PM/2/3, Minis, Gen3/Gen4 models, outdoor plugs) | shellyplus1pm, shellyplus2pm, shellypro1pm, shellypro3, shelly1g3, shelly1mini, shellyplugsg3 … | light / outlet / switch + power/energy where measured | 🟡 | | Other covers / rollers (Plus/Pro 2PM cover profile, Pro Dual Cover, Shutter) | shellyplus2pm, shellypro2cover, shellyshutter … | window covering + power/energy where measured | 🟡 | | Other dimmers (Dimmer 1, Plus Wall Dimmer, 0-10V/DALI dimmers, Pro Dimmers, Duo, Vintage) | shellydimmer, shellypluswdus, shellyplus010v, shellyddimmerg3, shellyprodm1pm, shellybulbduo, shellyvintage … | dimmable light | 🟡 | | Newer H&T / Flood generations (Plus H&T, H&T Gen3, Flood Gen4) | shellyplusht, shellyhtg3, shellyfloodg4 | temperature + humidity / water leak + battery | 🟡 | | Shelly Door/Window 2 | shellydw2 | contact + light level + temperature + battery (vibration as motion, opt-in) | ✅ #10 | | Shelly Door/Window 1 | shellydw | contact + light level + battery (vibration as motion, opt-in) | 🟡 | | Shelly Plus Smoke, Shelly Smoke (Gen 1) | shellyplussmoke, shellysmoke | smoke alarm + battery | 🟡 | | Shelly Gas | shellygas | alarm as smoke or CO alarm (opt-in gasAlarm; no Matter gas type) | ✅ #10 (CO alarm mode) | | Motion sensors | shellymotionsensor, shellymotion2 | motion + battery | ⏳ | | Buttons and inputs (Button1, i3, Plus i4) | shellybutton1, shellyix3, shellyplusi4 … | stateless switches | ⏳ | | RGB / RGBW / CCT lights (RGBW2, Color Bulb, Plus RGBW PM, Pro RGBWW PM) | shellyrgbw2, shellycolorbulb, shellyplusrgbwpm … | color lights | ⏳ | | Shelly EM Gen4 | shellyemg4 | relay as outlet + power/energy on the tile, second clamp as electrical sensor | ✅ #7 | | Shelly Pro 3EM / 3EM-63 Gen3 | shellypro3em, shelly3em63g3 | phase A/B/C electrical sensor endpoints (the total channel is hidden by default - the phases already sum to it, and exposing both double-counts in Apple Home's Energy tab; { "channel": 0, "hidden": false } opts it in) | ✅ #3 | | Other energy meters (Gen 1 EM / 3EM, Pro EM, PM Mini) | shellyem, shellyem3, shellypmmini … | electrical sensor endpoints (merged onto the relay where one exists - Gen 1 EM/3EM: first clamp on the contactor relay); Apple shows no measurement tile for relay-less meters | 🟡 | | TRV / thermostats | shellytrv … | thermostat | ⏳ | | BLU devices | via a Shelly BLE gateway | depends on device | ⏳ | | Shelly Wall Display | shellywalldisplay | — (it is a controller, not an accessory) | ❌ |

Devices without supported components are discovered but skipped with a log message.

Configuration

Most configuration happens in the plugin settings UI: discovered devices appear in a table where each device gets a friendly name, and each device (or each channel of a multi-channel device) gets an accessory type and a hide toggle. Everything is stored in a single devices array:

{
  "platform": "ShellyMatter",
  "name": "ShellyMatter",
  "mdnsDiscover": true,
  "devices": [
    { "device": "shellyplus1-441793AABBCC", "name": "Office Ceiling" },
    { "device": "shellyplus1-441793DDEEFF", "accessoryType": "switch" },
    {
      "device": "shellypro2pm-EC62AABBCC",
      "name": "Garage",
      "channels": [
        { "channel": 0, "name": "Garage Light" },
        { "channel": 1, "name": "Garage Door", "accessoryType": "switch" }
      ]
    },
    {
      "device": "shellypro2pm-EC62DDEEFF",
      "name": "Cinema",
      "splitChannels": false,
      "channels": [
        { "channel": 1, "accessoryType": "switch", "hidden": true }
      ]
    },
    { "host": "192.168.1.50", "powerMetering": false },
    { "device": "shellydw2-483FDAAABBCC", "name": "Package Box", "vibrationAsMotion": true },
    { "device": "shellygas-7C87CEAABBCC", "gasAlarm": "smoke" }
  ]
}

• device — the device id. One entry per physical device.
• host — IP address/hostname, optionally with a port (ip:port, e.g. a device behind a Shelly Range Extender); needed for devices mDNS cannot find, or for every device when mDNS discovery is disabled (they are added directly).
• name — the name shown in the Home app.
• accessoryType — light, outlet, or switch. Applies to relay/switch channels only (covers and dimmers have a fixed type). Defaults: plugs are outlets, wired relay devices are lights.
• hidden — set true to not expose the device (or a channel) to Matter at all. One inverted default: on three-phase meters the total channel (channel 0) is hidden unless you set "hidden": false on it — the phases already sum to the total, and exposing both would double-count energy in Apple Home.
• channels — per-channel settings for multi-channel devices (channel is 0-based): name, accessoryType, hidden. A channel name is only used in the Home app when the device's channels are split into separate accessories (the default) — grouped devices always use the device name plus the channel number, and their tiles are renamed in the Home app. Channels without an entry use the device settings.
• splitChannels — multi-channel devices only, on by default: each channel is its own accessory, so channels can be assigned to different rooms (Apple Home assigns rooms per accessory — even "separate tiles" of one accessory always move rooms together). Set false to expose the device as one grouped accessory. Changing this re-creates the device's accessories with fresh identities — reassign rooms after.
• powerMetering — set false to drop the power/energy clusters on a metering device.
• vibrationAsMotion — Door/Window sensors only (in the settings table: "impact as motion"): set true to expose the vibration (impact) detection as a motion sensor; an impact shows as motion for 10 seconds, each new impact restarts that window (Matter has no vibration sensor type, so Apple Home shows it as motion; off by default).
• gasAlarm — Shelly Gas only (in the settings table: "alarm shown as"): smoke or co exposes the detector's alarm as a smoke or carbon monoxide alarm (mild gas = warning, heavy gas = critical; the ppm value is not shown). Matter has no gas detector type, so this is a deliberate re-mapping; not exposed by default. The detection itself is a device setting: enable vibration and raise "Vibration sensitivity" in the Shelly app (the factory default of 50 is often too low; 100 works).

Devices need no entry at all when the defaults fit — entries only record deviations.

The platform also accepts rpcOverUdp (default false): see RPC over UDP below. It also accepts mdnsDiscover (default true). Set it to false to turn off background mDNS discovery — devices with a configured host still connect directly, so this is safe once every device has a fixed IP. New devices are then added by IP in this list, or via the settings UI's Scan network button (which runs a one-off scan regardless of this setting).

RPC over UDP (Gen 2+)

Gen 2+ devices normally report state changes over a WebSocket the plugin keeps open to each device. rpcOverUdp: true (settings form: "RPC over UDP") makes the plugin also listen on UDP port 8585, and devices you configure for it push their reports there instead:

1. On the device's web page open Settings > RPC over UDP, enable it, set the destination to <homebridge-ip>:8585 and the listening port to 8585.
2. Reboot the device (the setting only takes effect after a restart).
3. Restart Homebridge (or the child bridge). The settings table then shows "RPC over UDP" under the device; devices without the setting stay on "WebSocket", and a device configured for UDP while the plugin option is off (or pointing at another host) is flagged there.

Which transport for which device:

• Battery devices (Plus H&T, H&T Gen3, Flood Gen4, Plus Smoke): use UDP. They sleep and cannot hold a WebSocket, so this is the simplest way to receive their reports (not hardware-confirmed yet).
• Always-connected devices: WebSocket is the better default. It is reliable and ordered, and the plugin notices immediately when a device drops. UDP is fire-and-forget (a lost packet is a missed update until the device's next periodic report) and offers no such signal. Use it on mains devices only if you prefer push, e.g. on large installations. Verified on a Plus Plug S and two Plus 1 (Home app and wall switch both reflected immediately).
• A device has a single UDP destination, so it cannot also feed another integration over UDP; the Homebridge host needs a stable IP.

Changing a device's accessory type or split setting

Changing the accessory type of a device or channel, hiding channels, toggling splitChannels, powerMetering, vibrationAsMotion or gasAlarm — all composition changes are applied when the bridge restarts, so restart Homebridge (or this child bridge) after saving. Such changes deliberately re-create the device's Matter accessories with fresh identities (Apple Home mishandles devices that reappear with the same identity but a different structure, leaving them uneditable). The change is applied while the bridge restarts, before it comes back online, so paired controllers see a clean transition. Apple Home processes the change asynchronously — the re-created accessories typically appear after 2–3 minutes, in the room the bridge itself is assigned to; move them to their rooms once after the change.

Make all structural changes in one settings pass rather than several in a row: Apple Home ingests structure changes slowly, and back-to-back changes can make the second one take considerably longer to appear.

Troubleshooting: Apple Home's ingestion of structure changes can stall — if a re-created accessory has not appeared after ~5 minutes, reboot your Apple TV/HomePod hub and give it a few minutes; the pending change then processes (existing accessories keep their rooms). In the worst case the bridge may briefly show as "Matter Accessory" with devices missing — the same hub reboot heals it, though the bridge tile's own name/room may need to be set again.

Uninstalling / reinstalling

If the Homebridge UI option to remove plugin data on uninstall is enabled, uninstalling this plugin also deletes the bridge's Matter commissioning storage — which un-pairs it from Apple Home and discards room assignments. To move or reinstall the plugin without re-pairing, keep that option off (or back up <storage>/matter/<bridge-id>/ first); the pairing survives a plain reinstall.

Attribution

The Shelly protocol and device layer (src/shelly/) is derived from matterbridge-shelly by Luca Liguori, licensed under Apache-2.0 — see NOTICE. This plugin is an independent port to the Homebridge Matter plugin API and is not affiliated with Matterbridge or Allterco Robotics.