homebridge-bluos 0.1.0

package/dist/devices/volume-accessory.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The volume slider.
+ *
+ * HomeKit has no speaker volume control that the Home app renders, so the slider
+ * borrows one. Fanv2 `RotationSpeed` is the default and a Lightbulb's
+ * `Brightness` is offered as an alternative; they look identical in the Home app.
+ * The default is the fan because "turn off all the lights" and "set the lights to
+ * 100%" both sweep up a Lightbulb, and a speaker jumping to full volume because
+ * someone addressed the lights is a genuinely bad outcome. Every mature plugin in
+ * this space carries the same warning.
+ *
+ * Mapping to BluOS:
+ *
+ * - The slider position is the player's 0..100 level. The player converts that to
+ *   its own configured dB range, which differs per player and per configuration —
+ *   two identical PULSE FLEX 2i units measured 0.7 dB apart at levels 26 and 35 —
+ *   so the level is deliberately passed through rather than scaled here.
+ * - Off means level zero. A muted player reports `volume="0"`, so an external mute
+ *   shows up as Off without this accessory having to know about mute at all.
+ * - Any explicit level write unmutes first, because a slider that appears to move
+ *   while the player stays silent is indistinguishable from a broken plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VolumeAccessory = void 0;
+const sync_status_1 = require("../api/sync-status");
+const settings_1 = require("../settings");
+const utils_1 = require("../utils");
+const base_accessory_1 = require("./base-accessory");
+/** A volume slider for one player. */
+class VolumeAccessory extends base_accessory_1.BaseAccessory {
+    surface;
+    /** Last level read from the player. Undefined until the first observation. */
+    level;
+    /** True when the player reports a fixed output level. */
+    fixedVolume = false;
+    /** Level awaiting a coalesced write. */
+    pendingLevel;
+    /** In-flight coalesced write, shared by every handler that queued into it. */
+    flush;
+    constructor(init) {
+        super(init);
+        this.surface = this.buildSurface();
+        this.bindHandlers();
+    }
+    buildSurface() {
+        const { Characteristic: Char, Service: HapService } = this.host.hap;
+        const wantsLightbulb = this.context.sliderService === 'lightbulb';
+        // The slider style is deliberately not part of accessory identity, so
+        // switching it adopts the same accessory rather than replacing it. Without
+        // removing the old service the accessory would carry both, and the Home app
+        // would show two controls of which only one is bound to any handler.
+        this.dropService(wantsLightbulb ? HapService.Fanv2 : HapService.Lightbulb);
+        if (wantsLightbulb) {
+            const service = this.requireService(HapService.Lightbulb);
+            return {
+                service,
+                active: service.getCharacteristic(Char.On),
+                level: service.getCharacteristic(Char.Brightness),
+                toActiveValue: (on) => on,
+            };
+        }
+        const service = this.requireService(HapService.Fanv2);
+        return {
+            service,
+            active: service.getCharacteristic(Char.Active),
+            level: service.getCharacteristic(Char.RotationSpeed),
+            toActiveValue: (on) => (on ? Char.Active.ACTIVE : Char.Active.INACTIVE),
+        };
+    }
+    bindHandlers() {
+        const { Characteristic: Char } = this.host.hap;
+        this.surface.service.setCharacteristic(Char.Name, this.displayName);
+        // A whole-number step: BluOS levels are integers, and offering finer
+        // granularity would only invite rounding surprises.
+        this.surface.level.setProps({
+            minValue: settings_1.VOLUME_MIN,
+            maxValue: settings_1.VOLUME_MAX,
+            minStep: 1,
+        });
+        this.surface.active
+            .onGet(() => this.readActive())
+            .onSet(async (value) => this.writeActive(value));
+        this.surface.level
+            .onGet(() => this.readLevel())
+            .onSet(async (value) => this.writeLevel(value));
+    }
+    readActive() {
+        this.requireSlider();
+        return this.surface.toActiveValue((this.level ?? 0) > settings_1.VOLUME_MIN);
+    }
+    readLevel() {
+        this.requireSlider();
+        return this.level ?? settings_1.VOLUME_MIN;
+    }
+    /**
+     * Refuse a read when the value would be a guess.
+     *
+     * A fixed-output player is treated the same as an unreachable one: there is no
+     * level to report and writing one would do nothing, so No Response is the
+     * truthful answer rather than a slider that silently ignores input.
+     */
+    requireSlider() {
+        if (this.fixedVolume) {
+            throw this.communicationFailure();
+        }
+        this.requireObservedState();
+    }
+    async writeActive(value) {
+        const { Characteristic: Char } = this.host.hap;
+        const on = this.context.sliderService === 'lightbulb'
+            ? value === true
+            : value === Char.Active.ACTIVE;
+        if (!on) {
+            await this.queueLevel(settings_1.VOLUME_MIN);
+            return;
+        }
+        const observation = this.host.observationFor(this.deviceId);
+        const restore = (0, sync_status_1.restoreLevelFrom)(observation ?? {}, this.context.lastNonZeroVolume, settings_1.DEFAULT_RESTORE_VOLUME);
+        await this.queueLevel(restore);
+    }
+    async writeLevel(value) {
+        const requested = typeof value === 'number' ? Math.round(value) : Number.NaN;
+        if (!Number.isInteger(requested)) {
+            this.host.log.debug(`${(0, utils_1.forLog)(this.displayName)} ignoring non-numeric level ${String(value)}`);
+            return;
+        }
+        await this.queueLevel(Math.min(settings_1.VOLUME_MAX, Math.max(settings_1.VOLUME_MIN, requested)));
+    }
+    /**
+     * Record the intended level and write it once the coalescing window closes.
+     *
+     * The most recent request wins, which is what makes the `Active` + level pair
+     * that HomeKit sends when a slider leaves zero result in a single write.
+     */
+    async queueLevel(level) {
+        this.pendingLevel = level;
+        if (this.flush === undefined) {
+            this.flush = (0, utils_1.sleep)(settings_1.SLIDER_COALESCE_MS).then(async () => this.applyPendingLevel());
+        }
+        const flush = this.flush;
+        await this.completeWithinBudget('volume write', async () => flush);
+    }
+    async applyPendingLevel() {
+        const level = this.pendingLevel;
+        this.pendingLevel = undefined;
+        this.flush = undefined;
+        if (level === undefined) {
+            return;
+        }
+        if (this.fixedVolume) {
+            this.warnOnce('fixed-volume-write', `${(0, utils_1.forLog)(this.displayName)} reports a fixed output level; ignoring the volume write`);
+            return;
+        }
+        const endpoint = this.host.endpointFor(this.deviceId);
+        if (endpoint === undefined) {
+            throw new Error('player is no longer configured');
+        }
+        // An explicit level is meaningless while muted, so unmute first. Writing the
+        // level alone would leave the slider showing a value the room cannot hear.
+        const observation = this.host.observationFor(this.deviceId);
+        const scope = this.writeScope();
+        if (level > settings_1.VOLUME_MIN && observation?.muted === true) {
+            const unmuted = await this.host.client.setMute(endpoint, false, scope);
+            this.host.adoptWriteResult(this.deviceId, unmuted);
+        }
+        // A group write changes the followers too. They are not touched here: each
+        // zone runs its own long-poll, so their own etags move and they update within
+        // a poll round trip, without this accessory having to know who they are.
+        const result = await this.host.client.setVolume(endpoint, level, scope);
+        // The player clamps into its own configured range, so its answer is the
+        // truth and the requested value is only a request.
+        this.host.adoptWriteResult(this.deviceId, result);
+        this.logAction(`SET ${result.level ?? level}`, scope);
+        if (result.level !== undefined && result.level !== level) {
+            this.warnOnce('clamped', `${(0, utils_1.forLog)(this.displayName)} clamped volume ${level} to ${result.level}; `
+                + 'the player has a configured volume range');
+        }
+    }
+    updateFromObservation(observation, _reason) {
+        if (observation.fixedVolume) {
+            if (!this.fixedVolume) {
+                this.fixedVolume = true;
+                this.warnOnce('fixed-volume', `${(0, utils_1.forLog)(this.displayName)} reports a fixed output level, so its volume slider `
+                    + 'cannot do anything; disable the slider for this player in the plugin settings');
+                this.markUnavailable();
+            }
+            return;
+        }
+        this.fixedVolume = false;
+        // A muted player already reports level 0, so this needs no mute handling of
+        // its own; the guard is only for firmware that reports otherwise.
+        const level = observation.muted ? settings_1.VOLUME_MIN : observation.volume ?? settings_1.VOLUME_MIN;
+        this.level = level;
+        if (level > settings_1.VOLUME_MIN && this.context.lastNonZeroVolume !== level) {
+            this.context.lastNonZeroVolume = level;
+            // This accessory only: a front-panel knob produces a level change per step,
+            // and each one would otherwise rewrite the context of every accessory in the
+            // fleet to the cache file on disk.
+            this.host.persistContext(this.accessory);
+        }
+        const { Characteristic: Char } = this.host.hap;
+        this.surface.service.updateCharacteristic(this.context.sliderService === 'lightbulb' ? Char.On : Char.Active, this.surface.toActiveValue(level > settings_1.VOLUME_MIN));
+        this.surface.service.updateCharacteristic(this.context.sliderService === 'lightbulb' ? Char.Brightness : Char.RotationSpeed, level);
+    }
+    markUnavailable() {
+        const { Characteristic: Char } = this.host.hap;
+        const error = this.communicationFailure();
+        this.surface.service.updateCharacteristic(this.context.sliderService === 'lightbulb' ? Char.On : Char.Active, error);
+        this.surface.service.updateCharacteristic(this.context.sliderService === 'lightbulb' ? Char.Brightness : Char.RotationSpeed, error);
+    }
+}
+exports.VolumeAccessory = VolumeAccessory;

package/dist/devices/volume-preset-accessory.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview A switch that sets one specific volume level.
+ *
+ * This is the automation-safe counterpart to the slider. A scene or a Siri phrase
+ * can only ever put the player at the configured level, so there is no way for a
+ * misfiring automation or a misheard command to land on full volume at three in
+ * the morning. It is also the only control here that is meaningfully addressable
+ * by voice without a number: "turn on Bedtime Volume".
+ *
+ * On means the player is currently at this level and not muted. Turning the switch
+ * off has no meaning — there is no opposite of "be at 30" — so it is a no-op that
+ * re-asserts the real state.
+ */
+import type { PlayerObservation, RefreshReason } from '../types';
+import { BaseAccessory, type AccessoryInit } from './base-accessory';
+/** A one-level volume switch for one player. */
+export declare class VolumePresetAccessory extends BaseAccessory {
+    private readonly service;
+    private readonly target;
+    /** Whether the player is currently sitting at this preset's level. */
+    private applied;
+    constructor(init: AccessoryInit);
+    private readOn;
+    private writeOn;
+    protected updateFromObservation(observation: PlayerObservation, _reason: RefreshReason): void;
+    protected markUnavailable(): void;
+}

package/dist/devices/volume-preset-accessory.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview A switch that sets one specific volume level.
+ *
+ * This is the automation-safe counterpart to the slider. A scene or a Siri phrase
+ * can only ever put the player at the configured level, so there is no way for a
+ * misfiring automation or a misheard command to land on full volume at three in
+ * the morning. It is also the only control here that is meaningfully addressable
+ * by voice without a number: "turn on Bedtime Volume".
+ *
+ * On means the player is currently at this level and not muted. Turning the switch
+ * off has no meaning — there is no opposite of "be at 30" — so it is a no-op that
+ * re-asserts the real state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VolumePresetAccessory = void 0;
+const settings_1 = require("../settings");
+const utils_1 = require("../utils");
+const base_accessory_1 = require("./base-accessory");
+/** A one-level volume switch for one player. */
+class VolumePresetAccessory extends base_accessory_1.BaseAccessory {
+    service;
+    target;
+    /** Whether the player is currently sitting at this preset's level. */
+    applied;
+    constructor(init) {
+        super(init);
+        this.target = init.context.volume ?? settings_1.VOLUME_MIN;
+        const { Characteristic: Char, Service: HapService } = this.host.hap;
+        this.service = this.requireService(HapService.Switch);
+        this.service.setCharacteristic(Char.Name, this.displayName);
+        this.service
+            .getCharacteristic(Char.On)
+            .onGet(() => this.readOn())
+            .onSet(async (value) => this.writeOn(value));
+    }
+    readOn() {
+        this.requireObservedState();
+        return this.applied === true;
+    }
+    async writeOn(value) {
+        if (value !== true) {
+            // Nothing to undo. Re-assert observed state so the tile stops showing the
+            // user's tap rather than the player's reality.
+            const observation = this.host.observationFor(this.deviceId);
+            if (observation !== undefined) {
+                this.updateFromObservation(observation, 'post-set');
+            }
+            return;
+        }
+        await this.completeWithinBudget('preset write', async () => {
+            const endpoint = this.host.endpointFor(this.deviceId);
+            if (endpoint === undefined) {
+                throw new Error('player is no longer configured');
+            }
+            const observation = this.host.observationFor(this.deviceId);
+            const scope = this.writeScope();
+            // A preset that leaves the room silent would look like it had failed.
+            if (this.target > settings_1.VOLUME_MIN && observation?.muted === true) {
+                this.host.adoptWriteResult(this.deviceId, await this.host.client.setMute(endpoint, false, scope));
+            }
+            const result = await this.host.client.setVolume(endpoint, this.target, scope);
+            this.host.adoptWriteResult(this.deviceId, result);
+            this.logAction(`SET ${result.level ?? this.target}`, scope);
+            if (result.level !== undefined && result.level !== this.target) {
+                // The player's configured range can make a preset unreachable, in which
+                // case the switch would otherwise sit off forever with no explanation.
+                this.warnOnce('unreachable-preset', `${(0, utils_1.forLog)(this.displayName)} asked for volume ${this.target} but the player `
+                    + `settled at ${result.level}; its configured volume range cannot reach ${this.target}`);
+            }
+        });
+    }
+    updateFromObservation(observation, _reason) {
+        const applied = !observation.muted
+            && !observation.fixedVolume
+            && observation.volume === this.target;
+        this.applied = applied;
+        this.service.updateCharacteristic(this.host.hap.Characteristic.On, applied);
+    }
+    markUnavailable() {
+        this.service.updateCharacteristic(this.host.hap.Characteristic.On, this.communicationFailure());
+    }
+}
+exports.VolumePresetAccessory = VolumePresetAccessory;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Plugin entry point.
+ *
+ * The registered platform name must match `config.schema.json` and the
+ * `platform` value in the user's `config.json`, or Homebridge silently loads
+ * nothing at all.
+ */
+import type { API } from 'homebridge';
+declare const _default: (api: API) => void;
+export default _default;

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Plugin entry point.
+ *
+ * The registered platform name must match `config.schema.json` and the
+ * `platform` value in the user's `config.json`, or Homebridge silently loads
+ * nothing at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const platform_1 = require("./platform");
+const settings_1 = require("./settings");
+exports.default = (api) => {
+    api.registerPlatform(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, platform_1.BluOSPlatform);
+};

package/dist/platform.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The platform: configuration, accessory lifecycle, orchestration.
+ *
+ * Two policies here matter more than the mechanics.
+ *
+ * Accessories are adopted, never replaced. Identity is derived from the player's
+ * MAC and zone port and never from its address, so a DHCP lease change leaves
+ * every UUID untouched. When a cached accessory carries the right identity in its
+ * context but a different UUID — the situation an identity-scheme change would
+ * create — it is adopted rather than orphaned, because losing an accessory takes
+ * the user's rooms, scenes and automations with it.
+ *
+ * A broken configuration disables the platform instead of deleting anything. The
+ * accessories stay registered and report No Response, which is recoverable; a
+ * plugin that unregisters accessories when it cannot parse its own settings
+ * destroys work the user cannot get back.
+ */
+import type { API, DynamicPlatformPlugin, Logging, PlatformAccessory, PlatformConfig } from 'homebridge';
+import { BluOSClient, type Endpoint } from './api/client';
+import type { VolumeResult } from './api/sync-status';
+import { type AccessoryHost } from './devices';
+import type { PlayerObservation } from './types';
+/** The BluOS dynamic platform. */
+export declare class BluOSPlatform implements DynamicPlatformPlugin, AccessoryHost {
+    readonly log: Logging;
+    readonly client: BluOSClient;
+    readonly pluginVersion: string;
+    private readonly api;
+    private readonly config;
+    private readonly discovery;
+    /** Accessories restored from disk, by UUID. */
+    private readonly restored;
+    /** Live accessories, by UUID. */
+    private readonly active;
+    /** Accessory handlers grouped by the player they belong to. */
+    private readonly handlers;
+    private readonly pollers;
+    private devices;
+    private discoveryTimeoutSec;
+    /** True when configuration could not be used; nothing is polled. */
+    private disabled;
+    private shuttingDown;
+    /** Warnings raised while resolving options in the constructor, logged at start. */
+    private readonly discoveryWarnings;
+    /** Pending poller starts, tracked so a shutdown can clear them. */
+    private readonly staggerTimers;
+    /** The launch address sweep, tracked so a shutdown can wait for it to end. */
+    private launchSweep;
+    constructor(log: Logging, config: PlatformConfig, api: API);
+    get hap(): API['hap'];
+    /** Homebridge hands back every accessory it restored from disk. */
+    configureAccessory(accessory: PlatformAccessory): void;
+    endpointFor(deviceId: string): Endpoint | undefined;
+    observationFor(deviceId: string): PlayerObservation | undefined;
+    adoptWriteResult(deviceId: string, result: VolumeResult): void;
+    /**
+     * Write accessory context back to the Homebridge cache.
+     *
+     * One accessory by default, because `updatePlatformAccessories` makes
+     * Homebridge serialise and rewrite the whole cache file: a front-panel volume
+     * knob produces a stream of observations, and writing every accessory's context
+     * for each of them is sustained disk churn on the SD card of a typical host.
+     */
+    persistContext(accessory?: PlatformAccessory): void;
+    private start;
+    private stop;
+    /**
+     * Bring the registered accessory set in line with configuration.
+     *
+     * Creates what is missing, adopts what matches by identity, and unregisters
+     * only what configuration no longer asks for.
+     */
+    private syncAccessories;
+    private uuidFor;
+    /**
+     * Find a cached accessory that describes this one but under a different UUID.
+     *
+     * The safety net for an identity-scheme change: matching on the persisted
+     * context lets the accessory be adopted instead of being replaced by a fresh
+     * one, which would silently drop it out of every scene it belongs to.
+     */
+    private findByIdentity;
+    private createAccessory;
+    private adoptAccessory;
+    private buildContext;
+    /**
+     * Build the handler for an accessory from its persisted context.
+     *
+     * 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.
+     */
+    private attachHandler;
+    private startPollers;
+    /** Correct addresses once at launch, so a DHCP change needs no user action. */
+    private correctAddresses;
+    /** Record a new address in accessory context so it survives a restart. */
+    private rememberEndpoint;
+    private publish;
+    private reportUnavailable;
+    /**
+     * Put every cached accessory into No Response.
+     *
+     * Used when configuration is unusable. Handlers are attached first so that the
+     * characteristics exist to be marked, which also means HomeKit sees a
+     * well-formed accessory that happens to be unreachable rather than a
+     * half-registered one.
+     */
+    private reportEverythingUnavailable;
+    /**
+     * Push No Response onto an accessory that has no handler.
+     *
+     * Generic rather than per accessory kind, because the reason it is needed is
+     * that the context which would have told us the kind could not be read.
+     * Accessory Information is left alone so the tile keeps its name and model.
+     */
+    private markAccessoryUnavailable;
+    /** True when the platform gave up on its configuration. Exposed for tests. */
+    get isDisabled(): boolean;
+}