homebridge-bluos 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project are documented in this file. This file is maintained automatically by [release-please](https://github.com/googleapis/release-please) based on [Conventional Commits](https://www.conventionalcommits.org).
+
+## Unreleased
+
+* initial BluOS plugin

package/DEVELOPMENT.md

@@ -0,0 +1,65 @@
+# Development
+
+HomeKit talks to the platform. The platform owns accessory identity and starts one poller per zone. Each poller long-polls through the client; the client is the only place that talks to a player. Accessories render the last observation as HAP.
+
+```mermaid
+flowchart LR
+  HomeKit --> platform
+  platform --> poller
+  poller --> client
+  client --> player["BluOS player"]
+  ui["Settings page"] --> uiApi["ui-api"]
+  uiApi --> client
+  uiApi --> discovery
+```
+
+`src/api/` is the wire. `src/devices/` is HomeKit. `src/platform.ts` is the join. Protocol facts live in [docs/PROTOCOL.md](docs/PROTOCOL.md), not here.
+
+`dist/` is committed so a git install works. CI fails if it drifts from `src/`. Run `npm run build` and commit `dist/` with every source change. There is no `prepare` script: it would dirty the tree on every `npm install`. `prepublishOnly` still rebuilds.
+
+## Invariants
+
+Break these and you break someone's rooms, or you guess the protocol.
+
+- **Identity is `MAC:port:kind` (plus preset level), never the address.** A DHCP change must not mint new accessories. Adopt a cached accessory that matches identity; do not replace it. Changing a preset's level *is* a new accessory.
+- **Bad config disables the platform. It does not unregister anything.** Rooms and automations survive a typo. One bad `devices[]` entry is skipped; only a wholly unusable config is fatal.
+- **Unknown is No Response**, not zero. Until a real `/SyncStatus` arrives, and again when the player stops answering, characteristics report `SERVICE_COMMUNICATION_FAILURE`.
+- **Mute is inferred from `muteVolume` / `muteDb`.** `/SyncStatus` never sends `mute`. `volume="0" db="-100"` is the same for mute and for level zero. See PROTOCOL.md.
+- **`tell_slaves` is decided in one place** (`BaseAccessory.writeScope`): a group leader carries the group, everyone else writes locally. Do not special-case it per accessory.
+- **Rate rules live in `api/client.ts`.** One second between same-resource calls, 100 ms between control calls, writes serialised per chassis. Call through the client; do not open your own HTTP.
+- **Hardware wins the spec.** Record the measurement in PROTOCOL.md and pin a fixture. Never commit a raw capture — [scripts/README.md](scripts/README.md) is the pseudonymise path, and `tests/unit/fixtures.test.ts` allowlists every address and MAC in the tree.
+
+A capability ships if HomeKit can express it as a tile, a scene, an automation or a spoken command. A library, a queue and artwork cannot, so they stay in the BluOS app.
+
+## Commands
+
+Node 20+, matching `engines`. CI runs 20 / 22 / 24, a Homebridge 1.6 floor job, and a runtime `npm audit`.
+
+```bash
+npm install
+npm run build                          # commit dist/ with the source
+npm run lint                           # warnings are failures
+npx tsc --noEmit -p tsconfig.test.json # src + tests
+npm test                               # jest with coverage (NODE_ENV=test)
+```
+
+The suite never touches the network. Before a release, against real players (read-only):
+
+```bash
+npm run build
+node scripts/smoke.js
+node scripts/grouping.js
+```
+
+Tests inject fakes. `tests/helpers/hap.ts` is the HAP stand-in. `api/http.ts` is the one module tested against a loopback socket. Coverage includes `homebridge-ui/` and is gated at 80%. Fake timers, not real sleeps. Module mocks are plain classes behind a getter — `resetMocks` strips `mockImplementation` on a factory.
+
+## Adding a capability
+
+1. Verify the endpoint on a real player. If it disagrees with the spec, write it down in PROTOCOL.md first.
+2. Parse in `src/api/sync-status.ts`, call through `BluOSClient`.
+3. Add a `BaseAccessory` subclass under `src/devices/`.
+4. Extend `config.schema.json`, the config types, and `validateConfig` / `resolveAccessories`. Constrain the schema to what the plugin will accept. `required` must be an array of property names on the object (draft-07); a boolean on a field fails Homebridge verification CI.
+5. Wire `attachHandler` in `platform.ts`. Extend the identity key only if the new accessory needs more than `kind`.
+6. Tests for the parser, the client method, the accessory and the config path. A new response shape needs a recorded fixture.
+7. Update PROTOCOL.md and [docs/FEATURES.md](docs/FEATURES.md).
+8. `npm run build` and commit `dist/`.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,251 @@
+# 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) [![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)
+
+**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.
+
+The goal is a complete integration: everything about a BluOS player that HomeKit can express well, built one accessory at a time and verified against real hardware before it ships. Volume, mute, volume presets and battery are what exist today — the first set, not the ceiling. See the [roadmap](#roadmap) for what comes next.
+
+What stays in the BluOS app is the part HomeKit has no vocabulary for: browsing, search, building a queue, artwork, and setting a player up in the first place. HomeKit has no way to render a library and no way to say "play the third album by that artist", so anything this plugin exposed there would be a worse version of an app you already have. Where HomeKit is genuinely better is the tile, the scene, the automation and the spoken command, and that is the line this plugin draws.
+
+## Features
+
+### Accessories today, per zone
+
+- **Volume slider** — 0–100, the same scale the BluOS app uses. Exposed as a fan by default (see [why](#why-is-my-volume-a-fan))
+- **Mute switch** — On when the player is muted; unmuting restores the level the player remembered, not a guess
+- **Grouping-aware** — A zone that is leading a group moves the whole group, exactly as its slider does in the BluOS app. Every other zone moves alone
+- **Volume preset switches** — One switch per level, e.g. "Study Evening" at 15. Addressable by name with Siri, and far safer than a slider inside an automation
+- **Battery sensor** — Charge level, charging state and low-battery warning for players with a battery pack fitted (PULSE FLEX with BP100, PULSE M)
+- **Multi-zone chassis** — Each zone of a NAD CI-S2 or CI 580 is a separate player with its own accessories, discovered on its own port
+- **Accessory Information** — Brand and model as the player reports them, the plugin version as firmware revision, and an opaque, stable serial number
+
+### Reliability
+
+- **Discovery in the settings page** — Finds zones over mDNS and writes the configuration for you; manual address entry for networks where multicast is filtered
+- **Long-polling, not polling** — `/SyncStatus?timeout=100` with an `etag`, so a change made on the front panel, the remote or the BluOS app reaches HomeKit in about a second, without hammering the player
+- **Follows the API's rate rules** — One second minimum between two requests for the same resource, per the BluOS specification; writes to one chassis are serialised, and separate chassis stay parallel
+- **Survives a DHCP lease change** — Accessory identity is the player's MAC and zone port, never its address. If a player moves, the plugin re-resolves it and remembers the new address
+- **Backs off when a player is off** — Exponential delay to a one-minute ceiling instead of dialling an absent player every second; the first failure warns, the rest go to debug
+- **Answers HomeKit promptly** — A write returns inside HAP's patience window and finishes anything slower in the background, where the result still reaches HomeKit through the next poll
+- **No volume jumps** — The pair of writes HomeKit sends when a slider leaves zero is coalesced into one command
+- **Honest state** — An accessory reports No Response until the player has actually been read, and again once it stops answering, rather than showing a value it cannot confirm
+- **Never loses your rooms** — A broken configuration disables the platform and leaves every accessory registered and showing No Response. Accessories are adopted by identity, never replaced
+
+### Quality
+
+- **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, committed-`dist` drift check, dependency audit and OSV scanning
+- **No analytics** — No tracking, no cloud, no accounts
+
+## Quick Start
+
+### 1. Install
+
+**Homebridge UI** (recommended): Plugins → Search `homebridge-bluos` → Install
+
+```bash
+npm install -g homebridge-bluos
+```
+
+### 2. Prepare your players
+
+1. Give each player a static IP or a DHCP reservation. Not required — the plugin re-resolves addresses — but it makes logs easier to read
+2. Nothing needs enabling on the player: the BluOS LAN API is always on
+
+### 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.
+
+Or in `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "BluOS",
+      "name": "BluOS",
+      "devices": [
+        {
+          "id": "90:56:82:0A:00:01:11000",
+          "name": "Study",
+          "host": "192.168.4.10",
+          "port": 11000,
+          "volumeSlider": true,
+          "mute": true,
+          "volumePresets": [
+            { "name": "Study Quiet", "volume": 15 },
+            { "name": "Study Loud", "volume": 70 }
+          ]
+        },
+        {
+          "id": "90:56:82:0A:00:02:11010",
+          "name": "Library",
+          "host": "192.168.4.11",
+          "port": 11010,
+          "volumeSlider": true
+        }
+      ],
+      "options": {
+        "sliderService": "fan",
+        "discoveryTimeoutSec": 5
+      }
+    }
+  ]
+}
+```
+
+### 4. Restart Homebridge
+
+Accessories appear in the Home app after restart, showing No Response for the second or two before the first read completes.
+
+### Example: Apple Shortcuts
+
+A "settle in" shortcut, using preset switches rather than the slider so the levels are exact:
+
+1. Turn **Study Quiet** On
+2. Turn **Library Quiet** On
+3. Start your playlist in the BluOS app or with AirPlay
+
+For "quiet, now", one **Mute** switch is faster than any slider.
+
+### Example logs
+
+Startup:
+
+```text
+[BluOS] Initializing BluOS platform
+[BluOS] adding Study Volume
+[BluOS] adding Study Mute
+[BluOS] adding Study Quiet
+[BluOS] adding Library Volume
+[BluOS] BluOS is watching 2 zone(s) with 4 accessory(s)
+```
+
+A player that moved to a new address:
+
+```text
+[BluOS] Library Volume [90:56:82:0A:00:02:11010] is not responding: connect ETIMEDOUT 192.168.4.11:11010
+[BluOS] Library moved to 192.168.4.23:11010
+```
+
+The identity in brackets is the player's `id`, so two rooms that happen to share a name are still tellable apart.
+
+A HomeKit write that reached the player:
+
+```text
+[BluOS] Study Volume: SET 35
+[BluOS] Study Mute: ON
+[BluOS] Study Quiet: SET 15
+[BluOS] Study Volume: SET 40 (group)
+```
+
+Mute `ON` means muted. `(group)` means that zone is leading a BluOS group, so the write carried the followers.
+
+A configuration the plugin will not act on:
+
+```text
+[BluOS] devices[0] has no usable id (re-run discovery in the plugin settings); skipping devices[0]
+[BluOS] all 1 configured device(s) were rejected; see the warnings above
+[BluOS] BluOS is disabled until its configuration is fixed. Cached accessories are kept and will show as No Response, so rooms and automations are not lost.
+```
+
+The platform only disables itself when *every* player was rejected. One bad entry among several is skipped with the first line and nothing else changes.
+
+## Supported Devices
+
+Any BluOS player running the Custom Integration API, which is all of them from BluOS 3.x onwards.
+
+| Verified against | Notes |
+|---|---|
+| **NAD C658** | Streamer/preamp, firmware 4.16.6 |
+| **NAD CI-S2** | Two independent zones on one chassis, ports 11000 and 11010 |
+| **Bluesound P430** | Soundbar |
+| **Bluesound PULSE-class portable** | Battery pack reporting |
+
+Multi-zone chassis (CI-S2, CI 580) are supported by treating each zone as its own player. Fixed-output players are detected and get no slider, because writing a level to them does nothing.
+
+## Roadmap
+
+Ordered by how well HomeKit expresses the thing, not by how easy it is to build. Each one ships only after it has been verified against real hardware, with the protocol behaviour recorded in [docs/PROTOCOL.md](docs/PROTOCOL.md).
+
+**Next** — group scenes (one switch that forms or breaks a named group, which the BluOS app can do by hand but cannot put into an automation), a chime (`/Doorbell`, so a HomeKit doorbell or door sensor can sound on your speakers), transport (play and pause as a switch a scene or a spoken command can drive, with skip and back), and station preset switches (recall a saved BluOS preset by name, addressable by Siri).
+
+**Likely** — input switches for the physical inputs on players that have them, a playback sensor so "when music starts here" can trigger other accessories, relative volume nudges in dB for physical-button automations, and shuffle and repeat.
+
+**Needs verification first** — a sleep timer. `/Status` reports the minutes remaining, but v1.7 documents no way to set it, so the endpoint has to be confirmed against hardware before anything is built on it.
+
+**Being weighed** — a single media tile per player using HomeKit's `SmartSpeaker` or `Television` service instead of separate switches. It reads better in the Home app when it works, but its rendering varies by iOS version in ways that are worth confirming before anyone's rooms depend on it.
+
+**Not planned** — browsing, search, queue editing, artwork and now-playing metadata, and player setup. 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 this plugin will not pretend to.
+
+## Configuration Options
+
+Only one `BluOS` platform block is supported (`singular` in the schema); it can hold as many players as you like.
+
+| Option | Required | Description |
+|---|:-:|---|
+| `name` | ✓ (UI) | Plugin instance name in the Homebridge log. Homebridge itself falls back to the platform alias, `BluOS`, if a hand-edited `config.json` omits it |
+| `devices` | ✓ | List of players. An empty list is allowed and warns; a missing or non-list value is an error |
+| `options.sliderService` | | `fan` (default) or `lightbulb`, for every slider |
+| `options.discoveryTimeoutSec` | | mDNS listening window, 1–30 seconds (default 5) |
+
+### `devices[]` entries
+
+| Field | Required | Description |
+|---|:-:|---|
+| `id` | ✓ | Stable identity, normally `MAC:port`. Written by discovery. **Changing it detaches the accessories from their HomeKit rooms and automations** |
+| `name` | ✓ | The room's name. Every accessory is named from it: `Study Volume`, `Study Mute`, `Study Battery`, and each preset's own name |
+| `host` | ✓ | IP address or hostname |
+| `port` | | Control port (default 11000). Extra zones of a multi-zone chassis use 11010, 11020, 11030 |
+| `volumeSlider` | | Expose the slider (default true) |
+| `sliderService` | | Override the platform slider style for this player. Empty means "use the platform setting". Changing it removes the old control from the accessory rather than leaving both |
+| `mute` | | Expose a mute switch (default false) |
+| `battery` | | Expose a battery sensor (default false; only meaningful with a battery pack) |
+| `volumePresets[]` | | `{ "name": "...", "volume": 0-100 }`. Duplicate levels on one player are skipped with a warning |
+
+An accessory's identity is the player's `id` plus its kind (and, for a preset, its level). It deliberately does **not** include the address, so changing `host` or `port` keeps your existing accessories intact. Renaming a player is applied in place. Changing a preset's `volume`, however, creates a **new** accessory and removes the old one, which loses its room assignment, scenes and automations — rename freely, but change preset levels only when you are ready to re-add them in the Home app.
+
+Serial numbers in Accessory Information are opaque values generated once per accessory and kept in the Homebridge accessory cache. Clearing that cache issues new ones.
+
+## Not Working?
+
+1. **Nothing found by Discover Players?** mDNS is often filtered across VLANs and by some access points. Use the manual address entry, or add the player by hand in `config.json`
+2. **Everything shows No Response right after a restart** — normal until the first read completes; the plugin reports unknown state rather than guessing
+3. **Everything shows No Response and stays that way** — check the log for `BluOS is disabled until its configuration is fixed`. The plugin stays inert, without deleting anything, until the reported problem is fixed
+4. **A player has no slider** — it reports a fixed output level (`volume="-1"`), so a level cannot be written to it. The log says so once
+5. **The mute switch does not follow volume zero** — by design. Muting and setting level zero are different things to BluOS, and only mute remembers the level to come back to
+6. **A zone on a multi-zone chassis is missing** — check the port. Zone two is 11010, not 11000
+7. **The volume moved but the slider did not, for a second** — a change made on the player takes one long-poll round trip to arrive; a change made from HomeKit is immediate
+8. **One zone's slider moved several rooms** — that zone is currently leading a BluOS group, so it carries its followers, the same as its slider in the BluOS app. Ungroup in the BluOS app and it goes back to moving alone
+9. **100 is louder than you ever want** — set the limit on the player, in the BluOS app's settings for it (the wording varies by model: a volume limit on Bluesound players, a maximum volume on NAD amplifiers). The plugin deliberately has no ceiling of its own: the player maps 0–100 onto whatever range it is configured for and clamps anything above it, so a limit set there is enforced by the hardware for every controller — no HomeKit automation or misheard Siri phrase can exceed it, and a second limit here could only disagree with the first
+10. Restart Homebridge after editing `config.json` by hand
+
+### Why is my volume a fan?
+
+HomeKit has no speaker volume characteristic that the Home app renders, so every plugin borrows another accessory type. This one uses a **fan** and its rotation speed: it looks like a slider, and it is not swept up by "Hey Siri, turn off all the lights" — which, with a lightbulb, would silence your speakers, or worse, set them to maximum. A lightbulb is available if you prefer it.
+
+## Security
+
+The plugin talks only to the addresses in your configuration, on your LAN. No cloud, no accounts, no credentials — which also means the BluOS API has no authentication: anyone who can reach a player on your network can already control it, so secure the network rather than the plugin. Responses are parsed by a size-, depth- and element-capped XML reader rather than a general-purpose parser, everything interpolated into a log line is sanitised, and manual probe targets are validated before a request is made. See [`SECURITY.md`](SECURITY.md).
+
+## 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)
+- One or more BluOS players reachable on the same network
+
+## More Info
+
+- [Features](https://github.com/tbaur/homebridge-bluos/blob/main/docs/FEATURES.md)
+- [Protocol reference](https://github.com/tbaur/homebridge-bluos/blob/main/docs/PROTOCOL.md) — hardware-verified BluOS behaviour
+- [Development](https://github.com/tbaur/homebridge-bluos/blob/main/DEVELOPMENT.md)
+- [Report Issues](https://github.com/tbaur/homebridge-bluos/issues)
+- [Changelog](https://github.com/tbaur/homebridge-bluos/blob/main/CHANGELOG.md)
+
+## License
+
+Copyright 2026 tbaur
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) file for details.

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | ✅ Active support  |
+
+## Reporting a Vulnerability
+
+Do not open a public issue. Use GitHub's [private vulnerability reporting](https://github.com/tbaur/homebridge-bluos/security/advisories/new), and include a description, how to reproduce it, and the impact.
+
+## Security Measures
+
+- **LAN only** — Plain HTTP to the addresses in your configuration. The BluOS API has no authentication; this plugin stores no credentials.
+- **Input validation** — Config is checked at startup. A missing or non-list `devices` value disables the platform without unregistering accessories. A bad player or preset is skipped; hosts, ports and timeouts are rejected or clamped.
+- **Log safety** — Values written to logs have control characters stripped and are length-limited.
+- **Bounded I/O** — Connect and total timeouts on every request; responses capped at 128 KiB; XML parsed with size, depth and element caps.
+- **Discovery** — mDNS errors are caught so they cannot take Homebridge down. Browse results are capped.
+- **Settings probe** — Accepts only a private or local address and a documented BluOS port.
+- **Dependencies** — CI runs `npm audit` on the runtime tree and OSV-Scanner on the full tree.
+
+## Best Practices for Users
+
+1. Keep Homebridge and this plugin updated.
+2. Run Homebridge with minimal privileges, and do not expose it or player port 11000 to the internet.
+3. The BluOS LAN API is unauthenticated — anyone who can reach a player can already control it.
+4. Set volume limits in the BluOS app. The plugin has none of its own, so a limit there covers every controller.
+5. A group leader's volume change applies to the whole group.
+
+## Configuration Handling
+
+Homebridge stores platform config in plain text on the host. Debug logs include request URLs (player addresses), not secrets. HomeKit serial numbers are opaque generated values, not MAC addresses.
+
+## Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial assessment**: Within 1 week
+- **Fix timeline**: Depends on severity
+  - Critical: 24-48 hours
+  - High: 1 week
+  - Medium: 2 weeks
+  - Low: Next release