node-red-contrib-velbus-2026 0.8.1

package/nodes/velbus-clock/velbus-clock.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const { pkt } = require('../../lib/velbus-utils');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Velbus clock broadcast node
+//
+// Sends system time (0xD8), date (0xB7), daylight-saving flag (0xAF), and
+// wake/sleep clock alarms (0xC3) to the bus. Time/date/DST are broadcast-only
+// (address 0x00) — every RTC-equipped module receives and updates its own
+// clock from these. This is what a physical Signum master clock module
+// normally does; this node lets Node-RED (or the host it runs on) act as
+// that time source instead, or as a backup if no Signum clock is fitted.
+//
+// All commands confirmed against protocol_vmb4ryld_20_vmb4ryno_20_vmb1rys_20.pdf
+// (ed.3), and cross-checked identical in protocol_vmb8dc_20.pdf and
+// protocol_vmbgp1_20_vmbgp2_20_vmbgp4_20.pdf — this is a shared V2-only
+// "system clock" command block, confirmed absent entirely from the
+// original-series protocol PDFs. Every V2 module type implements it
+// identically; it is not tied to any one module's semantics.
+//
+//   0xD8 Set real time clock   — DLC=4, body=[0xD8, dayOfWeek, hours, minutes]
+//                                 broadcast (0x00) ONLY — no local variant exists.
+//   0xB7 Set date              — DLC=5, body=[0xB7, day, month, yearHi, yearLo]
+//                                 broadcast (0x00) ONLY — no local variant exists.
+//   0xAF Set daylight savings  — DLC=2, body=[0xAF, 0|1]
+//                                 broadcast (0x00) ONLY — no local variant exists.
+//   0xC3 Set clock alarm       — DLC=7, body=[0xC3, alarm(1|2), wakeHour,
+//                                 wakeMinute, bedHour, bedMinute, enable(0|1)]
+//                                 IDENTICAL body whether "global" (address
+//                                 0x00, every module gets the same alarm) or
+//                                 "local" (a specific module address, that
+//                                 module only) — the protocol PDF literally
+//                                 defines these as two address variants of
+//                                 the same command, not two different ones.
+//
+// dayOfWeek: 0=Monday...6=Sunday (NOT JS Date's 0=Sunday...6=Saturday).
+// 0x00 is broadcast-only — never assign it as a real module's own address.
+//
+// DELIBERATE EXCEPTION to this palette's usual "one node = one physical
+// module, fixed configured address" pattern: set_alarm accepts an optional
+// per-message address override (msg.payload.address). This is intentional,
+// not an oversight — 0xC3 is a bus-wide system command any V2 module can
+// receive, not a per-module-type feature like an RGBW device-type setting
+// or a thermostat setpoint. Putting "local alarm" support on every relevant
+// node type instead (velbus-relay-20, velbus-dimmer-20, velbus-glass-panel,
+// etc.) would mean duplicating an identical handler six times over for a
+// command that is, by the protocol's own design, address-scoped rather than
+// module-type-scoped. If this turns out to want per-module config instead
+// (e.g. a dedicated address field with scan-dropdown support, matching every
+// other node), that's a reasonable direction to revisit — this was a
+// judgement call, not a settled architecture decision.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BROADCAST_ADDR = 0x00;
+
+function velbusDow(jsDay) {
+  // JS Date#getDay(): 0=Sunday...6=Saturday. Velbus: 0=Monday...6=Sunday.
+  return (jsDay + 6) % 7;
+}
+
+// Best-effort DST detection from the host's own configured timezone.
+// Standard trick: compare the current UTC offset against the year's two
+// solstice-adjacent offsets (Jan 1 / Jul 1). Correct for any timezone that
+// observes DST with a single annual transition (UK/EU/US style). Assumes
+// the host machine's TZ is set correctly (e.g. Europe/London) — if the
+// Node-RED host's clock/timezone is wrong, this will be wrong too.
+function isDstActive(d) {
+  const jan = new Date(d.getFullYear(), 0, 1);
+  const jul = new Date(d.getFullYear(), 6, 1);
+  const stdOffset = Math.max(jan.getTimezoneOffset(), jul.getTimezoneOffset());
+  return d.getTimezoneOffset() < stdOffset;
+}
+
+function clampInt(v, min, max, fallback) {
+  const n = parseInt(v);
+  if (isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+module.exports = function(RED) {
+
+  function VelbusClockNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.bridge         = RED.nodes.getNode(config.bridge);
+    node.autoBroadcast   = !!config.autoBroadcast;
+    node.intervalMinutes = parseInt(config.intervalMinutes) || 60;
+    node.includeDate     = config.includeDate !== false;
+    node.includeDst      = config.includeDst !== false;
+
+    if (!node.bridge) {
+      node.status({ fill: 'red', shape: 'ring', text: 'no bridge' });
+      node.error('velbus-clock: no bridge configured');
+      return;
+    }
+
+    let _intervalTimer = null;
+    let _startupTimer  = null;
+
+    function setStatus(text, fill, shape) {
+      node.status({ fill: fill || 'green', shape: shape || 'dot', text });
+    }
+
+    // ── Packet senders ────────────────────────────────────────────────────
+
+    function sendTime(d) {
+      node.bridge.send(pkt(0xFB, BROADCAST_ADDR, [0xD8, velbusDow(d.getDay()), d.getHours(), d.getMinutes()]));
+    }
+
+    function sendDate(d) {
+      const year = d.getFullYear();
+      node.bridge.send(pkt(0xFB, BROADCAST_ADDR, [0xB7, d.getDate(), d.getMonth() + 1, (year >> 8) & 0xFF, year & 0xFF]));
+    }
+
+    function sendDst(active) {
+      node.bridge.send(pkt(0xFB, BROADCAST_ADDR, [0xAF, active ? 1 : 0]));
+    }
+
+    function sendAlarm(targetAddr, alarmNum, wakeHour, wakeMinute, bedHour, bedMinute, enabled) {
+      node.bridge.send(pkt(0xFB, targetAddr,
+        [0xC3, alarmNum, wakeHour, wakeMinute, bedHour, bedMinute, enabled ? 1 : 0]));
+    }
+
+    // Resolves msg.payload.address to a target address for set_alarm.
+    // Omitted/empty → broadcast (global alarm, every module). A valid
+    // 1-254 address (decimal or hex string) → that module only (local alarm).
+    function resolveTargetAddr(addrIn) {
+      if (addrIn === undefined || addrIn === null || addrIn === '') {
+        return { addr: BROADCAST_ADDR, label: 'global (0x00)' };
+      }
+      const a = (typeof addrIn === 'number') ? addrIn : parseInt(addrIn, 16);
+      if (isNaN(a) || a < 1 || a > 254) {
+        node.warn('velbus-clock: invalid address "' + addrIn + '" for set_alarm — sending globally instead');
+        return { addr: BROADCAST_ADDR, label: 'global (0x00)' };
+      }
+      return { addr: a, label: 'local (0x' + a.toString(16).padStart(2, '0').toUpperCase() + ')' };
+    }
+
+    function broadcastAll(d, opts) {
+      if (!node.bridge.isConnected()) {
+        node.warn('velbus-clock: bridge not connected, broadcast skipped');
+        setStatus('not connected', 'red');
+        return;
+      }
+
+      sendTime(d);
+      if (opts.date) sendDate(d);
+
+      let dst = null;
+      if (opts.includeDst) {
+        dst = (typeof opts.dstOverride === 'boolean') ? opts.dstOverride : isDstActive(d);
+        sendDst(dst);
+      }
+
+      setStatus('sent ' + d.toTimeString().slice(0, 8) +
+        (opts.date ? ' + date' : '') +
+        (opts.includeDst ? (' + DST:' + (dst ? 'on' : 'off')) : ''), 'green');
+
+      node.send({
+        payload: {
+          topic:     'clock_broadcast',
+          dayOfWeek: velbusDow(d.getDay()),
+          hours:     d.getHours(),
+          minutes:   d.getMinutes(),
+          date:      opts.date ? { day: d.getDate(), month: d.getMonth() + 1, year: d.getFullYear() } : null,
+          dst,
+          timestamp: d.getTime()
+        }
+      });
+    }
+
+    // ── Input ─────────────────────────────────────────────────────────────
+    // Bare inject (empty payload) triggers a full broadcast using node
+    // config defaults — no msg shaping required for the common case.
+
+    node.on('input', function(msg) {
+      const inp = (msg && msg.payload && typeof msg.payload === 'object') ? msg.payload : {};
+      const cmd = inp.cmd || 'broadcast';
+
+      let when = inp.date ? new Date(inp.date) : new Date();
+      if (isNaN(when.getTime())) {
+        node.warn('velbus-clock: invalid msg.payload.date, using current time instead');
+        when = new Date();
+      }
+
+      switch (cmd) {
+        case 'broadcast':
+          broadcastAll(when, { date: node.includeDate, includeDst: node.includeDst, dstOverride: inp.dst });
+          break;
+
+        case 'broadcast_time':
+          if (!node.bridge.isConnected()) { node.warn('velbus-clock: bridge not connected'); return; }
+          sendTime(when);
+          setStatus('sent time ' + when.toTimeString().slice(0, 8), 'green');
+          break;
+
+        case 'broadcast_date':
+          if (!node.bridge.isConnected()) { node.warn('velbus-clock: bridge not connected'); return; }
+          sendDate(when);
+          setStatus('sent date ' + when.toDateString(), 'green');
+          break;
+
+        case 'broadcast_dst': {
+          if (!node.bridge.isConnected()) { node.warn('velbus-clock: bridge not connected'); return; }
+          const dst = (typeof inp.dst === 'boolean') ? inp.dst : isDstActive(when);
+          sendDst(dst);
+          setStatus('sent DST:' + (dst ? 'on' : 'off'), 'green');
+          break;
+        }
+
+        case 'set_alarm': {
+          const alarmNum = parseInt(inp.alarm);
+          if (alarmNum !== 1 && alarmNum !== 2) {
+            node.warn('velbus-clock: set_alarm requires "alarm": 1 or 2');
+            return;
+          }
+          if (!node.bridge.isConnected()) { node.warn('velbus-clock: bridge not connected'); return; }
+
+          const wakeHour   = clampInt(inp.wakeHour,   0, 23, 0);
+          const wakeMinute = clampInt(inp.wakeMinute, 0, 59, 0);
+          const bedHour    = clampInt(inp.bedHour,    0, 23, 0);
+          const bedMinute  = clampInt(inp.bedMinute,  0, 59, 0);
+          const enabled    = inp.enabled !== false; // default true — set_alarm implies enabling it
+
+          const { addr: targetAddr, label } = resolveTargetAddr(inp.address);
+
+          sendAlarm(targetAddr, alarmNum, wakeHour, wakeMinute, bedHour, bedMinute, enabled);
+
+          setStatus('alarm ' + alarmNum + ' ' + (enabled ? 'set' : 'disabled') + ' — ' + label, 'green');
+
+          node.send({
+            payload: {
+              topic:      'alarm_set',
+              target:     targetAddr === BROADCAST_ADDR ? 'global' : ('0x' + targetAddr.toString(16).padStart(2, '0').toUpperCase()),
+              alarm:      alarmNum,
+              wakeHour, wakeMinute, bedHour, bedMinute,
+              enabled
+            }
+          });
+          break;
+        }
+
+        default:
+          node.warn('velbus-clock: unknown cmd "' + cmd + '"');
+      }
+    });
+
+    // ── Auto broadcast ────────────────────────────────────────────────────
+
+    if (node.autoBroadcast) {
+      const intervalMs = Math.max(1, node.intervalMinutes) * 60000;
+
+      function tick() {
+        broadcastAll(new Date(), { date: node.includeDate, includeDst: node.includeDst });
+      }
+
+      // Delayed first send — give the bridge a moment to connect after deploy.
+      _startupTimer  = setTimeout(tick, 5000);
+      _intervalTimer = setInterval(tick, intervalMs);
+    }
+
+    node.on('close', function() {
+      if (_startupTimer)  clearTimeout(_startupTimer);
+      if (_intervalTimer) clearInterval(_intervalTimer);
+    });
+
+    setStatus('ready', 'grey');
+  }
+
+  RED.nodes.registerType('velbus-clock', VelbusClockNode);
+};

package/nodes/velbus-dimmer/velbus-dimmer.html

@@ -0,0 +1,174 @@
+<script type="text/javascript">
+
+  // ── Shared address dropdown helper ──────────────────────────────────────────
+  function velbusPopulateAddressDropdown(nodeCtx, bridgeSelector, addrSelector, nodeTypes) {
+    var addrField  = $(addrSelector);
+    var currentVal = String(addrField.val() || nodeCtx.address || nodeCtx.moduleAddr || '').replace('0x','').toUpperCase();
+
+    function buildDropdown(modules) {
+      var filtered = nodeTypes
+        ? modules.filter(function(m) { return nodeTypes.indexOf(m.suggestedNode) !== -1; })
+        : modules;
+
+      if (filtered.length === 0) {
+        addrField.show();
+        return;
+      }
+
+      var select = $('<select>', { id: addrSelector.replace('#',''), style: 'width:100%' });
+      select.append($('<option>', { value: '', text: '\u2014 select or type address \u2014' }));
+
+      filtered.forEach(function(m) {
+        var addrHex = m.address.replace('0x','').toUpperCase();
+        var label = m.address + '  ' + m.module +
+          (m.velbusName && m.velbusName !== m.module ? '  "' + m.velbusName + '"' : '') +
+          '  (build ' + m.build + ', map v' + m.memoryMapVersion + ')';
+        var opt = $('<option>', { value: addrHex, text: label });
+        if (addrHex === currentVal) opt.prop('selected', true);
+        select.append(opt);
+        opt.data('module', m);
+      });
+
+      select.append($('<option>', { value: '__manual__', text: '\u2014 enter address manually \u2014' }));
+      addrField.replaceWith(select);
+
+      select.on('change', function() {
+        if ($(this).val() === '__manual__') {
+          var input = $('<input>', {
+            type: 'text', id: addrSelector.replace('#',''),
+            placeholder: 'hex e.g. A0', style: 'width:80px'
+          });
+          $(this).replaceWith(input);
+          return;
+        }
+        var m = $(this).find(':selected').data('module');
+        if (m && m.channels) {
+          var cc = $('#node-input-channelCount');
+          if (cc.length) cc.val(m.channels);
+        }
+      });
+    }
+
+    function loadResults() {
+      var bridgeId = $(bridgeSelector).val();
+      if (!bridgeId) return;
+      $.getJSON('velbus/scan-results?bridge=' + bridgeId, function(data) {
+        if (data && data.modules && data.modules.length > 0) buildDropdown(data.modules);
+      }).fail(function() {});
+    }
+
+    $(bridgeSelector).on('change', loadResults);
+    setTimeout(function() { $(bridgeSelector).trigger('change'); }, 150);
+  }
+
+  RED.nodes.registerType('velbus-dimmer', {
+    category: 'Velbus (outputs)',
+    color:    '#4A90D9',
+    defaults: {
+      name:         { value: '' },
+      bridge:       { value: '', type: 'velbus-bridge', required: true },
+      moduleAddr:   { value: '', required: true },
+      startChannel: { value: 1, required: true, validate: RED.validators.number() },
+      channelCount: { value: 1, required: true, validate: RED.validators.number() }
+    },
+    inputs:  1,
+    outputs: 2,
+    icon:    'font-awesome/fa-sliders',
+    label: function() {
+      if (this.name) return this.name;
+      return 'dimmer 0x' + (this.moduleAddr || '??');
+    },
+    outputLabels: ['state / events', 'warnings'],
+    oneditprepare: function() {
+      velbusPopulateAddressDropdown(
+        this,
+        '#node-input-bridge',
+        '#node-input-moduleAddr',
+        ['velbus-dimmer']
+      );
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="velbus-dimmer">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name override</label>
+    <input type="text" id="node-input-name"
+      placeholder="Leave blank to use module name from VelbusLink">
+  </div>
+  <div class="form-row">
+    <label for="node-input-bridge"><i class="fa fa-server"></i> Bridge</label>
+    <input type="text" id="node-input-bridge">
+  </div>
+  <div class="form-row">
+    <label for="node-input-moduleAddr"><i class="fa fa-microchip"></i> Address</label>
+    <input type="text" id="node-input-moduleAddr" placeholder="e.g. BF — run scan first for dropdown" style="width:100%">
+    <div class="form-tips" style="margin-top:4px">Run a <b>velbus-scan</b> node first to populate the dropdown with discovered modules.</div>
+  </div>
+  <div class="form-row">
+    <label for="node-input-startChannel"><i class="fa fa-list-ol"></i> Start channel</label>
+    <input type="number" id="node-input-startChannel" min="1" max="4" style="width:60px">
+  </div>
+  <div class="form-row">
+    <label for="node-input-channelCount"><i class="fa fa-hashtag"></i> Channel count</label>
+    <input type="number" id="node-input-channelCount" min="1" max="4" style="width:60px">
+  </div>
+</script>
+
+<script type="text/html" data-help-name="velbus-dimmer">
+    <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><strong>Original series only (pre V2.0)</strong></p>
+  <p>For V2.0 dimmer modules (VMB2DC-20, VMB8DC-20, VMB4LEDPWM-20) use the <b>velbus-dimmer-20</b> node instead.</p>
+
+  <p>Supports: <b>VMBDMI</b> (1ch), <b>VMBDMI-R</b> (1ch), <b>VMB4DC</b> (4ch)</p>
+
+  <h3>Address dropdown</h3>
+  <p>Run a <b>velbus-scan</b> node first to populate the address dropdown.</p>
+
+  <h3>Output 1 — State / Events</h3>
+  <pre>
+{
+  "topic":          "dimmer_status",
+  "address":        "0xBF",
+  "module":         "Bathroom",
+  "channel":        1,
+  "state":          "on",
+  "on":             true,
+  "level":          75,
+  "percent":        75.0,
+  "timerRemaining": 0,
+  "thermal": {
+    "tempBand": 0,
+    "loadType": 0,
+    "error":    0
+  },
+  "timestamp": 1719100000000
+}
+  </pre>
+
+  <h3>Input — Commands</h3>
+  <pre>
+{ "channel": 1, "cmd": "set",     "level": 75 }
+{ "channel": 1, "cmd": "set",     "percent": 75, "dimspeed": 3 }
+{ "channel": 1, "cmd": "on" }
+{ "channel": 1, "cmd": "off" }
+{ "channel": 1, "cmd": "restore" }
+{ "channel": 1, "cmd": "stop" }
+{ "channel": 1, "cmd": "timer",        "duration": 30 }
+{ "channel": 1, "cmd": "forced_on",    "duration": -1 }
+{ "channel": 1, "cmd": "forced_off",   "duration": 3600 }
+{ "channel": 1, "cmd": "cancel_forced_on" }
+{ "channel": 1, "cmd": "cancel_forced_off" }
+{ "channel": 1, "cmd": "inhibit",      "duration": 1800 }
+{ "channel": 1, "cmd": "cancel_inhibit" }
+{ "channel": 1, "cmd": "status" }
+  </pre>
+  <p>dimspeed in seconds (0=instant). Duration in seconds, -1=permanent.</p>
+  <p>VMB4DC: set <code>channel</code> to <code>"all"</code> for all channels simultaneously.</p>
+</script>