homebridge-bluos 0.1.0

package/docs/PROTOCOL.md

@@ -0,0 +1,194 @@
+# BluOS Custom Integration API — what this plugin relies on
+
+A reference for the subset of the API this plugin uses, and for the places where real hardware and the published specification disagree. Everything marked **verified** was measured against physical players running BluOS firmware **4.16.6**: a NAD C658, a two-zone NAD CI-S2, a Bluesound P430 soundbar and a battery-equipped portable. The recorded responses are committed under [`tests/fixtures`](../tests/fixtures), so the parser is tested against what the firmware sends rather than what the specification implies.
+
+Specification references are to **Custom Integration API v1.7**.
+
+## Transport
+
+| Property | Value |
+| --- | --- |
+| Protocol | HTTP/1.1, plain text XML, no authentication |
+| Port | `11000` for a player; `11010`, `11020`, `11030` for the extra zones of a multi-zone chassis (spec §1) |
+| Discovery | mDNS `_musc._tcp.local` (primary) and `_musp._tcp.local` (secondary zones) |
+
+There is no authentication of any kind. Anyone who can reach the port can change the volume, which is the security model the plugin inherits and cannot improve on; it is the reason nothing here is exposed beyond the LAN.
+
+### Rate rules the API imposes
+
+Spec §2, phrased as requirements rather than advice:
+
+- **At least one second** between two consecutive requests for the *same resource*, "even if the first request returns in less than one second"
+- **At most one request every 30 seconds** when long-polling is not used
+
+The first is enforced in `api/client.ts` rather than at the call sites, so no caller can violate it by accident. The second does not arise: every zone is long-polled, and a plain read happens only for the single cycle that follows a write, an address change or a failure, which the one-second rule already paces. The plugin adds two rules of its own: 100 ms between control calls to one endpoint, so a HomeKit scene touching several tiles cannot burst a player, and serialised writes per *chassis*, because the zones of a CI-S2 are one box on one IP.
+
+## `/SyncStatus`
+
+The state read. Volume, mute and grouping all come from here.
+
+A recorded response, from a NAD C658, complete apart from line wrapping — the wire form is one line, and the addresses and the MAC are pseudonymised as everything in [`tests/fixtures`](../tests/fixtures) is:
+
+```xml
+<SyncStatus etag="9" syncStat="9" version="4.16.6" id="192.168.4.10:11000"
+            db="-42" volume="41" name="Amplifier" model="C658" modelName="C658"
+            class="streamer" icon="/images/players/C658_nt.png" brand="NAD"
+            schemaVersion="34" initialized="true"
+            mac="90:56:82:0A:00:01"><bluetoothOutput></bluetoothOutput></SyncStatus>
+```
+
+| Attribute | Meaning |
+| --- | --- |
+| `volume` | `0`–`100`, or `-1` for a fixed-output player (spec §2.2) |
+| `db` | Current output in dB; `-100` means silence |
+| `muteVolume` | Level to return to on unmute. **Present only while muted** |
+| `muteDb` | dB to return to on unmute. Present only while muted |
+| `mac` | Chassis NIC. On a secondary zone, the zone's port is appended as a seventh colon-separated field |
+| `etag`, `syncStat` | Opaque state tokens; `etag` is what a long-poll passes back |
+| `id` | The `host:port` the player believes it is. `readSyncRole` compares `<master>` against it, falling back to the address the request was sent to, so a player reached by hostname still recognises its own `<master>` |
+| `brand`, `model`, `modelName`, `version` | Identity, published to HomeKit |
+| `<master>` | Present when this zone follows another; a group follower. Compare against `id`, since a zone can briefly report itself while regrouping |
+| `<slave>` | One per follower when this zone leads a group, carrying the follower's `id`, `port` and `name` |
+| `group` | Display string naming the group's members, e.g. `Zone Three+Zone Four`. Present on the leader only, and not used for any decision |
+| `<battery level="91" charging="false"/>` | Child element, only on players with a pack fitted |
+
+### Long-polling — verified
+
+`GET /SyncStatus?timeout=<seconds>&etag=<etag>` holds the connection until the state changes or the window elapses.
+
+- With a **current** etag, `timeout=15` held for **15.03 s** and returned the unchanged document
+- With a **stale** etag, the same request answered in **44 ms**
+- Held **per zone, not per chassis**: changing zone one's volume did not wake zone two's poll, so a multi-zone chassis needs one poll per zone
+- A control call on a separate TCP connection completes normally while a poll is being held, so writes need not interrupt reads
+
+The plugin uses `timeout=100`. The specification recommends 180 s for `/SyncStatus` and forbids under 10 s; 100 s stays inside that envelope while halving the worst-case delay before an unplugged player's socket read times out, which is how a silent disappearance — as opposed to a connection reset — gets noticed.
+
+### Mute is not what the specification suggests — verified
+
+This is the finding that shaped the plugin's state handling. The same zone, in three states:
+
+| State | `/SyncStatus` reports |
+| --- | --- |
+| Playing at 60 | `volume="60" db="-32.1"` |
+| **Muted** | `volume="0" db="-100" muteVolume="60" muteDb="-32.1"` |
+| **Level set to 0** | `volume="0" db="-100"` |
+
+Three consequences:
+
+1. **`/SyncStatus` never sends a `mute` attribute at all** — not `mute="0"` when unmuted, and not `mute="1"` when muted. `/Volume` does; `/SyncStatus` does not
+2. `volume="0"` and `db="-100"` are **identical** in the muted and the level-zero cases, so neither can be used to detect mute. Inferring mute from `db` would switch the mute tile on whenever a user dragged the slider to zero
+3. The only distinguishing signal is `muteVolume`/`muteDb`, which the firmware publishes **exclusively while muted**
+
+So mute is inferred from the presence of the remembered pre-mute level. See `readMuted` in `api/sync-status.ts`, and the `*-muted` and `*-level-zero` fixtures that pin both cases.
+
+### Multi-zone identity — verified
+
+On a two-zone CI-S2, both zones report the same chassis NIC, but the secondary appends its own port:
+
+| Zone | Endpoint | `mac` as reported |
+| --- | --- | --- |
+| One | `:11000` | `90:56:82:0A:00:02` |
+| Two | `:11010` | `90:56:82:0A:00:02:11010` |
+
+The MAC alone is therefore ambiguous across zones. Identity is derived as `MAC:port` (`api/identity.ts`), using the zone's own control port, which is stable across firmware updates and DHCP lease changes alike.
+
+## `/Volume`
+
+The write, and a second read.
+
+```
+GET /Volume?level=35&tell_slaves=0     → set this zone to 35, and nothing else
+GET /Volume?level=35&tell_slaves=1     → set this zone and anything grouped under it
+GET /Volume?mute=1&tell_slaves=0       → mute this zone
+GET /Volume                            → read
+```
+
+```xml
+<volume db="-42" offsetDb="0" mute="0" etag="4f3722e3..." source="Endpoint">41</volume>
+```
+
+The level is the element's **text content**, not an attribute — unlike `/SyncStatus`, where it is an attribute. `mute` *is* present here, in both states.
+
+### `mute=1` mutes — verified, and the spec's parameter table is wrong
+
+Spec §3.1's parameter table states the inverse mapping. Sections 3.4 and 3.5, the response attribute tables, and the hardware all agree with the mapping used here: writing `mute=1` produced `mute="1" muteVolume="72"` on a real player. Writing `mute=0` restored the level. The plugin follows the hardware.
+
+### `tell_slaves` is always sent explicitly, and follows the zone's role
+
+The parameter decides whether a change propagates to the players grouped under this one. The plugin never leaves it to the firmware's default, because the right answer depends on what the zone currently is:
+
+| Zone's `syncRole` | Sent | Reasoning |
+| --- | --- | --- |
+| `primary` (leads a group) | `tell_slaves=1` | While the group exists, the leader's tile *is* the group's control, which is how the BluOS app's own slider behaves |
+| `secondary` (follows one) | `tell_slaves=0` | A tile labelled one room must not change the room leading it |
+| `standalone` | `tell_slaves=0` | Nothing to propagate to |
+
+The role comes from the last `/SyncStatus`, so ungrouping takes effect on the next poll with no bookkeeping. The same rule applies to mute and to volume presets: they are all "put this room at this level", and one of them reaching the group while another did not would be indefensible.
+
+### Grouping as reported — verified
+
+Recorded from two zones of one CI-S2 while grouped, on firmware 4.16.6. The leader lists one `<slave>` per follower and gains a display-only `group` attribute:
+
+```xml
+<SyncStatus etag="101" id="192.168.4.14:11000" volume="60"
+            name="Zone Three" group="Zone Three+Zone Four" mac="90:56:82:0A:00:05">
+  <slave id="192.168.4.14" port="11010" name="Zone Four" model="CI-S2" icon="…"></slave>
+  <pairWithSub></pairWithSub>
+</SyncStatus>
+```
+
+The follower names its leader, with the port as an attribute rather than in the text:
+
+```xml
+<SyncStatus etag="108" id="192.168.4.14:11010" volume="60"
+            name="Zone Four" mac="90:56:82:0A:00:05:11010">
+  <master port="11000">192.168.4.14</master>
+</SyncStatus>
+```
+
+Both are pinned as fixtures. Two details worth noting:
+
+- Grouping is per zone, not per chassis. These two zones share a NIC and a MAC, and one leads the other, so nothing about identity or write scope can be derived from the MAC alone.
+- The follower keeps reporting **its own** volume while grouped (60 here, independent of the leader's), which is the behaviour `/Status` does not have.
+
+### `zoneMaster="true"` is not grouping
+
+A Bluesound player advertises stereo-pairing options as children:
+
+```xml
+<zoneOptions>
+  <option zoneMaster="true">left</option>
+  <option zoneMaster="true">right</option>
+</zoneOptions>
+```
+
+This is a pairing option and says nothing about groups. Any attribute lookup loose enough to see `zoneMaster` as `master` — a case-insensitive match, or a substring one — turns every paired speaker into a group follower. A fixture pins that such a player reads as `standalone`. A regex in `scripts/grouping.js` originally made exactly this mistake, which is what caught it.
+
+### The player's answer is authoritative
+
+A player clamps the requested level into its own configured dB range, so the response can differ from the request. The plugin adopts what the response says rather than optimistically showing what it asked for.
+
+This is also why the plugin has no maximum-volume setting of its own. Level 100 is not an absolute loudness: it is the top of whatever range the player is configured for, set per player in the BluOS app. A ceiling configured there is enforced by the player itself, for every controller including this one, and it cannot be bypassed by a HomeKit automation or a Siri phrase. A second ceiling here would only be able to lie about the first.
+
+## Discovery
+
+mDNS, browsing two service types:
+
+| Service | Advertised by |
+| --- | --- |
+| `_musc._tcp.local` | Primary players |
+| `_musp._tcp.local` | Secondary zones of a multi-zone chassis (spec appendix §13.1, LSDP class `0x0003`) |
+
+A zone is usable once its `SRV` record (for the port) and an IPv4 address are both known; the address comes from an `A` record when one is offered and otherwise from the responder's own source address. `TXT` records carry `model`, `version`, `mac` and `zs`, but secondary zones **omit `mac`**, which is why identity is always confirmed by reading `/SyncStatus` rather than trusted from the advertisement.
+
+**LSDP** (UDP 11430) is documented as an alternative and was tried first: it failed repeatedly against this fleet, while mDNS answered reliably. mDNS is therefore the only discovery path, with manual address entry as the fallback for networks that filter multicast.
+
+## What this plugin does not use yet
+
+`/Status`, `/Play`, `/Pause`, `/Skip`, `/Back`, `/Presets`, `/Browse`, `/AddSlave` and `/RemoveSlave` are unused today. Grouping and transport are on the [roadmap](../README.md#roadmap). Browsing, queue editing and artwork are not planned: HomeKit cannot render them, and a second controller with its own idea of that state is worse than none. See the scope note in the [README](../README.md).
+
+## Sources
+
+- BluOS Custom Integration API v1.7 (§1 ports, §2 polling and rate rules, §2.2 fixed volume, §3.1/3.4/3.5 `/Volume`, appendix §13.1 LSDP classes)
+- Measurements against NAD C658, NAD CI-S2 (both zones), Bluesound P430 and a battery-equipped portable, all on firmware 4.16.6
+- Recorded responses: [`tests/fixtures`](../tests/fixtures)

package/homebridge-ui/public/index.html

@@ -0,0 +1,87 @@
+<!--
+  Copyright (c) 2026 tbaur
+
+  Licensed under the Apache License, Version 2.0
+  See LICENSE file for full license text
+
+  Markup and styles for the custom configuration UI. The behaviour lives in
+  index.js, which is a separate file so that the linter and the tests can reach
+  it.
+-->
+<style>
+  .bluos-intro { margin-bottom: 1rem; }
+  .bluos-toolbar { display: flex; gap: .5rem; align-items: flex-end; flex-wrap: wrap; margin-bottom: 1rem; }
+  .bluos-toolbar .form-group { margin-bottom: 0; }
+  .bluos-card { border: 1px solid rgba(128, 128, 128, .3); border-radius: .5rem; padding: .85rem 1rem; margin-bottom: .75rem; }
+  .bluos-card.is-selected { border-color: #007bff; box-shadow: 0 0 0 1px rgba(0, 123, 255, .35); }
+  .bluos-card-head { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+  .bluos-card-title { font-weight: 600; flex: 1 1 12rem; min-width: 12rem; }
+  .bluos-meta { font-size: .82rem; opacity: .75; margin-top: .15rem; }
+  .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-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; }
+  .bluos-preset-row input[type="number"] { width: 5.5rem; }
+  .bluos-empty { opacity: .7; font-style: italic; padding: 1rem 0; }
+  .bluos-actions { display: flex; gap: .5rem; align-items: center; flex-wrap: wrap; margin-top: 1rem; }
+  .bluos-actions .spacer { flex: 1 1 auto; }
+</style>
+
+<div class="bluos-intro">
+  <p class="mb-1">
+    Discovery browses your network for BluOS zones. Multi-zone amplifiers such as the
+    NAD CI&nbsp;S2 and CI&nbsp;580 appear once per zone, each with its own volume.
+  </p>
+  <p class="mb-0 text-muted" style="font-size: .85rem;">
+    HomeKit has no speaker volume control that the Home app draws, so the volume slider is
+    exposed as a fan. Turning it off sets the level to zero; the mute switch is separate.
+  </p>
+</div>
+
+<div class="bluos-toolbar">
+  <button class="btn btn-primary" id="discover">Discover Players</button>
+  <div class="form-group">
+    <label for="timeout" class="mb-0" style="font-size: .8rem;">Listen for</label>
+    <select class="form-control form-control-sm" id="timeout">
+      <option value="3">3 seconds</option>
+      <option value="5" selected>5 seconds</option>
+      <option value="10">10 seconds</option>
+      <option value="20">20 seconds</option>
+    </select>
+  </div>
+  <div class="spacer" style="flex: 1 1 auto;"></div>
+  <button class="btn btn-outline-secondary btn-sm" id="toggle-manual">Add by address</button>
+  <button class="btn btn-outline-secondary btn-sm" id="toggle-json">Advanced editor</button>
+</div>
+
+<div id="manual" class="bluos-card" hidden>
+  <div class="form-row">
+    <div class="form-group col-sm-7 mb-2">
+      <label for="manual-host" style="font-size: .8rem;">IP address or hostname</label>
+      <input type="text" class="form-control form-control-sm" id="manual-host" placeholder="192.168.4.10" />
+    </div>
+    <div class="form-group col-sm-3 mb-2">
+      <label for="manual-port" style="font-size: .8rem;">Port (optional)</label>
+      <input type="number" class="form-control form-control-sm" id="manual-port" placeholder="all" />
+    </div>
+    <div class="form-group col-sm-2 mb-2 d-flex align-items-end">
+      <button class="btn btn-secondary btn-sm btn-block" id="manual-probe">Probe</button>
+    </div>
+  </div>
+  <div class="text-muted" style="font-size: .8rem;">
+    Use this when multicast is filtered on your network. Leave the port empty to try every
+    documented BluOS port.
+  </div>
+</div>
+
+<div id="players"></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>
+
+<script src="index.js"></script>