homebridge-somfy-rfxcom 2.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,45 @@
+---
+name: Bug report
+about: Report a problem with the plugin
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behaviour:
+1. ...
+2. ...
+3. ...
+
+**Expected behaviour**
+What you expected to happen.
+
+**Logs**
+Paste relevant Homebridge logs here. Enable `debug: true` in the plugin config to get more detail.
+
+```
+<paste logs here>
+```
+
+**Environment**
+- Plugin version:
+- Homebridge version:
+- Node.js version (`node -v`):
+- OS / platform:
+- RFXtrx model:
+- RFY device(s) being controlled (blind / awning / gate / other):
+
+**Configuration (sanitized)**
+```json
+{
+  "platform": "SomfyRFXCom",
+  ...
+}
+```
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an enhancement for the plugin
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of the problem.
+
+**Describe the solution you'd like**
+What you would like the plugin to do.
+
+**Describe alternatives you've considered**
+Any alternative solutions or workarounds you've considered.
+
+**Additional context**
+Add any other context, screenshots, or RFXcom protocol references here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 John Hurliman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# homebridge-somfy-rfxcom
+
+Homebridge plugin for controlling [Somfy RTS](https://www.somfy.com/) blinds, awnings, and gates through HomeKit, via an [RFXtrx433(E)](http://www.rfxcom.com/RFXtrx433E-USB-43392MHz-Transceiver/en) USB transceiver.
+
+This fork was rewritten with motorized Somfy RTS gates in mind and is, in my experience, the most reliable option for that use case. It also works with RFY blinds and awnings.
+
+Originally based on [glefand/homebridge-rfxcom](https://github.com/glefand/homebridge-rfxcom) and [jhurliman/homebridge-rfxcom](https://github.com/jhurliman/homebridge-rfxcom).
+
+## Features
+
+- **Homebridge v2.0 support** — fully compatible with Homebridge 2.0
+- **Homebridge UI configuration** — configure the plugin directly from the Homebridge UI (no manual JSON editing required)
+- **Modern characteristic API** — uses `onGet`/`onSet` for reliable accessory restoration after restarts
+- **Node 22 / 24 support**
+
+## Compatibility
+
+| Requirement | Version |
+|---|---|
+| Homebridge | ^1.6.0 \|\| ^2.0.0 |
+| Node.js | ^22.12.0 \|\| ^24.0.0 |
+
+## Installation
+
+```bash
+npm install -g homebridge-somfy-rfxcom
+```
+
+Or install via the **Homebridge UI** by searching for `homebridge-somfy-rfxcom`.
+
+## Configuration
+
+This plugin can be configured through the **Homebridge UI**. Alternatively, add the following to your `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "SomfyRFXCom",
+      "name": "Somfy RFXCom",
+      "tty": "/dev/ttyUSB0",
+      "debug": false,
+      "rfyRemotes": [
+        {
+          "name": "Awning",
+          "deviceID": "0x010000/1",
+          "openCloseSeconds": 18
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Platform Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `platform` | Yes | — | Must be `SomfyRFXCom` |
+| `name` | Yes | — | Display name for the platform |
+| `tty` | No | `/dev/ttyUSB0` | Path to the RFXtrx USB device |
+| `debug` | No | `false` | Enable debug logging |
+
+### RFY Remotes
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `name` | Yes | — | Display name in HomeKit |
+| `deviceID` | Yes | — | Remote address and unit code (e.g. `0x010000/1`). Found in RFXMngr (Windows). |
+| `openCloseSeconds` | No | `5` | Seconds for the blinds/awning/gate to fully open or close |
+
+## How It Works
+
+Each RFY remote creates three switches in HomeKit: **Up**, **Down**, and **Stop**. The active switch auto-resets after `openCloseSeconds` to reflect that the movement has completed.
+
+## Programming a New Remote
+
+Before a Somfy device will respond to commands from your RFXtrx, the device's address must be programmed into the motor. Use [RFXMngr](http://www.rfxcom.com/epages/78165469.sf/en_GB/?ObjectPath=/Shops/78165469/Categories/Downloads) (Windows) to assign and program a new remote address, then use that address as the `deviceID` in your config.
+
+## License
+
+MIT

package/config.schema.json

@@ -0,0 +1,60 @@
+{
+  "pluginAlias": "SomfyRFXCom",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge plugin for controlling Somfy RTS blinds, awnings, and gates via an RFXtrx433(E) transceiver.",
+  "footerDisplay": "For help, see the [README](https://github.com/nroughol-dev/homebridge-somfy-rfxcom#readme).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Somfy RFXCom",
+        "required": true,
+        "description": "Display name for the platform."
+      },
+      "tty": {
+        "title": "Serial Port",
+        "type": "string",
+        "default": "/dev/ttyUSB0",
+        "description": "Path to the RFXtrx USB device."
+      },
+      "debug": {
+        "title": "Debug Mode",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable debug logging for the RFXtrx communication."
+      },
+      "rfyRemotes": {
+        "title": "RFY Remotes",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "required": true,
+              "description": "Display name of the remote in HomeKit."
+            },
+            "deviceID": {
+              "title": "Device ID",
+              "type": "string",
+              "required": true,
+              "pattern": "^0x[0-9a-fA-F]+/\\d+$",
+              "description": "Remote address and unit code (e.g. 0x000001/1). Found in RFXMngr."
+            },
+            "openCloseSeconds": {
+              "title": "Open/Close Duration",
+              "type": "integer",
+              "default": 5,
+              "minimum": 1,
+              "description": "Seconds for the blinds/awning/gate to fully open or close."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/erase.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict'
+
+// Standalone helper to erase an RFY remote address from a Somfy motor.
+// Usage: node erase.js <tty> <deviceID>
+//   e.g. node erase.js /dev/ttyUSB0 0x010000/1
+
+const rfxcom = require('rfxcom')
+
+const tty = process.argv[2] || '/dev/ttyUSB0'
+const deviceID = process.argv[3]
+
+if (!deviceID) {
+  console.error('Usage: node erase.js <tty> <deviceID>')
+  console.error('  e.g. node erase.js /dev/ttyUSB0 0x010000/1')
+  process.exit(1)
+}
+
+const rfxtrx = new rfxcom.RfxCom(tty, { debug: true })
+const rfy = new rfxcom.Rfy(rfxtrx, rfxcom.rfy.RFY)
+
+rfxtrx.initialise(() => {
+  rfy.erase(deviceID, (err) => {
+    if (err) {
+      console.error('Erase failed:', err)
+      process.exit(1)
+    }
+    console.log('complete')
+    process.exit(0)
+  })
+})

package/index.js

@@ -0,0 +1,235 @@
+const rfxcom = require('rfxcom')
+
+const PLUGIN_ID = 'homebridge-somfy-rfxcom'
+const PLUGIN_NAME = 'SomfyRFXCom'
+const DEFAULT_OPEN_CLOSE_SECONDS = 5
+
+let Accessory, Service, Characteristic, UUIDGen
+
+module.exports = function(homebridge) {
+  Accessory = homebridge.platformAccessory
+  Service = homebridge.hap.Service
+  Characteristic = homebridge.hap.Characteristic
+  UUIDGen = homebridge.hap.uuid
+
+  homebridge.registerPlatform(PLUGIN_ID, PLUGIN_NAME, RFXComPlatform, true)
+}
+
+function RFXComPlatform(log, config, api) {
+  this.log = log
+  this.config = config || { platform: PLUGIN_NAME }
+  this.tty = this.config.tty || '/dev/ttyUSB0'
+  this.debug = this.config.debug || false
+
+  const rfyRemotes = this.config.rfyRemotes || this.config.rfyremotes
+  this.rfyRemotes = Array.isArray(rfyRemotes) ? rfyRemotes : []
+
+  this.accessories = {}
+  this.rfxtrx = null
+  this.rfy = null
+
+  if (api) {
+    this.api = api
+    this.api.on('didFinishLaunching', this.didFinishLaunching.bind(this))
+  }
+}
+
+// Method to restore accessories from cache
+RFXComPlatform.prototype.configureAccessory = function(accessory) {
+  this.log(
+    `Loaded from cache: ${accessory.context.name} (${accessory.context
+      .switchID})`
+  )
+
+  const existing = this.accessories[accessory.context.switchID]
+  if (existing) this.removeAccessory(existing)
+
+  this.accessories[accessory.context.switchID] = accessory
+}
+
+// Method to setup accesories from config.json
+RFXComPlatform.prototype.didFinishLaunching = function() {
+  if (!this.rfyRemotes.length) {
+    this.log('No RFY remotes configured. Add remotes via the Homebridge UI to get started.')
+    this.removeAccessories()
+    return
+  }
+
+  this.rfxtrx = new rfxcom.RfxCom(this.tty, { debug: this.debug })
+  this.rfy = new rfxcom.Rfy(this.rfxtrx, rfxcom.rfy.RFY)
+
+  this.rfxtrx.on('disconnect', () => this.log('ERROR: RFXtrx disconnect'))
+  this.rfxtrx.on('connectfailed', () => this.log('ERROR: RFXtrx connect fail'))
+
+  // Compare local config against RFXCom-registered remotes
+  this.listRFYRemotes()
+    .then(deviceRemotes => {
+      this.log(`Received ${deviceRemotes.length} remote(s) from device`)
+
+      this.rfyRemotes.forEach(remote => {
+        // Handle different capitalizations of deviceID
+        remote.deviceID = remote.deviceID || remote.deviceId
+
+        const deviceID = remote.deviceID
+        const device = deviceRemotes.find(dR => deviceID === dR.deviceId)
+
+        if (device) {
+          this.addRFYRemote(remote, device)
+          this.log(`Added accessories for RFY remote ${remote.deviceID}`)
+        } else {
+          const msg = deviceRemotes.map(dR => `${dR.deviceId}`).join(', ')
+          this.log(`ERROR: RFY remote ${deviceID} not found. Found: ${msg}`)
+        }
+      })
+    })
+    .catch(err => {
+      this.log(`UNHANDLED ERROR: ${err}`)
+    })
+}
+
+RFXComPlatform.prototype.listRFYRemotes = function() {
+  return new Promise((resolve, reject) => {
+    this.rfxtrx.once('rfyremoteslist', remotes => resolve(remotes))
+
+    this.rfxtrx.initialise(() => {
+      this.log('RFXtrx initialized, listing remotes...')
+      this.rfy.listRemotes()
+    })
+  })
+}
+
+// Method to add or update HomeKit accessory
+RFXComPlatform.prototype.addRFYRemote = function(remote, device) {
+  remote.switches = {}
+
+  this.addRFYRemoteSwitch(remote, device, 'Up')
+  this.addRFYRemoteSwitch(remote, device, 'Down')
+  this.addRFYRemoteSwitch(remote, device, 'Stop')
+}
+
+RFXComPlatform.prototype.addRFYRemoteSwitch = function(remote, device, type) {
+  const deviceID = remote.deviceID
+  const switchID = `${deviceID}/${type}`
+  const name = `${remote.name} ${type}`
+
+  let accessory = this.accessories[switchID]
+  let isNew = false
+
+  if (!accessory) {
+    this.log(`Creating new accessory: ${switchID}`)
+    const uuid = UUIDGen.generate(switchID)
+    accessory = new Accessory(remote.name, uuid)
+    isNew = true
+  } else {
+    this.log(`Restoring cached accessory: ${switchID}`)
+  }
+
+  this.accessories[switchID] = accessory
+
+  accessory.context = {
+    deviceID: deviceID,
+    switchID: switchID,
+    name: name,
+    device: device,
+    isOn: accessory.context.isOn || false
+  }
+
+  remote.switches[type] = accessory
+
+  if (!accessory.getService(Service.Switch)) {
+    accessory.addService(Service.Switch, name)
+  }
+
+  accessory
+    .getService(Service.AccessoryInformation)
+    .setCharacteristic(Characteristic.Manufacturer, 'RFXCOM')
+    .setCharacteristic(Characteristic.Model, device.remoteType)
+    .setCharacteristic(
+      Characteristic.SerialNumber,
+      `${deviceID}-${device.unitCode}-${type}`
+    )
+
+  accessory
+    .on('identify', (paired, callback) => {
+      this.log(`${name} identify requested, paired=${paired}`)
+      callback()
+    })
+
+  const characteristic = accessory
+    .getService(Service.Switch)
+    .getCharacteristic(Characteristic.On)
+
+  characteristic.removeAllListeners('get')
+  characteristic.removeAllListeners('set')
+
+  characteristic
+    .onGet(() => accessory.context.isOn)
+    .onSet((value) => {
+      if (!value || type === 'Stop') {
+        this.log(`RFY STOP ${remote.deviceID}`)
+        this.rfy.stop(remote.deviceID)
+
+        setTimeout(() => {
+          for (const t in remote.switches)
+            this.setSwitch(remote.switches[t], false)
+        }, 100)
+
+        return
+      }
+
+      switch (type) {
+        case 'Up':
+          this.log(`RFY UP ${remote.deviceID}`)
+          this.rfy.up(remote.deviceID)
+          break
+        case 'Down':
+          this.log(`RFY DOWN ${remote.deviceID}`)
+          this.rfy.down(remote.deviceID)
+          break
+      }
+
+      for (const t in remote.switches)
+        this.setSwitch(remote.switches[t], t === type)
+
+      const ms = isNaN(remote.openCloseSeconds)
+        ? DEFAULT_OPEN_CLOSE_SECONDS * 1000
+        : Math.round(remote.openCloseSeconds * 1000)
+      clearTimeout(accessory.timerID)
+      accessory.timerID = setTimeout(() => this.setSwitch(accessory, false), ms)
+    })
+
+  if (isNew) {
+    this.api.registerPlatformAccessories(PLUGIN_ID, PLUGIN_NAME, [accessory])
+  } else {
+    this.api.updatePlatformAccessories([accessory])
+  }
+
+  this.setSwitch(accessory, accessory.context.isOn)
+
+  return accessory
+}
+
+RFXComPlatform.prototype.setSwitch = function(accessory, isOn) {
+  this.log(`Updating switch ${accessory.context.switchID}, on=${isOn}`)
+
+  accessory.context.isOn = isOn
+  accessory
+    .getService(Service.Switch)
+    .getCharacteristic(Characteristic.On)
+    .updateValue(isOn)
+}
+
+// Method to remove accessories from HomeKit
+RFXComPlatform.prototype.removeAccessory = function(accessory) {
+  if (!accessory) return
+
+  const switchID = accessory.context.switchID
+  this.log(`${accessory.context.name} (${switchID}) removed from HomeBridge.`)
+  this.api.unregisterPlatformAccessories(PLUGIN_ID, PLUGIN_NAME, [accessory])
+  delete this.accessories[switchID]
+}
+
+// Method to remove all accessories from HomeKit
+RFXComPlatform.prototype.removeAccessories = function() {
+  Object.values(this.accessories).forEach(accessory => this.removeAccessory(accessory))
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "homebridge-somfy-rfxcom",
+  "displayName": "Somfy RFXcom",
+  "version": "2.0.0",
+  "description": "Homebridge plugin for controlling Somfy RTS blinds, awnings, and gates via an RFXtrx433(E) transceiver.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "rfyerase": "node erase.js",
+    "rfyprogram": "node program.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nroughol-dev/homebridge-somfy-rfxcom.git"
+  },
+  "author": "Nicolas Roughol",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nroughol-dev/homebridge-somfy-rfxcom/issues"
+  },
+  "homepage": "https://github.com/nroughol-dev/homebridge-somfy-rfxcom#readme",
+  "keywords": [
+    "homebridge-plugin",
+    "rfxcom",
+    "rfxtrx",
+    "rfxtrx433",
+    "rfxtrx433e",
+    "433",
+    "somfy",
+    "rts",
+    "rfy",
+    "homebridge",
+    "homekit",
+    "window",
+    "blinds",
+    "awning",
+    "gate",
+    "remote"
+  ],
+  "engines": {
+    "homebridge": "^1.6.0 || ^2.0.0",
+    "node": "^22.12.0 || ^24.0.0"
+  },
+  "dependencies": {
+    "rfxcom": ">=2.1.0"
+  }
+}

package/program.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict'
+
+// Standalone helper to program an RFY remote address into a Somfy motor.
+// Put the motor into programming mode first, then run:
+//   node program.js <tty> <deviceID>
+//   e.g. node program.js /dev/ttyUSB0 0x010000/1
+
+const rfxcom = require('rfxcom')
+
+const tty = process.argv[2] || '/dev/ttyUSB0'
+const deviceID = process.argv[3]
+
+if (!deviceID) {
+  console.error('Usage: node program.js <tty> <deviceID>')
+  console.error('  e.g. node program.js /dev/ttyUSB0 0x010000/1')
+  process.exit(1)
+}
+
+const rfxtrx = new rfxcom.RfxCom(tty, { debug: true })
+const rfy = new rfxcom.Rfy(rfxtrx, rfxcom.rfy.RFY)
+
+rfxtrx.initialise(() => {
+  rfy.program(deviceID, (err) => {
+    if (err) {
+      console.error('Program failed:', err)
+      process.exit(1)
+    }
+    console.log('complete')
+    process.exit(0)
+  })
+})