1.9.0 • Published 5d ago

@lucavb/homebridge-shelly-ds9

Licence

GPL-3.0

Version

1.9.0

Deps

Size

496 kB

Vulns

Weekly

447

Summary Dependency Versions

homebridge-shelly-ds9

Homebridge plugin for Shelly Gen2/Gen3/Gen4 devices, enabling HomeKit support via mDNS discovery and WebSocket RPC.

Supported devices

Installation

Either install this plugin through Homebridge Config UI X or manually by following these instructions:

Install Homebridge by following the instructions.
Install this plugin by running npm install -g @lucavb/homebridge-shelly-ds9.
Add this plugin to the Homebridge config.json:

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

By default, devices will be discovered on your local network using mDNS and WebSockets will then be used to communicate with them.

Shelly Sensor Add-on

Compatible host devices with the Shelly Plus Add-on can expose DS18B20 and DHT22 peripherals as HomeKit sensors.

Prerequisites (configured in the Shelly web UI, not in Homebridge):

Enable the add-on under Settings → Add-on and reboot the host device (addon_type must be sensor).
Add peripherals under Peripherals (DS18B20 temperature probes and/or a DHT22).
Reboot again after adding or removing peripherals.

HomeKit accessories created by this plugin:

Add-on peripheral	HomeKit service
DS18B20 (`temperature:100`–`104`)	Temperature Sensor
DHT22 (`temperature:N` + `humidity:N`, same ID)	Temperature + Humidity Sensor on one accessory

DS18B20 and DHT22 cannot be used on the same 1-Wire bus. Add-on digital/analog inputs are not supported yet.

Per-sensor exclusion is available via temperature:100.exclude and humidity:100.exclude in the device config (component IDs 100–199).

Configuration

The following configuration options are available. Note that they are all optional.

{
  "devices": [
    {
      "id": "e.g. shellyplus1-abcdef123456",
      "name": "My Device",
      "exclude": false,
      "hostname": "e.g. 192.168.1.200",
      "password": "pa$word",
      "switch:0": {
        "exclude": false,
        "type": "switch"
      },
      "switch:1": {
        "exclude": false,
        "type": "outlet"
      },
      "switch:2": {
        "exclude": false,
        "type": "switch"
      },
      "switch:3": {
        "exclude": false,
        "type": "switch"
      },
      "cover:0": {
        "exclude": false,
        "type": "windowCovering"
      },
      "temperature:100": {
        "exclude": false
      },
      "humidity:100": {
        "exclude": false
      }
    }
  ],
  "mdns": {
    "enable": true,
    "interface": "e.g. eth0 or 192.168.1.100"
  },
  "websocket": {
    "requestTimeout": 10,
    "pingInterval": 60,
    "reconnectInterval": [ 5, 10, 30, 60, 300, 600 ]
  }
}

See below for descriptions of each configuration option.

Option	Description
`devices`	An array of one or more objects with options for specific devices.
`devices. id`	The device ID, e.g. `shellyplus1-abcdef123456`. Find it in the Shelly app under device settings, or in the device web UI hostname.
`devices. name`	The name of the device. This will be shown in the homebridge log and will be used as the default name when the device is added to HomeKit. Note though that setting this value after the device has been added will not change the name in HomeKit. If no name is specified, this plugin will use the device name set in the Shelly app, or the name of the device model.
`devices. exclude`	Set this option to `true` to make this plugin ignore this device.
`devices. hostname`	The IP address or hostname of the device. Set this value if your device can't be discovered automatically.
`devices. password`	The password to use if authentication has been enabled for the device.
`devices. switch:0-3.exclude`	Set this option to `true` to prevent the switch with the specified index number from being added to HomeKit.
`devices. switch:0-3.type`	The type of accessory used to represent the switch with the specified index number. Available options are `"outlet"` and `"switch"` (default).
`devices. cover:0.exclude`	Set this option to `true` to prevent this cover from being added to HomeKit.
`devices. cover:0.type`	Only available for devices in cover mode. The type of accessory used to represent the cover. Available options are `"door"`, `"window"` (default) and `"windowCovering"`.
`devices. light:0.exclude`	Set this option to `true` to prevent this light from being added to HomeKit.
`devices. temperature:100.exclude`	Set this option to `true` to prevent an add-on DS18B20 temperature sensor (component ID 100) from being added to HomeKit. Same pattern applies for `temperature:101`–`199`.
`devices. humidity:100.exclude`	Set this option to `true` to prevent an add-on DHT22 humidity sensor (component ID 100) from being added to HomeKit. Same pattern applies for `humidity:101`–`199`.
`mdns`	Settings for the mDNS device discovery service.
`mdns. enable`	Set this option to `false` to disable automatic device discovery using mDNS.
`mdns. interface`	The network interface to use when sending and receiving mDNS packets. You probably don't need to use this setting unless you know what you're doing. If not specified, all available network interfaces will be used.
`websocket. requestTimeout`	The time, in seconds, to wait for a response before a request is aborted.
`websocket. pingInterval`	The interval, in seconds, at which ping requests should be made to verify that the connection is open. Set to `0` to disable.
`websocket. reconnectInterval`	The interval, in seconds, at which a connection attempt should be made after a socket has been closed. If an array or a comma-separated list of numbers is specified, the first value will be used for the first connection attempt, the second value for the second attempt and so on. When the last value has been reached, it will be used for all subsequent connection attempts; unless the value is `0`, in which case no more attempts will be made. Set to `0` to disable.

@lucavb/homebridge-shelly-ds9

homebridge-shelly-ds9

Supported devices

Installation

Shelly Sensor Add-on

Configuration

Maintainer

Credits

Keywords