node-red-contrib-velbus-2026 0.8.1

package/lib/sensor-types.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sensor/input module type registry — original series
+// Covered by velbus-sensor node.
+//
+// VMB7IN (0x22): 8 digital inputs + 4 pulse counters (channels 1-4)
+//   lockStyle: 'bitmask' — DB2 of lock/unlock/enable/disable is channel bitmask
+//   nameStyle: 'bitmask' — DB2 of 0xF0/F1/F2 is channel bitmask
+//   hasCounter: true — 0xBE pulse counter on channels 1-4
+//
+// VMB4AN (0x32): 16 logical channels across 3 functional groups
+//   GROUP 1: alarm outputs (channels 1-8)  — 0x00 press/release
+//   GROUP 2: sensor inputs (channels 9-12) — analogue, 4 presets
+//   GROUP 3: analogue outputs (ch 13-16)   — 0-10V, original dimmer protocol
+//   lockStyle: 'bitmask'
+//   nameStyle: 'bitmask'
+//   hasCounter: false
+//   hasAnalogue: true
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SENSOR_TYPES = {
+  0x22: {
+    name:         'VMB7IN',
+    channels:     8,
+    counterCh:    [1, 2, 3, 4],  // channels with pulse counter capability
+    hasCounter:   true,
+    hasAnalogue:  false,
+    lockStyle:    'bitmask',
+    nameStyle:    'bitmask',
+    minMapVer:    null,
+    series:       'original',
+  },
+  0x32: {
+    name:         'VMB4AN',
+    channels:     8,    // alarm output channels (group 1, produce 0x00 events)
+    counterCh:    [],
+    hasCounter:   false,
+    hasAnalogue:  true, // groups 2 and 3 — handled separately
+    lockStyle:    'bitmask',
+    nameStyle:    'bitmask',
+    minMapVer:    null,
+    series:       'original',
+  },
+};
+
+const SENSOR_TYPE_IDS = new Set(Object.keys(SENSOR_TYPES).map(k => parseInt(k)));
+
+module.exports = { SENSOR_TYPES, SENSOR_TYPE_IDS };

package/lib/velbus-utils.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * velbus-utils.js
+ * Shared Velbus packet framing, checksum, and parse/build utilities.
+ * Used by velbus-bridge (splitter) and velbus-relay (encoder/decoder).
+ */
+
+/**
+ * Compute Velbus packet checksum.
+ * Sum all bytes mod 256, return two's complement.
+ */
+function chk(bytes) {
+  let s = 0;
+  for (const x of bytes) s = (s + x) & 0xFF;
+  return ((~s + 1) & 0xFF);
+}
+
+/**
+ * Build a Velbus packet.
+ * @param {number} pri - Priority byte (0xF8 commands, 0xFB status/RTR)
+ * @param {number} addr - Module address (0x01–0xFE)
+ * @param {number[]} body - Body bytes array
+ * @returns {Buffer}
+ */
+function pkt(pri, addr, body) {
+  const dlc = body.length & 0x0F;
+  const h = [0x0F, pri, addr, dlc, ...body];
+  return Buffer.from([...h, chk(h), 0x04]);
+}
+
+/**
+ * Build an RTR (request-to-respond / bus scan) packet for a given address.
+ * RTR packets have DLC=0x40 and no body.
+ */
+function rtrPkt(addr) {
+  const h = [0x0F, 0xFB, addr, 0x40];
+  return Buffer.from([...h, chk(h), 0x04]);
+}
+
+/**
+ * Parse a raw Velbus packet buffer.
+ * @param {Buffer} raw
+ * @returns {{ pri, addr, rtr, body, cmd } | null}
+ */
+function parsePkt(raw) {
+  if (!Buffer.isBuffer(raw) || raw.length < 6) return null;
+  if (raw[0] !== 0x0F || raw[raw.length - 1] !== 0x04) return null;
+  const pri = raw[1], addr = raw[2], dlc = raw[3];
+  const rtr = (dlc & 0x40) !== 0;
+  const bl = rtr ? 0 : (dlc & 0x0F);
+  if (raw.length < 4 + bl + 2) return null;
+  const body = Array.from(raw.slice(4, 4 + bl));
+  return { pri, addr, rtr, body, cmd: body.length > 0 ? body[0] : null };
+}
+
+/**
+ * Split a raw TCP stream buffer into complete Velbus packets.
+ * Returns { packets: Buffer[], remainder: Buffer }
+ * Caller is responsible for persisting remainder across TCP data events.
+ */
+function splitPackets(buf) {
+  const packets = [];
+  let i = 0;
+  while (i < buf.length) {
+    if (buf[i] !== 0x0F) { i++; continue; }
+    if (i + 3 >= buf.length) break;
+    const dl = buf[i + 3];
+    const rtr = (dl & 0x40) !== 0;
+    const bl = rtr ? 0 : (dl & 0x0F);
+    const pl = 4 + bl + 2;
+    if (i + pl > buf.length) break;
+    const p = buf.slice(i, i + pl);
+    if (p[p.length - 1] === 0x04) packets.push(Buffer.from(p));
+    i += pl;
+  }
+  return { packets, remainder: buf.slice(i) };
+}
+
+module.exports = { chk, pkt, rtrPkt, parsePkt, splitPackets };

package/nodes/velbus-blind/velbus-blind.html

@@ -0,0 +1,165 @@
+<script type="text/javascript">
+(function() {
+
+  const BLIND_TYPES = {
+    0x03: { name: 'VMB1BL', channels: 1 },
+    0x09: { name: 'VMB2BL', channels: 2 },
+  };
+
+  RED.nodes.registerType('velbus-blind', {
+    category:  'Velbus (outputs)',
+    color:     '#4A90D9',
+    defaults: {
+      name:       { value: '' },
+      bridge:     { value: '', type: 'velbus-bridge', required: true },
+      address:    { value: '', required: true, validate: function(v) { return /^(0x)?[0-9a-fA-F]{1,2}$/.test(v); } },
+      channel:    { value: 1, required: true },
+      moduleName: { value: '' },
+      typeId:     { value: '' },
+    },
+    inputs:  1,
+    outputs: 1,
+    outputLabels: ['blind events / status'],
+    icon:    'font-awesome/fa-arrows-v',
+    paletteLabel: 'blind',
+
+    label: function() {
+      const t = this.typeId ? BLIND_TYPES[parseInt(this.typeId, 16)] : null;
+      const n = this.name || this.moduleName || (t ? t.name : 'blind');
+      return n + ' ch' + this.channel + ' 0x' +
+        (parseInt(this.address) || 0).toString(16).padStart(2,'0').toUpperCase();
+    },
+
+    oneditprepare: function() {
+      const savedAddr = this.address;
+      const savedCh   = this.channel;
+      $('#node-input-typeId').prop('readonly', true).css('background', '#f0f0f0');
+
+      function populateDropdown(bridgeId) {
+        if (!bridgeId) return;
+        $.getJSON('velbus/scan-results?bridge=' + bridgeId, function(results) {
+          const modules = (results && results.modules) ? results.modules : [];
+          const $addr = $('#node-input-address');
+          $addr.empty().append($('<option>').val('').text('— select address —'));
+
+          const typeIds = Object.keys(BLIND_TYPES).map(k => parseInt(k));
+          const filtered = modules.filter(m => typeIds.includes(parseInt(m.typeId, 16)));
+
+          if (!filtered.length) {
+            $addr.append($('<option>').val('').text('No blind modules found on bus'));
+            return;
+          }
+          filtered.forEach(function(m) {
+            const tid   = parseInt(m.typeId, 16);
+            const label = m.address + ' — ' + m.module;
+            const $opt  = $('<option>').val(m.addressDec).text(label).data('typeid', tid);
+            if (m.addressDec === parseInt(savedAddr)) $opt.attr('selected', true);
+            $addr.append($opt);
+          });
+        });
+      }
+
+      function updateChannelSelect(typeId) {
+        const t = BLIND_TYPES[typeId];
+        const $ch = $('#node-input-channel');
+        $ch.empty();
+        if (t) {
+          for (let i = 1; i <= t.channels; i++) {
+            $ch.append($('<option>').val(i).text('Channel ' + i));
+          }
+          $ch.val(savedCh || 1);
+          $('#node-input-typeId').val('0x' + typeId.toString(16).padStart(2,'0').toUpperCase());
+          $('#blind-type-hint').text(t.name + ' · ' + t.channels + ' channel' + (t.channels > 1 ? 's' : '')).show();
+        }
+      }
+
+      $('#node-input-bridge').on('change', function() { populateDropdown($(this).val()); });
+      $('#node-input-address').on('change', function() {
+        const tid = $(this).find(':selected').data('typeid');
+        if (tid) updateChannelSelect(tid);
+      });
+      // Deferred load — TypedInput sets value async after oneditprepare
+
+      $('#node-input-bridge').trigger('change');
+
+      setTimeout(function() { $('#node-input-bridge').trigger('change'); }, 150);
+    },
+
+    oneditsave: function() {
+      this.address = parseInt($('#node-input-address').val()) || 0;
+      this.channel = parseInt($('#node-input-channel').val()) || 1;
+      const tid = $('#node-input-typeId').val();
+      this.typeId = tid || '';
+      if (tid) {
+        const t = BLIND_TYPES[parseInt(tid, 16)];
+        if (t) this.moduleName = t.name;
+      }
+    },
+  });
+
+})();
+</script>
+
+<script type="text/html" data-template-name="velbus-blind">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Optional label">
+  </div>
+  <div class="form-row">
+    <label for="node-input-bridge"><i class="fa fa-plug"></i> Bridge</label>
+    <input type="text" id="node-input-bridge">
+  </div>
+  <div class="form-row">
+    <label for="node-input-address"><i class="fa fa-map-marker"></i> Address</label>
+    <select id="node-input-address" style="width:70%">
+      <option value="">— select bridge first —</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-channel"><i class="fa fa-arrows-v"></i> Channel</label>
+    <select id="node-input-channel" style="width:70%">
+      <option value="1">Channel 1</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label></label>
+    <span id="blind-type-hint" style="color:#888; font-size:0.9em; display:none;"></span>
+  </div>
+  <div class="form-row" style="display:none">
+    <input type="text" id="node-input-typeId">
+    <input type="text" id="node-input-moduleName">
+  </div>
+</script>
+
+<script type="text/html" data-help-name="velbus-blind">
+    <p style="background:#fff3cd; border-left:4px solid #ffc107; padding:8px 12px; margin-bottom:12px; font-size:0.85em;">
+    <strong>&#9888; Testing status:</strong> This node was generated with Claude.ai and is in
+    need of extensive field testing before being deployed into a commercial project.
+    It is presented "as is" &mdash; any use beyond testing is entirely at your own risk and liability.
+    Constructive feedback is welcomed, accompanied by as many examples and debug captures as possible.
+    <a href="https://github.com/MDAR/node-red-contrib-velbus-2026/issues" target="_blank">File an issue on GitHub</a>.
+    </p>
+  <p>Blind/shutter motor controller for original series — VMB1BL (0x03), VMB2BL (0x09).</p>
+  <p>For VMB1BLS/VMB2BLE with position control use <strong>velbus-blind-s</strong>.</p>
+
+  <h3>Output — Blind events and status</h3>
+  <p>Relay/button event (0x00):</p>
+  <pre>{ "type": "blind_event", "channel": 1,
+  "events": [{ "channel": 1, "event": "relay_up_on" }] }</pre>
+  <p>Event types: relay_up_on, relay_up_off, relay_down_on, relay_down_off,
+  btn_up_pressed, btn_up_released, btn_up_long, btn_down_pressed, btn_down_released, btn_down_long.</p>
+
+  <p>Blind status (0xEC):</p>
+  <pre>{ "type": "blind_status", "channel": 1, "on": true, "status": "up",
+  "timeoutSetting": "1min", "delayRemaining": 42,
+  "led": { "upOn": true, "downOn": false, ... } }</pre>
+
+  <h3>Input commands</h3>
+  <dl>
+    <dt><code>{ "cmd": "stop" }</code></dt><dd>Stop blind movement.</dd>
+    <dt><code>{ "cmd": "up", "timeout": 0 }</code></dt><dd>Move up. timeout=0 uses dip switch setting. timeout=0xFFFFFF = permanent.</dd>
+    <dt><code>{ "cmd": "down", "timeout": 0 }</code></dt><dd>Move down.</dd>
+    <dt><code>{ "cmd": "get_status" }</code></dt><dd>Request blind status.</dd>
+    <dt><code>{ "cmd": "get_name" }</code></dt><dd>Request blind name from VelbusLink.</dd>
+  </dl>
+</script>

package/nodes/velbus-blind/velbus-blind.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const { pkt, parsePkt } = require('../../lib/velbus-utils');
+const { BLIND_TYPES, BLIND_TYPE_IDS } = require('../../lib/blind-types');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+// VMB1BL: 0x00 bitmask uses bits 0-1 for relays, bits 4-5 for local buttons
+// VMB2BL: 0x00 bitmask bits 0-1=ch1 relays, 2-3=ch2 relays,
+//          4-5=ch1 local buttons, 6-7=ch2 local buttons
+function decodeBlindEvent(pressedByte, releasedByte, longByte, typeDesc) {
+  const events = [];
+  const masks = typeDesc.channelMasks;
+
+  for (const [chStr, mask] of Object.entries(masks)) {
+    const ch = parseInt(chStr);
+    const upBit   = mask & 0x01 ? 0x01 : (mask >> 2) & 0x01 ? 0x04 : 0;
+    const downBit = mask & 0x02 ? 0x02 : (mask >> 2) & 0x02 ? 0x08 : 0;
+
+    // Relay state changes
+    if (pressedByte & upBit)    events.push({ channel: ch, event: 'relay_up_on' });
+    if (releasedByte & upBit)   events.push({ channel: ch, event: 'relay_up_off' });
+    if (pressedByte & downBit)  events.push({ channel: ch, event: 'relay_down_on' });
+    if (releasedByte & downBit) events.push({ channel: ch, event: 'relay_down_off' });
+  }
+
+  // Local button events (if module has them)
+  if (typeDesc.hasLocalButtons) {
+    // VMB1BL: up=bit4, down=bit5
+    // VMB2BL: ch1 up=bit4, ch1 down=bit5, ch2 up=bit6, ch2 down=bit7
+    const btnBases = typeDesc.channels === 1
+      ? [{ ch: 1, upBit: 0x10, downBit: 0x20 }]
+      : [{ ch: 1, upBit: 0x10, downBit: 0x20 }, { ch: 2, upBit: 0x40, downBit: 0x80 }];
+
+    for (const { ch, upBit: ub, downBit: db } of btnBases) {
+      if (pressedByte & ub)  events.push({ channel: ch, event: 'btn_up_pressed' });
+      if (releasedByte & ub) events.push({ channel: ch, event: 'btn_up_released' });
+      if (longByte & ub)     events.push({ channel: ch, event: 'btn_up_long' });
+      if (pressedByte & db)  events.push({ channel: ch, event: 'btn_down_pressed' });
+      if (releasedByte & db) events.push({ channel: ch, event: 'btn_down_released' });
+      if (longByte & db)     events.push({ channel: ch, event: 'btn_down_long' });
+    }
+  }
+
+  return events;
+}
+
+const TIMEOUT_LABELS = { 0: '15s', 1: '30s', 2: '1min', 3: '2min' };
+const BLIND_STATUS   = { 0: 'off', 1: 'up', 2: 'down' };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Node
+// ─────────────────────────────────────────────────────────────────────────────
+
+module.exports = function(RED) {
+
+  function VelbusBlindNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.bridge     = RED.nodes.getNode(config.bridge);
+    node.address    = typeof config.address === 'number'
+      ? config.address  // legacy saves stored decimal numbers
+      : (parseInt(config.address, 16) || 0);  // editor stores hex strings
+    node.moduleName = config.moduleName || '';
+    node.typeId     = config.typeId ? parseInt(config.typeId) : null;
+    node.channel    = parseInt(config.channel) || 1;
+
+    if (!node.bridge) {
+      node.status({ fill: 'red', shape: 'ring', text: 'no bridge' });
+      node.error('velbus-blind: no bridge configured');
+      return;
+    }
+    if (!node.address || node.address < 1 || node.address > 254) {
+      node.status({ fill: 'red', shape: 'ring', text: 'invalid address' });
+      node.error('velbus-blind: invalid address ' + node.address);
+      return;
+    }
+
+    const typeDesc = node.typeId !== null ? (BLIND_TYPES[node.typeId] || null) : null;
+    const chMask   = typeDesc ? (typeDesc.channelMasks[node.channel] || 0x03) : 0x03;
+
+    const _addrHex = '0x' + node.address.toString(16).padStart(2, '0').toUpperCase();
+    function setStatus(text, fill, shape) {
+      const label = node.moduleName
+        ? node.moduleName + ' ch' + node.channel + ' (' + _addrHex + ')'
+        : _addrHex + ' ch' + node.channel;
+      node.status({ fill: fill || 'green', shape: shape || 'dot', text: label + ' ' + text });
+    }
+
+    // ── Packet handler ────────────────────────────────────────────────────
+
+    function onPacket(raw) {
+      const p = parsePkt(raw);
+      if (!p || p.rtr) return;
+      if (p.addr !== node.address) return;
+
+      const { cmd, body } = p;
+
+      switch (cmd) {
+
+        // ── 0x00  Relay events and local button events ────────────────────
+        case 0x00: {
+          if (body.length < 4) return;
+          // body[0]=cmd, body[1]=pressed, body[2]=released, body[3]=longPressed
+          if (!typeDesc) return;
+          const events = decodeBlindEvent(body[1], body[2], body[3], typeDesc);
+          if (!events.length) return;
+
+          // Filter to events relevant to this node's channel
+          const myEvents = events.filter(e => e.channel === node.channel);
+          if (!myEvents.length) return;
+
+          // Determine overall motion state from relay events
+          const relayOn  = myEvents.filter(e => e.event === 'relay_up_on' || e.event === 'relay_down_on');
+          const relayOff = myEvents.filter(e => e.event === 'relay_up_off' || e.event === 'relay_down_off');
+          const moving   = relayOn.some(e => e.event === 'relay_up_on') ? 'up'
+                         : relayOn.some(e => e.event === 'relay_down_on') ? 'down'
+                         : null;
+          if (moving) setStatus(moving);
+          else if (relayOff.length) setStatus('stopped');
+
+          const payload = {
+            type:   'blind_event',
+            channel: node.channel,
+            events: myEvents,
+          };
+          node.send([{ payload }]);
+          break;
+        }
+
+        // ── 0xEC  Blind status ────────────────────────────────────────────
+        case 0xEC: {
+          if (body.length < 8) return;
+          // body[0]=0xEC, body[1]=channel mask, body[2]=timeout setting,
+          // body[3]=blind status, body[4]=LED status,
+          // body[5-7]=24-bit current delay time remaining
+          const statusMask = body[1];
+
+          // Only process if this packet is for our channel
+          if (statusMask !== chMask) return;
+
+          const timeoutSetting = TIMEOUT_LABELS[body[2]] || body[2] + 's';
+          const blindStatus    = BLIND_STATUS[body[3]] || 'unknown';
+          const ledByte        = body[4];
+          const delayRemaining = (body[5] << 16) | (body[6] << 8) | body[7];
+
+          const ledStatus = {
+            downOn:        !!(ledByte & 0x80),
+            downSlowBlink: !!(ledByte & 0x40),
+            downFastBlink: !!(ledByte & 0x20),
+            downVFastBlink:!!(ledByte & 0x10),
+            upOn:          !!(ledByte & 0x08),
+            upSlowBlink:   !!(ledByte & 0x04),
+            upFastBlink:   !!(ledByte & 0x02),
+            upVFastBlink:  !!(ledByte & 0x01),
+          };
+
+          const on = blindStatus !== 'off';
+          setStatus(blindStatus);
+
+          const payload = {
+            type:            'blind_status',
+            channel:         node.channel,
+            on,
+            status:          blindStatus,
+            timeoutSetting,
+            delayRemaining,
+            led:             ledStatus,
+          };
+          node.send([{ payload }]);
+          break;
+        }
+
+        // ── 0xF0/F1/F2  Blind name parts ─────────────────────────────────
+        case 0xF0:
+        case 0xF1:
+        case 0xF2: {
+          // body[0]=cmd, body[1]=channel mask, body[2..]=chars
+          if (body[1] !== chMask) return;
+          let text = '';
+          for (let i = 2; i < body.length; i++) {
+            if (body[i] === 0 || body[i] === 0xFF) break;
+            text += String.fromCharCode(body[i]);
+          }
+          if (text && cmd === 0xF0) node.moduleName = text;
+          break;
+        }
+
+        default:
+          break;
+      }
+    }
+
+    node.bridge.register(node.address, onPacket);
+
+    // ── Input commands ────────────────────────────────────────────────────
+
+    node.on('input', function(msg) {
+      const cmd = msg.payload && msg.payload.cmd;
+      if (!cmd) return;
+
+      if (cmd === 'get_status') {
+        node.bridge.send(pkt(0xFB, node.address, [0xFA, chMask]));
+        return;
+      }
+
+      if (cmd === 'stop') {
+        node.bridge.send(pkt(0xF8, node.address, [0x04, chMask]));
+        return;
+      }
+
+      if (cmd === 'up') {
+        const timeout = parseInt(msg.payload.timeout) || 0;
+        const hi = (timeout >> 16) & 0xFF;
+        const mid = (timeout >> 8) & 0xFF;
+        const lo = timeout & 0xFF;
+        node.bridge.send(pkt(0xF8, node.address, [0x05, chMask, hi, mid, lo]));
+        return;
+      }
+
+      if (cmd === 'down') {
+        const timeout = parseInt(msg.payload.timeout) || 0;
+        const hi = (timeout >> 16) & 0xFF;
+        const mid = (timeout >> 8) & 0xFF;
+        const lo = timeout & 0xFF;
+        node.bridge.send(pkt(0xF8, node.address, [0x06, chMask, hi, mid, lo]));
+        return;
+      }
+
+      if (cmd === 'get_name') {
+        node.bridge.send(pkt(0xF8, node.address, [0xEF, chMask]));
+        return;
+      }
+
+      node.warn('velbus-blind: unknown cmd: ' + cmd);
+    });
+
+    // ── Cleanup ───────────────────────────────────────────────────────────
+
+    node.on('close', function() {
+      node.bridge.deregister(node.address, onPacket);
+    });
+
+    setStatus('ready', 'grey', 'dot');
+  }
+
+  RED.nodes.registerType('velbus-blind', VelbusBlindNode);
+};