homebridge-bluos 1.1.2 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.1.3](https://github.com/tbaur/homebridge-bluos/compare/v1.1.2...v1.1.3) (2026-08-30)
+
+
+### Bug Fixes
+
+* host battery on the volume or mute tile ([#29](https://github.com/tbaur/homebridge-bluos/issues/29)) ([beee853](https://github.com/tbaur/homebridge-bluos/commit/beee8532ca39af8c2b97a7c7412b4c5b82c66621))
+
 ## [1.1.2](https://github.com/tbaur/homebridge-bluos/compare/v1.1.1...v1.1.2) (2026-08-30)
 
 

package/README.md

@@ -13,7 +13,7 @@ Browsing, search, queues and artwork stay in the BluOS app, which HomeKit cannot
 - **Volume slider:** 0–100, the same scale the BluOS app uses. A fan by default, a lightbulb if you prefer
 - **Mute switch:** unmuting restores the level the player remembered, not a guess
 - **Volume presets:** one switch per exact level, addressable by name with Siri
-- **Battery sensor:** level, charging state and low-battery warning, for players with a battery pack
+- **Battery:** level, charging and low-battery, on the volume tile (or mute if there is no slider). A battery-only player still gets its own tile; the Home app will not render that one
 - **Reboot switch:** momentary, so a scene cannot reboot your stereo, and still pressable when the player has stopped answering
 - **Grouping-aware:** a zone leading a BluOS group moves the whole group, exactly as it does in the BluOS app
 - **Multi-zone chassis:** each zone of a NAD CI S2 or CI 580 is its own player, on its own port
@@ -56,7 +56,7 @@ Nothing needs enabling on the player, because the BluOS LAN API is always on. A
 
 ### 3. Configure
 
-**Homebridge UI** (recommended): open the plugin settings and press **Discover Players**. Every zone that answers is listed with a suggested set of accessories. Tick what you want and save.
+**Homebridge UI** (recommended): open the plugin settings and press **Discover Players**. Every zone that answers is listed with a suggested set of accessories. Tick what you want, then press the Homebridge Save button.
 
 Or in `config.json`:
 

package/config.schema.json

@@ -119,7 +119,7 @@
               "title": "Battery Sensor",
               "type": "boolean",
               "default": false,
-              "description": "State of charge. Only for players with a battery pack fitted, such as a PULSE FLEX with the BP100."
+              "description": "State of charge for a player with a battery pack (PULSE FLEX with the BP100, PULSE M). Appears on the volume tile, or on mute if there is no slider. A battery-only player gets its own tile, which the Home app cannot render."
             },
             "reboot": {
               "title": "Reboot Switch",

package/dist/devices/battery-accessory.d.ts

@@ -4,25 +4,19 @@
  * Licensed under the Apache License, Version 2.0
  * See LICENSE file for full license text
  *
- * @fileoverview State of charge for a portable player.
+ * @fileoverview Standalone battery accessory, used only when no other tile exists.
  *
- * `/SyncStatus` already carries `<battery level charging/>` on players with a
- * battery pack fitted, so this costs one service and no extra traffic. A player
- * without a pack never reports the element, and the accessory then reports No
- * Response rather than inventing a charge level.
+ * HomeKit will not render this in the Home app. Prefer hosting the Battery
+ * service on the volume or mute accessory, which resolveAccessories does
+ * whenever one of those is enabled. This class remains for a player that
+ * exposes battery and nothing else.
  */
 import type { PlayerObservation, RefreshReason } from '../types';
 import { BaseAccessory, type AccessoryInit } from './base-accessory';
-/** A battery sensor for one player. */
+/** A battery sensor for one player, with no other HomeKit service beside it. */
 export declare class BatteryAccessory extends BaseAccessory {
-    private readonly service;
-    private level;
-    private charging;
+    private readonly battery;
     constructor(init: AccessoryInit);
-    private readLevel;
-    private readLowBattery;
-    private readChargingState;
-    private requireBattery;
     protected updateFromObservation(observation: PlayerObservation, _reason: RefreshReason): void;
     protected markUnavailable(): void;
 }

package/dist/devices/battery-accessory.js

@@ -5,81 +5,36 @@
  * Licensed under the Apache License, Version 2.0
  * See LICENSE file for full license text
  *
- * @fileoverview State of charge for a portable player.
+ * @fileoverview Standalone battery accessory, used only when no other tile exists.
  *
- * `/SyncStatus` already carries `<battery level charging/>` on players with a
- * battery pack fitted, so this costs one service and no extra traffic. A player
- * without a pack never reports the element, and the accessory then reports No
- * Response rather than inventing a charge level.
+ * HomeKit will not render this in the Home app. Prefer hosting the Battery
+ * service on the volume or mute accessory, which resolveAccessories does
+ * whenever one of those is enabled. This class remains for a player that
+ * exposes battery and nothing else.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BatteryAccessory = void 0;
-const utils_1 = require("../utils");
 const base_accessory_1 = require("./base-accessory");
-/** Below this percentage HomeKit is told the battery is low. */
-const LOW_BATTERY_THRESHOLD = 20;
-/** A battery sensor for one player. */
+const player_battery_1 = require("./player-battery");
+/** A battery sensor for one player, with no other HomeKit service beside it. */
 class BatteryAccessory extends base_accessory_1.BaseAccessory {
-    service;
-    level;
-    charging = false;
+    battery;
     constructor(init) {
         super(init);
-        const { Characteristic: Char, Service: HapService } = this.host.hap;
-        this.service = this.requireService(HapService.Battery);
-        this.service.setCharacteristic(Char.Name, this.displayName);
-        this.service.getCharacteristic(Char.BatteryLevel).onGet(() => this.readLevel());
-        this.service.getCharacteristic(Char.StatusLowBattery).onGet(() => this.readLowBattery());
-        this.service.getCharacteristic(Char.ChargingState).onGet(() => this.readChargingState());
-    }
-    readLevel() {
-        this.requireBattery();
-        return this.level ?? 0;
-    }
-    readLowBattery() {
-        this.requireBattery();
-        const { Characteristic: Char } = this.host.hap;
-        return (this.level ?? 100) <= LOW_BATTERY_THRESHOLD
-            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
-            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL;
-    }
-    readChargingState() {
-        this.requireBattery();
-        const { Characteristic: Char } = this.host.hap;
-        return this.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING;
-    }
-    requireBattery() {
-        this.requireObservedState();
-        if (this.level === undefined) {
-            throw this.communicationFailure();
-        }
+        this.battery = new player_battery_1.PlayerBattery({
+            hap: this.host.hap,
+            accessory: this.accessory,
+            displayName: this.displayName,
+            warnOnce: (key, message) => this.warnOnce(key, message),
+            communicationFailure: () => this.communicationFailure(),
+            hasObservedState: () => this.hasObservedState(),
+        });
     }
     updateFromObservation(observation, _reason) {
-        const battery = observation.battery;
-        if (battery === undefined) {
-            if (this.level !== undefined) {
-                this.level = undefined;
-            }
-            this.warnOnce('no-battery', `${(0, utils_1.forLog)(this.displayName)} reports no battery pack; disable the battery sensor `
-                + 'for this player in the plugin settings');
-            this.markUnavailable();
-            return;
-        }
-        this.level = battery.level;
-        this.charging = battery.charging;
-        const { Characteristic: Char } = this.host.hap;
-        this.service.updateCharacteristic(Char.BatteryLevel, battery.level);
-        this.service.updateCharacteristic(Char.StatusLowBattery, battery.level <= LOW_BATTERY_THRESHOLD
-            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
-            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL);
-        this.service.updateCharacteristic(Char.ChargingState, battery.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING);
+        this.battery.apply(observation);
     }
     markUnavailable() {
-        const { Characteristic: Char } = this.host.hap;
-        const error = this.communicationFailure();
-        this.service.updateCharacteristic(Char.BatteryLevel, error);
-        this.service.updateCharacteristic(Char.StatusLowBattery, error);
-        this.service.updateCharacteristic(Char.ChargingState, error);
+        this.battery.markUnavailable();
     }
 }
 exports.BatteryAccessory = BatteryAccessory;

package/dist/devices/mute-accessory.d.ts

@@ -27,6 +27,8 @@ export declare class MuteAccessory extends BaseAccessory {
     private readonly service;
     /** Last mute state read from the player. */
     private muted;
+    /** Present when this switch also carries the player's battery. */
+    private readonly battery;
     constructor(init: AccessoryInit);
     private readOn;
     private writeOn;

package/dist/devices/mute-accessory.js

@@ -25,11 +25,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MuteAccessory = void 0;
 const utils_1 = require("../utils");
 const base_accessory_1 = require("./base-accessory");
+const player_battery_1 = require("./player-battery");
 /** A mute switch for one player. */
 class MuteAccessory extends base_accessory_1.BaseAccessory {
     service;
     /** Last mute state read from the player. */
     muted;
+    /** Present when this switch also carries the player's battery. */
+    battery;
     constructor(init) {
         super(init);
         const { Characteristic: Char, Service: HapService } = this.host.hap;
@@ -39,6 +42,14 @@ class MuteAccessory extends base_accessory_1.BaseAccessory {
             .getCharacteristic(Char.On)
             .onGet(() => this.readOn())
             .onSet(async (value) => this.writeOn(value));
+        this.battery = (0, player_battery_1.attachHostedBattery)({
+            hap: this.host.hap,
+            accessory: this.accessory,
+            displayName: this.displayName,
+            warnOnce: (key, message) => this.warnOnce(key, message),
+            communicationFailure: () => this.communicationFailure(),
+            hasObservedState: () => this.hasObservedState(),
+        }, this.context.hostsBattery === true);
     }
     readOn() {
         this.requireObservedState();
@@ -63,9 +74,11 @@ class MuteAccessory extends base_accessory_1.BaseAccessory {
     updateFromObservation(observation, _reason) {
         this.muted = observation.muted;
         this.service.updateCharacteristic(this.host.hap.Characteristic.On, observation.muted);
+        this.battery?.apply(observation);
     }
     markUnavailable() {
         this.service.updateCharacteristic(this.host.hap.Characteristic.On, this.communicationFailure());
+        this.battery?.markUnavailable();
     }
 }
 exports.MuteAccessory = MuteAccessory;

package/dist/devices/player-battery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The HAP Battery service for one player.
+ *
+ * HomeKit will not render a Battery accessory on its own: the Home app parks
+ * that tile under Other and says Not Supported. The service has to sit on a
+ * tile Home already understands, which for this plugin is the volume slider or
+ * the mute switch. A player that exposes neither still gets a standalone
+ * Battery accessory, and Home will keep saying Not Supported for that one.
+ *
+ * `/SyncStatus` already carries `<battery level charging/>` when a pack is
+ * fitted, so this costs no extra traffic. A player without a pack never reports
+ * the element, and the service then reports No Response rather than inventing
+ * a charge level.
+ */
+import type { API, PlatformAccessory } from 'homebridge';
+import type { PlayerObservation } from '../types';
+/** Collaborators for one Battery service. */
+export interface PlayerBatteryInit {
+    hap: API['hap'];
+    accessory: PlatformAccessory;
+    displayName: string;
+    warnOnce: (key: string, message: string) => void;
+    communicationFailure: () => Error;
+    hasObservedState: () => boolean;
+}
+/** Charge level, charging state and low-battery on one HAP Battery service. */
+export declare class PlayerBattery {
+    private readonly init;
+    private readonly service;
+    private level;
+    private charging;
+    constructor(init: PlayerBatteryInit);
+    apply(observation: PlayerObservation): void;
+    markUnavailable(): void;
+    private readLevel;
+    private readLowBattery;
+    private readChargingState;
+    private requireBattery;
+}
+/** Bind a Battery service, or drop a leftover one when this tile no longer hosts it. */
+export declare function attachHostedBattery(init: PlayerBatteryInit, hosts: boolean): PlayerBattery | undefined;
+/** Drop a leftover Battery service when this accessory no longer hosts one. */
+export declare function dropPlayerBattery(accessory: PlatformAccessory, hap: API['hap']): void;

package/dist/devices/player-battery.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The HAP Battery service for one player.
+ *
+ * HomeKit will not render a Battery accessory on its own: the Home app parks
+ * that tile under Other and says Not Supported. The service has to sit on a
+ * tile Home already understands, which for this plugin is the volume slider or
+ * the mute switch. A player that exposes neither still gets a standalone
+ * Battery accessory, and Home will keep saying Not Supported for that one.
+ *
+ * `/SyncStatus` already carries `<battery level charging/>` when a pack is
+ * fitted, so this costs no extra traffic. A player without a pack never reports
+ * the element, and the service then reports No Response rather than inventing
+ * a charge level.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayerBattery = void 0;
+exports.attachHostedBattery = attachHostedBattery;
+exports.dropPlayerBattery = dropPlayerBattery;
+const utils_1 = require("../utils");
+/** Below this percentage HomeKit is told the battery is low. */
+const LOW_BATTERY_THRESHOLD = 20;
+/** Charge level, charging state and low-battery on one HAP Battery service. */
+class PlayerBattery {
+    init;
+    service;
+    level;
+    charging = false;
+    constructor(init) {
+        this.init = init;
+        const { Characteristic: Char, Service: HapService } = init.hap;
+        this.service = requireService(init.accessory, HapService.Battery, init.displayName);
+        this.service.setCharacteristic(Char.Name, init.displayName);
+        this.service.getCharacteristic(Char.BatteryLevel).onGet(() => this.readLevel());
+        this.service.getCharacteristic(Char.StatusLowBattery).onGet(() => this.readLowBattery());
+        this.service.getCharacteristic(Char.ChargingState).onGet(() => this.readChargingState());
+    }
+    apply(observation) {
+        const battery = observation.battery;
+        if (battery === undefined) {
+            this.level = undefined;
+            this.init.warnOnce('no-battery', `${(0, utils_1.forLog)(this.init.displayName)} reports no battery pack; disable the battery sensor `
+                + 'for this player in the plugin settings');
+            this.markUnavailable();
+            return;
+        }
+        this.level = battery.level;
+        this.charging = battery.charging;
+        const { Characteristic: Char } = this.init.hap;
+        this.service.updateCharacteristic(Char.BatteryLevel, battery.level);
+        this.service.updateCharacteristic(Char.StatusLowBattery, battery.level <= LOW_BATTERY_THRESHOLD
+            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
+            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL);
+        this.service.updateCharacteristic(Char.ChargingState, battery.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING);
+    }
+    markUnavailable() {
+        const { Characteristic: Char } = this.init.hap;
+        const error = this.init.communicationFailure();
+        this.service.updateCharacteristic(Char.BatteryLevel, error);
+        this.service.updateCharacteristic(Char.StatusLowBattery, error);
+        this.service.updateCharacteristic(Char.ChargingState, error);
+    }
+    readLevel() {
+        this.requireBattery();
+        return this.level ?? 0;
+    }
+    readLowBattery() {
+        this.requireBattery();
+        const { Characteristic: Char } = this.init.hap;
+        return (this.level ?? 100) <= LOW_BATTERY_THRESHOLD
+            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
+            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL;
+    }
+    readChargingState() {
+        this.requireBattery();
+        const { Characteristic: Char } = this.init.hap;
+        return this.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING;
+    }
+    requireBattery() {
+        if (!this.init.hasObservedState() || this.level === undefined) {
+            throw this.init.communicationFailure();
+        }
+    }
+}
+exports.PlayerBattery = PlayerBattery;
+/** Bind a Battery service, or drop a leftover one when this tile no longer hosts it. */
+function attachHostedBattery(init, hosts) {
+    if (!hosts) {
+        dropPlayerBattery(init.accessory, init.hap);
+        return undefined;
+    }
+    return new PlayerBattery(init);
+}
+/** Drop a leftover Battery service when this accessory no longer hosts one. */
+function dropPlayerBattery(accessory, hap) {
+    const stale = accessory.services.find((service) => service.UUID === hap.Service.Battery.UUID);
+    if (stale !== undefined) {
+        accessory.removeService(stale);
+    }
+}
+function requireService(accessory, ServiceType, displayName) {
+    const existing = accessory.services.find((service) => service.UUID === ServiceType.UUID);
+    return existing ?? accessory.addService(new ServiceType(displayName));
+}

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

@@ -36,6 +36,8 @@ export declare class VolumeAccessory extends BaseAccessory {
     private fixedVolume;
     /** Level awaiting a coalesced write. */
     private pendingLevel;
+    /** Present when this slider also carries the player's battery. */
+    private readonly battery;
     /** In-flight coalesced write, shared by every handler that queued into it. */
     private flush;
     constructor(init: AccessoryInit);

package/dist/devices/volume-accessory.js

@@ -32,6 +32,7 @@ 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");
+const player_battery_1 = require("./player-battery");
 /** A volume slider for one player. */
 class VolumeAccessory extends base_accessory_1.BaseAccessory {
     surface;
@@ -41,12 +42,22 @@ class VolumeAccessory extends base_accessory_1.BaseAccessory {
     fixedVolume = false;
     /** Level awaiting a coalesced write. */
     pendingLevel;
+    /** Present when this slider also carries the player's battery. */
+    battery;
     /** In-flight coalesced write, shared by every handler that queued into it. */
     flush;
     constructor(init) {
         super(init);
         this.surface = this.buildSurface();
         this.bindHandlers();
+        this.battery = (0, player_battery_1.attachHostedBattery)({
+            hap: this.host.hap,
+            accessory: this.accessory,
+            displayName: this.displayName,
+            warnOnce: (key, message) => this.warnOnce(key, message),
+            communicationFailure: () => this.communicationFailure(),
+            hasObservedState: () => this.hasObservedState(),
+        }, this.context.hostsBattery === true);
     }
     buildSurface() {
         const { Characteristic: Char, Service: HapService } = this.host.hap;
@@ -190,6 +201,7 @@ class VolumeAccessory extends base_accessory_1.BaseAccessory {
                     + 'cannot do anything; disable the slider for this player in the plugin settings');
                 this.markUnavailable();
             }
+            this.battery?.apply(observation);
             return;
         }
         this.fixedVolume = false;
@@ -207,12 +219,14 @@ class VolumeAccessory extends base_accessory_1.BaseAccessory {
         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);
+        this.battery?.apply(observation);
     }
     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);
+        this.battery?.markUnavailable();
     }
 }
 exports.VolumeAccessory = VolumeAccessory;

package/dist/platform.js

@@ -404,6 +404,9 @@ class BluOSPlatform {
         if (Number.isInteger(previous?.lastNonZeroVolume)) {
             context.lastNonZeroVolume = previous?.lastNonZeroVolume;
         }
+        if (accessory.hostsBattery === true) {
+            context.hostsBattery = true;
+        }
         return context;
     }
     /**

package/dist/types/index.d.ts

@@ -18,10 +18,11 @@ export interface PluginLogger {
  * What an accessory does. Part of its identity, and therefore of its UUID.
  *
  * `volume` is the fake slider, `mute` the mute switch, `volumePreset` a
- * one-level switch, `battery` the state-of-charge sensor for portables, and
- * `reboot` a momentary switch that restarts one player. `rebootAll` is the only
- * kind with no player behind it: it belongs to the platform and restarts every
- * player it can find.
+ * one-level switch, `battery` a standalone charge sensor used only when the
+ * player has no volume or mute tile to host it, and `reboot` a momentary
+ * switch that restarts one player. `rebootAll` is the only kind with no
+ * player behind it: it belongs to the platform and restarts every player it
+ * can find.
  */
 export declare const ACCESSORY_KINDS: readonly ["volume", "mute", "volumePreset", "battery", "reboot", "rebootAll"];
 /** @see ACCESSORY_KINDS */
@@ -121,6 +122,14 @@ export interface ResolvedAccessory {
     sliderService: SliderService;
     /** Target level, for `volumePreset` only. */
     volume?: number;
+    /**
+     * True when this volume or mute accessory also carries the Battery service.
+     *
+     * HomeKit will not render a Battery accessory on its own. The service sits
+     * on the volume tile when that exists, otherwise on mute. A player that
+     * exposes neither still gets a standalone `battery` accessory.
+     */
+    hostsBattery?: boolean;
 }
 /**
  * What gets persisted in `PlatformAccessory.context`.
@@ -150,6 +159,8 @@ export interface AccessoryContext {
      * authoritative and preferred.
      */
     lastNonZeroVolume?: number;
+    /** True when this volume or mute accessory also carries the Battery service. */
+    hostsBattery?: boolean;
 }
 /**
  * How a player relates to a runtime sync group.

package/dist/types/index.js

@@ -16,10 +16,11 @@ exports.isSliderService = isSliderService;
  * What an accessory does. Part of its identity, and therefore of its UUID.
  *
  * `volume` is the fake slider, `mute` the mute switch, `volumePreset` a
- * one-level switch, `battery` the state-of-charge sensor for portables, and
- * `reboot` a momentary switch that restarts one player. `rebootAll` is the only
- * kind with no player behind it: it belongs to the platform and restarts every
- * player it can find.
+ * one-level switch, `battery` a standalone charge sensor used only when the
+ * player has no volume or mute tile to host it, and `reboot` a momentary
+ * switch that restarts one player. `rebootAll` is the only kind with no
+ * player behind it: it belongs to the platform and restarts every player it
+ * can find.
  */
 exports.ACCESSORY_KINDS = [
     'volume',

package/dist/utils/context.js

@@ -52,5 +52,8 @@ function parseAccessoryContext(accessory) {
     if (Number.isInteger(raw.lastNonZeroVolume)) {
         context.lastNonZeroVolume = raw.lastNonZeroVolume;
     }
+    if (raw.hostsBattery === true) {
+        context.hostsBattery = true;
+    }
     return context;
 }

package/dist/utils/validators.js

@@ -432,6 +432,9 @@ function resolveAccessories(devices, warnings, platform) {
                 // ambiguous both on screen and to Siri.
                 name: suffixName(device.name, 'Volume'),
                 sliderService: device.sliderService,
+                // Home will not render a Battery accessory on its own. The service sits
+                // on this tile when a slider exists, so the charge icon appears there.
+                ...(device.battery ? { hostsBattery: true } : {}),
             });
         }
         if (device.mute) {
@@ -440,9 +443,11 @@ function resolveAccessories(devices, warnings, platform) {
                 deviceId: device.id,
                 name: suffixName(device.name, 'Mute'),
                 sliderService: device.sliderService,
+                // Mute hosts the battery only when there is no slider to put it on.
+                ...(device.battery && !device.volumeSlider ? { hostsBattery: true } : {}),
             });
         }
-        if (device.battery) {
+        if (device.battery && !device.volumeSlider && !device.mute) {
             accessories.push({
                 kind: 'battery',
                 deviceId: device.id,

package/docs/FEATURES.md

@@ -11,7 +11,7 @@ A checklist of what is built. The plugin aims to cover everything about a BluOS
 - ✅ Slider exposed as a fan (default) or a lightbulb. Siri commands aimed at lights do not sweep up the fan
 - ✅ Mute switch, with unmute restoring the level the player remembered instead of a guess
 - ✅ Volume preset switches: one exact level per switch, addressable by name with Siri; set On sets the level, set Off is a no-op
-- ✅ Battery sensor (level, charging state, low-battery) for players with a battery pack fitted
+- ✅ Battery (level, charging state, low-battery) on the volume tile, or on mute if there is no slider, for players with a pack fitted. A battery-only player still gets a standalone tile; the Home app will not render that one
 - ✅ Reboot switch per player, momentary so a scene or "turn everything off" cannot reboot the stereo, and still pressable when the player has stopped answering. Reboots the whole box on a multi-zone chassis, which BluOS gives no way to avoid, and warns at startup when that means other configured rooms
 - ✅ Optional "reboot all" switch that reboots every BluOS player on the network, sending once per box instead of once per zone. The info log is a count (`found … device(s), … player(s)`), then `N of N device(s) rebooted`. The debug log names each box before anything is sent. Accessories on a box that was just rebooted stay quiet until it answers again, then take its live state. You choose its name with `options.rebootAllName`, so it can sit in whichever Home app room suits you
 - ✅ Fixed-output players detected from `volume="-1"` and given no slider, with one explanatory log line
@@ -82,7 +82,7 @@ HomeKit has no way to render a library or a queue, and no vocabulary for "play t
 | `volumeSlider` | Fanv2 (default) or Lightbulb, as a 0–100 slider |
 | `mute` | Switch |
 | `volumePresets[]` | Switch, one per level |
-| `battery` | Battery |
+| `battery` | Battery service on the volume tile, or on mute if there is no slider. Standalone Battery accessory only when both are off |
 | `reboot` | Switch, momentary |
 
 ## Accessories per platform

package/docs/README-DETAILED.md

@@ -36,7 +36,7 @@ Where HomeKit is genuinely better is the tile, the scene, the automation and the
 
 **Volume preset switches.** One switch per level, for example "Study Evening" at 15. Addressable by name with Siri, and far safer than a slider inside an automation. Setting one On sets the level. Setting it Off does nothing.
 
-**Battery sensor.** Charge level, charging state and low-battery warning, for players with a battery pack fitted (PULSE FLEX with BP100, PULSE M).
+**Battery.** Charge level, charging state and low-battery warning, for players with a battery pack fitted (PULSE FLEX with BP100, PULSE M). The Home app will not render a Battery accessory on its own, so the service sits on the volume tile when that exists, otherwise on mute. A player that exposes battery and nothing else still gets a standalone tile, and Home will keep saying Not Supported for that one.
 
 **Reboot switch.** Reboots the player. It springs back to off and ignores being switched off, so a scene or "turn everything off" cannot reboot your stereo. It stays pressable while a player is showing No Response, which is exactly when you want it.
 

package/homebridge-ui/public/index.html

@@ -20,6 +20,9 @@
   .bluos-badge { font-size: .7rem; text-transform: uppercase; letter-spacing: .03em; padding: .12rem .4rem; border-radius: .25rem; background: rgba(128, 128, 128, .2); }
   .bluos-badge.warn { background: rgba(255, 193, 7, .28); }
   .bluos-options { display: flex; gap: 1.1rem; flex-wrap: wrap; margin-top: .6rem; }
+  .bluos-check { display: inline-flex; align-items: center; gap: .4rem; margin: 0; }
+  .bluos-check input { margin: 0; }
+  .bluos-check label { margin: 0; }
   .bluos-presets { margin-top: .6rem; }
   .bluos-preset-row { display: flex; gap: .4rem; align-items: center; margin-bottom: .35rem; }
   .bluos-preset-row input[type="text"] { flex: 1 1 8rem; }
@@ -83,7 +86,7 @@
     <div class="bluos-card-title">Whole install</div>
   </div>
   <div class="bluos-options">
-    <label class="mb-0">
+    <label class="bluos-check">
       <input type="checkbox" id="reboot-all" />
       Reboot All switch
     </label>
@@ -96,13 +99,10 @@
     <label for="reboot-all-name" style="font-size: .8rem;">Name in the Home app</label>
     <input type="text" class="form-control form-control-sm" id="reboot-all-name"
            maxlength="64" placeholder="BluOS Reboot All" />
-    <div class="bluos-meta">Name it for the room you want to keep it in.</div>
   </div>
 </div>
 
 <div class="bluos-actions">
-  <button class="btn btn-success" id="save" disabled>Save</button>
-  <span class="spacer"></span>
   <span id="summary" class="text-muted" style="font-size: .85rem;"></span>
 </div>
 

package/homebridge-ui/public/index.js

@@ -80,9 +80,8 @@
       platformConfig.devices = []
     }
     // Copied rather than aliased: `getPluginConfig` hands back the live objects,
-    // and editing a control should not change the saved configuration until the
-    // user presses Save. `devices` is already rebuilt from scratch on save, so
-    // this closes the same gap for the install-wide settings.
+    // and editing a control must not change them. The page pushes a fresh copy
+    // into Homebridge; the footer Save is what writes that copy to disk.
     platformConfig.options = typeof platformConfig.options === 'object' && platformConfig.options !== null
       ? Object.assign({}, platformConfig.options)
       : {}
@@ -115,9 +114,9 @@
           ? device.volumePresets.filter((preset) => preset && typeof preset.name === 'string')
             .map((preset) => ({ name: preset.name, volume: Number(preset.volume) || 0 }))
           : [],
-        // Kept so that saving preserves settings this page does not model, such
-        // as a per-device sliderService written in the advanced editor. Without
-        // it, opening this page and pressing Save would silently discard them.
+        // Kept so that a later push preserves settings this page does not model,
+        // such as a per-device sliderService written in the advanced editor.
+        // Without it, opening this page and saving would silently discard them.
         saved: device,
       })
     }
@@ -140,6 +139,9 @@
         if (existing.fixedVolume) {
           existing.volumeSlider = false
         }
+        if (!existing.hasBattery) {
+          existing.battery = false
+        }
         continue
       }
       players.set(player.id, {
@@ -178,7 +180,7 @@
         port: player.port,
         volumeSlider: player.volumeSlider === true,
         mute: player.mute === true,
-        battery: player.battery === true,
+        battery: player.battery === true && player.hasBattery === true,
         reboot: player.reboot === true,
       })
       if (player.brand) {
@@ -239,22 +241,33 @@
     }
   }
 
-  async function save() {
-    const devices = toDevices()
-    platformConfig.devices = devices
+  /**
+   * Copy the form into Homebridge's in-memory plugin config.
+   *
+   * The purple footer Save writes that copy to disk. This page does not save on
+   * its own: a second Save is easy to miss, and `savePluginConfig` is the same
+   * action as that footer button.
+   */
+  async function pushConfig() {
+    platformConfig.devices = toDevices()
     applyPlatformOptions()
     try {
       await homebridge.updatePluginConfig([platformConfig])
-      await homebridge.savePluginConfig()
-      homebridge.toast.success(
-        devices.length === 1 ? '1 player saved.' : `${devices.length} players saved.`,
-        'Saved',
-      )
     } catch (error) {
-      homebridge.toast.error(describeError(error), 'Could not save')
+      homebridge.toast.error(describeError(error), 'Could not update the configuration')
     }
   }
 
+  function changed() {
+    refreshSummary()
+    void pushConfig()
+  }
+
+  function renderChanged() {
+    render()
+    void pushConfig()
+  }
+
   // --- Rendering ----------------------------------------------------------
 
   function renderPresets(player) {
@@ -270,7 +283,7 @@
       name.value = preset.name
       name.addEventListener('input', () => {
         preset.name = name.value
-        refreshSummary()
+        changed()
       })
 
       const volume = el('input', {
@@ -279,12 +292,13 @@
       volume.value = String(preset.volume)
       volume.addEventListener('input', () => {
         preset.volume = Number(volume.value)
+        changed()
       })
 
       const remove = el('button', { class: 'btn btn-outline-danger btn-sm', type: 'button' }, 'Remove')
       remove.addEventListener('click', () => {
         player.presets.splice(index, 1)
-        render()
+        renderChanged()
       })
 
       row.append(name, volume, remove)
@@ -294,20 +308,23 @@
     const add = el('button', { class: 'btn btn-outline-secondary btn-sm', type: 'button' }, 'Add volume preset')
     add.addEventListener('click', () => {
       player.presets.push({ name: '', volume: 30 })
-      render()
+      renderChanged()
     })
     wrapper.append(add)
     return wrapper
   }
 
   function checkbox(label, checked, disabled, onChange) {
-    const wrapper = el('div', { class: 'custom-control custom-switch' })
+    const wrapper = el('div', { class: 'bluos-check' })
     const id = `opt-${Math.random().toString(36).slice(2)}`
-    const input = el('input', { type: 'checkbox', class: 'custom-control-input', id })
+    const input = el('input', { type: 'checkbox', id })
     input.checked = checked
     input.disabled = disabled === true
-    input.addEventListener('change', () => onChange(input.checked))
-    const text = el('label', { class: 'custom-control-label', for: id }, label)
+    input.addEventListener('change', () => {
+      onChange(input.checked)
+      changed()
+    })
+    const text = el('label', { for: id }, label)
     wrapper.append(input, text)
     return wrapper
   }
@@ -321,7 +338,7 @@
     include.setAttribute('aria-label', 'Expose this player in HomeKit')
     include.addEventListener('change', () => {
       player.selected = include.checked
-      render()
+      renderChanged()
     })
 
     const title = el('div', { class: 'bluos-card-title' })
@@ -329,7 +346,7 @@
     nameInput.value = player.name
     nameInput.addEventListener('input', () => {
       player.name = nameInput.value
-      refreshSummary()
+      changed()
     })
     title.append(nameInput)
 
@@ -371,12 +388,14 @@
       (value) => { player.volumeSlider = value },
     ))
     options.append(checkbox('Mute switch', player.mute, false, (value) => { player.mute = value }))
-    options.append(checkbox(
-      player.hasBattery ? 'Battery sensor' : 'Battery sensor (no pack fitted)',
-      player.battery && player.hasBattery,
-      !player.hasBattery,
-      (value) => { player.battery = value },
-    ))
+    if (player.hasBattery) {
+      options.append(checkbox(
+        'Battery (on the volume or mute tile; its own tile only if those are off)',
+        player.battery,
+        false,
+        (value) => { player.battery = value },
+      ))
+    }
     options.append(checkbox(
       'Reboot switch (reboots this player, and any zone sharing its box)',
       player.reboot,
@@ -397,7 +416,7 @@
     for (const device of devices) {
       tiles += device.volumeSlider ? 1 : 0
       tiles += device.mute ? 1 : 0
-      tiles += device.battery ? 1 : 0
+      tiles += device.battery && !device.volumeSlider && !device.mute ? 1 : 0
       tiles += device.reboot ? 1 : 0
       tiles += Array.isArray(device.volumePresets) ? device.volumePresets.length : 0
     }
@@ -407,7 +426,6 @@
     byId('summary').textContent = devices.length === 0 && tiles === 0
       ? 'Nothing selected.'
       : `${devices.length} player(s), ${tiles} HomeKit accessory(s).`
-    byId('save').disabled = false
   }
 
   function render() {
@@ -449,7 +467,7 @@
         }
       }
       mergeDiscovered(found)
-      render()
+      renderChanged()
       if (found.length === 0) {
         homebridge.toast.warning(
           'No players answered. If multicast is filtered on your network, add a player by address.',
@@ -487,7 +505,7 @@
           player.selected = true
         }
       }
-      render()
+      renderChanged()
       homebridge.toast.success(`Found ${found.length} zone(s) at ${host}.`, 'Player added')
     } catch (error) {
       homebridge.toast.error(describeError(error), 'Probe failed')
@@ -498,10 +516,12 @@
 
   byId('discover').addEventListener('click', () => void discover())
   byId('manual-probe').addEventListener('click', () => void probe())
-  byId('save').addEventListener('click', () => void save())
   byId('reboot-all').addEventListener('change', () => {
     refreshRebootAllName()
-    refreshSummary()
+    changed()
+  })
+  byId('reboot-all-name').addEventListener('input', () => {
+    changed()
   })
   byId('toggle-manual').addEventListener('click', () => {
     const panel = byId('manual')
@@ -524,6 +544,7 @@
   loadConfig()
     .then(() => {
       render()
+      return pushConfig()
     })
     .catch((error) => {
       homebridge.toast.error(describeError(error), 'Could not read the configuration')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-bluos",
   "displayName": "Homebridge BluOS",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "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",