homebridge-shelly-blu-trv 1.0.6 → 1.0.8

package/README.md

@@ -99,22 +99,73 @@ To ensure coverage is sufficient:
 
 ## Publishing
 
-Automatic publishing is configured to run on new GitHub releases (see `.github/workflows/publish.yml`).
-To publish manually:
+### Manual device configuration (fallback when discovery unavailable) ✅
 
-1. Ensure you're logged in to npm (`npm login`).
+If your Shelly BLU Gateway Gen3 does not expose the `/status` discovery endpoint (returns 404) or discovery is otherwise unavailable, you can manually configure TRV devices in the gateway entry of your Homebridge config. The plugin will use this list when discovery fails or returns no devices.
+
+Example gateway configuration with manual devices:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "ShellyBluTRV",
+      "gateways": [
+        {
+          "host": "10.0.0.171",
+          "token": "<optional-auth-token>",
+          "pollInterval": 60,
+          "devices": [
+            { "id": 100, "name": "Living TRV" },
+            { "id": 101, "name": "Kitchen TRV" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Notes:
+
+- `id` is the TRV numeric id assigned by the gateway; the plugin uses this id for polling and state updates.
+- If `name` is omitted, a default name `BLU TRV <id>` will be used.
+- When both discovery and manual `devices` are available, discovery takes precedence.
+
+## Publishing
+
+- The repository contains two publishing workflows:
+  - **Publish** (`.github/workflows/publish.yml`) — runs when a GitHub Release is *created* and performs an `npm publish` step.
+  - **Semantic Release** (`.github/workflows/semantic-release.yml`) — when enabled, automatically creates releases, changelogs and publishes to npm on `main` via `semantic-release`.
+
+**NOTE:** The automatic semantic-release runs are currently **paused** (workflow trigger switched to `workflow_dispatch`). To run it manually: go to the Actions tab → **Semantic Release** → **Run workflow** (choose `main`).
+
+Manual publish steps
+
+1. Ensure you're logged in to npm: `npm login`.
 2. Build the package: `npm run build`.
-3. Bump the version and push tags, or run `npm version <patch|minor|major>` and push tags.
-4. Publish: `npm publish --access public`.
+3. Bump the package version (e.g. `npm version patch`) and push the tag.
+4. Create a GitHub Release (or run `npm publish --access public` manually).
+
+Developer notes about `NPM_TOKEN` and automation
 
-Automated semantic releases are configured with `semantic-release`. The workflow runs on pushes to `main` and publishes a GitHub Release + npm package when a new release is performed.
+- For CI-based publishing you must set the repository secret `NPM_TOKEN` (Settings → Secrets → Actions) to a valid **npm automation token** with publish rights.
+  - Create it on npm: Settings → Access Tokens → **Create New Token** → choose **Automation** and ensure it has publish rights.
+  - If your npm account uses Two-Factor Authentication (2FA), pick a token that is usable for CI (set 2FA to **Authorization only** for automation tokens). See https://docs.npmjs.com/getting-started/working_with_tokens for details.
+- If semantic-release reports `EINVALIDNPMTOKEN` or `401 Unauthorized`, try re-creating the token and updating `NPM_TOKEN` in repo secrets.
+- The repository also includes a Publish workflow (triggered on Release creation) which can publish even if semantic-release is paused — this is useful for one-off releases.
 
-Note: You must add the following repository secrets for automatic publishing to work:
+E2E and local verification (developer)
 
-- `NPM_TOKEN` — npm token with publish permissions
-- `GITHUB_TOKEN` — typically provided automatically by GitHub Actions (`secrets.GITHUB_TOKEN`) but keep it available if you customize tokens
+- Run the E2E runner locally: `npm run e2e` — this will install deps, build the project, install a local shim, start the fake gateway and a headless Homebridge instance and look for discovery/polling logs.
+- Run unit tests + coverage: `npm test` (creates `coverage/lcov.info` and an `lcov-report` directory).
+- Check coverage threshold: `npm run check-coverage` (defaults to 80% lines; use `COVERAGE_THRESHOLD` to override).
+
+If you'd like, I can add a small diagnostic Action that runs `npm whoami` using `NPM_TOKEN` (safely) so you can quickly confirm which npm account the token maps to before re-enabling semantic-release.
+
+---
 
-If you'd like me to open a PR with this setup and add a draft release, say so and I will create the branch and PR now.
+If you want this documentation expanded into a `DEVELOPING.md` file or want me to add the diagnostic Action, tell me which and I'll add it in a PR.
 
 ## License
 

package/config.schema.json

@@ -24,6 +24,17 @@
               "title": "Polling interval (seconds)",
               "default": 60,
               "minimum": 15
+            },
+            "devices": {
+              "type": "array",
+              "title": "Manual TRV devices (optional)",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "number", "title": "TRV ID", "required": true },
+                  "name": { "type": "string", "title": "Display name" }
+                }
+              }
             }
           }
         }

package/dist/accessory.js

@@ -52,7 +52,7 @@ class ShellyTrvAccessory {
             this.log.warn(`[${this.accessory.displayName}] Device offline, unable to retrieve ${key}`);
             throw new this.platform.api.hap.HapStatusError(-70402 /* this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
         }
-        // accessing dynamic state keys
+        // accessing typed state keys
         const value = s[key];
         this.log.debug(`[${this.accessory.displayName}] Retrieved ${key}: ${value}`);
         return value;

package/dist/platform.js

@@ -40,10 +40,21 @@ class ShellyBluPlatform {
             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) {
-                this.log.error(`[ShellyBluPlatform] Failed to discover devices on gateway ${gw.host}: ${error instanceof Error ? error.message : String(error)}`);
-                continue;
+                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) {
                 const uuid = this.api.hap.uuid.generate(`${gw.host}-${trv.id}`);

package/dist/shellyApi.js

@@ -21,8 +21,16 @@ class ShellyApi {
                 signal: AbortSignal.timeout(this.requestTimeout)
             });
             if (!res.ok) {
-                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host}`);
-                throw new Error(`HTTP ${res.status}`);
+                // Try to extract body text for better diagnostics
+                let bodyText = '';
+                try {
+                    bodyText = await res.text();
+                }
+                catch {
+                    bodyText = '<no body>';
+                }
+                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host}${path} - ${bodyText}`);
+                throw new Error(`HTTP ${res.status}: ${bodyText}`);
             }
             const data = await res.json();
             this.log.debug(`[ShellyApi] Successfully fetched from ${this.gw.host}${path}`);
@@ -30,11 +38,58 @@ class ShellyApi {
         }
         catch (error) {
             if (error instanceof Error) {
-                this.log.error(`[ShellyApi] Request failed to ${this.gw.host}: ${error.message}`);
+                this.log.error(`[ShellyApi] Request failed to ${this.gw.host}${path}: ${error.message}`);
             }
             throw error;
         }
     }
+    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}`
+        ];
+        for (const path of candidates) {
+            try {
+                return await this.get(path);
+            }
+            catch (err) {
+                // If 404, try next candidate; otherwise propagate
+                if (err instanceof Error && err.message.includes('HTTP 404')) {
+                    this.log.debug(`[ShellyApi] RPC variant failed (404), trying next: ${path}`);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        // Fallback: try POST to /rpc/BluTrv.call with JSON body
+        try {
+            const url = buildUrl(this.gw.host, '/rpc/BluTrv.call', this.gw.token);
+            const res = await fetch(url, {
+                method: 'POST',
+                body: JSON.stringify({ id, method, params }),
+                headers: { 'Content-Type': 'application/json' },
+                signal: AbortSignal.timeout(this.requestTimeout)
+            });
+            if (!res.ok) {
+                let bodyText = '';
+                try {
+                    bodyText = await res.text();
+                }
+                catch {
+                    bodyText = '<no body>';
+                }
+                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host} (POST /rpc/BluTrv.call): ${bodyText}`);
+                throw new Error(`HTTP ${res.status}: ${bodyText}`);
+            }
+            return res.json();
+        }
+        catch (err) {
+            this.log.error(`[ShellyApi] RPC call failed for TRV ${id} method ${method}: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+    }
     async discoverTrvs() {
         this.log.debug(`[ShellyApi] Discovering TRVs from gateway ${this.gw.host}`);
         try {
@@ -57,7 +112,7 @@ class ShellyApi {
     async getTrvState(id) {
         this.log.debug(`[ShellyApi] Fetching state for TRV ${id}`);
         try {
-            const rpc = await this.get(`/rpc/BluTrv.call&id=${id}&method=TRV.GetStatus`);
+            const rpc = await this.rpcCall(id, 'TRV.GetStatus');
             const status = await this.get("/status");
             const dev = status.ble?.devices?.find((d) => d.id === id);
             const state = {
@@ -78,8 +133,7 @@ class ShellyApi {
     async setTargetTemp(id, value) {
         this.log.debug(`[ShellyApi] Setting target temperature for TRV ${id} to ${value}°C`);
         try {
-            await this.get(`/rpc/BluTrv.call&id=${id}&method=TRV.SetTarget&params=` +
-                encodeURIComponent(JSON.stringify({ target_C: value })));
+            await this.rpcCall(id, 'TRV.SetTarget', { 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.6",
+  "version": "1.0.8",
   "description": "Homebridge plugin for Shelly BLU TRV thermostats via Shelly BLU Gateway Gen3",
   "license": "MIT",
   "author": "agiplv",