homebridge-bluos 0.1.0

package/dist/utils/validators.js

@@ -0,0 +1,461 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Configuration validation.
+ *
+ * The split between fatal and non-fatal is deliberate. A structural problem —
+ * `devices` present but not an array — means the file does not describe anything
+ * we can act on, so the platform disables itself while leaving cached
+ * accessories registered, and HomeKit shows them as No Response rather than
+ * losing the rooms and automations built on them.
+ *
+ * A problem with one device is different: rejecting the whole fleet because one
+ * entry is malformed would be a worse outcome than skipping that entry. Skipped
+ * devices are warned about by name and reason, because a device that silently
+ * fails to appear is the hardest kind of bug for a user to report.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forLog = forLog;
+exports.forDisplay = forDisplay;
+exports.isIpv4 = isIpv4;
+exports.isValidHost = isValidHost;
+exports.isNonPrivateIpv4 = isNonPrivateIpv4;
+exports.isProbeableHost = isProbeableHost;
+exports.resolveDiscoveryTimeoutSec = resolveDiscoveryTimeoutSec;
+exports.resolveSliderService = resolveSliderService;
+exports.validateConfig = validateConfig;
+exports.resolveAccessories = resolveAccessories;
+const identity_1 = require("../api/identity");
+const settings_1 = require("../settings");
+const types_1 = require("../types");
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/;
+/**
+ * The same class, global, for replacement.
+ * Kept separate because a global regex carries `lastIndex` state, which would
+ * make the `test` calls above return alternating answers for one input.
+ */
+const ALL_CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/g;
+const HOSTNAME = /^[A-Za-z0-9]([A-Za-z0-9._-]{0,252}[A-Za-z0-9])?$/;
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * Make an untrusted string safe to interpolate into a log line.
+ *
+ * Device names come from configuration and from the players themselves, so they
+ * are attacker-influenced in the threat model where someone can write to either.
+ * A newline in a log line lets them forge entries; truncation stops one long
+ * name from burying everything else.
+ */
+function forLog(value) {
+    const text = typeof value === 'string' ? value : String(value);
+    const sanitized = text.replace(ALL_CONTROL_CHARACTERS, '\uFFFD');
+    return sanitized.length > settings_1.MAX_LOG_FIELD_LENGTH
+        ? `${sanitized.slice(0, settings_1.MAX_LOG_FIELD_LENGTH)}\u2026`
+        : sanitized;
+}
+/**
+ * Make an untrusted string safe to publish to HomeKit.
+ *
+ * Same sanitising as {@link forLog} but capped at HomeKit's name budget rather
+ * than the log field budget, for values that become characteristic values and
+ * are written into the accessory cache. An empty result becomes undefined, so a
+ * caller keeps the value it already had instead of publishing a blank.
+ */
+function forDisplay(value) {
+    const cleaned = value.replace(ALL_CONTROL_CHARACTERS, '').trim();
+    if (cleaned.length === 0) {
+        return undefined;
+    }
+    return cleaned.length > settings_1.MAX_NAME_LENGTH
+        ? `${cleaned.slice(0, settings_1.MAX_NAME_LENGTH - 1)}\u2026`
+        : cleaned;
+}
+/** True for an IPv4 literal whose octets are all in range. */
+function isIpv4(value) {
+    const match = IPV4.exec(value);
+    if (match === null) {
+        return false;
+    }
+    // Canonical form only. A leading zero is rejected rather than normalised
+    // because `010` is decimal ten to this check and octal eight to some
+    // resolvers, and the address we validate must be the address that gets dialled.
+    return match.slice(1).every((octet) => {
+        const number = Number(octet);
+        return number >= 0 && number <= 255 && String(number) === octet;
+    });
+}
+/** True for something usable as an HTTP host: an IPv4 literal or a hostname. */
+function isValidHost(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length > 253) {
+        return false;
+    }
+    // A four-octet dotted quad is an address, never a hostname. Falling through
+    // to HOSTNAME would accept `192.168.04.11` and `999.999.999.999`, undoing
+    // isIpv4's canonical-form check — the exact octal-ambiguity case that check
+    // exists to reject.
+    if (IPV4.test(trimmed)) {
+        return isIpv4(trimmed);
+    }
+    return HOSTNAME.test(trimmed);
+}
+/**
+ * True for an address outside the ranges treated as local.
+ *
+ * Local here is RFC 1918, RFC 6598 shared address space (CGNAT / Tailscale),
+ * loopback, and link-local. Not blocked in configuration, only warned about:
+ * the BluOS API is unauthenticated and intended for a local network, and a
+ * routable address in the configuration is much more likely to be a typo than
+ * an intention. Hostnames cannot be classified this way and are left alone
+ * in configuration; the settings-page probe uses {@link isProbeableHost}.
+ */
+function isNonPrivateIpv4(value) {
+    if (!isIpv4(value)) {
+        return false;
+    }
+    const [a = 0, b = 0] = value.split('.').map(Number);
+    if (a === 10 || a === 127) {
+        return false;
+    }
+    if (a === 192 && b === 168) {
+        return false;
+    }
+    if (a === 172 && b >= 16 && b <= 31) {
+        return false;
+    }
+    if (a === 169 && b === 254) {
+        return false;
+    }
+    // RFC 6598: 100.64.0.0/10. Tailscale and carrier-grade NAT live here.
+    if (a === 100 && b >= 64 && b <= 127) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Suffixes that name a host on this network rather than on the public internet.
+ *
+ * `.local` is mDNS. `.localhost`, `.internal` and `.home.arpa` are IANA
+ * special-use. A single-label name (no dots) is a DHCP / local-resolver name.
+ */
+const PROBE_LOCAL_SUFFIXES = ['.local', '.localhost', '.internal', '.home.arpa'];
+/**
+ * True for a host the settings-page probe is allowed to dial.
+ *
+ * Narrower than {@link isValidHost}: configuration may name a split-DNS
+ * hostname that happens to look public, but the probe is an authenticated
+ * Homebridge administrator asking this host to open a connection, so it must
+ * not become a scanner. Public IPv4 literals and multi-label public names
+ * (`example.com`) are refused. Private IPv4 (including CGNAT) and local
+ * hostnames are accepted.
+ */
+function isProbeableHost(value) {
+    if (!isValidHost(value)) {
+        return false;
+    }
+    const host = value.trim();
+    if (isIpv4(host)) {
+        return !isNonPrivateIpv4(host);
+    }
+    const lower = host.toLowerCase();
+    if (!lower.includes('.')) {
+        return true;
+    }
+    return PROBE_LOCAL_SUFFIXES.some((suffix) => lower.endsWith(suffix) && lower.length > suffix.length);
+}
+/** Clamp the discovery window into the supported range. */
+function resolveDiscoveryTimeoutSec(value, warnings) {
+    if (value === undefined) {
+        return settings_1.DEFAULT_DISCOVERY_TIMEOUT_SEC;
+    }
+    const numeric = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(numeric)) {
+        warnings?.push(`options.discoveryTimeoutSec is not a number; using ${settings_1.DEFAULT_DISCOVERY_TIMEOUT_SEC}s`);
+        return settings_1.DEFAULT_DISCOVERY_TIMEOUT_SEC;
+    }
+    const clamped = Math.min(settings_1.MAX_DISCOVERY_TIMEOUT_SEC, Math.max(settings_1.MIN_DISCOVERY_TIMEOUT_SEC, Math.round(numeric)));
+    if (clamped !== numeric) {
+        warnings?.push(`options.discoveryTimeoutSec clamped to ${clamped}s`);
+    }
+    return clamped;
+}
+/**
+ * Resolve a slider service, falling back to the platform default then `fan`.
+ *
+ * An empty string counts as absent, because that is what the Homebridge form
+ * writes for the per-device "use the platform setting" option; treating it as a
+ * bad value would make choosing that option override the platform setting.
+ */
+function resolveSliderService(deviceValue, platformValue, warnings, label) {
+    const where = label === undefined ? '' : `${label} `;
+    for (const candidate of [deviceValue, platformValue]) {
+        if (candidate === undefined || candidate === '') {
+            continue;
+        }
+        if ((0, types_1.isSliderService)(candidate)) {
+            return candidate;
+        }
+        warnings?.push(`${where}sliderService ${JSON.stringify(forLog(candidate))} is not "fan" or "lightbulb"; `
+            + 'using "fan"');
+        return 'fan';
+    }
+    // Fanv2 by default: a Lightbulb renders the same slider but is swept up by
+    // "turn off all the lights", which would silence the house.
+    return 'fan';
+}
+function validateName(value, label, problems) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        problems.push(`${label} is missing a name`);
+        return undefined;
+    }
+    const name = value.trim();
+    if (CONTROL_CHARACTERS.test(name)) {
+        problems.push(`${label} name contains control characters`);
+        return undefined;
+    }
+    if (name.length > settings_1.MAX_NAME_LENGTH) {
+        problems.push(`${label} name is longer than ${settings_1.MAX_NAME_LENGTH} characters`);
+        return undefined;
+    }
+    return name;
+}
+function validatePort(value, label, warnings) {
+    if (value === undefined) {
+        return settings_1.DEFAULT_BLUOS_PORT;
+    }
+    const numeric = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(numeric) || numeric < settings_1.MIN_PORT || numeric > settings_1.MAX_PORT) {
+        warnings.push(`${label} port ${forLog(value)} is invalid; using ${settings_1.DEFAULT_BLUOS_PORT}`);
+        return settings_1.DEFAULT_BLUOS_PORT;
+    }
+    if (!settings_1.DOCUMENTED_BLUOS_PORTS.includes(numeric)) {
+        // Accepted anyway: the SRV record, not this list, is the authority on which
+        // port a zone listens to.
+        warnings.push(`${label} uses port ${numeric}, which is outside the documented BluOS ports `
+            + `(${settings_1.DOCUMENTED_BLUOS_PORTS.join(', ')})`);
+    }
+    return numeric;
+}
+/**
+ * Validate volume presets, dropping any that cannot be exposed.
+ *
+ * Two presets on one device with the same level would generate the same
+ * accessory UUID, so the duplicate is dropped rather than allowed to collide.
+ */
+function validatePresets(value, label, warnings) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        warnings.push(`${label} volumePresets is not a list; ignoring it`);
+        return [];
+    }
+    const presets = [];
+    const levels = new Set();
+    value.forEach((entry, index) => {
+        const presetLabel = `${label} volumePresets[${index}]`;
+        if (typeof entry !== 'object' || entry === null) {
+            warnings.push(`${presetLabel} is not an object; skipping it`);
+            return;
+        }
+        const candidate = entry;
+        const problems = [];
+        const name = validateName(candidate.name, presetLabel, problems);
+        const volume = typeof candidate.volume === 'number' ? candidate.volume : Number(candidate.volume);
+        if (!Number.isInteger(volume) || volume < settings_1.VOLUME_MIN || volume > settings_1.VOLUME_MAX) {
+            problems.push(`${presetLabel} volume must be an integer ${settings_1.VOLUME_MIN}-${settings_1.VOLUME_MAX}`);
+        }
+        if (name === undefined || problems.length > 0) {
+            warnings.push(`${problems.join('; ')}; skipping this preset`);
+            return;
+        }
+        if (levels.has(volume)) {
+            warnings.push(`${presetLabel} repeats volume ${volume}; skipping the duplicate`);
+            return;
+        }
+        levels.add(volume);
+        presets.push({ name, volume });
+    });
+    return presets;
+}
+function validateDevice(input) {
+    const { entry, index, platformSlider, warnings } = input;
+    const label = `devices[${index}]`;
+    if (typeof entry !== 'object' || entry === null) {
+        warnings.push(`${label} is not an object; skipping it`);
+        return undefined;
+    }
+    const device = entry;
+    const problems = [];
+    const name = validateName(device.name, label, problems);
+    if (!(0, identity_1.isValidPlayerId)(device.id)) {
+        problems.push(`${label} has no usable id (re-run discovery in the plugin settings)`);
+    }
+    if (!isValidHost(device.host)) {
+        problems.push(`${label} host ${forLog(device.host)} is not a valid address or hostname`);
+    }
+    if (problems.length > 0) {
+        warnings.push(`${problems.join('; ')}; skipping ${name === undefined ? label : forLog(name)}`);
+        return undefined;
+    }
+    // Narrowed by the guards above; the early return covers every failing case.
+    const id = device.id;
+    const host = device.host.trim();
+    const port = validatePort(device.port, label, warnings);
+    if (isNonPrivateIpv4(host)) {
+        warnings.push(`${label} host ${forLog(host)} is not a private address; the BluOS API is `
+            + 'unauthenticated and meant for a local network');
+    }
+    const resolved = {
+        id,
+        name: name,
+        host,
+        port,
+        // Absent means on, matching the schema default, the settings page and the
+        // documented default. The other three accessories are opt-in, so they read
+        // the other way round; a hand-written entry of just id, name and host is
+        // meant to give you a working slider and nothing else.
+        volumeSlider: device.volumeSlider !== false,
+        sliderService: resolveSliderService(device.sliderService, platformSlider, warnings, label),
+        mute: device.mute === true,
+        battery: device.battery === true,
+        volumePresets: validatePresets(device.volumePresets, label, warnings),
+    };
+    if (typeof device.model === 'string' && device.model.trim().length > 0) {
+        resolved.model = forLog(device.model.trim());
+    }
+    if (typeof device.brand === 'string' && device.brand.trim().length > 0) {
+        resolved.brand = forLog(device.brand.trim());
+    }
+    return resolved;
+}
+/**
+ * Validate a platform configuration block.
+ *
+ * Never throws: the platform needs the errors and warnings in order to report
+ * them, and a configuration problem should produce a diagnosable log rather than
+ * an exception during Homebridge startup.
+ */
+function validateConfig(config) {
+    const errors = [];
+    const warnings = [];
+    if (typeof config !== 'object' || config === null) {
+        return { errors: ['platform configuration is missing'], warnings, devices: [] };
+    }
+    const platform = config;
+    const rawDevices = platform.devices;
+    if (rawDevices === undefined) {
+        return {
+            errors: ['configuration has no "devices" list; open the plugin settings and run discovery'],
+            warnings,
+            devices: [],
+        };
+    }
+    if (!Array.isArray(rawDevices)) {
+        return { errors: ['configuration "devices" must be a list'], warnings, devices: [] };
+    }
+    const platformSlider = platform.options?.sliderService;
+    const devices = [];
+    const seenIds = new Set();
+    rawDevices.forEach((entry, index) => {
+        const device = validateDevice({ entry, index, platformSlider, warnings });
+        if (device === undefined) {
+            return;
+        }
+        if (seenIds.has(device.id)) {
+            warnings.push(`devices[${index}] repeats id ${forLog(device.id)}; skipping the duplicate`);
+            return;
+        }
+        seenIds.add(device.id);
+        devices.push(device);
+    });
+    if (rawDevices.length > 0 && devices.length === 0) {
+        // Every entry was rejected. The user plainly meant to configure something,
+        // so this is fatal rather than an idle platform.
+        errors.push(`all ${rawDevices.length} configured device(s) were rejected; see the warnings above`);
+    }
+    else if (rawDevices.length === 0) {
+        warnings.push('no devices are configured; open the plugin settings and run discovery');
+    }
+    const exposed = devices.filter((device) => device.volumeSlider || device.mute || device.battery || device.volumePresets.length > 0);
+    if (devices.length > 0 && exposed.length === 0) {
+        warnings.push('no device has a volume slider, mute switch, battery sensor or volume preset enabled, '
+            + 'so nothing will appear in HomeKit');
+    }
+    return { errors, warnings, devices };
+}
+/**
+ * Expand validated devices into the accessories to expose.
+ *
+ * Names are derived here rather than at use time so that duplicates can be
+ * detected once: two accessories sharing a name still work, but they make Siri
+ * ambiguous, which is worth a warning.
+ */
+function resolveAccessories(devices, warnings) {
+    const accessories = [];
+    for (const device of devices) {
+        // Whether a player reports a fixed output level is only knowable from a live
+        // `/SyncStatus`, so the slider is created here and disables itself on first
+        // observation if the player turns out to have no adjustable volume.
+        if (device.volumeSlider) {
+            accessories.push({
+                kind: 'volume',
+                deviceId: device.id,
+                // Suffixed like the others rather than taking the player's name bare: the
+                // slider is a fan tile, and a bare room name sitting among real fans is
+                // ambiguous both on screen and to Siri.
+                name: suffixName(device.name, 'Volume'),
+                sliderService: device.sliderService,
+            });
+        }
+        if (device.mute) {
+            accessories.push({
+                kind: 'mute',
+                deviceId: device.id,
+                name: suffixName(device.name, 'Mute'),
+                sliderService: device.sliderService,
+            });
+        }
+        if (device.battery) {
+            accessories.push({
+                kind: 'battery',
+                deviceId: device.id,
+                name: suffixName(device.name, 'Battery'),
+                sliderService: device.sliderService,
+            });
+        }
+        for (const preset of device.volumePresets) {
+            accessories.push({
+                kind: 'volumePreset',
+                deviceId: device.id,
+                name: preset.name,
+                sliderService: device.sliderService,
+                volume: preset.volume,
+            });
+        }
+    }
+    const names = new Map();
+    for (const accessory of accessories) {
+        names.set(accessory.name, (names.get(accessory.name) ?? 0) + 1);
+    }
+    for (const [name, count] of names) {
+        if (count > 1) {
+            warnings?.push(`${count} accessories are named ${forLog(name)}; Siri cannot tell them apart`);
+        }
+    }
+    return accessories;
+}
+/** Append a suffix to a device name without exceeding HomeKit's name budget. */
+function suffixName(name, suffix) {
+    const combined = `${name} ${suffix}`;
+    if (combined.length <= settings_1.MAX_NAME_LENGTH) {
+        return combined;
+    }
+    return `${name.slice(0, settings_1.MAX_NAME_LENGTH - suffix.length - 2)}\u2026 ${suffix}`;
+}

package/docs/FEATURES.md

@@ -0,0 +1,91 @@
+# Features
+
+**homebridge-bluos**
+
+A checklist of what is built. The plugin aims to cover everything about a BluOS player that HomeKit can express well, so this list is expected to grow; see the [roadmap](../README.md#roadmap) for what is coming and [PROTOCOL.md](PROTOCOL.md) for the API surface already mapped.
+
+## Built
+
+- ✅ Multi-player platform: as many BluOS zones as you like in one platform block
+- ✅ Volume slider per zone, 0–100, on the same scale as the BluOS app
+- ✅ Slider exposed as a fan (default) or a lightbulb — the fan is not swept up by Siri commands aimed at lights
+- ✅ Mute switch, with unmute restoring the level the player remembered rather than 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
+- ✅ Fixed-output players detected from `volume="-1"` and given no slider, with one explanatory log line
+- ✅ Multi-zone chassis support (NAD CI-S2, CI 580): each zone is a separate player on its own port
+- ✅ mDNS discovery in the settings page, with manual address entry for networks that filter multicast
+- ✅ Discovery writes configuration for you, including the stable identity the platform will look for
+- ✅ Long-polling `/SyncStatus`, so a change made at the front panel, on the remote or in the BluOS app reaches HomeKit in about a second
+- ✅ One poll loop per zone, because the long-poll etag is per zone and not per chassis
+- ✅ The API's one-second same-resource rule enforced centrally, plus a control rate limit and per-chassis write serialisation
+- ✅ Separate connect and total timeouts, and a capped response size
+- ✅ A connection per request, so a held long-poll cannot queue a write behind it
+- ✅ Writes scoped by the zone's current grouping role, verified against a live group: a group leader carries its followers (`tell_slaves=1`), every other zone moves alone (`tell_slaves=0`), and the scope is always stated rather than left to the firmware default
+- ✅ No volume ceiling of its own: the player's configured limit is the one limit, enforced by the hardware for every controller
+- ✅ The player's own clamped answer is adopted rather than the requested value
+- ✅ HomeKit writes that reach the player are logged as `Name: SET n` / `ON` / `OFF`, with `(group)` when the zone is leading
+- ✅ Writes answer inside HomeKit's write window and finish slower work in the background
+- ✅ The pair of writes HomeKit sends when a slider leaves zero is coalesced into one command
+- ✅ Set/poll race protection with a generation counter, so a slider never springs back
+- ✅ A deliberately cancelled poll is not counted as a failure
+- ✅ Exponential backoff to a one-minute ceiling for an unreachable player; the first failure warns, the rest go to debug
+- ✅ Automatic address re-resolution after repeated failures, rate-limited, so a DHCP lease change needs no user action
+- ✅ New addresses persisted into the accessory cache so they survive a restart
+- ✅ Accessory identity is `MAC:port:kind` (plus the preset level), never the address, so an IP change keeps your accessories
+- ✅ Cached accessories adopted by identity rather than replaced, preserving rooms, scenes and automations
+- ✅ Renaming a player applied in place
+- ✅ Reports HomeKit "No Response" until real state has been observed, and again once the player stops answering
+- ✅ An unusable configuration disables the platform and keeps every accessory registered, rather than deleting anything
+- ✅ Per-device validation: one bad entry is skipped with a warning instead of stopping the rest
+- ✅ Size-, depth-, element- and attribute-capped XML parsing, sanitised log output, and a length cap on any identity a player reports for itself
+- ✅ Bounded discovery: the records kept from a browse, the candidates verified from it and the verifications in flight are all capped
+- ✅ Clean shutdown: poll loops, backoff delays and mDNS browses are cancelled rather than run out
+- ✅ A cached accessory the plugin cannot drive reports No Response and says what to do about it, rather than showing 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
+
+## Not built yet
+
+Planned, in roughly this order. Each needs its protocol behaviour verified against hardware first, so none of it is committed to a date:
+
+- ⏳ Group scenes: one switch that forms or breaks a named group (`/AddSlave`, `/RemoveSlave`), which the BluOS app cannot put into an automation
+- ⏳ A chime (`/Doorbell?play=1`), so a HomeKit doorbell or door sensor can sound on your speakers
+- ⏳ Transport control: play and pause as a switch a scene or a spoken command can drive, with skip and back
+- ⏳ Station preset switches, recalling a saved BluOS preset by name (`/Presets`, `/Preset?id=`)
+- ⏳ Input switches for the physical inputs on players that have them (`/RadioBrowse?service=Capture`, `/Play?url=`)
+- ⏳ A playback sensor, so "when music starts in here" can trigger other accessories
+- ⏳ Relative volume nudges in dB (`/Volume?db=±2`), for mapping physical buttons to a step up or down
+- ⏳ Shuffle and repeat
+- ⏳ A sleep timer, once the way to set one is confirmed: `/Status` reports the minutes remaining, but API v1.7 documents no endpoint that sets it
+
+Anything reading playback state needs a second long-poll per zone, because `/Status` carries its own etag. That cost is why it will be opt-in per player rather than always on. Note also that the firmware proxies `/Status` and playback control from a group follower to its leader, so a follower's transport tile necessarily acts on the group.
+
+Being weighed, because the Home app's rendering of them varies by iOS version: a single media tile per player (`SmartSpeaker` or `Television`) instead of separate switches.
+
+## Not planned
+
+HomeKit has no way to render a library or a queue, and no vocabulary for "play the third album by that artist". The BluOS app does these properly, and a second controller with its own idea of the state is worse than none:
+
+- ❌ Browsing, search and favourites
+- ❌ Queue building and editing
+- ❌ Now-playing metadata and artwork
+- ❌ Player setup, streaming-service sign-in, firmware updates
+
+## Accessories per player
+
+| Configuration | HomeKit service |
+| --- | --- |
+| `volumeSlider` | Fanv2 (default) or Lightbulb, as a 0–100 slider |
+| `mute` | Switch |
+| `volumePresets[]` | Switch, one per level |
+| `battery` | Battery |
+
+## Protocol surface
+
+The subset of the BluOS Custom Integration API this plugin uses, and the places where real hardware disagrees with the specification: [PROTOCOL.md](PROTOCOL.md).
+
+## Architecture
+
+See [DEVELOPMENT.md](../DEVELOPMENT.md) for how to build, test and add a capability.