homebridge-shelly-3em-energy

Homebridge plugin for Shelly 3EM-63 Gen3 and Shelly EM Gen3 energy meters — with automatic mDNS discovery and Apple HomeKit integration.

⚠️ Important limitation — Apple HomeKit does not support watts

Apple HomeKit has no native accessory type for electrical power or energy consumption. As a workaround, this plugin exposes energy data using a Light Sensor, where 1 lux = 1 watt. The numeric value is accurate, but the unit displayed in the Apple Home app will be lux (lx), not watts (W). This is a platform limitation and cannot be changed without Apple adding native energy monitoring support to HomeKit.

If you want to see proper energy data with the correct unit and historical graphs within the Apple ecosystem, the Eve app (free, no account required) reads HomeKit energy characteristics and displays them correctly alongside the Home app.

Supported devices

| Device | Type | Accessories created | |---|---|---| | Shelly 3EM-63 Gen3 | Three-phase | Total + Phase A + Phase B + Phase C | | Shelly EM Gen3 | Single-phase (2 clamps) | Channel A + Channel B |

How it works

Automatic discovery

The plugin listens for the _shelly._tcp mDNS service on the local network — the same mechanism used by homebridge-shelly-ng. When a supported Shelly energy meter is found, it is registered in HomeKit automatically with no manual configuration required.

A query is sent at startup and repeated every 30 seconds to catch newly connected devices.

What you see in the Home app

Each accessory appears as a Light Sensor:

• The value shown is numerically equal to watts consumed (1 lx = 1 W)
• The maximum displayable value is 100 000 W
• Each accessory also includes a Contact Sensor that opens when consumption exceeds a configurable threshold (default: 5 000 W) — useful for automations and notifications

Installation

npm install -g homebridge-shelly-3em-energy

Or search for homebridge-shelly-3em-energy in the Homebridge Config UI X plugin store.

Minimal configuration (automatic discovery)

Add to your Homebridge config.json — no further setup needed:

{
  "platforms": [
    {
      "platform": "Shelly3EM",
      "name": "Shelly Energy"
    }
  ]
}

The plugin will automatically discover all Shelly 3EM-63 Gen3 and EM Gen3 devices on your network.

Advanced configuration

Use the devices array to customise names, exclude devices, force a static IP, or change per-device options:

{
  "platforms": [
    {
      "platform": "Shelly3EM",
      "name": "Shelly Energy",
      "mdns": {
        "enable": true,
        "interface": "eth0"
      },
      "devices": [
        {
          "id": "shellyem3g3-aabbcc112233",
          "name": "Home",
          "showPhases": true,
          "alertThreshold": 8000
        },
        {
          "id": "shellyemg3-ddeeff445566",
          "name": "Garage",
          "showChannels": true,
          "alertThreshold": 3000
        },
        {
          "ip": "192.168.1.105",
          "name": "Warehouse",
          "model": "3em"
        },
        {
          "id": "shellyem3g3-000000000000",
          "exclude": true
        }
      ]
    }
  ]
}

Configuration reference

mdns section

| Field | Default | Description | |---|---|---| | enable | true | Set to false to disable automatic mDNS discovery. | | interface | (all) | Network interface for mDNS (e.g. eth0). Leave blank to use all interfaces. |

devices section (all fields optional)

| Field | Description | |---|---| | id | mDNS device ID (e.g. shellyem3g3-aabbcc112233). Links this config entry to a discovered device. | | name | Custom name shown in the Home app. | | ip | Static IP address. Use when mDNS discovery does not work (e.g. VLANs, network segmentation). | | model | "3em" or "em". Auto-detected if omitted. | | exclude | true to prevent this device from being added to HomeKit. | | username / password | Credentials, if device authentication is enabled. | | pollInterval | Seconds between data reads (default: 10, min: 5). | | showPhases | Show individual phases A/B/C for 3EM devices (default: true). | | showChannels | Show both channels A/B for EM Gen3 devices (default: true). | | alertThreshold | Watts above which the contact sensor opens (default: 5000). |

Troubleshooting

Devices are not discovered automatically

• Make sure the NAS/server running Homebridge and the Shelly devices are on the same Layer 2 subnet. mDNS does not cross VLANs without a relay.
• Try setting mdns.interface to a specific network interface.
• As a fallback, set a static IP using the ip field in the devices array.

Error: addMembership ENOBUFS

• Your machine has too many active network interfaces. Specify one in mdns.interface (e.g. eth0 or bond0).

Values shown as "lux" instead of "watts"

• This is an Apple HomeKit limitation. The numeric value is correct — only the unit label and icon differ. See the disclaimer at the top of this page.

Contributing

Issues and pull requests are welcome on GitHub.

License

MIT © see LICENSE