homebridge-shelly-blu-trv 1.0.8 → 1.1.1

package/README.md

@@ -3,86 +3,86 @@
 [![CI](https://github.com/agiplv/homebridge-shelly-blu-trv/actions/workflows/ci.yml/badge.svg)](https://github.com/agiplv/homebridge-shelly-blu-trv/actions)
 
 Homebridge plugin for Shelly BLU Thermostatic Radiator Valve (TRV) devices
-via the Shelly BLU Gateway Gen3.
 
-This plugin exposes BLU TRV devices to Apple HomeKit using a local Shelly BLU
-Gateway Gen3. It supports current temperature, target temperature control,
-valve position, battery level and offline detection.
+# Homebridge Shelly BLU TRV Platform Plugin
+
+Homebridge plugin for controlling Shelly BLU TRV (Thermostatic Radiator Valve) devices via a Shelly Plus/Pro Gateway. **Only manual device configuration is supported.**
 
 ## Features
 
-- BLU TRV discovery via Shelly BLU Gateway Gen3
-- Current temperature
-- Target temperature control
-- Valve position (percent)
-- Battery level
-- Offline detection
-- Multiple gateways
+- Control Shelly BLU TRV devices from HomeKit
+- Direct communication with TRVs (no cloud)
+- Battery, temperature, and valve state reporting
+- Fast polling and state updates
 
 ## Requirements
 
-- Node.js 18+
-- Homebridge 1.6+
-- Shelly BLU Gateway Gen3
-- Shelly BLU TRV
+- Homebridge v1.6+
+- Node.js v18+
+- Shelly Plus/Pro Gateway (with local network access)
+- Shelly BLU TRV devices
 
 ## Installation
 
-Install via npm:
+Install via Homebridge UI or npm:
 
-```bash
+```sh
 npm install -g homebridge-shelly-blu-trv
 ```
 
-## Configuration (Homebridge UI)
+## Configuration
 
-Add the platform under `platforms` in Homebridge configuration. Example:
+Add the platform to your Homebridge `config.json`. You **must** specify each gateway and the list of TRVs to control. **Automatic discovery is not supported.**
 
 ```json
 {
-  "platforms": [
+  "platform": "ShellyBluPlatform",
+  "gateways": [
     {
-      "platform": "ShellyBluTRV",
-      "gateways": [
-        {
-          "host": "192.168.1.50",
-          "token": "<optional-auth-token>",
-          "pollInterval": 60
-        }
+      "host": "192.168.1.10",
+      "token": "your-gateway-token",
+      "pollInterval": 60,
+      "devices": [
+        { "id": 123, "name": "Living Room" },
+        { "id": 456, "name": "Bedroom" }
       ]
     }
   ]
 }
 ```
 
-Notes:
+### Config Options
 
-- Auth token is optional.
-- Valve position is reported as 0–100% (read-only).
-- Offline TRVs are shown as “Not Responding” in HomeKit.
+- `host` (string, required): IP or hostname of your Shelly Plus/Pro Gateway
+- `token` (string, required): Gateway authentication token
+- `pollInterval` (number, optional): Polling interval in seconds (default: 60)
+- `devices` (array, required): List of TRVs to control. Each device must have:
+  - `id` (number, required): TRV device ID (as shown in the Shelly app or web UI)
+  - `name` (string, required): Name for HomeKit
 
----
+**Note:** You must manually add each TRV you want to control. The plugin will not scan or discover devices automatically.
 
-## Development
+## Usage
 
-- Build: `npm run build`
-- Lint: `npm run lint`
-- Test: `npm test`
+Once configured, your Shelly BLU TRVs will appear in HomeKit as Thermostat accessories. You can control target temperature, view current temperature, battery, and valve state.
 
-Contributions welcome — open an issue or a pull request.
+## Troubleshooting
 
----
+- Ensure your Homebridge server can reach the Shelly Gateway and TRVs on the local network.
+- Double-check the device IDs and gateway token.
+- Check Homebridge logs for errors.
 
-## Local testing
+## Development & Testing
 
-To test the plugin locally in a running Homebridge instance:
+Run tests with:
 
-- Build a tarball: `npm pack`
-- Install into Homebridge (on same machine): `npm i -g ./homebridge-shelly-blu-trv-<version>.tgz` or upload the tarball in Homebridge UI as a plugin file.
+```sh
+npm test
+```
 
-To test in a development Homebridge container, you can mount the packed tarball or install from the working directory with `npm i -g` after `npm run build`.
+## License
 
-### E2E (fake gateway) tests
+MIT
 
 We include a simple fake Shelly BLU gateway and an E2E runner to validate discovery and polling locally:
 

package/config.schema.json

@@ -27,13 +27,15 @@
             },
             "devices": {
               "type": "array",
-              "title": "Manual TRV devices (optional)",
+              "title": "TRV devices (required)",
+              "minItems": 1,
               "items": {
                 "type": "object",
                 "properties": {
                   "id": { "type": "number", "title": "TRV ID", "required": true },
                   "name": { "type": "string", "title": "Display name" }
-                }
+                },
+                "required": ["id"]
               }
             }
           }

package/dist/platform.js

@@ -31,32 +31,15 @@ class ShellyBluPlatform {
             this.log.warn("[ShellyBluPlatform] No gateways configured in config.json");
             return;
         }
-        this.log.info(`[ShellyBluPlatform] Starting device discovery for ${gateways.length} gateway(s)`);
+        this.log.info(`[ShellyBluPlatform] Registering manually configured TRVs for ${gateways.length} gateway(s)`);
         for (const gw of gateways) {
-            this.log.debug(`[ShellyBluPlatform] Discovering devices on gateway: ${gw.host}`);
+            if (!gw.devices || gw.devices.length === 0) {
+                this.log.warn(`[ShellyBluPlatform] No TRVs configured for gateway ${gw.host}`);
+                continue;
+            }
             const api = new shellyApi_1.ShellyApi(gw, this.log);
             const pollMs = (gw.pollInterval ?? 60) * 1000;
-            let trvs;
-            try {
-                trvs = await api.discoverTrvs();
-                this.log.info(`[ShellyBluPlatform] Discovered ${trvs.length} TRV(s) on gateway ${gw.host}`);
-                // If discovery returned nothing but user provided manual devices, use them
-                if ((!trvs || trvs.length === 0) && gw.devices && gw.devices.length > 0) {
-                    this.log.warn(`[ShellyBluPlatform] Discovery returned no devices; using manual device list for gateway ${gw.host}`);
-                    trvs = gw.devices.map((d) => ({ id: d.id, name: d.name || `BLU TRV ${d.id}` }));
-                }
-            }
-            catch (error) {
-                if (gw.devices && gw.devices.length > 0) {
-                    this.log.warn(`[ShellyBluPlatform] Discovery failed for gateway ${gw.host}, using manual device list: ${error instanceof Error ? error.message : String(error)}`);
-                    trvs = gw.devices.map((d) => ({ id: d.id, name: d.name || `BLU TRV ${d.id}` }));
-                }
-                else {
-                    this.log.error(`[ShellyBluPlatform] Failed to discover devices on gateway ${gw.host}: ${error instanceof Error ? error.message : String(error)}`);
-                    continue;
-                }
-            }
-            for (const trv of trvs) {
+            for (const trv of gw.devices) {
                 const uuid = this.api.hap.uuid.generate(`${gw.host}-${trv.id}`);
                 let acc = this.accessories.get(uuid);
                 if (!acc) {

package/dist/shellyApi.js

@@ -46,10 +46,17 @@ class ShellyApi {
     async rpcCall(id, method, params) {
         // Try several RPC variants for wider compatibility with firmware differences
         const paramsStr = params ? `&params=${encodeURIComponent(JSON.stringify(params))}` : '';
-        const candidates = [
-            `/rpc/BluTrv.call?id=${id}&method=${method}${paramsStr}`,
-            `/rpc/BluTrv.call&id=${id}&method=${method}${paramsStr}`
-        ];
+        // Try direct GetStatus endpoints first (some firmwares expose dedicated GET endpoints)
+        const candidates = [];
+        if (method === 'TRV.GetStatus') {
+            candidates.push(`/rpc/BluTrv.GetStatus?id=${id}`);
+            candidates.push(`/rpc/BluTrv.GetStatus&id=${id}`);
+        }
+        // Common CALL variants (different firmware use call vs Call and different query separators)
+        candidates.push(`/rpc/BluTrv.Call?id=${id}&method=${method}${paramsStr}`);
+        candidates.push(`/rpc/BluTrv.call?id=${id}&method=${method}${paramsStr}`);
+        candidates.push(`/rpc/BluTrv.Call&id=${id}&method=${method}${paramsStr}`);
+        candidates.push(`/rpc/BluTrv.call&id=${id}&method=${method}${paramsStr}`);
         for (const path of candidates) {
             try {
                 return await this.get(path);
@@ -90,37 +97,28 @@ class ShellyApi {
             throw err;
         }
     }
-    async discoverTrvs() {
-        this.log.debug(`[ShellyApi] Discovering TRVs from gateway ${this.gw.host}`);
-        try {
-            const status = await this.get("/status");
-            const devices = status.ble?.devices ?? [];
-            const trvs = devices
-                .filter((d) => d.type === "trv")
-                .map((d) => ({
-                id: d.id ?? 0,
-                name: d.name || `BLU TRV ${d.id ?? 'unknown'}`
-            }));
-            this.log.debug(`[ShellyApi] Found ${trvs.length} TRV(s) on gateway ${this.gw.host}`);
-            return trvs;
-        }
-        catch (error) {
-            this.log.error(`[ShellyApi] Failed to discover TRVs: ${error instanceof Error ? error.message : String(error)}`);
-            throw error;
-        }
-    }
     async getTrvState(id) {
         this.log.debug(`[ShellyApi] Fetching state for TRV ${id}`);
         try {
-            const rpc = await this.rpcCall(id, 'TRV.GetStatus');
-            const status = await this.get("/status");
-            const dev = status.ble?.devices?.find((d) => d.id === id);
+            // Only use direct RPC response; no /status fallback
+            const rpcAny = await this.rpcCall(id, 'TRV.GetStatus');
+            const rpc = rpcAny;
+            // Validate required fields
+            if (typeof rpc.current_C !== 'number' ||
+                typeof rpc.target_C !== 'number' ||
+                typeof rpc.pos !== 'number') {
+                throw new Error(`Missing required TRV state fields in RPC response: ${JSON.stringify(rpc)}`);
+            }
+            // Use battery/online from RPC response if present, else default
+            const battery = typeof rpc.battery === 'number' ? rpc.battery : 0;
+            // Accept either paired or online as online indicator
+            const online = typeof rpc.online === 'boolean' ? rpc.online : (typeof rpc.paired === 'boolean' ? rpc.paired : true);
             const state = {
                 currentTemp: rpc.current_C,
                 targetTemp: rpc.target_C,
                 valve: rpc.pos,
-                battery: dev?.battery ?? 0,
-                online: !!dev?.online
+                battery,
+                online
             };
             this.log.debug(`[ShellyApi] TRV ${id} state: temp=${state.currentTemp}°C, target=${state.targetTemp}°C, valve=${state.valve}%, battery=${state.battery}%, online=${state.online}`);
             return state;
@@ -133,7 +131,8 @@ class ShellyApi {
     async setTargetTemp(id, value) {
         this.log.debug(`[ShellyApi] Setting target temperature for TRV ${id} to ${value}°C`);
         try {
-            await this.rpcCall(id, 'TRV.SetTarget', { target_C: value });
+            // Include an explicit id:0 in params (observed in some firmware examples)
+            await this.rpcCall(id, 'TRV.SetTarget', { id: 0, target_C: value });
             this.log.debug(`[ShellyApi] Successfully set target temperature for TRV ${id}`);
         }
         catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-shelly-blu-trv",
   "displayName": "Shelly BLU TRV",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "description": "Homebridge plugin for Shelly BLU TRV thermostats via Shelly BLU Gateway Gen3",
   "license": "MIT",
   "author": "agiplv",
@@ -39,7 +39,6 @@
     "test": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint . --ext .ts",
-    "e2e": "node scripts/run-e2e.js",
     "check-coverage": "node scripts/check-coverage.js",
     "release:patch": "npm version patch -m \"chore(release): %s\" && git push --follow-tags",
     "semantic-release": "semantic-release"