homebridge2.0-shelly

Homebridge 2.0 compatibility fork of homebridge-shelly, a Homebridge plugin for Shelly that enables HomeKit support for first generation Shelly devices.

The npm package name is homebridge-2-0-shelly. The repository/display name is homebridge2.0-shelly.

This fork keeps the Homebridge platform alias as Shelly, so existing config.json entries can continue to work when switching from the original plugin. The internal Homebridge plugin identifier is homebridge-2-0-shelly, matching the npm package name expected by Homebridge.

For the next generation, see homebridge-shelly-ng.

Homebridge 2.0 compatibility

This fork updates deprecated Homebridge/HAP API usage that breaks on Homebridge 2.0 while retaining fallback support for Homebridge 1.x:

• Service.BatteryService now falls back to Service.Battery.
• Characteristic.Formats and Characteristic.Perms now use homebridge.hap.Formats and homebridge.hap.Perms.
• Accessory categories now use homebridge.hap.Categories, with fallback support for the old Accessory.Categories location.

Supported devices

• Shelly 1
• Shelly 1L
• Shelly 1PM
• Shelly 2 1
• Shelly 2.5 1
• Shelly 3EM
• Shelly 4Pro
• Shelly Air
• Shelly Bulb 2
• Shelly Button 1 3
• Shelly Dimmer
• Shelly Dimmer 2
• Shelly Door/Window
• Shelly Door/Window 2 3
• Shelly Duo
• Shelly EM
• Shelly Flood
• Shelly HD
• Shelly H&T
• Shelly i3
• Shelly Motion 4
• Shelly Plug
• Shelly Plug S
• Shelly Plug US
• Shelly RGBW2
• Shelly Sense
• Shelly Uni
• Shelly Vintage

Is your device not on the list? See the section about unsupported devices below.

Notes

1 To use Shelly 2 or Shelly 2.5 in roller shutter mode the device must have been calibrated and be running firmware version 1.4.9 or later.

2 Requires firmware version 1.5.1 or later.

3 Requires firmware version 1.8.0 or later.

4 Requires setting the Internet & Security -> CoIoT -> Remote address option on the Shelly device to the IP address of your device running homebridge.

Installation

1. Install Homebridge by following the instructions.
2. Install this plugin using Homebridge UI, or by running:

   npm install -g homebridge-2-0-shelly

3. Add the configuration to your homebridge config.json.

Configuration

In most cases, simply adding this plugin to the homebridge config.json will be enough:

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

Your Shelly devices should then be automatically discovered, as long as they use the stock firmware (no Tasmota etc.) and are on the same network and subnet as the device running homebridge. See this wiki page if that doesn't work.

To see a list of all discovered devices, visit the administration page by going to http://<IP-ADDRESS>:8181/, where IP-ADDRESS is the address of the device that you are running homebridge on.

Network interface

Sometimes setting the "networkInterface" option to the name of the network interface or the local IP address of your device will help when your devices aren't automatically discovered, or you see error messages like addMembership EADDRNOTAVAIL or addMembership EADDRINUSE.

Authentication

Set the "username" and "password" options if you have restricted the web interface with a username and password. Note that this configuration applies to all Shelly devices.

Request timeout

The "requestTimeout" option can be used to configure the timeout for HTTP requests to the Shelly devices. Specify in milliseconds. Default is 10 seconds.

Stale timeout

Use the "staleTimeout" option to configure how long a device can be offline before it is regarded as stale and unregistered from HomeKit. Specify in milliseconds. Set to 0 or false to disable. Disabled by default.

Administration interface

By default, this plugin will launch an HTTP server on port 8181 to serve an administration interface. You can disable this by setting "admin"."enabled" to false. You can also change the port number using "admin"."port".

Device specific configurations

Configurations for specific Shelly devices can be set using the "devices" array. Each object in the array must contain an "id" property with the ID of the Shelly device that you want to target. IDs are always made up of 6 or 12 hexadecimal characters and can be found in the Shelly Cloud app or the web interface of a device, under Settings -> Device info -> Device ID.

General configurations

• "exclude" - set to true to exclude the device from Homebridge.
• "username" and "password" - set these if you have restricted the web interface of the device with a username and password. This will override the global "username" and "password" options.
• "name" - sets a custom name for the device.

Shelly switch configurations

Applies to Shelly 1, 1PM, 2 and 2.5 in relay mode, 4Pro, EM, Plug and Plug S.

• "type" - sets the type of accessory the device is identified as. Available types are "contactSensor", "motionSensor", "occupancySensor", "outlet", "switch" (default) and "valve".

Shelly 2.5 configurations

• "type" - in roller mode, the device can be identified as either "door", "garageDoorOpener", "window" or "windowCovering" (default).

Shelly RGBW2 configurations

• "colorMode" - set to "rgbw" (default) to have HomeKit control all four channels of the device (R, G, B, and W), or to "rgb" to omit the W channel.

Example configuration

"platforms": [
  {
    "platform": "Shelly",
    "name": "Shelly",
    "username": "admin",
    "password": "pa$$word",
    "devices": [
      { "id": "74B5A3", "exclude": true },
      { "id": "A612F0", "username": "admin", "password": "pa$$word2" },
      { "id": "6A78BB", "colorMode": "rgb" },
      { "id": "AD2214", "name": "My Device" },
      { "id": "1D56AF", "type": "outlet" }
    ],
    "admin": {
      "enabled": true,
      "port": 8181
    }
  }
]

Unsupported devices

If you have a Shelly device that is not yet supported by this plugin you can help adding support for it by following these steps:

1. Open the Shelly device web interface and collect its device type, firmware version, status output and settings output.
2. Create a new issue and post that information.

Credits

Original plugin by Alexander Rydén, published as homebridge-shelly.

Homebridge 2.0 compatibility patch by 0xSkipper81.

This fork keeps the original MIT license and project credits.

Original Donations

Alexander Rydén develops the original plugin in his spare time. If you like it and you find it useful, please consider donating a small amount by clicking the button below. That will allow him to buy new Shelly devices so that he can add support for them.