node-red-contrib-velbus-2026 0.9.2 → 0.10.1

package/CHANGELOG_FORUM.md

@@ -14,6 +14,249 @@ All feedback via GitHub issues, with examples and debug captures where possible.
 
 ---
 
+## Field-confirmed — 09/07/2026
+
+**v0.9.3 confirmed working against real hardware** (Stuart, his own home
+installation). Both real VMBGPOD panels present on the bus (addresses 0x05
+and 0x18/0x2C) now report correctly — `"module":"VMBGPOD"`, correct
+suggested node, correct channel count — where a rescan previously showed
+`unknown_0x28` twice. The only remaining unknown in the same scan is
+`unknown_0x42` (VMBKP, address 0xFD on Stuart's bus) — expected and correct,
+since that module genuinely has no node built yet. This closes out the
+VMBGPOD saga (v0.9.2 → v0.9.3) with an actual confirmed result, not just
+passing tests — worth the distinction given how much back-and-forth two
+separate duplicate-table bugs took to fully resolve.
+
+---
+
+## v0.10.1 — 09/07/2026
+
+### Two critical bugs found on real hardware — velbus-dimmer and velbus-glass-panel
+
+**velbus-dimmer — `on`/`state` always wrong for original-series dimmers.**
+Reported by Stuart: a VMBDMI at 75% dim showing `state:"off"`, `on:false`.
+Root cause was a genuine misunderstanding of the protocol, not a small
+off-by-one: `0xB8`'s `DATABYTE3` packs run-mode, error, load-type, and
+temperature band **all into one status byte** (confirmed identical across
+`protocol_vmbdmi.pdf`, `protocol_vmbdmi_r.pdf`, and `protocol_vmb4dc.pdf`).
+The previous code treated this as if it were a separate mode-byte +
+status-byte pair (the way relay modules genuinely have), and additionally
+read `DATABYTE5` (LED indicator status — real values `0x00`/`0x80`/`0x40`/
+`0x20`/`0x10`) as a second status word, checking its low 2 bits for
+confirmation. Since none of the real LED status values have those bits
+set, a dimmer in ordinary "normal running" mode — the overwhelmingly
+common case — always fell through to `'off'`, regardless of actual dim
+level. Also fixed in the same pass: the 24-bit current-delay timer was
+being read as only 16 bits from the wrong byte offset, and `decodeThermal`
+was being called on the LED byte instead of the real status byte (explains
+why `thermal` always showed all zeros in the field report). `ledState` is
+now correctly decoded and added to the payload. Verified against the exact
+reported scenario plus inhibited/forced_on/disabled/thermal-alarm cases,
+with the bit-field math for the packed status byte hand-checked.
+
+**velbus-glass-panel — `0xEA` thermostat status has been silently crashing
+since it was written.** Reported by Stuart via a `"velbus-bridge dispatch
+error: currentTemp is not defined"` message appearing repeatedly while
+testing a VMBGP2. Root cause: `currentTemp` and `targetTemp` were only ever
+assigned as properties of the `payload` object literal, never declared as
+their own variables — but the very next line referenced them as bare
+identifiers in the `setStatus(...)` call. Because JS evaluates a function's
+arguments before calling it, this threw a `ReferenceError` before
+`node.send()` on the following line ever executed. **This means the
+`type:"thermostat"` payload has likely never once been successfully
+delivered for any thermostat-equipped glass panel** — the bridge's
+dispatch-error handling caught the exception each time rather than
+crashing the whole process, which is exactly why this went unnoticed for
+so long rather than being immediately obvious. Fixed by declaring both as
+proper local `const`s before use. Did a full sweep of every other packet
+case in this file (button, module status, temperature, light sensor, memo
+text, counter, name parts) via the mock harness afterward, specifically
+exercising the OLED- and PIR-gated branches too — no other instances
+found. Also swept every other node file for the same bare-identifier
+`.toFixed()` pattern that caused this — one other match (`velbus-meteo`)
+checked and confirmed already correct (properly prefixed with `payload.`).
+
+Both verified via the mock-RED harness against the exact reported symptoms
+before and after the fix — not just re-reading the corrected code. Not yet
+re-confirmed on Stuart's real hardware.
+
+---
+
+## v0.10.0 — 09/07/2026
+
+### Coverage roadmap implementation — 9 new module types, velbus-button overhaul, velbus-clock sunrise/sunset
+
+Following a full rationalization pass over every unaddressed Velbus module
+type and feature (see `coverage-roadmap.md`), this implements everything
+confirmed in scope. Every single item below was checked against its actual
+protocol document before being added — several real divergences were caught
+in the process that would otherwise have shipped silently wrong.
+
+**velbus-button — substantial overhaul, not just new registry entries:**
+- 7 new module types: VMB8IR, VMB4PD, VMB4RF, VMBRFR8S, VMBVP01, VMBKP, VMBIN.
+- **Lock/unlock (0x12/0x13)** — confirmed present on 8 of the 12 total types
+  now covered; **NOT universal**, despite being asked for as "a key Velbus
+  feature." VMB8PB, VMB8IR, VMB4PD, and VMBVP01 genuinely lack this command
+  in their own protocol documents. Gated per-type (`hasLock`) — sending it to
+  an unsupported type now warns clearly on output 2 rather than silently
+  doing nothing.
+- **Richer 0xED status decode** (locked/enabled/inverted/program-disabled) —
+  also NOT universal. VMB8PB's 0xED is a completely different, simpler
+  LED-only format; VMB4RF's status uses command byte 0xB4, not 0xED, with a
+  different field at DATABYTE4 ("learn transmitter mode"); VMBVP01's 0xED is
+  a third, shorter shape again. Gated per-type (`hasRichStatus`) — decoding
+  is skipped entirely for types that don't match, rather than risk
+  misreading whatever they actually send.
+- **Channel names surfaced in event output** (0xF0/F1/F2) — found the
+  selector byte convention itself is inconsistent across types: some use a
+  bitmask (one bit per channel), others a literal 1-based number. These
+  produce the *same* byte value for channels 1-2, diverging only from
+  channel 3 onward — exactly the kind of thing that would pass casual
+  testing and then silently corrupt every name from channel 3 up. Verified
+  explicitly at channel 3 for both conventions before shipping.
+- **VMBVP01 (DoorBird)** gets fixed semantic channel labels (Motion 1/2,
+  Bell 1/2, Door 1/2, Virtual button 1/2) — hardware-fixed functions, not
+  VelbusLink-configurable names, so not sourced from 0xF0-F2 at all.
+- Output changed from 1 to 2 (events/status, warnings) — non-breaking for
+  existing flows, the new output simply has no wires by default.
+- **Real mistake caught before shipping:** first pass had VMB4RF at 8
+  channels; its own status packet says "channel 1 to 4," matching its name.
+  Corrected to 4 before release, not after.
+- **A second, more serious pre-existing bug found and fixed, unrelated to
+  today's additions:** `VMB4PB` and `VMB6PB-20` — two of the *original* five
+  button types, present since v0.5.2 — were registered under wrong type
+  bytes (`0x1C` and `0x20`) in this file's own registry. `0x1C` isn't a real
+  Velbus type byte at all; `0x20` actually belongs to `VMBGP4`, an unrelated
+  glass panel type. `velbus-scan.js` has always had the correct values
+  (`0x44`/`0x4C`) — only this file's internal lookup was wrong, meaning a
+  real `VMB4PB` or `VMB6PB-20`, correctly identified by a scan, would never
+  have matched this file's own type descriptor at all. Every type-specific
+  feature (and now, lock/unlock and rich status too) would have silently
+  never activated for these two types. Found by cross-referencing the
+  official type list while writing this changelog entry, not by design —
+  worth remembering that documentation review can surface real bugs too.
+
+**velbus-sensor:** VMB6IN added. Confirmed simpler than its VMB7IN sibling,
+not just a smaller version of it — no lock/unlock command exists for it at
+all, and its 0xED module status is 5 bytes vs VMB7IN's 7. The existing
+`body.length < 7` guard already skips it safely; no code change needed
+beyond the registry entry itself.
+
+**velbus-glass-panel:** VMBGP4PIR-2 (0x3E) and VMBGPTC (0x25) added.
+- **Real mistake caught:** VMBGP4PIR-2's channels 5-8 have completely
+  different semantics from its 0x2D sibling despite the near-identical name
+  (Dark/Light output, Motion output, Light-depending-motion, Absence output
+  — not virtual/dark/light/motion). Copying the sibling's mapping would have
+  silently mislabeled four channels.
+- VMBGPTC confirmed sharing its actual protocol document with VMBGPO
+  (0x21) — a thermostat-only variant of the same panel hardware, added to
+  the glass-panel registry rather than as thermostat-node-only, so
+  `velbus-thermostat` picks up its function automatically the same way it
+  already does for every other panel address.
+
+**velbus-clock:** sunrise/sunset enable/disable (0xAE) added, same
+global/local address pattern as the existing `set_alarm` — confirmed
+identical packet body for both from the protocol PDF.
+
+**velbus-scan:** all of the above added across its three independent tables
+(`ALL_TYPES`/`NODE_SUGGESTION`/`MODULE_CHANNELS`) — the exact lesson from
+the VMBGPOD saga (v0.9.2/v0.9.3), applied proactively this time rather than
+discovered the hard way again. Also adds explicit `"Not supported"` scan
+labels (rather than falling through to a bare name with no node) for
+VMBDALI, VMBDALI-20, VMBLCDWB, VMCM3, VMBSIG, VMBSIG-20, and VMBSIG-21 —
+recognized correctly in a scan, deliberately not built, by design rather
+than oversight.
+
+**Explicitly deferred, not built this round:** VMB1DM, VMBDME, and VMB1LED
+(the dimmer-family additions) all turned out to use a genuinely different
+single-channel `0xEE` status layout — distinct from both `velbus-dimmer`'s
+own format and `velbus-dimmer-20`'s multi-channel bitmask format. This needs
+real new decode logic, not a registry entry, and doesn't meet the
+"minimal effort" bar set for this round. Parked rather than forced in.
+
+**Verification:** every new packet format checked against its actual
+protocol document (not inferred from a same-named sibling) before being
+implemented; every new command exercised through the mock-RED harness with
+hand-checked checksums; the channel-3 naming-convention divergence
+specifically tested for both conventions, not just one; a full simulated
+scan run across every new and "not supported" type confirmed correct
+`suggestedNode`/`channels` output end to end. Not yet sent to a real bus.
+
+---
+
+## v0.9.4 — 09/07/2026
+
+### velbus-button — critical bug, live since v0.5.2: button events shifted by one byte
+
+- **Found while scoping VMBKP's decode logic, not reported directly** — checking
+  `velbus-button.js` as a template surfaced that its `0x00` handler read
+  `body[0]`/`body[1]`/`body[2]` for pressed/released/long-pressed, when
+  `body[0]` is always the command byte itself (always `0x00`, per this
+  project's own most-repeated rule — see `HANDOVER.md` section 4.3). Every
+  field was reading one byte too early.
+- **Real impact, not theoretical:** `pressed` was always empty (reading the
+  constant command byte), `released` was actually reporting what DATABYTE2
+  (the real "pressed" bitmask) contained, `longPressed` was reporting what
+  DATABYTE3 (the real "released" bitmask) contained, and the real
+  DATABYTE4 (long-press bitmask) was never read at all. The `on` field
+  followed the same corruption — it could report `true` on a release and
+  never correctly on an immediate press.
+- **Confirmed live since `velbus-button`'s introduction in v0.5.2** — this
+  is not a new regression, it has been shipping incorrect button-event data
+  for the entire time this node has existed. `velbus-glass-panel`'s own
+  `0x00` handler was checked immediately afterward and confirmed **not**
+  affected — it already used the correct `body[1]`/`body[2]`/`body[3]`
+  indexing, so this was isolated to one file, not systemic.
+- **Fixed and verified with a real repro, not just a corrected read of the
+  code:** built a mock-harness test that reproduces the exact failure first
+  (channel 3 pressed came back reported as "released") before applying the
+  fix, then re-ran the same test plus three more (release, long-press,
+  simultaneous multi-channel press) to confirm all four now report
+  correctly.
+- **If you have flows depending on `velbus-button`'s `pressed`/`released`/
+  `longPressed` distinction** (rather than just the `on` boolean, or
+  scanning/discovery, which were unaffected), check them after updating —
+  behaviour that previously "worked" by only watching `on`, or by
+  compensating for the shift some other way in the flow itself, may now
+  behave differently now that the underlying data is actually correct.
+
+---
+
+## v0.9.3 — 09/07/2026
+
+### velbus-scan — VMBGPOD still showed "unknown_0x28" after the v0.9.2 fix
+
+- **Reported by Stuart:** re-ran a scan against v0.9.2 pulled fresh from npm,
+  `VMBGPOD` still showed as `unknown_0x28`.
+- **Root cause:** `velbus-scan.js` has its **own, third, independent copy**
+  of the type table — `ALL_TYPES`, `NODE_SUGGESTION`, and `MODULE_CHANNELS`
+  — entirely separate from `lib/glass-panel-types.js` (used by
+  `velbus-glass-panel` at runtime) and the duplicate list inside
+  `velbus-glass-panel.html` (used for the editor dropdown), both already
+  fixed in v0.9.2. The v0.9.2 fix genuinely worked for the glass-panel node
+  itself; the bus scanner simply had no idea `VMBGPOD` existed, since it
+  never reads either of the other two files at all.
+- **This is now the third type table found in this codebase.** Searched
+  exhaustively this time (`grep -rln "VMBGPO'"` across the whole `nodes/`
+  and `lib/` tree) rather than assume these three are the only ones — they
+  are, confirmed by the search coming back with exactly these three files
+  and no others.
+- Added `0x28: 'VMBGPOD'` to all three tables in `velbus-scan.js`.
+- **Verified end-to-end this time, not just by inspecting the table.** Built
+  a full mock-harness test that triggers a real scan, feeds a simulated
+  `0xFF` response for `VMBGPOD` (using the exact build/serial from Stuart's
+  own scan output), and confirms the emitted `module_found` payload reports
+  `"module":"VMBGPOD"`, the correct suggested node, and the correct channel
+  count — not just that the table lookup would theoretically work.
+- **Worth remembering for any future module type addition:** check all
+  three of `lib/<family>-types[-20].js`, the corresponding node's own
+  `.html` (editor dropdown), and `velbus-scan.js` (bus-wide discovery).
+  Missing any one of the three produces a real, user-visible symptom in a
+  different part of the palette than wherever the fix was actually made —
+  exactly what happened here.
+
+---
+
 ## v0.9.2 — 09/07/2026
 
 ### velbus-glass-panel — VMBGPOD (0x28) registry gap fixed

package/HANDOVER.md

@@ -6,7 +6,7 @@ you're a new contributor, a new maintainer, or an AI assistant starting a fresh
 with no memory of previous work — this document should be sufficient on its own, together
 with the source code in this repository, to continue development competently.
 
-Current state at time of writing: **v0.9.2, 19 nodes, published on npm.**
+Current state at time of writing: **v0.10.1, 19 nodes, published on npm.**
 
 ---
 
@@ -106,7 +106,7 @@ lib/                       Shared code — protocol utilities and per-module-fam
   dimmer-types.js            Original-series dimmer module type registry
   dimmer-types-20.js         V2 dimmer module type registry (incl. LED grouping mode / Device
                              Type table for VMB4LEDPWM-20)
-  glass-panel-types.js       All 27 glass panel module types in one registry (hasOled/hasPir/
+  glass-panel-types.js       All 29 glass panel module types in one registry (hasOled/hasPir/
                              hasOc/minMapVer flags per type)
   pir-types.js / pir-types-20.js       PIR sensor module type registries
   sensor-types.js / sensor-types-20.js Sensor/meteo module type registries
@@ -144,6 +144,24 @@ boilerplate (bridge lookup, packet registration, status bar handling, firmware c
 V2 nodes) is consistent across every node and easy to get subtly wrong if rebuilt from
 scratch.
 
+**Adding or fixing a module type touches three separate files, not one — confirmed
+the hard way (v0.9.2 → v0.9.3).** A module type used to exist in exactly one place per
+node family; it doesn't. Check all three every time:
+1. `lib/<family>-types[-20].js` — used by the actual node at runtime (`velbus-glass-panel`,
+   `velbus-sensor`, etc.)
+2. The corresponding node's own `.html` file — a **separate, duplicate** copy used only
+   to populate the editor's address dropdown and type hint. Not read by the running node
+   at all.
+3. `nodes/velbus-scan/velbus-scan.js` — has its **own, third, entirely independent** copy
+   (`ALL_TYPES`, `NODE_SUGGESTION`, `MODULE_CHANNELS`), used only for bus-discovery
+   reporting. Doesn't read either of the other two files.
+
+Missing any one of the three produces a real, user-visible symptom in a *different* part
+of the palette than wherever the fix actually needs to happen — a scan reporting
+`unknown_0x28` while the glass-panel node itself handles that type perfectly correctly,
+for instance. When in doubt, `grep -rln "<ModuleName>'" nodes/ lib/` to find every file
+that mentions a given type by name, rather than assume you've found all the copies.
+
 ---
 
 ## 4. Architecture overview
@@ -244,6 +262,22 @@ implementing a new packet handler, always write out the DATABYTE-to-`body[]` ind
 mapping explicitly as a comment before writing the parsing logic — it is not something
 to trust from memory or infer quickly.
 
+**The canonical real example: `velbus-button` shipped this exact bug from its very
+first version (v0.5.2) until v0.9.4** — over 30 versions, undetected. Its `0x00`
+handler read `body[0]`/`body[1]`/`body[2]` for pressed/released/long-pressed, when the
+correct indices are `body[1]`/`body[2]`/`body[3]`. The practical effect: `pressed` was
+always empty (silently reading the constant command byte), `released` actually reported
+what was really the pressed bitmask, `longPressed` reported what was really the released
+bitmask, and the real long-press data was never read at all. It went unnoticed for this
+long specifically because `velbus-glass-panel`'s own, separately-written `0x00` handler
+got the indexing right from the start, and nobody had directly exercised
+`velbus-button`'s press/release distinction against real hardware — only its
+scan/discovery path (`0xFF`/`0xB0`, handled entirely separately) had seen real traffic.
+A bug in one packet handler is invisible from the outside if nothing forces that
+specific handler to run against real data. If you're verifying a node, verify the
+specific packet type you care about — passing scan/discovery doesn't imply anything
+about a different command byte's handler in the same file.
+
 ### 4.4 Address format
 
 Module addresses are stored as **hex strings in the editor's dropdown UI** (e.g.
@@ -266,18 +300,18 @@ or a string before assuming the parsing logic itself is wrong.
 | `velbus-relay-20` | Velbus (outputs) | V2 relays: VMB1RYS-20, VMB4RYLD-20, VMB4RYNO-20 |
 | `velbus-dimmer` | Velbus (outputs) | Original-series dimmers: VMBDMI, VMBDMI-R, VMB4DC |
 | `velbus-dimmer-20` | Velbus (outputs) | V2 dimmers: VMB2DC-20, VMB8DC-20, VMB4LEDPWM-20 (incl. RGB/RGBW grouping mode) |
-| `velbus-glass-panel` | Velbus (inputs) | All 27 glass panel types (original + V2), buttons/OLED/PIR/open-collector as applicable per type |
+| `velbus-glass-panel` | Velbus (inputs) | All 29 glass panel types (original + V2), buttons/OLED/PIR/open-collector as applicable per type |
 | `velbus-thermostat` | Velbus (inputs) | Thermostat function on any glass panel module that has one — same address as the corresponding glass-panel node, coexists without conflict |
-| `velbus-button` | Velbus (inputs) | Dedicated push-button modules: VMB8PB, VMB8PBU, VMB6PBN, VMB2PBN, VMB4PB, VMB6PB-20 |
+| `velbus-button` | Velbus (inputs) | 12 types across original and V2 series (VMB8PB, VMB8PBU, VMB6PBN, VMB2PBN, VMB4PB, VMB6PB-20, VMB8IR, VMB4PD, VMB4RF, VMBRFR8S, VMBVP01, VMBKP, VMBIN) — plain button events for all; lock/unlock and richer status decode for the 8 types confirmed to support them; fixed semantic channel labels for VMBVP01 (DoorBird) |
 | `velbus-pir` | Velbus (inputs) | Original-series PIR: VMBPIRO-10, VMBPIRM, VMBPIRC, VMBPIRO |
 | `velbus-pir-20` | Velbus (inputs) | V2 PIR: VMBPIR-20, VMBPIRO-20 |
 | `velbus-meteo` | Velbus (inputs) | Weather station: VMBMETEO |
-| `velbus-sensor` | Velbus (inputs) | Original-series input/analogue: VMB7IN, VMB4AN |
+| `velbus-sensor` | Velbus (inputs) | Original-series input/analogue: VMB7IN, VMB4AN, VMB6IN |
 | `velbus-sensor-20` | Velbus (inputs) | V2 input: VMB8IN-20 |
 | `velbus-blind` | Velbus (outputs) | VMB1BL, VMB2BL |
 | `velbus-blind-s` | Velbus (outputs) | VMB1BLS, VMB2BLE, VMB2BLE-10 |
 | `velbus-blind-20` | Velbus (outputs) | VMB2BLE-20 |
-| `velbus-clock` | Velbus (outputs) | **No fixed module address.** Broadcasts system time/date/DST to the bus broadcast address (`0x00`), and sets clock alarms either globally (broadcast) or locally (a specific module, via a per-message address override) |
+| `velbus-clock` | Velbus (outputs) | **No fixed module address.** Broadcasts system time/date/DST to the bus broadcast address (`0x00`), sets clock alarms and sunrise/sunset enable state either globally (broadcast) or locally (a specific module, via a per-message address override) |
 | `velbus-energy` | Velbus (inputs) | VMBPSUMNGR-20 — power supply manager: PSU load percentages, live wattage/voltage/amperage per rail, a warranty (hours-in-operation) counter, and PSU/warranty alarm status |
 
 Palette group colours: **Velbus (inputs)** is teal (`#3A8C8C`), **Velbus (outputs)** is
@@ -313,23 +347,31 @@ blue (`#4A90D9`).
 | 0x2F | VMBDMI-R | velbus-dimmer | n/a |
 | 0x4B | VMB8DC-20 | velbus-dimmer-20 | n/a |
 
-### Push buttons
-| Type byte | Module | Node |
-|---|---|---|
-| 0x01 | VMB8PB | velbus-button |
-| 0x16 | VMB8PBU | velbus-button |
-| 0x17 | VMB6PBN | velbus-button |
-| 0x18 | VMB2PBN | velbus-button |
-| 0x44 | VMB4PB | velbus-button |
-| 0x4C | VMB6PB-20 | velbus-button |
-
-### Glass panels (all → velbus-glass-panel, 27 types)
+### Push buttons (all → velbus-button, 12 types)
+| Type byte | Module | Lock/unlock | Notes |
+|---|---|---|---|
+| 0x01 | VMB8PB | No | Simpler 0xED (LED status only), no lock command at all |
+| 0x16 | VMB8PBU | Yes | |
+| 0x17 | VMB6PBN | Yes | |
+| 0x18 | VMB2PBN | — | Not yet cross-checked for lock support, treated conservatively |
+| 0x44 | VMB4PB | Yes | **Type byte corrected 09/07/2026** — was wrongly keyed 0x1C in `velbus-button.js`'s own registry (not a real type byte at all); `velbus-scan.js` always had 0x44 right |
+| 0x4C | VMB6PB-20 | Yes | **Type byte corrected 09/07/2026** — was wrongly keyed 0x20 (which is actually VMBGP4, a different module); `velbus-scan.js` always had 0x4C right |
+| 0x0A | VMB8IR | No | IR receiver — presents fixed Velbus IR codes as button events |
+| 0x0B | VMB4PD | No | LCD module — only the 4 button channels covered, not the LCD |
+| 0x1A | VMB4RF | Yes | 4 channels (matches its name) — status uses 0xB4, not 0xED, so rich status is not decoded even though lock/unlock works |
+| 0x30 | VMBRFR8S | Yes | |
+| 0x33 | VMBVP01 | No | DoorBird — fixed semantic labels (Motion 1/2, Bell 1/2, Door 1/2, Virtual button 1/2), different/shorter 0xED not decoded |
+| 0x42 | VMBKP | Yes | |
+| 0x43 | VMBIN | Yes | Single channel |
+
+### Glass panels (all → velbus-glass-panel, 29 types)
 | Type byte | Module | OLED | PIR | Open collector | Min. map version |
 |---|---|---|---|---|---|
 | 0x1E | VMBGP1 | no | no | unconfirmed¹ | — |
 | 0x1F | VMBGP2 | no | no | unconfirmed¹ | — |
 | 0x20 | VMBGP4 | no | no | unconfirmed¹ | — |
 | 0x21 | VMBGPO | yes | no | yes | 2 |
+| 0x25 | VMBGPTC | yes | no | no | — |
 | 0x28 | VMBGPOD | yes | no | no | — |
 | 0x2D | VMBGP4PIR | no | yes | unconfirmed¹ | — |
 | 0x34 | VMBEL1 | no | no | yes | 2 |
@@ -341,6 +383,7 @@ blue (`#4A90D9`).
 | 0x3B | VMBGP2-2 | no | no | no² | — |
 | 0x3C | VMBGP4-2 | no | no | no² | — |
 | 0x3D | VMBGPOD-2 | yes | no | unconfirmed¹ | 2 |
+| 0x3E | VMBGP4PIR-2 | no | yes | unconfirmed¹ | — |
 | 0x47 | VMBEL2PIR | no | yes | yes | — |
 | 0x4F | VMBEL1-20 | no | no | yes | — |
 | 0x50 | VMBEL2-20 | no | no | yes | — |
@@ -354,6 +397,14 @@ blue (`#4A90D9`).
 | 0x5C | VMBEL2PIR-20³ | no | yes | yes | — |
 | 0x5F | VMBGP4PIR-20 | no | yes | unconfirmed¹ | — |
 
+⁴ VMBGPTC (0x25) shares its actual protocol document with VMBGPO (0x21) — a
+thermostat-only variant of the same touch panel hardware, not a separate
+product. Type byte confirmed from the official type list, not spelled out
+separately in the shared document's body. VMBGP4PIR-2 (0x3E) has genuinely
+different channel 5-8 semantics from its 0x2D sibling despite the similar
+name (Dark/Light output, Motion output, Light-depending-motion, Absence
+output — not virtual/dark/light/motion) — confirmed directly, not assumed.
+
 ¹ Open-collector support unconfirmed against real hardware — see [section 13](#13-known-open-issues).
 ² Confirmed no open-collector commands in the protocol PDF, but not yet live-verified.
 ³ The official Velbus type list shows different module names at these two type bytes than
@@ -377,6 +428,7 @@ what this registry currently uses — flagged for verification, see
 | 0x31 | VMBMETEO | velbus-meteo |
 | 0x32 | VMB4AN | velbus-sensor |
 | 0x4E | VMB8IN-20 | velbus-sensor-20 |
+| 0x05 | VMB6IN | velbus-sensor — simpler sibling of VMB7IN, no lock/unlock at all, 5-byte 0xED (vs VMB7IN's 7) safely skipped by the existing length guard |
 
 ### Blind / shutter
 | Type byte | Module | Node |
@@ -476,6 +528,36 @@ body[6] = error bitmask
 body[7] = alarm/program byte
 ```
 
+### 7.5a `0xB8` dimmer status — original series (VMBDMI, VMBDMI-R, VMB4DC)
+
+**Not the same shape as 7.5 above, despite both being "dimmer status."**
+Confirmed identical across all three original-series protocol PDFs — one
+combined status byte, not separate mode/status bytes the way relay modules
+or the V2 dimmer status have:
+```
+body[0] = 0xB8
+body[1] = channel (VMBDMI/-R: always 0x01; VMB4DC: bitmask)
+body[2] = status byte — MULTIPLE bit-fields packed together:
+            bits 0-1: run mode (00=normal, 01=inhibited, 10=forced_on, 11=disabled)
+            bits 2-3: error (VMBDMI/-R only — VMB4DC has no thermal section at all)
+            bit 4:    load type (VMBDMI/-R only: 0=resistive, 1=inductive)
+            bits 5-7: temperature band (VMBDMI/-R only, 8 levels)
+body[3] = dim value (0-100%)
+body[4] = LED indicator status ONLY — unrelated to run state (0x00 off,
+          0x80 on, 0x40 slow blink, 0x20 fast blink, 0x10 very fast blink)
+body[5-7] = 24-bit current delay time, MSB first
+```
+There is no separate `"forced_off"` status — that's a real, distinct
+*command* (0x12) you can send, but the module reports its result through
+the same four-value run-mode set above, same as relay's forced/inhibited
+pattern conceptually, but packed into one byte here rather than two.
+`on` is true for `forced_on`, or for `normal` mode with a nonzero dim
+value — **not** simply "mode equals the literal string on," which was the
+real bug (v0.10.1): a dimmer in ordinary normal-running mode — by far the
+most common real-world state — was being read as `off` regardless of dim
+level, because the code checked the LED status byte's low bits for
+confirmation instead of using the dim value directly.
+
 ### 7.6 `0xA5` dim level — up to four channels packed per packet
 ```
 body[0] = 0xA5, body[1] = channel, body[2] = level (0-254)
@@ -603,7 +685,7 @@ about why in the commit message.
 
 - **Generational split.** Nodes generally split at the V2.0 boundary — one node for
   original-series, a separate node for V2. **Exceptions:** `velbus-glass-panel` (one
-  node covers all 27 types, both generations, via the type registry's per-type flags
+  node covers all 29 types, both generations, via the type registry's per-type flags
   rather than a code-level split), `velbus-thermostat` (covers the thermostat function
   on any glass panel type), `velbus-meteo` (only one generation exists), and the blind
   family (`velbus-blind` / `velbus-blind-s` / `velbus-blind-20`, split by actual protocol
@@ -757,6 +839,25 @@ orientation at the time of writing:
 
 - **Field-tested against live hardware:** the core relay, dimmer, glass panel, and
   thermostat nodes have real-hardware confirmation for their primary functions.
+  `VMBGPOD` (0x28) specifically confirmed 09/07/2026 against two real panels on
+  Stuart's own home bus, closing out the v0.9.2/v0.9.3 registry-gap saga with an
+  actual result rather than just a passing test.
+- **`velbus-dimmer`'s `0xB8` status decode was fundamentally wrong from when it was
+  first written until v0.10.1** — see section 7.5a. A dimmer in ordinary "normal
+  running" mode always reported `off` regardless of actual dim level. Fixed and
+  verified via the mock harness against the exact reported scenario, but not yet
+  re-confirmed against Stuart's real VMBDMI.
+- **`velbus-glass-panel`'s `0xEA` thermostat status has been silently crashing
+  since it was written, until v0.10.1** — see section 16's code style rules for
+  the full story. The `type:"thermostat"` payload has likely never once been
+  successfully delivered for any real thermostat-equipped panel. Fixed and swept
+  for the same pattern elsewhere in the file (none found), but not yet
+  re-confirmed against Stuart's real hardware.
+- **`velbus-button` had a critical, real bug from its first version until v0.9.4** —
+  see section 4.3 for the full story. Its press/release/long-press decode is now
+  fixed and verified with a real repro, but has not yet been re-confirmed against a
+  live button press on real hardware (only via the mock harness) — worth doing
+  before trusting it fully, given how long the broken version went unnoticed.
 - **Mock-harness verified only, not yet confirmed against a real bus:** `velbus-clock`
   (both the time/date/DST broadcast and the `set_alarm` command), the
   `velbus-dimmer-20` `get_device_type` read command, and `velbus-energy` in its
@@ -772,9 +873,10 @@ orientation at the time of writing:
 ## 13. Known open issues
 
 - **`VMBKP` (0x42, "Keypad interface module") has no node at all.** Found scanning a
-  real installation (Stuart's home) alongside the `VMBGPOD` gap below — a genuinely new
-  module type, not yet scoped. Its protocol PDF (`protocol_vmbkp.pdf`, 28 pages) is
-  substantial: channel status, module status, and a full per-channel LED control layer
+  real installation (Stuart's home) — confirmed present at address `0xFD`, a real
+  module on a real bus, not a hypothetical. A genuinely new module type, not yet
+  scoped. Its protocol PDF (`protocol_vmbkp.pdf`, 28 pages) is substantial: channel
+  status, module status, and a full per-channel LED control layer
   (clear/set/slow-blink/fast-blink/very-fast-blink), similar in spirit to `velbus-button`
   but with LED feedback control `velbus-button` doesn't have. This needs the same
   "how much work would this involve" scoping pass `velbus-energy` got before it was
@@ -808,6 +910,33 @@ orientation at the time of writing:
   against the year's January/July offsets to infer whether daylight saving is active)
   has only been sanity-checked in an environment where daylight saving never applies —
   a genuine positive "DST is active" case hasn't been observed and confirmed correct.
+- **`VMB1DM`, `VMBDME`, `VMB1LED` (dimmer-family additions) deferred, not built.**
+  All three use a genuinely different single-channel `0xEE` status layout
+  (mode/dim-value/LED/timer/config in one packet) — distinct from both
+  `velbus-dimmer`'s own `0xB8`-based format and `velbus-dimmer-20`'s
+  multi-channel bitmask `0xEE` format. Needs real new decode logic, not a
+  registry entry — see `coverage-roadmap.md` for the full reasoning.
+- **Bus error counter (`0xDA`) — design settled, not built.** Confirmed
+  useful but explicitly framed as a rare edge case. Resolved design: every
+  node that registers for its own address already receives an unsolicited
+  `0xDA` broadcast if one occurs, so no new request command is needed —
+  just passive decoding, emitted only on a secondary output and only when
+  at least one counter is non-zero, so it never appears during normal
+  operation. Deliberately deferred since it touches most/all existing nodes
+  — a session of its own, not a quick addition.
+- **OLED image writing — stretch goal, not built.** Pushing a custom B&W
+  1-bit bitmap to an OLED glass panel (e.g. swapping in a different-language
+  greeting for a visitor without opening VelbusLink) — genuine use case,
+  explicitly not urgent. `velbus-glass-panel` currently only reads memo text
+  (`0xAC`), no write path exists in either direction for display content.
+- **`VMBDALI`/`VMBDALI-20`, `VMBLCDWB`, `VMCM3`, `VMBSIG`/`VMBSIG-20`/`VMBSIG-21`
+  — recognized, deliberately not supported.** These show their correct name
+  in a scan (not `unknown_0xNN`) with an explicit `"Not supported"` in place
+  of a suggested node, rather than silently falling through to `null`. DALI
+  is its own protocol layer beyond the gateway; the Signum types are a
+  proprietary HomeAssistant-based master clock, not interactable; VMBLCDWB
+  and VMCM3 are legacy/custom modules with no planned support. By design,
+  not oversight — see `coverage-roadmap.md` for the full per-type reasoning.
 
 ---
 
@@ -894,6 +1023,53 @@ git push --tags
   exceptions — see section 4.3 if this isn't already second nature.
 - **Numbers are always numbers in payloads, never strings.**
 - **`results.modules`, not `results`,** when reading the scan endpoint.
+- **A module type lives in three separate files, not one** (per-node `lib/` registry,
+  that node's own `.html` dropdown copy, and `velbus-scan.js`'s independent copy) —
+  see section 3 for the full explanation. Missing one produces a symptom in a
+  different part of the palette than wherever the type was actually added.
+- **Never assume a feature is universal across a module family — check each type's
+  own protocol document.** Proven wrong repeatedly (09/07/2026) while adding
+  lock/unlock and richer status decode to `velbus-button`: of 12 button-family
+  types, 4 genuinely lack the lock/unlock command entirely (not "probably most
+  don't" — specific, named exceptions); one type's status uses a completely
+  different command byte (`0xB4` instead of `0xED`); the "which channel" selector
+  byte in the name-request commands uses two incompatible conventions (bitmask vs.
+  literal number) that happen to produce identical values for channels 1-2 and only
+  diverge from channel 3 onward — exactly the kind of divergence that survives
+  casual testing. When a person asks for a capability "because it's a key feature,"
+  that's a reason to verify it broadly, not a reason to skip checking each type.
+- **Registry type-byte keys need the same verification as everything else** — don't
+  assume an existing entry's key is correct just because it's already shipped.
+  Found 09/07/2026: `VMB4PB` and `VMB6PB-20` had been keyed under wrong type bytes
+  in `velbus-button.js`'s own registry since v0.5.2 (`0x1C`, which isn't a real
+  Velbus type byte at all, and `0x20`, which actually belongs to `VMBGP4`) — while
+  `velbus-scan.js` had always had the correct values. Cross-check against the
+  official type list (section 15) periodically, not just when adding something new.
+- **Never reference a variable that was only ever assigned as an object property.**
+  Real bug, live since the code was written (fixed v0.10.1): `velbus-glass-panel`'s
+  `0xEA` handler built `currentTemp`/`targetTemp` only inside a `payload = {...}`
+  object literal, then referenced them as bare identifiers on the very next line
+  (`setStatus('...' + currentTemp.toFixed(1) + ...)`). Since JS evaluates a
+  function's arguments before calling it, this threw a `ReferenceError` *before*
+  `node.send()` on the following line — meaning the entire payload silently never
+  went out, for as long as this code existed. The bridge's own dispatch-error
+  handling caught the exception each time rather than crashing the process, which
+  is exactly what let this go unnoticed rather than being immediately obvious.
+  If a value is going into both a status/log string and a payload object, declare
+  it as its own `const` first and use that name in both places — never build it
+  only inside the object literal and assume you can reference it by name outside.
+- **Don't assume a "two-byte status" pattern applies to every module family.**
+  Real bug, live since the code was written (fixed v0.10.1): the original-series
+  dimmer's `0xB8` status was assumed to work like relay's genuine separate
+  mode-byte + status-byte pair. In reality `VMBDMI`/`VMBDMI-R`/`VMB4DC` pack
+  run-mode, error, load-type, and temperature into a *single* status byte
+  (confirmed identical across all three protocol PDFs — see section 7.5a), and
+  the code was additionally reading the LED indicator byte as if it were a second
+  status word. The result: a dimmer in ordinary "normal running" mode — the most
+  common real-world state — always reported `off` regardless of actual dim level.
+  Same underlying lesson as the button-family capability work: check each
+  module's own protocol document for its actual byte layout, don't port a pattern
+  from a different (even superficially similar) module family.
 - **Thermostat commands go to the primary address only,** never a subaddress.
 - **Respect the 20ms minimum between `0xFC` writes** on original-series modules — this
   is real EEPROM wear, not an arbitrary rate limit.

package/lib/glass-panel-types.js

@@ -61,6 +61,24 @@ const GLASS_PANEL_TYPES = {
     minMapVer: 2,
     series: 'original',
   },
+  0x25: {
+    // Added 09/07/2026. Shares its actual protocol document with VMBGPO
+    // (protocol_vmbgpo_vmbgptc.pdf) — a thermostat-only variant of the same
+    // touch panel hardware, not a separate product. Type byte 0x25 confirmed
+    // from the official Velbus type list, not spelled out separately in the
+    // body of the shared document (it only gives VMBGPO's H'21' as a worked
+    // example). hasOc set conservatively to false — the shared document has
+    // no "collector" mention at all for either variant, unlike whatever
+    // source justified VMBGPO's own hasOc:true above (a different document,
+    // not re-verified here — that entry is untouched).
+    name: 'VMBGPTC',
+    channels: 32,
+    hasOled: true,
+    hasPir: false,
+    hasOc: false,
+    minMapVer: null,
+    series: 'original',
+  },
   0x28: {
     name: 'VMBGPOD',
     // Added 09/07/2026 — found as "unknown_0x28" scanning a real installation.
@@ -98,6 +116,24 @@ const GLASS_PANEL_TYPES = {
     minMapVer: null,
     series: 'original',
   },
+  0x3E: {
+    // Added 09/07/2026. IMPORTANT: this is NOT the same channel 5-8 mapping
+    // as its 0x2D sibling above, despite the similar name — confirmed
+    // directly from protocol_vmbgp4pir_ed2.pdf, which gives an entirely
+    // different set of labels. Copying the 0x2D mapping here would have
+    // silently mislabeled four channels.
+    name: 'VMBGP4PIR-2',
+    channels: 8,
+    hasOled: false,
+    hasPir: true,
+    hasOc: null,        // no mention found in this PDF either — same unconfirmed state as 0x2D
+    pirChannels: {
+      1: 'button1', 2: 'button2', 3: 'button3', 4: 'button4',
+      5: 'dark_light', 6: 'motion', 7: 'light_motion', 8: 'absence',
+    },
+    minMapVer: null,
+    series: 'original',
+  },
   0x34: {
     name: 'VMBEL1',
     channels: 1,