homebridge-bluos 1.1.6 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [2.0.0](https://github.com/tbaur/homebridge-bluos/compare/v1.1.6...v2.0.0) (2026-09-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* requires Homebridge 2.0 or newer and Node 22, 24 or 26. Homebridge 1.x and Node 20 are no longer supported.
+
+### Features
+
+* require Homebridge 2 and Node 22+, and fix cached-context persistence ([#39](https://github.com/tbaur/homebridge-bluos/issues/39)) ([72fdbf8](https://github.com/tbaur/homebridge-bluos/commit/72fdbf80de22183ca79b5da4c3cdda575e4ef8d1))
+
 ## [1.1.6](https://github.com/tbaur/homebridge-bluos/compare/v1.1.5...v1.1.6) (2026-08-31)
 
 

package/DEVELOPMENT.md

@@ -35,7 +35,7 @@ A capability ships if HomeKit can express it as a tile, a scene, an automation o
 
 ## Commands
 
-Node 20+, matching `engines`. CI runs 20 / 22 / 24, a Homebridge 1.6 floor job, and a runtime `npm audit`. `@types/node` stays on the 20 line for the same reason: newer types let the compiler accept API that the oldest supported runtime does not have. Dependabot is told not to raise it, because the floor and the types are meant to move together.
+Node 22, 24 or 26, matching `engines`. CI runs 22 / 24 / 26 and a runtime `npm audit`. `@types/node` tracks the top of that range rather than its floor, so the Node 22 job in the matrix is what catches an API the oldest supported runtime does not have. Dependabot is told not to raise it on its own, because the range and the types are meant to move together.
 
 ```bash
 npm install

package/README.md

@@ -1,6 +1,6 @@
 # homebridge-bluos
 
-[![Tests](https://github.com/tbaur/homebridge-bluos/actions/workflows/test.yml/badge.svg)](https://github.com/tbaur/homebridge-bluos/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/homebridge-bluos?style=flat-square)](https://www.npmjs.com/package/homebridge-bluos) [![npm downloads](https://img.shields.io/npm/dt/homebridge-bluos?label=downloads&style=flat-square)](https://www.npmjs.com/package/homebridge-bluos) [![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org) [![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins) [![Homebridge](https://img.shields.io/badge/homebridge-%3E%3D1.6.0%20%7C%7C%202.x-purple)](https://homebridge.io) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Tests](https://github.com/tbaur/homebridge-bluos/actions/workflows/test.yml/badge.svg)](https://github.com/tbaur/homebridge-bluos/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/homebridge-bluos?style=flat-square)](https://www.npmjs.com/package/homebridge-bluos) [![npm downloads](https://img.shields.io/npm/dt/homebridge-bluos?label=downloads&style=flat-square)](https://www.npmjs.com/package/homebridge-bluos) [![Node.js](https://img.shields.io/badge/node-22%20%7C%7C%2024%20%7C%7C%2026-green)](https://nodejs.org) [![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins) [![Homebridge](https://img.shields.io/badge/homebridge-2.x-purple)](https://homebridge.io) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 **BluOS players in Apple HomeKit, over your LAN.** No cloud, no accounts, no polling loops hammering your speakers. Verified against NAD and Bluesound hardware. Other BluOS brands (DALI, Monitor Audio, Roksan) run the same firmware and are expected to work, but are untested here.
 
@@ -133,8 +133,8 @@ The plugin talks only to the addresses in your configuration, on your LAN. There
 
 ## Requirements
 
-- Homebridge 1.6.0+ or 2.0+
-- Node.js 20+ (Homebridge 2.x itself requires Node 22+, so the Node 20 floor applies to Homebridge 1.x hosts)
+- Homebridge 2.x
+- Node.js 22, 24 or 26, matching what Homebridge 2.x itself supports
 - One or more BluOS players reachable on the same network
 
 ## More Info

package/dist/api/client.d.ts

@@ -83,8 +83,15 @@ export declare class BluOSClient {
     /** Tail of the write queue for each chassis host. */
     private readonly chassisWriteQueue;
     constructor(options: BluOSClientOptions);
-    /** Read `/SyncStatus` once, without long-polling. */
-    readSyncStatus(endpoint: Endpoint): Promise<PlayerObservation>;
+    /**
+     * Read `/SyncStatus` once, without long-polling.
+     *
+     * Takes a signal for the same reason the long poll does. This read is bounded
+     * by {@link STATUS_TIMEOUT_MS} rather than by a poll window, but a shutdown
+     * still has to be able to drop it: an unreachable player holds it for the full
+     * timeout, and a shutdown waits for every poller.
+     */
+    readSyncStatus(endpoint: Endpoint, signal?: AbortSignal): Promise<PlayerObservation>;
     /**
      * Long-poll `/SyncStatus`, returning when the player's state changes or the
      * poll window elapses.

package/dist/api/client.js

@@ -58,13 +58,21 @@ class BluOSClient {
         this.now = options.now ?? Date.now;
         this.sleep = options.sleep ?? timing_1.sleep;
     }
-    /** Read `/SyncStatus` once, without long-polling. */
-    async readSyncStatus(endpoint) {
+    /**
+     * Read `/SyncStatus` once, without long-polling.
+     *
+     * Takes a signal for the same reason the long poll does. This read is bounded
+     * by {@link STATUS_TIMEOUT_MS} rather than by a poll window, but a shutdown
+     * still has to be able to drop it: an unreachable player holds it for the full
+     * timeout, and a shutdown waits for every poller.
+     */
+    async readSyncStatus(endpoint, signal) {
         const body = await this.get({
             endpoint,
             resource: 'SyncStatus',
             query: {},
             totalTimeoutMs: settings_1.STATUS_TIMEOUT_MS,
+            signal,
         });
         return (0, sync_status_1.parseSyncStatus)(body, (0, identity_1.formatEndpoint)(endpoint.host, endpoint.port));
     }

package/dist/platform.d.ts

@@ -136,6 +136,10 @@ export declare class BluOSPlatform implements DynamicPlatformPlugin, AccessoryHo
      *
      * Driven by context rather than configuration so that the same path works when
      * the platform is disabled and there is no valid configuration to consult.
+     *
+     * The validated context becomes the accessory's own, so the handler and the
+     * Homebridge cache hold one object. Anything a handler remembers is then in
+     * the object `persistContext` serialises. See {@link bindAccessoryContext}.
      */
     private attachHandler;
     private startPollers;

package/dist/platform.js

@@ -349,6 +349,9 @@ class BluOSPlatform {
             device,
             serialNumber: (0, utils_1.newAccessorySerialNumber)(),
             adoptedLegacyUuid: false,
+            // Nothing to carry over: this path is taken only when no cached accessory
+            // answered to this identity.
+            previous: undefined,
         });
         this.attachHandler(platformAccessory);
         this.active.set(uuid, platformAccessory);
@@ -372,6 +375,11 @@ class BluOSPlatform {
             device,
             serialNumber,
             adoptedLegacyUuid: adopted || alreadyAdopted,
+            // Read off the accessory being adopted rather than looked up by the UUID
+            // this identity produces now. An adopted accessory is cached under its old
+            // UUID, so that lookup misses on exactly the path this branch exists for,
+            // and the level the user last set would be dropped by the migration.
+            previous: existing.context,
         });
         if (existing.displayName !== accessory.name) {
             this.log.info(`${(0, utils_1.forLog)(existing.displayName)} is now named ${(0, utils_1.forLog)(accessory.name)}`);
@@ -382,8 +390,7 @@ class BluOSPlatform {
         this.api.updatePlatformAccessories([existing]);
     }
     buildContext(input) {
-        const { accessory, device, serialNumber, adoptedLegacyUuid } = input;
-        const previous = this.restored.get(this.uuidFor(accessory))?.context;
+        const { accessory, device, serialNumber, adoptedLegacyUuid, previous } = input;
         // The platform's own switch has no device, and so no address: its host and
         // port are placeholders that nothing reads, because it resolves its targets
         // when it is pressed rather than holding one endpoint.
@@ -414,11 +421,15 @@ class BluOSPlatform {
      *
      * Driven by context rather than configuration so that the same path works when
      * the platform is disabled and there is no valid configuration to consult.
+     *
+     * The validated context becomes the accessory's own, so the handler and the
+     * Homebridge cache hold one object. Anything a handler remembers is then in
+     * the object `persistContext` serialises. See {@link bindAccessoryContext}.
      */
     attachHandler(accessory) {
         let context;
         try {
-            context = (0, utils_1.parseAccessoryContext)(accessory);
+            context = (0, utils_1.bindAccessoryContext)(accessory);
         }
         catch (error) {
             this.log.warn(`${(0, utils_1.forLog)(accessory.displayName)} cannot be driven: ${(0, utils_1.describeError)(error)}. `

package/dist/poller.d.ts

@@ -90,6 +90,13 @@ export declare class DevicePoller {
     /** Cancel the request in flight and wake any backoff sleep. */
     private interrupt;
     private run;
+    /**
+     * Read this zone once, long-polling when there is a token to poll with.
+     *
+     * Both reads are abortable, not just the long poll. A plain read is the path an
+     * unreachable player takes — a failure clears the etag — and it can sit for the
+     * whole status timeout, which a shutdown would otherwise wait out per player.
+     */
     private readOnce;
     private handleFailure;
     /**

package/dist/poller.js

@@ -199,15 +199,21 @@ class DevicePoller {
             }
         }
     }
+    /**
+     * Read this zone once, long-polling when there is a token to poll with.
+     *
+     * Both reads are abortable, not just the long poll. A plain read is the path an
+     * unreachable player takes — a failure clears the etag — and it can sit for the
+     * whole status timeout, which a shutdown would otherwise wait out per player.
+     */
     async readOnce() {
         const etag = this.etag;
-        if (etag === undefined) {
-            return this.options.client.readSyncStatus(this.currentEndpoint);
-        }
         const abort = new AbortController();
         this.abort = abort;
         try {
-            return await this.options.client.pollSyncStatus(this.currentEndpoint, etag, abort.signal);
+            return etag === undefined
+                ? await this.options.client.readSyncStatus(this.currentEndpoint, abort.signal)
+                : await this.options.client.pollSyncStatus(this.currentEndpoint, etag, abort.signal);
         }
         catch (error) {
             throw abort.signal.aborted ? new PollInterrupted() : error;

package/dist/utils/context.d.ts

@@ -16,3 +16,18 @@ import type { PlatformAccessory } from 'homebridge';
 import { type AccessoryContext } from '../types';
 /** Read and validate a restored accessory's context. */
 export declare function parseAccessoryContext(accessory: PlatformAccessory): AccessoryContext;
+/**
+ * Validate a restored accessory's context and make it the accessory's own.
+ *
+ * What a handler is given has to be the object Homebridge serialises, because
+ * handlers remember things in it: a slider's last non-zero level, a brand the
+ * player reported that configuration got wrong. {@link parseAccessoryContext}
+ * returns a new object by design, so a handler driven by that alone would write
+ * those values to a detached copy — thrown away at the next restart, after
+ * paying a full accessory-cache rewrite per volume step to save nothing.
+ *
+ * Kept separate from {@link parseAccessoryContext} so validating a context stays
+ * free of side effects for a caller that only wants to know whether it can be
+ * read.
+ */
+export declare function bindAccessoryContext(accessory: PlatformAccessory): AccessoryContext;

package/dist/utils/context.js

@@ -15,6 +15,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseAccessoryContext = parseAccessoryContext;
+exports.bindAccessoryContext = bindAccessoryContext;
 const settings_1 = require("../settings");
 const types_1 = require("../types");
 const errors_1 = require("./errors");
@@ -57,3 +58,22 @@ function parseAccessoryContext(accessory) {
     }
     return context;
 }
+/**
+ * Validate a restored accessory's context and make it the accessory's own.
+ *
+ * What a handler is given has to be the object Homebridge serialises, because
+ * handlers remember things in it: a slider's last non-zero level, a brand the
+ * player reported that configuration got wrong. {@link parseAccessoryContext}
+ * returns a new object by design, so a handler driven by that alone would write
+ * those values to a detached copy — thrown away at the next restart, after
+ * paying a full accessory-cache rewrite per volume step to save nothing.
+ *
+ * Kept separate from {@link parseAccessoryContext} so validating a context stays
+ * free of side effects for a caller that only wants to know whether it can be
+ * read.
+ */
+function bindAccessoryContext(accessory) {
+    const context = parseAccessoryContext(accessory);
+    accessory.context = context;
+    return context;
+}

package/docs/FEATURES.md

@@ -45,8 +45,8 @@ A checklist of what is built. The plugin aims to cover everything about a BluOS
 - ✅ Clean shutdown: poll loops, backoff delays and mDNS browses are cancelled, not left to run out
 - ✅ A cached accessory that the plugin cannot drive reports No Response and says what to do about it. It never shows a stale value forever
 - ✅ Custom Homebridge UI settings page, plus a plain `config.schema.json` form
-- ✅ Homebridge v1.6.0+ and v2.0+ support
-- ✅ Node.js 20+ support
+- ✅ Homebridge v2.0+ support
+- ✅ Node.js 22, 24 and 26 support
 
 ## Not built yet
 

package/docs/README-DETAILED.md

@@ -275,7 +275,7 @@ Responses are parsed by a size-, depth- and element-capped XML reader instead of
 
 - **Strict TypeScript:** `strict`, plus `noUncheckedIndexedAccess` and type-aware lint
 - **Tested:** a behavioural Jest suite over 95% of statements, including XML fixtures recorded from real hardware (NAD C658, CI S2, Bluesound P430, portable player) and the settings page that writes your configuration
-- **CI:** build, lint (warnings are failures), type-check and test on Node 20/22/24, a job against the oldest supported Homebridge, a committed-`dist` drift check, a dependency audit and OSV scanning
+- **CI:** build, lint (warnings are failures), type-check and test on Node 22/24/26, a job against the oldest supported Homebridge, a committed-`dist` drift check, a dependency audit and OSV scanning
 - **No analytics:** no tracking, no cloud, no accounts
 
 ## More

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-bluos",
   "displayName": "Homebridge BluOS",
-  "version": "1.1.6",
+  "version": "2.0.0",
   "description": "Homebridge plugin for BluOS players — per-zone volume, mute, volume-preset and battery accessories over the LAN Custom Integration API. Verified on NAD and Bluesound hardware",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
   },
   "homepage": "https://github.com/tbaur/homebridge-bluos#readme",
   "overrides": {
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.1",
     "brace-expansion": "^5.0.9"
   },
   "dependencies": {
@@ -51,7 +51,7 @@
     "@types/dns-packet": "^5.6.5",
     "@types/jest": "^30.0.0",
     "@types/multicast-dns": "^7.2.4",
-    "@types/node": "^20.19.43",
+    "@types/node": "^26",
     "@typescript-eslint/eslint-plugin": "^8.51.0",
     "@typescript-eslint/parser": "^8.51.0",
     "eslint": "^10.6.0",
@@ -62,8 +62,8 @@
     "typescript": "^6.0.3"
   },
   "engines": {
-    "homebridge": "^1.6.0 || ^2.0.0",
-    "node": ">=20.0.0"
+    "homebridge": "^2.0.0",
+    "node": "^22 || ^24 || ^26"
   },
   "scripts": {
     "build": "tsc",