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

package/CHANGELOG_FORUM.md

@@ -29,6 +29,53 @@ separate duplicate-table bugs took to fully resolve.
 
 ---
 
+## v0.10.2 — 09/07/2026
+
+### velbus-sensor — VMB4AN generic analogue reading (channels 9-12)
+
+- **Prompted by Stuart noticing `isVMB4AN` was defined but never used** —
+  confirmed the sensor-input channels (Group 2 of VMB4AN's three functional
+  groups) produced literally no output at all beforehand; the packet
+  carrying that data wasn't handled anywhere in the file.
+- **Real trap found and avoided:** the obviously-named `0xEA`
+  ("sensor status") packet does **not** carry a value at all — it's
+  operating-mode/sleep-timer/auto-send configuration only. The actual
+  reading lives in a separate, easy-to-miss packet earlier in the protocol
+  document: `0xA9` (`COMMAND_SENSOR_RAW_DATA`, "Transmit the sensor raw
+  value"), genuinely standalone with no need to cross-reference anything
+  else. Also confirmed `0xE8`/`0xE9` ("sensor settings") is preset
+  *configuration* storage, not a live value either — three different
+  packets that could each plausibly have been mistaken for "the reading."
+- Deliberately generic, per explicit preference: emits `{ type: "analogue",
+  channel, mode, raw }` with no engineering-unit conversion attempted —
+  `mode` (voltage/current/resistance/period) and the PDF's resolution
+  table are exposed in the node's help so conversion can happen in the flow
+  instead.
+- New `get_analogue` input command (`0xE5`, request-a-reading-now) — uses
+  the protocol's own "auto-send config byte = 0" option to request a value
+  without side-effecting the module's existing auto-send schedule.
+  **Priority byte corrected during verification:** the protocol PDF
+  explicitly states "SID10-SID9 = 11 (lowest priority)" for this specific
+  command — `0xFB`, not the `0xF8` most other commands in this file use.
+  Checked directly rather than assumed, since this is the one place it
+  genuinely differs from the file's established convention.
+- Both confirmed absent from `VMB7IN`'s own protocol PDF before wiring
+  in — this file's switch statement handles both module types together,
+  so a collision would misfire for `VMB7IN` modules if either byte had
+  been reused there.
+- **Full Group 2 configuration (presets, mode-switching, sleep time,
+  offset, auto-send interval config) and all of Group 3 (analog outputs)
+  remain parked** — see `coverage-roadmap.md` section 6. This is
+  deliberately just the minimal reading piece, not the full feature.
+
+Verified via the mock-RED harness: voltage/period modes, both period
+special-value cases (`0x000000` short-circuit, `0xFFFFFF` open-circuit),
+`VMB7IN` isolation confirmed (same bytes produce no output on that type),
+`get_analogue` checksum hand-verified, correctly rejected on non-VMB4AN
+types. Not yet sent to a real bus.
+
+---
+
 ## v0.10.1 — 09/07/2026
 
 ### Two critical bugs found on real hardware — velbus-dimmer and velbus-glass-panel

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.10.1, 19 nodes, published on npm.**
+Current state at time of writing: **v0.10.2, 19 nodes, published on npm.**
 
 ---
 
@@ -306,7 +306,7 @@ or a string before assuming the parsing logic itself is wrong.
 | `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, VMB6IN |
+| `velbus-sensor` | Velbus (inputs) | Original-series input/analogue: VMB7IN, VMB4AN (channels 1-8 alarm outputs + generic analogue reading on channels 9-12; full sensor/preset config and analog outputs on channels 13-16 remain parked), 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 |
@@ -589,6 +589,23 @@ Address assignment: allow 500ms, then rescan to confirm the new address took eff
 not the right trigger for an automatic write-back, both for the EEPROM-wear reason above
 and because it risks a feedback loop. Reads have no such constraint and are always safe.
 
+### 7.8a `VMB4AN` — three similar-sounding packets, only one has the actual value
+
+A real trap, worth remembering for any future work on this module's
+sensor channels (9-12): `0xEA` ("sensor status") sounds like it should be
+the reading, but it's operating-mode/sleep-timer/auto-send configuration
+only — no value field at all. `0xE8`/`0xE9` ("sensor settings") sounds
+promising too, but that's stored preset *configuration*, not a live
+reading. The actual value lives in `0xA9` (`COMMAND_SENSOR_RAW_DATA`,
+labelled "Transmit the sensor raw value" in the PDF) — a completely
+standalone packet with no need to cross-reference either of the other two.
+```
+body[0] = 0xA9, body[1] = channel (9-12)
+body[2] = operating mode (00=voltage, 01=current, 10=resistance, 11=period)
+body[3-5] = 24-bit raw value, MSB first
+  (period mode: 0x000000 = short-circuited, 0xFFFFFF = open-circuit)
+```
+
 ### 7.9 Thermostat commands — always to the primary address
 ```
 0xDB = comfort mode, 0xDC = day mode, 0xDD = night mode, 0xDE = safe mode

package/nodes/velbus-sensor/velbus-sensor.html

@@ -137,12 +137,24 @@
   "enabled": [1,2,3,4,5,6,7,8], "locked": [], "progDisabled": [],
   "program": "summer", "alarms": { "alarm1Active": false, "alarm2Active": false } }</pre>
 
-  <h3>Output 2 — Counter data (VMB7IN only)</h3>
+  <h3>Output 2 — Counter data (VMB7IN) / Analogue readings (VMB4AN)</h3>
   <pre>{ "type": "counter", "channel": 1, "count": 12345,
   "pulsesPerUnit": 1000, "periodMs": 3600, "overflow": false }</pre>
   <p>Engineering units: calculate in flow using pulsesPerUnit and periodMs.</p>
   <p>Power (W) = 3,600,000,000 / (periodMs × pulsesPerUnit)</p>
 
+  <p>VMB4AN sensor channels (9-12) — deliberately generic, no engineering-unit
+  conversion attempted here (mode-aware scaling, presets, and sleep-timer
+  configuration are a larger, separately-scoped piece of work — see
+  <code>coverage-roadmap.md</code>):</p>
+  <pre>{ "type": "analogue", "channel": 9, "mode": "voltage", "raw": 12345 }</pre>
+  <p><code>mode</code> is <code>"voltage"</code> (0-10V, 0.25mV/count),
+  <code>"current"</code> (4-20mA, 5µA/count), <code>"resistance"</code>
+  (PT100/PT1000/Ni1000, 0.25Ω/count), or <code>"period"</code> (0.5µs/count —
+  <code>raw</code> of <code>0</code> means short-circuited, <code>16777215</code>
+  means open-circuit). Apply the resolution yourself in the flow, e.g.
+  <code>volts = raw * 0.00025</code> for voltage mode.</p>
+
   <h3>Input commands</h3>
   <dl>
     <dt><code>{ "cmd": "get_status" }</code></dt><dd>Request module status.</dd>
@@ -150,6 +162,10 @@
     <dd>Request counter (VMB7IN). channels=bitmask of ch1-4 (default 15=all). interval=0 no change.</dd>
     <dt><code>{ "cmd": "reset_counter", "channel": 1 }</code></dt><dd>Reset pulse counter to zero.</dd>
     <dt><code>{ "cmd": "load_counter", "channel": 1, "value": 12345 }</code></dt><dd>Load counter with preset value (build 1426+).</dd>
+    <dt><code>{ "cmd": "get_analogue", "channel": 9 }</code></dt>
+    <dd>Request an analogue reading now (VMB4AN, channel 9-12). Doesn't change
+    the module's own auto-send interval configuration — it already sends
+    readings on its own schedule; this just asks for one immediately.</dd>
     <dt><code>{ "cmd": "get_name", "channel": 1 }</code></dt><dd>Request channel name from VelbusLink.</dd>
   </dl>
 </script>

package/nodes/velbus-sensor/velbus-sensor.js

@@ -172,6 +172,34 @@ module.exports = function(RED) {
           break;
         }
 
+        // ── 0xA9  Sensor raw value (VMB4AN channels 9-12 only) ────────────
+        // Confirmed from protocol_vmb4an.pdf, "Transmit the sensor raw
+        // value" — a genuinely standalone packet (COMMAND_SENSOR_RAW_DATA),
+        // not to be confused with 0xEA "sensor status" (that one carries
+        // operating mode / sleep timer / auto-send config, no actual value
+        // at all — a real trap if you assume "status" means "reading").
+        // body[0]=0xA9, body[1]=channel(9-12), body[2]=operating mode,
+        // body[3-5]=24-bit raw value (upper/high/low, MSB first).
+        // Deliberately generic per Stuart's own preference — engineering-
+        // unit conversion (voltage/current/resistance/period) is left to
+        // the flow, not attempted here. The PDF's resolution table (e.g.
+        // 0.25mV/count for voltage) is available in this node's help if
+        // conversion is ever wanted downstream.
+        case 0xA9: {
+          if (!isVMB4AN) return;
+          if (body.length < 6) return;
+
+          const channel  = body[1];
+          const modeCode = body[2] & 0x03;
+          const mode     = ['voltage', 'current', 'resistance', 'period'][modeCode];
+          const raw      = (body[3] << 16) | (body[4] << 8) | body[5];
+
+          const payload = { type: 'analogue', channel, mode, raw };
+
+          node.send([null, { payload }]);
+          break;
+        }
+
         // ── 0xF0/F1/F2  Channel name parts ───────────────────────────────
         case 0xF0:
         case 0xF1:
@@ -222,6 +250,25 @@ module.exports = function(RED) {
         return;
       }
 
+      // Request an analogue reading now — VMB4AN channels 9-12 only.
+      // DATABYTE3=0 explicitly means "don't change the auto-send interval
+      // config" per the protocol PDF — this just asks for a value without
+      // side effects on the module's existing auto-send behaviour.
+      // Priority: protocol PDF explicitly states "SID10-SID9 = 11 (lowest
+      // priority)" for this specific command — 0xFB, not the 0xF8 used by
+      // most other commands in this file. Checked directly rather than
+      // assumed, since this is the one place it genuinely differs.
+      if (cmd === 'get_analogue') {
+        if (!isVMB4AN) { node.warn('velbus-sensor: this module has no analogue sensor channels'); return; }
+        const ch = parseInt(msg.payload.channel);
+        if (!ch || ch < 9 || ch > 12) {
+          node.warn('velbus-sensor: get_analogue requires "channel": 9-12');
+          return;
+        }
+        node.bridge.send(pkt(0xFB, node.address, [0xE5, ch, 0x00]));
+        return;
+      }
+
       // Load counter — DB2=channel number (0-3), DB3=don't care, DB4-7=32-bit value
       if (cmd === 'load_counter') {
         if (!hasCounter) { node.warn('velbus-sensor: this module has no pulse counter'); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-velbus-2026",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Node-RED palette for Velbus building automation \u2014 relay, dimmer, glass panel, PIR, blind, sensor, meteo, clock nodes. Original and V2 (-20) series.",
   "keywords": [
     "node-red",