@ecopoesis/homebridge-dmx 0.3.0 → 0.5.0

package/CLAUDE.md

@@ -11,6 +11,7 @@ Published to npm as **`@ecopoesis/homebridge-dmx`** (scoped because the unscoped
 - HomeKit set → render bytes via the fixture's color model → write to universe buffer → debounce (750 ms) → spawn `tools/send_dmx.mjs` as a child process per transaction
 - Subprocess approach: empirical workaround — in-process protocol only works for the FIRST transaction per long-lived plugin process; sessions 2+ silently fail to drive output. Fresh node process per transaction reliably works. Cost: ~1.5-2 s per change.
 - Color models: dimmer, cct, rgb, rgbw, rgbww, rgbaw, hsvcct (the WAC native model)
+- Keepalive refresh (0.4.0): per-controller `refreshMinutes` (default 30, 0 = off) re-sends the last-known state after that much idle time. Reason: the Stick drifts into a wedged state after hours without traffic — sessions + crypto succeed but live output is dark (2026-08-22..25); regular traffic prevents/corrects it and re-asserts state after the nightly 4:30 AM ET PoE power-cycle (systemd user timer on homebridge01 → UniFi API poe_mode off/auto on sw01 port 15; see `tools/stick-power-cycle.py`). The Stick also has a ~3 min post-boot grace period where sessions succeed but output is ignored.
 - `tools/send_dmx.mjs` is now structurally critical (frozen reference shipped in the npm tarball)
 
 ## Current deployment

package/ENCRYPTION.md

@@ -0,0 +1,207 @@
+# Stick-DE3 Encryption
+
+All of the encryption used by the Stick-DE3 / Hardware Manager protocol,
+recovered by reverse engineering and verified end-to-end against captured
+sessions.
+
+Two independent crypto primitives are involved:
+
+1. **HMAC-SHA256** — TCP auth handshake (opcode 0x48). Fixed key.
+2. **AES-256-CBC** with a P-256 ECDH-derived per-session key — the DMX UDP
+   stream and the 0x011c control reply.
+
+For the wire format that uses these, see [PROTOCOL.md](PROTOCOL.md). For the
+working implementation, see [`tools/send_dmx.mjs`](tools/send_dmx.mjs) and
+[`tools/derive-dmx-key.mjs`](tools/derive-dmx-key.mjs).
+
+## 1. TCP auth — HMAC-SHA256
+
+The opcode 0x48 message authenticates the client to the Stick. The signed
+region is the 82-byte head of the message (everything up to and not
+including the trailing HMAC):
+
+```
+HMAC-SHA256(AUTH_KEY, magic(8) ‖ 0x48 ‖ token(8) ‖ softwareName(32) ‖ stickHandshakeKey(32))
+```
+
+The HMAC is appended (32 bytes) to make the full 0x48 message 114 bytes.
+
+### `AUTH_KEY`
+
+A 15-byte ASCII string baked into Hardware Manager. The literal string is:
+
+```
+#h.6xcKsGD{y}-z
+```
+
+As bytes (hex):
+
+```
+23 68 2e 36 78 63 4b 73 47 44 7b 79 7d 2d 7a
+```
+
+Embedded as a constant in [`tools/send_dmx.mjs`](tools/send_dmx.mjs#L45) as
+`AUTH_KEY`. Originally extracted at runtime with `tools/hmac-key.sh` /
+`tools/lldb_hmac_key.py`, then verified against a captured HWM handshake.
+
+A bad HMAC results in 0x48 reply status 100 (`PermissionDenied`), and the
+session is never promoted to a live control session — no further opcodes will
+work.
+
+## 2. DMX stream cipher — AES-256-CBC, P-256-derived key
+
+The 544-byte body of every DMX UDP frame is AES-256 in CBC mode. The IV is
+constructed from two fields in the clear 32-byte header
+(`fieldA ‖ nonce`, see [PROTOCOL.md](PROTOCOL.md#aes-iv)). The key is
+derived freshly each session from an ECDH-style handshake on opcode 0x0F.
+
+### Mode confirmation
+
+The cipher was statically reverse-engineered from the 2024-03-21 Hardware
+Manager binary: custom-inlined AES (S-box at `DAT_1007c0010`), not the
+Gladman library reference. The mode bit in the cipher state structure
+selects CBC or CFB; the live Stick-DE3 path uses **CBC**, confirmed by
+re-encrypting a captured plaintext with the recovered key + IV and
+byte-matching the captured ciphertext.
+
+### The KDF (`deriveDmxKey`)
+
+Implemented in [`tools/derive-dmx-key.mjs`](tools/derive-dmx-key.mjs).
+Recovered from `FUN_100107650` in the binary. In full:
+
+```
+1. d   = random scalar mod n            (client ephemeral private key)
+2. our = d · G                          (client ephemeral public key)
+3. send `our`, receive Stick pubkey `Q`  (opcode 0x0F handshake)
+4. S   = decompress(STATIC_POINT_COMPRESSED)
+5. AES-256 key = LE( X(d · S)  XOR  X(d · Q) )
+```
+
+This is a **two-DH construction**: one ECDH against the hardcoded static
+point `S` (authenticates the application — anyone who doesn't know `S`
+can't talk to the Stick), and one against the Stick's per-session ephemeral
+`Q` (provides forward secrecy across sessions).
+
+The Stick computes the identical key on its side as
+`X(s · our) XOR X(e · our)`, where `s` and `e` are the Stick's static and
+ephemeral private scalars. The two agree by ECDH symmetry.
+
+### Curve parameters
+
+NIST P-256 / secp256r1 / prime256v1. Confirmed three ways from the binary —
+prime, order, and base point all byte-match P-256, and the curve `b`
+constant `5ac635d8…27d2604b` is used during point decompression.
+
+```javascript
+p  = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff
+n  = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551
+a  = 0xffffffff00000001000000000000000000000000fffffffffffffffffffffffc  // -3 mod p
+b  = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b
+Gx = 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296
+Gy = 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5
+```
+
+### The static point `S`
+
+A 33-byte SEC1-compressed P-256 point stored verbatim in the Hardware
+Manager binary at file offset `0x7b0490` (vmaddr `0x1007b0490`). The
+prefix byte `0x03` indicates odd-Y:
+
+```
+03 28 08 12 90 39 6d 06 3e 51 14 52 6e d9 78 b9
+26 55 8f 6b a1 c9 6a d2 fa cf 76 ff fb 3f fe a0 fe
+```
+
+Embedded as `STATIC_POINT_COMPRESSED` in
+[`tools/derive-dmx-key.mjs`](tools/derive-dmx-key.mjs#L68).
+
+(An earlier RE pass tried XOR-masking these bytes with `0x51, 0x52, …`,
+which produces a different point used elsewhere in the app. That isn't the
+KDF static point — the raw bytes above are the ones that reproduce a real
+session's installed AES key. Confirmed by `tools/verify-kdf.mjs` against an
+lldb-dumped ephemeral `d` plus the Stick pubkey from a captured handshake.)
+
+### Endianness
+
+The Stick stores every 256-bit coordinate as **little-endian limbs** (byte 0
+is the least-significant byte). Node's `crypto` works in big-endian SEC1
+form, so a byte-reverse happens at every wire boundary:
+
+- The 64-byte public key sent on opcode 0x0F is `LE(X) ‖ LE(Y)`. See
+  `pointToWire()` / `wireToPoint()` in `derive-dmx-key.mjs`.
+- The installed AES key is the **little-endian form** of `X(d·S) ⊕ X(d·Q)`.
+  See `deriveDmxKey()` lines 128-135.
+
+Forgetting the byte-reverse on the key was a multi-day debugging detour.
+
+### Plaintext header `P0`
+
+The first 16 bytes of every frame's plaintext are a fixed constant baked
+into Hardware Manager:
+
+```
+5b 4e 99 da 96 85 ad 97 6c 43 2b 0a 7f f9 ff cc
+```
+
+Embedded as `P0` in [`tools/send_dmx.mjs`](tools/send_dmx.mjs#L41). The
+Stick decrypts the body and verifies the first 16 bytes equal `P0` before
+accepting the frame. This is effectively a known-plaintext anchor /
+integrity check — a frame encrypted with the wrong key fails this check
+even though CBC otherwise has no built-in authentication.
+
+The 16 bytes immediately after `P0` are zero in every observed frame; we
+send zeros there. The 512 DMX channel bytes follow at plaintext offset 32.
+
+## 3. The 0x011c reply
+
+The TCP/2431 reply to opcode 0x011c is encrypted device-info using the same
+AES-256 session key. The body is not needed for the DMX control path and
+its plaintext schema is not fully documented here. Tooling that decrypted
+it for analysis:
+
+- [`tools/extract-011c.mjs`](tools/extract-011c.mjs)
+- [`tools/find-011c-key.mjs`](tools/find-011c-key.mjs)
+- [`tools/decrypt-011c.mjs`](tools/decrypt-011c.mjs)
+- [`tools/verify-011c-key.mjs`](tools/verify-011c-key.mjs)
+- [`tools/diff-011c.mjs`](tools/diff-011c.mjs)
+
+`send_dmx.mjs` sends the 0x011c request (it's part of the wire-faithful
+handshake sequence) and discards the reply.
+
+## What's NOT encrypted
+
+- **Discovery broadcasts** on UDP/2430 (the four `LSAG_ALL`/`Stick_U1`/
+  `Stick_3A`/`Siudi_7B` startup packets) are clear.
+- **UDP/2430 "Quick Trigger"** is clear and unauthenticated by design — see
+  [PROTOCOL.md §Quick Trigger](PROTOCOL.md#udp2430--quick-trigger-documented-but-limited).
+  Scene-level only; cannot set individual DMX channels.
+- **`LIGHTINGSOFT_XHL`** beacons on UDP/24299 are clear.
+- **The 32-byte UDP/2431 DMX frame header** is clear (this is what carries
+  the IV components).
+- **TCP opcodes 0x47, 0x48, and the handshake chatter (0x46, 0x09, 0x00,
+  0x05, 0x10, 0x0F, 0x70, 0x71, 0x74, 0x75, 0x2e, 0x11)** are clear. Only
+  the 0x011c reply body and the DMX UDP body are AES-encrypted.
+
+## Verification harness
+
+The KDF self-test runs without hardware:
+
+```sh
+node tools/derive-dmx-key.mjs
+```
+
+It exercises ECDH symmetry, the wire round-trip, and the real static point.
+End-to-end verification against captured sessions uses
+`tools/verify-kdf.mjs`, `tools/verify-011c-key.mjs`, and the lldb dumps in
+`tools/lldb_*.py`.
+
+## Provenance summary
+
+| Constant | Where it lives in HWM | Recovery method |
+|----------|----------------------|-----------------|
+| `AUTH_KEY` (15B) | string literal | `tools/hmac-key.sh`, lldb HMAC trace |
+| `STATIC_POINT_COMPRESSED` (33B) | file offset `0x7b0490` | static RE (Ghidra), verified against captured KDF output |
+| `P0` (16B plaintext header) | constant inlined in frame builder | static RE, verified against decrypted captured frame |
+| Curve = P-256 | code constants | byte-match against NIST P-256 |
+| Mode = AES-256-CBC | custom-inlined AES, S-box at `DAT_1007c0010` | static RE + ciphertext byte-match |
+| KDF = `X(d·S) ⊕ X(d·Q)` | `FUN_100107650` | static RE, verified `tools/verify-kdf.mjs` |

package/PROTOCOL.md

@@ -0,0 +1,277 @@
+# Stick-DE3 Protocol
+
+What we know about the Nicolaudie Stick-DE3 wire protocol, focused on the path
+needed to drive per-channel DMX from a third-party client. Everything below
+was reverse-engineered from packet captures of Hardware Manager / ESA Pro 2
+plus static RE of the 2024-03-21 macOS Hardware Manager binary.
+
+The authoritative implementation is [`tools/send_dmx.mjs`](tools/send_dmx.mjs).
+This document is the explanation; the code is the spec.
+
+For the encryption details (KDF, key material, AES mode), see
+[ENCRYPTION.md](ENCRYPTION.md).
+
+## Ports & transports
+
+| Port | Transport | Direction | Purpose |
+|------|-----------|-----------|---------|
+| 2431 | TCP       | client → Stick | Control + per-session key exchange. Single session, mutually exclusive with HWM. |
+| 2431 | UDP       | client → Stick | Live DMX stream (encrypted 576-byte frames). |
+| 2430 | UDP       | bidirectional, broadcast | Discovery + the documented "Quick Trigger" scene control. |
+| 24299 | UDP      | client broadcast | Hardware Manager presence announce (`LIGHTINGSOFT_XHL`). |
+
+The DMX UDP stream uses **source port 2430** and destination port 2431.
+This pairing matters — the Stick filters on it.
+
+## Message framing (TCP/2431)
+
+Every TCP message starts with an 8-byte ASCII magic, then a 2-byte
+little-endian opcode, then opcode-specific payload:
+
+```
++--------+--------+----------------+
+| magic  | opcode | payload …      |
+| 8B     | 2B LE  | variable       |
++--------+--------+----------------+
+```
+
+Two magics are used:
+
+- `Stick_3A` — the Stick's identity; used for most messages.
+- `LSAG_ALL` — broadcast/handshake magic; used for the initial auth opcodes
+  (0x47, 0x48) and for discovery.
+
+Most payloads begin with an 8-byte session token. The token is a single
+monotonically-increasing little-endian uint32 (padded to 8 bytes) that
+**continues across both TCP messages and the UDP DMX frames** within the same
+session. Restarting the counter, or using a separate counter for UDP, causes
+the Stick to drop every frame. Initial value in our implementation is `0x80`
+to mirror HWM.
+
+## TCP handshake (go-live)
+
+Sequence observed from HWM and replicated by `send_dmx.mjs`. Numbers in
+parens are the opcode in hex.
+
+1. **`LSAG_ALL` 0x47 — hello.** Client sends `magic ‖ opcode ‖ token(8)`.
+   Stick replies with a 54-byte message; bytes `[0x16:0x36]` are a 32-byte
+   per-session "Stick handshake key" used in step 2.
+2. **`LSAG_ALL` 0x48 — authenticated handshake.** Layout:
+   ```
+   magic(8) ‖ 0x48 ‖ token(8) ‖ softwareName(32) ‖ stickHandshakeKey(32) ‖ hmac(32)
+   ```
+   The HMAC is `HMAC-SHA256(AUTH_KEY, first 82 bytes)`. `AUTH_KEY` is a
+   15-byte string baked into Hardware Manager (see [ENCRYPTION.md](ENCRYPTION.md)
+   for the recovered value). Reply contains a status uint32 at `[0x12]`:
+   `0` = ok, `100` = `PermissionDenied`. A rejected HMAC means the session
+   never gets promoted to live.
+3. **Pre-DMX chatter** — six small messages, **each sent in its own TCP
+   segment** (HWM never coalesces these; coalescing them empirically prevents
+   the Stick from emitting its 0xc9 status):
+   ```
+   Stick_3A 0x46  4 zero bytes
+   Stick_3A 0x09  "14000000"
+   Stick_3A 0x09  "14000000"
+   Stick_3A 0x00  "14000000"
+   Stick_3A 0x011c  token(8) ‖ "01001600"
+   Stick_3A 0x05  "0200"
+   ```
+   After this the Stick sends a `0x00c9` status indicating the session is
+   registered. Our implementation paces these with `CHATTER_MS` (default 10ms;
+   tested down to 5ms with no failures).
+4. **`Stick_3A` 0x10 — crypto-state query.** Reply has a state uint32 at
+   `[0x12]`: state 3 on a fresh device, state 4 if a DMX key from a previous
+   session is still latched.
+5. **`Stick_3A` 0x0F — DMX key exchange.** Client sends its 64-byte P-256
+   ephemeral public key (X ‖ Y, both little-endian limbs — see
+   [ENCRYPTION.md](ENCRYPTION.md)). Stick replies with its own 64-byte
+   P-256 public key at `[0x16:0x56]`. The Stick's public key has been
+   observed identical across every session captured to date; a static
+   fallback is hardcoded in `send_dmx.mjs` for resiliency.
+6. **Device sync chatter** — observed from HWM, byte-for-byte:
+   ```
+   Stick_3A 0x10  token
+   Stick_3A 0x75  token
+   Stick_3A 0x74  token
+   Stick_3A 0x71  token ‖ "0200000000"
+   Stick_3A 0x71  token ‖ "0100000000"
+   Stick_3A 0x71  token ‖ "0100000000"
+   Stick_3A 0x71  token ‖ "02b37f0000"
+   ```
+   These appear to be informational reads. The 4th `0x71` was the one HWM
+   pattern previously missed by our impl.
+7. **`Stick_3A` 0x70 — sector reads (skippable).** HWM reads sector 0
+   followed by sectors 63..185 (124 reads) to populate its commissioning UI.
+   Empirically the Stick will latch values even with `SECTORS=0`; this is
+   HWM UI chatter, not a Stick precondition. `send_dmx.mjs` defaults to
+   skipping it (saves ~1.5s/transaction).
+8. **`Stick_3A` 0x2e — go-live primer.** 32 zero bytes payload. HWM then
+   waits ~3.7s (UI-paced); the Stick only needs a much shorter settle. We
+   use 50ms via `SETTLE_2E_MS`.
+9. **`Stick_3A` 0x10, 0x11, 0x10** — enters live mode. The 0x11 reply
+   confirms live mode is active; a follow-up 0x10 should now report crypto
+   state 4.
+
+## DMX UDP frames (576 bytes)
+
+Once the session is live, DMX values are sent as encrypted 576-byte UDP
+datagrams from src-port 2430 → dst-port 2431.
+
+```
++----------------------------------+-----------------------------------------+
+| 32-byte clear header             | 544-byte AES-256-CBC ciphertext         |
++----------------------------------+-----------------------------------------+
+```
+
+### Clear header (32 bytes)
+
+| Offset | Size | Field | Value / meaning |
+|--------|------|-------|-----------------|
+| 0x00   | 8    | magic | `Stick_3A` |
+| 0x08   | 2    | opcode | `0x0019` LE |
+| 0x0a   | 8    | `fieldA` | session token (same counter as TCP tokens — continues the sequence) |
+| 0x12   | 2    | port / universe | DMX port selector, LE |
+| 0x14   | 2    | channel count | `512` LE |
+| 0x16   | 1    | constant | `100` (HWM's value) |
+| 0x17   | 1    | sequence byte | per-frame counter mod 256 |
+| 0x18   | 8    | nonce | random per frame |
+
+### AES IV
+
+The 16-byte AES-CBC IV is `fieldA (8) ‖ nonce (8)` — i.e. the two header
+fields at offsets 0x0a and 0x18. The receiver pulls these straight out of
+the clear header to decrypt.
+
+### Plaintext layout (544 bytes)
+
+```
++---------------------+---------------------+-------------------------+
+| P0 (16B constant)   | header2 (16B zeros) | 512 DMX channel bytes   |
++---------------------+---------------------+-------------------------+
+0                    16                   32                       544
+```
+
+`P0` is a fixed 16-byte constant baked into HWM (see
+[ENCRYPTION.md](ENCRYPTION.md)). It serves as a known-plaintext anchor —
+when the Stick decrypts a frame, the first 16 bytes of plaintext must
+equal `P0` or the frame is dropped.
+
+`header2` has been observed all-zero in every captured frame. It may be
+meaningful in some other path; we send zeros and the Stick accepts it.
+
+**Channel data starts at plaintext offset 32**, not 16. This was an
+off-by-16 bug in an earlier impl (we lit HWM's channel 6 when sending to
+ours-channel 22, because 22 - 16 = 6).
+
+## Transactional streaming & the latch
+
+The Stick holds the last received DMX values **on disconnect** (any kind that
+doesn't send HWM's "polite goodbye" opcode — which we have never observed
+identified). This lets a client be transactional rather than maintaining a
+persistent stream:
+
+1. Connect, run the handshake, derive the session key.
+2. Stream encrypted DMX frames at 25Hz for ~750ms (~19 frames). The Stick
+   commits values after roughly 12 frames at 25Hz; below ~500ms wall-time
+   the commit doesn't happen.
+3. `socket.destroy()` (RST). The Stick latches the last frame's values.
+
+Trade-off: each transaction takes ~1.5–2s end-to-end (handshake + stream +
+disconnect), and the wall controller blinks briefly on disconnect — HWM
+exhibits the same blink, so it's at the protocol layer, not avoidable from
+the client side.
+
+## UDP/2430 broadcast — discovery
+
+HWM emits a startup burst on UDP/2430 (255.255.255.255):
+
+```
+LSAG_ALL <8B zeros> 14 00 00 00
+Stick_U1 <8B zeros> 14 00 00 00
+Stick_3A <8B zeros> 14 00 00 00
+Siudi_7B <8B zeros> 14 00 00 00
+```
+
+…repeated three times with a 25ms gap. `send_dmx.mjs` does the same before
+connecting; it doesn't appear to be required (the Stick is reachable by IP
+without it) but matches HWM exactly.
+
+## UDP/2430 — "Quick Trigger" (documented but limited)
+
+Nicolaudie's STICK Remote Protocol spec defines a 24-byte UDP packet on port
+2430 with **no authentication** and **no encryption**. See
+[`tools/quick-trigger.mjs`](tools/quick-trigger.mjs):
+
+```
+[0..7]   "Stick_3A"
+[8..9]   opcode 109 (0x6D 0x00)
+[10..11] Scene number (page*50 + sceneInPage), LE
+[12]     ZoneSyncId
+[13]     Command (0=scene-off, 1=scene-on, 5=dimmer, 7=color, 8/9=blackout, …)
+[14..15] Dimmer, LE
+[16..17] Speed, LE
+[18..19] unused
+[20..23] R, G, B, 0
+```
+
+Useful for testing connectivity but **scene-level only**: it cannot set
+individual DMX channels, and on fw3.08 it is gated by "Security for Cloud
+Access" (must be disabled in Hardware Manager for the device to action it).
+For per-fixture HomeKit control, the encrypted UDP/2431 path is the only
+route.
+
+## UDP/24299 — `LIGHTINGSOFT_XHL` presence broadcast
+
+HWM broadcasts an "I am Hardware Manager" beacon on UDP/24299 (src+dst
+24299) at startup: one 114-byte announce containing the literal string
+`Hardware Manager`, followed by two 46-byte status packets. The 32-byte
+header is:
+
+```
+"LIGHTINGSOFT_XHL"  16B
+00 00 00 00 00 00 00 00   8B zeros
+14 00 00 00               op/len = 20
+01 00 00 00               version = 1
+```
+
+We have no Stick-side traffic acknowledging these but HWM emits them
+consistently, and `send_dmx.mjs` replicates them. Mode of action unconfirmed.
+
+## TCP/2431 — passive status
+
+Per the STICK Remote Protocol spec, once a client connects to TCP/2431 the
+Stick emits a status packet every 5s. [`tools/stick-status.mjs`](tools/stick-status.mjs)
+reads it:
+
+| Offset | Field |
+|--------|-------|
+| 0..7   | `Stick_3A` |
+| 8      | opcode |
+| 9      | version |
+| 10..11 | scene number |
+| 12..23 | scene name (NUL-terminated) |
+| 24     | zone number |
+| 25..36 | zone name |
+| 37..38 | dimmer |
+| 39..41 | R, G, B |
+| 42..43 | speed |
+| 47     | **RemoteClientsCount** |
+| 48     | **LiveModeIsActivated** (1 = live/remote, 0 = standalone) |
+
+On fw2.x/3.x the LSAG/auth challenge must complete before status is emitted;
+without that the client sees only the auth-challenge reply.
+
+## Open questions
+
+- **The "polite goodbye" opcode** — HWM has a right-click menu option that
+  cleanly disconnects and *does not* latch. The opcode that triggers that
+  exit path has not been identified. Every other disconnect we've tried
+  (FIN, RST, process kill, cmd-Q) latches.
+- **The 0x011c reply body** is AES-encrypted device-info; the full payload
+  schema is undocumented. `tools/decrypt-011c.mjs`, `extract-011c.mjs`,
+  `find-011c-key.mjs`, `verify-011c-key.mjs`, `diff-011c.mjs` were used to
+  recover its key; the contents are not needed for the DMX path.
+- **The 0x10 crypto-state values** — 3 = pre-handshake, 4 = key installed.
+  Other values not observed.
+- **`Siudi_7B`** discovery magic — the Stick-DE3 doesn't respond to this
+  one; presumably it targets a different product line.

package/README.md

@@ -8,6 +8,28 @@ stream, reverse-engineered from the ESA2 Hardware Manager).
 
 [![npm](https://img.shields.io/npm/v/@ecopoesis/homebridge-dmx.svg)](https://www.npmjs.com/package/@ecopoesis/homebridge-dmx)
 
+## Nicolaudie Stick-DE3
+
+Please, under no circumstances, should you buy a Nicolaudie Stick-DE3 because this plugin exists.
+
+The Stick-DE3 hardware, and its accompanying software, are some of the worst I have had the misfortune to use.
+
+Some of the litany of problems with the Stick-DE3 ecosystem:
+* The Stick does not support power-over-ethernet. It takes power over an Ethernet (8P8C) shaped port, but it's non-standard.
+* The Stick touchscreen is very touchy. And not in a good way. Phantom clicks, slow responsiveness: all the problems from pre-iPhone touchscreens are here. I believe I've clicked buttons by looking at it too hard.
+* Every setting change also changes the MAC address. Hope you didn't want to give it a static address via DHCP.
+* HSV-style color spaces are not supported at all. Except: look at the color-wheel. It's in HSV. So they do support converting from HSV to RGB or various RGB+W derivatives, but can't pass the native values their controller's UI generates straight through to DMX channels.
+* The software suite is ancient and terrible. ESA Pro, ESA Pro 2, and Hardware Manager all only support x86 on MacOS. In 2026. Apple Silicon came out 6 years ago!
+* The software has a UI that would have looked dated in Windows 95.
+* Why is there so much encryption? This is my hardware. Nicolaudie sensibly ships a way to turn off IoT access, making this a pure NoT ("Network of Things") device. Let me talk to it.
+* Why do you make a DMX interface without simple channel control? It'd be great if I could use this as intended, but since it doesn't support HSV-style color, give me an easy escape hatch. You have a (poorly) documented API. Just add the ability for me to send a DMX packet. I shouldn't need to break AES to do that.
+
+That said, this plugin does just that. Reusing the encryption scheme used by Hardware Manager (with keys extracted from the binary) lets us send the same type of per-channel control used there. We then cleanly disconnect; the Stick latches the last frame, with a brief wall-controller blink as a side effect.
+
+`send_dmx.mjs` is the pieces of the protocol needed to authenticate and start streaming, including the keys extracted from Hardware Manager. Other files in `tools` are the code developed to get to that point.
+
+If you, like me, bought a Stick-DE3 based on the assumption that it was competently executed and are now stuck with it, hopefully this repo and the research it contains can help you actually make it useful.
+
 ## Status
 
 | Piece | State |
@@ -15,8 +37,9 @@ stream, reverse-engineered from the ESA2 Hardware Manager).
 | Stick-DE3 control (auth, ECDH, encrypted DMX stream) | ✅ working |
 | Color models: dimmer, cct, rgb, rgbw, rgbww, rgbaw, hsvcct | ✅ |
 | YAML and Homebridge-UI config | ✅ |
-| Multiple controllers in one patch | ✅ (only `StickDE3` type supported today) |
-| Universe B on the Stick | 🚧 plumbed but the wire encoding is unknown |
+| sACN (E1.31) gateways, e.g. ENTTEC DIN Ethergate Mk2 | ✅ (`sACN` type; unicast, A/B → sACN universes 1/2, 1 Hz keepalive stream) |
+| Multiple controllers in one patch | ✅ (`sACN` and `StickDE3` types) |
+| Universe B on the Stick | 🚧 plumbed but the wire encoding is unknown (works on `sACN`) |
 | Stick-DE3 password / "Cloud Access" auth | 🚧 not implemented |
 | State read-back | 🚧 Homebridge holds the canonical state; local drift accepted |
 

package/config.schema.json

@@ -2,7 +2,7 @@
   "pluginAlias": "DMX",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "Homebridge platform for DMX controllers. Currently supports the Nicolaudie Stick-DE3; the controller abstraction is structured so additional DMX controllers can be added later without rewriting your patch.",
+  "headerDisplay": "Homebridge platform for DMX controllers. Supports sACN (E1.31) gateways such as the ENTTEC DIN Ethergate Mk2, and the Nicolaudie Stick-DE3.",
   "footerDisplay": "For larger setups, point **yamlPath** at an external YAML file containing the controllers + profiles + patch. The YAML replaces the inline JSON below entirely.",
   "schema": {
     "type": "object",
@@ -37,10 +37,12 @@
               "title": "Controller type",
               "type": "string",
               "required": true,
-              "default": "StickDE3",
+              "default": "sACN",
               "oneOf": [
+                { "title": "sACN / E1.31 gateway (e.g. ENTTEC DIN Ethergate Mk2)", "enum": ["sACN"] },
                 { "title": "Nicolaudie Stick-DE3", "enum": ["StickDE3"] }
-              ]
+              ],
+              "description": "sACN packets are unicast to the gateway's IP; patch universes A/B map to sACN universes 1/2 (configure the gateway's ports to match)."
             },
             "ip": {
               "title": "IP address",
@@ -48,6 +50,51 @@
               "format": "ipv4",
               "required": true,
               "description": "Static IP of the controller on its DMX VLAN (e.g. 192.168.96.2). Discovery is not supported."
+            },
+            "refreshMinutes": {
+              "title": "Keepalive refresh (minutes, StickDE3 only)",
+              "type": "integer",
+              "required": false,
+              "default": 30,
+              "minimum": 0,
+              "description": "StickDE3: re-send the last-known DMX state after this many idle minutes. Keeps the Stick-DE3 from drifting into a wedged no-output state and re-asserts state after a power-cycle. 0 disables. The sACN controller streams a 1 Hz keepalive instead and ignores this."
+            },
+            "priority": {
+              "title": "sACN priority (sACN only)",
+              "type": "integer",
+              "required": false,
+              "default": 100,
+              "minimum": 0,
+              "maximum": 200,
+              "description": "E1.31 source priority. Only matters if a second sACN source targets the same universe."
+            }
+          }
+        }
+      },
+      "zones": {
+        "title": "Zones",
+        "type": "array",
+        "required": false,
+        "description": "Virtual zones: group fixtures into one multi-member HomeKit accessory.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Zone id",
+              "type": "string",
+              "required": true,
+              "description": "kebab-case identifier."
+            },
+            "name": {
+              "title": "HomeKit name",
+              "type": "string",
+              "required": true
+            },
+            "members": {
+              "title": "Member fixture ids",
+              "type": "array",
+              "required": true,
+              "items": { "type": "string" }
             }
           }
         }
@@ -125,8 +172,9 @@
               "default": "A",
               "oneOf": [
                 { "title": "A", "enum": ["A"] },
-                { "title": "B (untested)", "enum": ["B"] }
-              ]
+                { "title": "B", "enum": ["B"] }
+              ],
+              "description": "On sACN controllers, A/B go out as sACN universes 1/2. On the Stick-DE3, B is untested."
             },
             "start": {
               "title": "DMX start channel",

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export interface ControllerSpec {
     id: string;
     type: string;
     ip: string;
+    refreshMinutes?: number;
+    priority?: number;
 }
 export interface ProfileSpec {
     name: string;
@@ -35,12 +37,14 @@ export interface Profile {
     model: ColorModel;
     channels: ChannelDef[];
 }
-export declare const CONTROLLER_TYPES: readonly ["StickDE3"];
+export declare const CONTROLLER_TYPES: readonly ["StickDE3", "sACN"];
 export type ControllerType = typeof CONTROLLER_TYPES[number];
 export interface Controller {
     id: string;
     type: ControllerType;
     ip: string;
+    refreshMinutes: number;
+    priority: number;
 }
 export interface Fixture {
     id: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAI5E,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,uBAAwB,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;wEAEwE;AACxE,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,eAAe,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C;;;;oEAIoE;AACpE,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,CAmLzE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK5E,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,+BAAgC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;wEAEwE;AACxE,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,eAAe,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C;;;;oEAIoE;AACpE,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,CA6LzE"}