homebridge-garagedooropenercloud 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Tom Rodrigues & Andreas Hähnel
+
+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,101 @@
+# homebridge-garagedooropenercloud
+
+[![npm](https://img.shields.io/npm/v/homebridge-garagedooropenercloud.svg)](https://www.npmjs.com/package/homebridge-garagedooropenercloud)
+[![GitHub stars](https://img.shields.io/github/stars/torresyago/homebridge-garagedooropenercloud.svg)](https://github.com/torresyago/homebridge-garagedooropenercloud)
+
+**Homebridge plugin para abrir/cerrar garaje usando Shelly Cloud API** 🚪☁️
+
+## Descripción
+
+Fork mejorado de [jmaferreira/homebridge-garage-door-shelly1](https://github.com/jmaferreira/homebridge-garage-door-shelly1)
+
+**Novedades:**
+- ✅ Control remoto vía Shelly Cloud (**sin IP local**)
+- ✅ Polling de estado real vía Cloud API  
+- ✅ Sensor de puerta integrado (reed switch)
+- ✅ Compatible Homebridge Config UI X
+
+## 🔧 Instalación
+
+npm install -g torresyago/homebridge-garagedooropenercloud
+
+text
+
+## ⚙️ Configuración
+
+{
+"accessory": "GarageDoorOpener",
+"name": "Garage Door",
+"plugin": "homebridge-garagedooropenercloud",
+"deviceId": "441793a44db8",
+"authKey": "MTAzNDxxxxx",
+"channel": "0",
+"openTime": 20,
+"closeTime": 20,
+"polling": true,
+"pollInterval": 30,
+"debug": true
+}
+
+text
+
+### 📱 Credenciales Shelly Cloud
+
+1. **App Shelly** → Dispositivo → **Settings** → **Cloud** → **Device ID**
+2. **App Shelly** → **Perfil** → **Auth Key**
+
+## 📋 Opciones completas
+
+| Parámetro | Descripción | Por defecto |
+|-----------|-------------|-------------|
+| `deviceId` | **ID dispositivo** | **Obligatorio** |
+| `authKey` | **Auth Key** | **Obligatorio** |
+| `channel` | Canal relay | `0` |
+| `openTime` | Segundos apertura | `10` |
+| `closeTime` | Segundos cierre | `10` |
+| `polling` | Polling activo | `false` |
+| `pollInterval` | Segundos polling | `30` |
+| `debug` | Logs detallados | `false` |
+
+## 🔌 Cableado Shelly 1PM
+
+Pulsador garaje:
+├── L → Fase pulsador
+├── N → Neutro
+└── O → Pulsador (Relay)
+
+Sensor reed (SW + L):
+├── SW → Terminal reed
+└── L → Terminal reed
+
+text
+
+## 🎯 Funcionamiento
+
+Abrir/Cerrar → POST /relay/control?turn=on
+Estado → POST /device/status → input:0.state
+false → 🚪 ABIERTA
+true → 🚪 CERRADA
+
+text
+
+## 🏠 Estados HomeKit
+
+| Estado HomeKit | Valor | Sensor |
+|----------------|-------|--------|
+| **Abierta** | `0` | `false` |
+| **Cerrada** | `1` | `true` |
+| **Abriendo** | `2` | Simulado |
+| **Cerrando** | `3` | Simulado |
+
+## 👨‍💻 Autor
+
+**torresyago** - [GitHub](https://github.com/torresyago)
+
+**Basado en:**
+- [jmaferreira/homebridge-garage-door-shelly1](https://github.com/jmaferreira/homebridge-garage-door-shelly1)
+- [andreaseu/homebridge-garage-remote-http](https://github.com/andreaseu/homebridge-garage-remote-http)
+
+## 📄 Licencia
+
+MIT License

package/config.sample.json

@@ -0,0 +1,18 @@
+{
+  "accessory": "GarageDoorOpener",
+  "name": "Garage Door",
+  "plugin": "homebridge-garagedooropenercloud",
+  "cloudBaseURL": "https://shelly-38-eu.shelly.cloud/device/relay/control",
+  "statusCloudURL": "https://shelly-38-eu.shelly.cloud/device/status",
+  "deviceId": "YOUR_DEVICE_ID",
+  "authKey": "YOUR_AUTH_KEY",
+  "channel": "0",
+  "statusKey": "$.data.device_status.input:0.state",
+  "statusValueOpen": "false",
+  "statusValueClosed": "true",
+  "openTime": 20,
+  "closeTime": 20,
+  "polling": true,
+  "pollInterval": 30,
+  "debug": true
+}

package/config.schema.json

@@ -0,0 +1,112 @@
+{
+  "pluginAlias": "GarageDoorOpenerCloud",
+  "pluginType": "accessory",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "required": true,
+        "description": "Name to appear in the Home app"
+      },
+      "deviceId": {
+        "title": "Shelly Device ID",
+        "type": "string",
+        "required": true,
+        "description": "Device ID from Shelly App → Settings → Cloud → Advanced"
+      },
+      "authKey": {
+        "title": "Shelly Auth Key", 
+        "type": "string",
+        "required": true,
+        "description": "Auth Key from Shelly App → Profile"
+      },
+      "channel": {
+        "title": "Channel",
+        "type": "string",
+        "default": "0",
+        "description": "Relay channel (0 or 1)"
+      },
+      "cloudBaseURL": {
+        "title": "Cloud Control URL",
+        "type": "string",
+        "default": "https://shelly-38-eu.shelly.cloud/device/relay/control",
+        "description": "Shelly Cloud relay control endpoint"
+      },
+      "statusCloudURL": {
+        "title": "Cloud Status URL",
+        "type": "string", 
+        "default": "https://shelly-38-eu.shelly.cloud/device/status",
+        "description": "Shelly Cloud status endpoint"
+      },
+              "statusKey": {
+          "title": "Status Key",
+          "type": "string",
+          "default": "$.data["input:0"].state",
+          "description": "JSONPath for door sensor"
+        },
+        "title": "Status Key",
+        "type": "string",
+        "default": "$..["input:0"].state
+        "description": "JSONPath for door sensor (input:0.state for Shelly)"
+      },
+      "statusValueOpen": {
+        "title": "Open Status Value",
+        "type": "string",
+        "default": "false",
+        "description": "Sensor value when door is OPEN"
+      },
+      "statusValueClosed": {
+        "title": "Closed Status Value",
+        "type": "string", 
+        "default": "true",
+        "description": "Sensor value when door is CLOSED"
+      },
+      "openTime": {
+        "title": "Open Time",
+        "type": "integer",
+        "default": 10,
+        "description": "Seconds to simulate door opening"
+      },
+      "closeTime": {
+        "title": "Close Time",
+        "type": "integer",
+        "default": 10,
+        "description": "Seconds to simulate door closing"
+      },
+      "polling": {
+        "title": "Enable Polling",
+        "type": "boolean",
+        "default": true,
+        "description": "Poll real door state from Shelly Cloud"
+      },
+      "pollInterval": {
+        "title": "Poll Interval",
+        "type": "integer",
+        "default": 30,
+        "description": "Seconds between status polls"
+      },
+      "debug": {
+        "title": "Debug Mode",
+        "type": "boolean",
+        "default": false,
+        "description": "Show detailed logs"
+      },
+      "manufacturer": {
+        "title": "Manufacturer",
+        "type": "string",
+        "default": "yago",
+        "description": "Manufacturer name in HomeKit"
+      },
+      "model": {
+        "title": "Model",
+        "type": "string",
+        "default": "GarageDoorOpenerCloud",
+        "description": "Model name in HomeKit"
+      }
+    }
+  }
+}
+

package/index.js

@@ -0,0 +1,161 @@
+var Service, Characteristic;
+const packageJson = require("./package.json");
+const request = require("request");
+const jp = require("jsonpath");
+
+module.exports = function(homebridge) {
+    Service = homebridge.hap.Service;
+    Characteristic = homebridge.hap.Characteristic;
+    homebridge.registerAccessory(
+        "homebridge-garagedooropenercloud",
+        "GarageDoorOpener",
+        GarageDoorOpener
+    );
+};
+
+function GarageDoorOpener(log, config) {
+    this.log = log;
+    this.config = config;
+    this.name = config.name;
+    this.deviceId = config.deviceId;
+    this.authKey = config.authKey;
+    this.channel = config.channel || 0;
+    this.statusKey = config.statusKey || "$.data.device_status.relays[0].ison";
+    this.statusValueOpen = config.statusValueOpen !== undefined ? config.statusValueOpen : true;
+    this.statusValueClosed = config.statusValueClosed !== undefined ? config.statusValueClosed : false;
+    this.openTime = config.openTime || 20;
+    this.closeTime = config.closeTime || 20;
+    this.polling = config.polling !== false;
+    this.debug = config.debug !== false;
+    
+    this.statusCloudURL = "https://shelly-38-eu.shelly.cloud/device/status";
+    this.controlCloudURL = "https://shelly-38-eu.shelly.cloud/device/relay/control";
+    
+    this.service = new Service.GarageDoorOpener(this.name);
+    this.informationService = new Service.AccessoryInformation();
+    
+    this.informationService
+        .setCharacteristic(Characteristic.Manufacturer, "Shelly Cloud")
+        .setCharacteristic(Characteristic.Model, "Garage Door Opener")
+        .setCharacteristic(Characteristic.SerialNumber, this.deviceId);
+    
+    this.service
+        .getCharacteristic(Characteristic.TargetDoorState)
+        .on('set', this.setTargetState.bind(this));
+    
+    this.service
+        .getCharacteristic(Characteristic.CurrentDoorState)
+        .on('get', this.getCurrentState.bind(this));
+    
+    if (this.polling) {
+        setInterval(this.pollStatus.bind(this), 30000);
+        this.pollStatus();
+    }
+    
+    this.log("[%s] Initializing GarageDoorOpener accessory...", this.name);
+}
+
+GarageDoorOpener.prototype = {
+    getServices: function() {
+        return [this.informationService, this.service];
+    },
+    
+    setTargetState: function(targetState, callback) {
+        this.log("[%s] Target state: %s", this.name, targetState);
+        
+        const toggleData = {
+            id: this.deviceId,
+            channel: this.channel,
+            auth_key: this.authKey,
+            turn: "toggle"
+        };
+        
+        request.post({
+            url: this.controlCloudURL,
+            form: toggleData
+        }, (err, response, body) => {
+            if (err) {
+                this.log("[%s] Control error: %s", this.name, err.message);
+                callback(err);
+                return;
+            }
+            
+            this.log("[%s] Toggle command sent", this.name);
+            callback(null);
+        });
+    },
+    
+    getCurrentState: function(callback) {
+        this.getStatus((err, status) => {
+            if (err) {
+                this.log("[%s] Status error: %s", this.name, err.message);
+                callback(err);
+                return;
+            }
+            
+            let currentState;
+            if (status === undefined || status === null || status === false) {
+                currentState = Characteristic.CurrentDoorState.CLOSED;
+                this.log("[%s] Status: %s -> HomeKit: CLOSED (1)", this.name, status || "undefined");
+            } else if (status === true) {
+                currentState = Characteristic.CurrentDoorState.OPEN;
+                this.log("[%s] Status: %s -> HomeKit: OPEN (0)", this.name, status);
+            } else {
+                currentState = Characteristic.CurrentDoorState.STOPPED;
+                this.log("[%s] Status: %s -> HomeKit: STOPPED (4)", this.name, status);
+            }
+            
+            callback(null, currentState);
+        });
+    },
+    
+    getStatus: function(callback) {
+        const statusData = {
+            channel: this.channel,
+            id: this.deviceId,
+            auth_key: this.authKey
+        };
+        
+        request.post({
+            url: this.statusCloudURL,
+            form: statusData
+        }, (err, response, body) => {
+            if (err) {
+                callback(err);
+                return;
+            }
+            
+            try {
+                const json = JSON.parse(body);
+                if (this.debug) {
+                    this.log("[%s] FULL JSON: %j", this.name, json);
+                }
+                
+                const rawStatus = json.data.device_status.relays[0]?.ison ?? false;
+                const status = rawStatus;
+                this.log("[%s] RAW RELAY: %s", this.name, status);
+                
+                callback(null, status);
+            } catch (parseErr) {
+                this.log("[%s] Error parsing status JSON: %s", this.name, parseErr.message);
+                callback(parseErr);
+            }
+        });
+    },
+    
+    pollStatus: function() {
+        if (this.debug) {
+            this.log("[%s] Getting status: %s channel=%s&id=%s&auth_key=...", 
+                this.name, this.statusCloudURL, this.channel, this.deviceId);
+        }
+        
+        this.getStatus((err, status) => {
+            if (!err && status !== undefined) {
+                const currentState = status === true ? Characteristic.CurrentDoorState.OPEN : Characteristic.CurrentDoorState.CLOSED;
+                this.service.getCharacteristic(Characteristic.CurrentDoorState).updateValue(currentState);
+                this.service.getCharacteristic(Characteristic.TargetDoorState).updateValue(currentState === Characteristic.CurrentDoorState.OPEN ? Characteristic.TargetDoorState.OPEN : Characteristic.TargetDoorState.CLOSED);
+                this.log("[%s] Status: %s -> HomeKit: %s", this.name, status, currentState === Characteristic.CurrentDoorState.OPEN ? "OPEN (0)" : "CLOSED (1)");
+            }
+        });
+    }
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "homebridge-garagedooropenercloud",
+  "version": "1.2.0",
+  "description": "Homebridge plugin for garage door opener using Shelly Cloud API",
+  "main": "index.js",
+  "engines": {
+    "homebridge": ">=0.4.50",
+    "node": ">=12.13.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yago/homebridge-garagedooropenercloud"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "garage",
+    "garagedoor",
+    "shelly",
+    "shelly-cloud",
+    "cloud"
+  ],
+  "author": "yago",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yago/homebridge-garagedooropenercloud/issues"
+  },
+  "homepage": "https://github.com/yago/homebridge-garagedooropenercloud#readme",
+  "dependencies": {
+    "jsonpath": "^1.0.2",
+    "request": "^2.88.2"
+  }
+}