node-red-contrib-velbus-2026 0.8.1

package/nodes/velbus-button/velbus-button.html

@@ -0,0 +1,172 @@
+<script type="text/javascript">
+(function() {
+
+  const BUTTON_TYPES = {
+    0x01: { name: 'VMB8PB',    channels: 8, series: 'original' },
+    0x16: { name: 'VMB8PBU',   channels: 8, series: 'original' },
+    0x17: { name: 'VMB6PBN',   channels: 6, series: 'original' },
+    0x1C: { name: 'VMB4PB',    channels: 4, series: 'original' },
+    0x20: { name: 'VMB6PB-20', channels: 6, series: 'v2'       },
+  };
+
+  RED.nodes.registerType('velbus-button', {
+    category:  'Velbus (inputs)',
+    color:     '#3A8C8C',
+    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); } },
+      channelCount: { value: 8 },
+      moduleName:   { value: '' },
+      typeId:       { value: '' },
+    },
+    inputs:  0,
+    outputs: 1,
+    outputLabels: ['button events'],
+    icon:    'font-awesome/fa-hand-pointer-o',
+    paletteLabel: 'button',
+
+    label: function() {
+      return this.name || this.moduleName ||
+        ('BTN 0x' + (parseInt(this.address) || 0).toString(16).padStart(2, '0').toUpperCase());
+    },
+
+    oneditprepare: function() {
+      const savedAddr   = this.address;
+      const savedTypeId = this.typeId ? parseInt(this.typeId, 16) : null;
+
+      $('#node-input-typeId').prop('readonly', true).css('background', '#f0f0f0');
+
+      function populateDropdown(bridgeId) {
+        const $addr = $('#node-input-address');
+        if (!bridgeId) return;
+
+        $.getJSON('velbus/scan-results?bridge=' + bridgeId, function(results) {
+          const modules = (results && results.modules) ? results.modules : [];
+          if (!modules.length) return;
+
+          $addr.empty().append($('<option>').val('').text('— select address —'));
+
+          const btnTypeIds = Object.keys(BUTTON_TYPES).map(k => parseInt(k));
+          const btnModules = modules.filter(m => btnTypeIds.includes(parseInt(m.typeId, 16)));
+
+          if (!btnModules.length) {
+            $addr.append($('<option>').val('').text('No button modules found on bus'));
+            return;
+          }
+
+          btnModules.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);
+          });
+
+          if (savedAddr) updateHint(parseInt(savedAddr));
+        });
+      }
+
+      function updateHint(addrDec) {
+        const $opt = $('#node-input-address option[value="' + addrDec + '"]');
+        const tid  = $opt.data('typeid');
+        if (tid && BUTTON_TYPES[tid]) {
+          const t = BUTTON_TYPES[tid];
+          $('#btn-type-hint').text(t.name + ' — ' + t.channels + ' ch · ' + t.series).show();
+          $('#node-input-typeId').val('0x' + tid.toString(16).padStart(2,'0').toUpperCase());
+          const $ch = $('#node-input-channelCount');
+          if (!$ch.val() || $ch.data('auto')) $ch.val(t.channels).data('auto', true);
+        } else {
+          $('#btn-type-hint').hide();
+        }
+      }
+
+      $('#node-input-bridge').on('change', function() { populateDropdown($(this).val()); });
+      $('#node-input-address').on('change', function() { updateHint(parseInt($(this).val())); });
+      $('#node-input-channelCount').on('input', function() { $(this).data('auto', false); });
+
+      // 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;
+      const tid = $('#node-input-typeId').val();
+      this.typeId = tid || '';
+      if (tid) {
+        const t = BUTTON_TYPES[parseInt(tid, 16)];
+        if (t) this.moduleName = t.name;
+      }
+    },
+  });
+
+})();
+</script>
+
+<script type="text/html" data-template-name="velbus-button">
+  <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></label>
+    <span id="btn-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>
+  <div class="form-row">
+    <label for="node-input-channelCount"><i class="fa fa-list-ol"></i> Channels</label>
+    <input type="number" id="node-input-channelCount" min="1" max="32" style="width:80px">
+    <span style="margin-left:8px; color:#888; font-size:0.9em;">auto-filled from scan</span>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="velbus-button">
+  <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>
+    Button and input module node for Velbus push-button panels — original and V2 series.
+    For glass panel modules (VMBEL, VMBGP) with thermostat use <strong>velbus-glass-panel</strong> instead.
+  </p>
+
+  <h3>Supported modules</h3>
+  <p>VMB8PB, VMB8PBU, VMB6PBN, VMB4PB (original series) · VMB6PB-20 (V2 series).</p>
+  <p>Also suitable for glass panel sub-addresses when button events need separate wiring.</p>
+
+  <h3>Output</h3>
+  <pre>{
+  "type":        "button",
+  "on":          true,
+  "pressed":     [1, 3],
+  "released":    [],
+  "longPressed": []
+}</pre>
+  <p>
+    <code>on</code> is <code>true</code> when any channel is pressed or long-pressed,
+    <code>false</code> when only releases are present.
+    Channel numbers are 1-indexed. All three arrays are always present —
+    empty arrays when no channels in that state.
+  </p>
+</script>

package/nodes/velbus-button/velbus-button.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const { parsePkt } = require('../../lib/velbus-utils');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Button module type registry
+// ─────────────────────────────────────────────────────────────────────────────
+const BUTTON_TYPES = {
+  0x01: { name: 'VMB8PB',    channels: 8, series: 'original' },
+  0x16: { name: 'VMB8PBU',   channels: 8, series: 'original' },
+  0x17: { name: 'VMB6PBN',   channels: 6, series: 'original' },
+  0x1C: { name: 'VMB4PB',    channels: 4, series: 'original' },
+  0x20: { name: 'VMB6PB-20', channels: 6, series: 'v2'       },
+};
+
+const BUTTON_TYPE_IDS = new Set(Object.keys(BUTTON_TYPES).map(k => parseInt(k)));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Channel bitmask helper
+// ─────────────────────────────────────────────────────────────────────────────
+function bitsToChannels(byte1, byte2, byte3, byte4) {
+  const channels = [];
+  const bytes = [byte1 || 0, byte2 || 0, byte3 || 0, byte4 || 0];
+  for (let b = 0; b < 4; b++) {
+    for (let bit = 0; bit < 8; bit++) {
+      if (bytes[b] & (1 << bit)) channels.push(b * 8 + bit + 1);
+    }
+  }
+  return channels;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Node
+// ─────────────────────────────────────────────────────────────────────────────
+module.exports = function(RED) {
+
+  function VelbusButtonNode(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.channelCount = parseInt(config.channelCount) || 8;
+    node.moduleName   = config.moduleName || '';
+    node.typeId       = config.typeId ? parseInt(config.typeId) : null;
+
+    if (!node.bridge) {
+      node.status({ fill: 'red', shape: 'ring', text: 'no bridge' });
+      node.error('velbus-button: 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-button: invalid address ' + node.address);
+      return;
+    }
+
+    const _label = node.moduleName
+      ? node.moduleName + ' (0x' + node.address.toString(16).padStart(2, '0').toUpperCase() + ')'
+      : '0x' + node.address.toString(16).padStart(2, '0').toUpperCase();
+
+    function setStatus(text, fill, shape) {
+      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;
+
+      // 0x00 — button press / release / long-press
+      if (cmd === 0x00) {
+        if (body.length < 2) return;
+
+        const pressed     = bitsToChannels(body[0]);
+        const released    = bitsToChannels(body[1]);
+        const longPressed = body.length >= 3 ? bitsToChannels(body[2]) : [];
+
+        const on = pressed.length > 0 || longPressed.length > 0;
+
+        const payload = {
+          type:        'button',
+          on,
+          pressed,
+          released,
+          longPressed,
+        };
+
+        setStatus(
+          pressed.length     ? 'pressed ch' + pressed.join(',')
+          : longPressed.length ? 'long ch' + longPressed.join(',')
+          : 'released ch' + released.join(',')
+        );
+
+        node.send({ payload });
+      }
+    }
+
+    node.bridge.register(node.address, onPacket);
+
+    // ── Cleanup ──────────────────────────────────────────────────────────
+
+    node.on('close', function() {
+      node.bridge.deregister(node.address, onPacket);
+    });
+
+    setStatus('ready', 'grey', 'dot');
+  }
+
+  RED.nodes.registerType('velbus-button', VelbusButtonNode);
+};

package/nodes/velbus-clock/velbus-clock.html

@@ -0,0 +1,198 @@
+<script type="text/javascript">
+(function() {
+
+  RED.nodes.registerType('velbus-clock', {
+    category:  'Velbus (outputs)',
+    color:     '#4A90D9',
+    defaults: {
+      name:            { value: '' },
+      bridge:          { value: '', type: 'velbus-bridge', required: true },
+      autoBroadcast:   { value: false },
+      intervalMinutes: { value: 60, validate: function(v) { return parseInt(v) > 0; } },
+      includeDate:     { value: true },
+      includeDst:      { value: true },
+    },
+    inputs:  1,
+    outputs: 1,
+    outputLabels: ['broadcast sent'],
+    icon:    'font-awesome/fa-clock-o',
+    paletteLabel: 'clock',
+
+    label: function() {
+      return this.name || (this.autoBroadcast
+        ? 'clock (auto, ' + this.intervalMinutes + 'm)'
+        : 'clock (manual)');
+    },
+
+    oneditprepare: function() {
+      function toggleIntervalRow() {
+        $('#clock-interval-row').toggle($('#node-input-autoBroadcast').is(':checked'));
+      }
+      $('#node-input-autoBroadcast').on('change', toggleIntervalRow);
+      toggleIntervalRow();
+    },
+  });
+
+})();
+</script>
+
+<script type="text/html" data-template-name="velbus-clock">
+  <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-autoBroadcast"><i class="fa fa-refresh"></i> Auto-broadcast</label>
+    <input type="checkbox" id="node-input-autoBroadcast" style="width:auto; vertical-align:middle;">
+    <span style="color:#888; font-size:0.9em;">send automatically on an interval</span>
+  </div>
+  <div class="form-row" id="clock-interval-row">
+    <label for="node-input-intervalMinutes"><i class="fa fa-hourglass-half"></i> Interval (min)</label>
+    <input type="number" id="node-input-intervalMinutes" min="1" style="width:80px">
+  </div>
+  <div class="form-row">
+    <label for="node-input-includeDate"><i class="fa fa-calendar"></i> Include date</label>
+    <input type="checkbox" id="node-input-includeDate" style="width:auto; vertical-align:middle;">
+    <span style="color:#888; font-size:0.9em;">also send 0xB7 (day/month/year)</span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-includeDst"><i class="fa fa-sun-o"></i> Include DST flag</label>
+    <input type="checkbox" id="node-input-includeDst" style="width:auto; vertical-align:middle;">
+    <span style="color:#888; font-size:0.9em;">also send 0xAF (daylight saving on/off)</span>
+  </div>
+  <div class="form-tips" style="margin-top:8px">
+    Broadcasts to bus address <code>0x00</code> — every RTC-equipped module on
+    the bus receives this and updates its own clock. Uses the Node-RED host's
+    own system clock and timezone, so make sure that's set correctly
+    (e.g. <code>timedatectl set-timezone Europe/London</code>).
+  </div>
+</script>
+
+<script type="text/html" data-help-name="velbus-clock">
+  <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>
+    Broadcasts system time, date, and daylight-saving state to the bus broadcast
+    address <code>0x00</code>. Every RTC-equipped Velbus module (relays, dimmers,
+    glass panels with clock features, etc.) receives and updates its own real-time
+    clock from this — this is what a physical Signum master clock module normally
+    does. Use this node if you don't have one fitted, or want Node-RED to be the
+    time source instead.
+  </p>
+
+  <h3>Commands sent</h3>
+  <ul>
+    <li><code>0xD8</code> Set real time clock — day of week, hour, minute</li>
+    <li><code>0xB7</code> Set date — day, month, year (only if "Include date" is on)</li>
+    <li><code>0xAF</code> Set daylight savings — on/off flag (only if "Include DST flag" is on)</li>
+  </ul>
+  <p>
+    All three are sent to address <code>0x00</code> at low priority, matching every
+    module protocol PDF checked. <b>Never</b> configure <code>0x00</code> as a real
+    module's own address — it is reserved for bus-wide broadcast.
+  </p>
+
+  <h3>DST detection</h3>
+  <p>
+    The daylight-saving flag is worked out from the Node-RED host's own configured
+    timezone (comparing the current UTC offset against the year's Jan 1 / Jul 1
+    offsets) — correct for UK/EU/US-style single-transition DST, but only as
+    accurate as the host's own clock and <code>TZ</code> setting. Override it
+    manually with <code>msg.payload.dst</code> (see below) if needed.
+  </p>
+
+  <h3>Input — Commands</h3>
+  <pre>
+{}                                              // bare inject — broadcast time (+date/DST per config), using now
+{ "cmd": "broadcast" }
+{ "cmd": "broadcast", "date": "2026-07-06T14:32:00" }   // override the time sent (testing)
+{ "cmd": "broadcast", "dst": true }             // override the DST flag sent
+{ "cmd": "broadcast_time" }                     // 0xD8 only, ignores config toggles
+{ "cmd": "broadcast_date" }                     // 0xB7 only
+{ "cmd": "broadcast_dst" }                      // 0xAF only, auto-detected
+{ "cmd": "broadcast_dst", "dst": false }        // 0xAF only, forced value
+{ "cmd": "set_alarm", "alarm": 1, "wakeHour": 7, "wakeMinute": 15, "bedHour": 22, "bedMinute": 30 }
+{ "cmd": "set_alarm", "alarm": 2, "wakeHour": 6, "wakeMinute": 45, "bedHour": 23, "bedMinute": 0, "address": "0x30" }
+{ "cmd": "set_alarm", "alarm": 1, "enabled": false }   // disable, address omitted = global
+  </pre>
+
+  <h3>Output</h3>
+  <pre>
+{
+  "topic":     "clock_broadcast",
+  "dayOfWeek": 1,              // 0=Monday...6=Sunday (Velbus convention, not JS)
+  "hours":     14,
+  "minutes":   32,
+  "date":      { "day": 6, "month": 7, "year": 2026 },  // null if date not included
+  "dst":       false,           // null if DST flag not included
+  "timestamp": 1783348320000
+}
+  </pre>
+  <p>
+    Only emitted for <code>"cmd": "broadcast"</code> / bare inject. The single-purpose
+    commands (<code>broadcast_time</code> etc.) update the status text but don't emit
+    an output message.
+  </p>
+
+  <h3>Auto-broadcast</h3>
+  <p>
+    When enabled, sends automatically on the configured interval (first send
+    5 seconds after deploy, to give the bridge time to connect). Manual input
+    commands still work alongside this.
+  </p>
+
+  <h3>set_alarm — global or local clock alarm (0xC3)</h3>
+  <p>
+    Sets a wake/sleep alarm (alarm 1 or 2). Omit <code>address</code> for a
+    <b>global</b> alarm — every V2 module on the bus receives the same
+    wake/sleep schedule. Provide <code>address</code> (hex string or decimal)
+    for a <b>local</b> alarm on that one module only. The packet body is
+    identical either way — only the destination address differs, per the
+    protocol's own design.
+  </p>
+  <p>
+    <b>Note on scope:</b> this is the one command on this node that breaks
+    from the palette's usual "one node = one physical module" pattern — it
+    accepts a per-message address override instead of a fixed node config.
+    That's deliberate: 0xC3 is a shared V2 system command any module type can
+    receive (confirmed identical across relay-20, dimmer-20, and glass-panel-20
+    protocol PDFs), not a feature specific to one module type the way an RGBW
+    setting or thermostat setpoint is — so it lives here rather than being
+    duplicated across every V2 node type.
+  </p>
+  <pre>
+{ "cmd": "set_alarm", "alarm": 1, "wakeHour": 7, "wakeMinute": 15, "bedHour": 22, "bedMinute": 30 }
+// → global: every module gets this schedule
+
+{ "cmd": "set_alarm", "alarm": 2, "wakeHour": 6, "wakeMinute": 45, "bedHour": 23, "bedMinute": 0, "address": "0x30" }
+// → local: only module 0x30 gets this schedule
+
+{ "cmd": "set_alarm", "alarm": 1, "enabled": false }
+// → disable alarm 1 (global) — wakeHour/wakeMinute/bedHour/bedMinute default to 0 if omitted
+  </pre>
+  <p>Output:</p>
+  <pre>
+{
+  "topic":      "alarm_set",
+  "target":     "global",   // or "0x30" etc. for a local alarm
+  "alarm":      1,
+  "wakeHour":   7,
+  "wakeMinute": 15,
+  "bedHour":    22,
+  "bedMinute":  30,
+  "enabled":    true
+}
+  </pre>
+  <p><code>enabled</code> defaults to <code>true</code> if omitted. An invalid
+  <code>address</code> falls back to a global broadcast with a warning, rather
+  than silently failing.</p>
+</script>