node-red-contrib-velbus-2026 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stuart Hanlon, MDAR Limited (https://mdar.co.uk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# node-red-contrib-velbus-2026
+
+A Node-RED palette for [Velbus](https://www.velbus.eu) building automation systems.
+
+> **⚠ Testing status:** This palette 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" — 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. Please
+> [file an issue on GitHub](https://github.com/MDAR/node-red-contrib-velbus-2026/issues).
+
+---
+
+## About
+
+Velbus is a CAN-bus building automation system manufactured in Belgium. This palette
+provides Node-RED nodes for all major Velbus module families — both the original series
+and the current V2 (-20 series) modules.
+
+Developed and maintained by [MDAR Limited](https://mdar.co.uk), the UK distributor
+for Velbus building automation systems.
+
+This is a ground-up rewrite replacing the abandoned
+[node-red-contrib-velbus](https://github.com/gertst/node-red-contrib-velbus) palette
+(last updated 2020).
+
+---
+
+## Requirements
+
+- Node-RED v3.0 or later (tested on v5.0)
+- A Velbus TCP gateway:
+  - [velbus-tcp snap](https://snapcraft.io/velbus-tcp) (default port 6000)
+  - [python-velbustcp](https://github.com/velbus/python-velbustcp) (default port 27015)
+- Node.js 18+
+
+---
+
+## Installation
+
+Via palette manager: search for `velbus-2026`.
+
+Via npm:
+```bash
+cd ~/.node-red
+npm install node-red-contrib-velbus-2026
+```
+
+Via local tarball:
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-contrib-velbus-2026_v0.8.1.tar.gz
+```
+
+---
+
+## Nodes
+
+### Infrastructure
+| Node | Description |
+|---|---|
+| `velbus-bridge` | Config node. TCP/TLS connection to gateway. Handles packet routing, subaddress mapping, scan locking. |
+| `velbus-scan` | Bus scanner. Sends RTR to all addresses 0xFE→0x01, collects 0xFF responses. Populates address dropdowns in all other nodes. |
+
+### Inputs (teal)
+| Node | Modules |
+|---|---|
+| `velbus-glass-panel` | All VMBEL and VMBGP variants — 26 types including OLED, PIR, and original series. Thermostat, LED control, open collector. |
+| `velbus-thermostat` | Dedicated thermostat node for all glass panel modules. |
+| `velbus-button` | VMB8PB, VMB8PBU, VMB6PBN, VMB2PBN, VMB4PB, VMB6PB-20 |
+| `velbus-pir` | VMBPIRM, VMBPIRC, VMBPIRO, VMBPIRO-10 |
+| `velbus-pir-20` | VMBPIR-20, VMBPIRO-20 |
+| `velbus-meteo` | VMBMETEO — wind, rain, light, temperature, alarm outputs |
+| `velbus-sensor` | VMB7IN (8 digital inputs + 4 pulse counters), VMB4AN (16-channel analogue/alarm) |
+| `velbus-sensor-20` | VMB8IN-20 (8 digital + 24 alarm channels via subaddresses, energy counters) |
+
+### Outputs (blue)
+| Node | Modules |
+|---|---|
+| `velbus-relay` | VMB1RY, VMB4RY, VMB4RYLD, VMB4RYNO, VMB1RYNO, VMB1RYNOS, VMB1RYS, VMB4RYLD-10, VMB4RYNO-10 |
+| `velbus-relay-20` | VMB1RYS-20, VMB4RYLD-20, VMB4RYNO-20 |
+| `velbus-dimmer` | VMBDMI, VMBDMI-R, VMB4DC |
+| `velbus-dimmer-20` | VMB2DC-20, VMB8DC-20, VMB4LEDPWM-20 |
+| `velbus-blind` | VMB1BL, VMB2BL — original series, stop/up/down only |
+| `velbus-blind-s` | VMB1BLS, VMB2BLE, VMB2BLE-10 — full position, lock, force, inhibit |
+| `velbus-blind-20` | VMB2BLE-20 — V2 series with CAN FD support |
+| `velbus-clock` | No fixed module — broadcasts time/date/DST to bus address `0x00`, plus global/local clock alarm (V2 series only) |
+
+---
+
+## Examples
+
+After installation, example flows are available via **Import → Examples → node-red-contrib-velbus-2026**
+in the Node-RED editor.
+
+### velbus-basic-relay-dimmer
+A minimal working example with:
+- Bus scan (inject to discover modules)
+- Relay toggle — Dashboard 2 switch → velbus-relay command, with state feedback
+- Dimmer slider — Dashboard 2 slider (0-100%) → velbus-dimmer-20 command, with level readout
+
+**To use:** configure the velbus-bridge node, scan the bus, open the relay and dimmer
+nodes and select your module addresses from the dropdowns, then deploy. Dashboard UI
+at `/velbus`.
+
+---
+
+## Quick start
+
+1. Add a **velbus-bridge** config node pointing at your gateway (default: `127.0.0.1:6000`)
+2. Add a **velbus-scan** node, connect to the bridge, deploy and inject to scan
+3. All other nodes will have address dropdowns populated from the scan results
+4. Add the node for your module type, select the address, deploy
+
+---
+
+## Confirmed hardware
+
+Tested on a live 18-module installation including VMBEL4, VMBELO, VMBELPIR,
+VMBPIR-20, VMB1RYS, and VMB8DC-20. CAN FD modules confirmed working.
+
+---
+
+## Contributing
+
+Issues and pull requests welcome at the
+[GitHub repository](https://github.com/MDAR/node-red-contrib-velbus-2026).
+
+Please include Node-RED version, gateway type, module model and firmware build,
+and a packet capture where possible.
+
+---
+
+## Licence
+
+MIT — see [LICENSE](LICENSE)
+
+## Author
+
+Stuart Hanlon, [MDAR Limited](https://mdar.co.uk)

package/examples/velbus-basic-relay-dimmer.json

@@ -0,0 +1,328 @@
+[
+  {
+    "id": "tab-velbus-example",
+    "type": "tab",
+    "label": "Velbus Basic Example",
+    "disabled": false,
+    "info": "Basic Velbus example — relay toggle and dimmer control.\n\nBefore using:\n1. Configure the velbus-bridge node with your gateway address.\n2. Deploy and inject the 'Scan bus' node to discover modules.\n3. Open each velbus-relay and velbus-dimmer node and select the correct address from the dropdown.\n4. Re-deploy.\n\nThe Dashboard 2 UI will be available at /dashboard"
+  },
+
+  {
+    "id": "bridge-example",
+    "type": "velbus-bridge",
+    "name": "Velbus Gateway",
+    "host": "127.0.0.1",
+    "port": "6000",
+    "tls": false,
+    "authKey": ""
+  },
+
+  {
+    "id": "comment-scan",
+    "type": "comment",
+    "z": "tab-velbus-example",
+    "name": "STEP 1 — Scan the bus first",
+    "info": "Inject once to discover all modules. Address dropdowns in relay/dimmer nodes are populated from scan results.",
+    "x": 200,
+    "y": 60,
+    "wires": []
+  },
+
+  {
+    "id": "inject-scan",
+    "type": "inject",
+    "z": "tab-velbus-example",
+    "name": "Scan bus",
+    "props": [{"p": "payload"}],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "",
+    "payload": "{}",
+    "payloadType": "json",
+    "x": 160,
+    "y": 120,
+    "wires": [["scan-example"]]
+  },
+  {
+    "id": "scan-example",
+    "type": "velbus-scan",
+    "z": "tab-velbus-example",
+    "name": "Bus scan",
+    "bridge": "bridge-example",
+    "x": 340,
+    "y": 120,
+    "wires": [["debug-scan"]]
+  },
+  {
+    "id": "debug-scan",
+    "type": "debug",
+    "z": "tab-velbus-example",
+    "name": "Scan results",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 540,
+    "y": 120,
+    "wires": []
+  },
+
+  {
+    "id": "comment-relay",
+    "type": "comment",
+    "z": "tab-velbus-example",
+    "name": "STEP 2 — Relay control",
+    "info": "Dashboard toggle → relay on/off command.\nRelay status events → Dashboard state indicator.\n\nOpen velbus-relay and select your relay module address and channel.",
+    "x": 200,
+    "y": 220,
+    "wires": []
+  },
+
+  {
+    "id": "ui-relay-toggle",
+    "type": "ui-switch",
+    "z": "tab-velbus-example",
+    "name": "Relay toggle",
+    "label": "Relay",
+    "group": "ui-group-main",
+    "order": 1,
+    "width": 3,
+    "height": 1,
+    "passthru": false,
+    "decouple": true,
+    "topic": "relay",
+    "topicType": "str",
+    "style": "",
+    "className": "",
+    "onvalue": "true",
+    "onvalueType": "bool",
+    "onicon": "",
+    "oncolor": "#00897B",
+    "onlabel": "ON",
+    "offvalue": "false",
+    "offvalueType": "bool",
+    "officon": "",
+    "offcolor": "",
+    "offlabel": "OFF",
+    "x": 160,
+    "y": 280,
+    "wires": [["fn-relay-command"]]
+  },
+  {
+    "id": "fn-relay-command",
+    "type": "function",
+    "z": "tab-velbus-example",
+    "name": "Toggle → relay cmd",
+    "func": "// Convert Dashboard 2 switch to velbus-relay command\nmsg.payload = { cmd: msg.payload ? 'on' : 'off' };\nreturn msg;",
+    "outputs": 1,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "x": 360,
+    "y": 280,
+    "wires": [["relay-example"]]
+  },
+  {
+    "id": "relay-example",
+    "type": "velbus-relay",
+    "z": "tab-velbus-example",
+    "name": "Relay ch1",
+    "bridge": "bridge-example",
+    "address": "",
+    "channel": "1",
+    "x": 580,
+    "y": 280,
+    "wires": [["fn-relay-status"]]
+  },
+  {
+    "id": "fn-relay-status",
+    "type": "function",
+    "z": "tab-velbus-example",
+    "name": "Relay status → switch",
+    "func": "// Feed relay state back to Dashboard switch\nif (msg.payload && msg.payload.hasOwnProperty('on')) {\n    msg.payload = msg.payload.on;\n    return msg;\n}\nreturn null;",
+    "outputs": 1,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "x": 780,
+    "y": 280,
+    "wires": [["ui-relay-toggle"]]
+  },
+
+  {
+    "id": "comment-dimmer",
+    "type": "comment",
+    "z": "tab-velbus-example",
+    "name": "STEP 3 — Dimmer control",
+    "info": "Dashboard slider (0-100%) → dimmer level command.\nDimmer status events → slider and text readout.\n\nOpen velbus-dimmer-20 and select your dimmer module address and channel.",
+    "x": 200,
+    "y": 380,
+    "wires": []
+  },
+
+  {
+    "id": "ui-dimmer-slider",
+    "type": "ui-slider",
+    "z": "tab-velbus-example",
+    "name": "Dimmer slider",
+    "label": "Dimmer level",
+    "group": "ui-group-main",
+    "order": 2,
+    "width": 6,
+    "height": 1,
+    "passthru": false,
+    "outs": "end",
+    "topic": "dimmer",
+    "topicType": "str",
+    "min": 0,
+    "max": 100,
+    "step": 1,
+    "className": "",
+    "x": 160,
+    "y": 440,
+    "wires": [["fn-dimmer-command"]]
+  },
+  {
+    "id": "fn-dimmer-command",
+    "type": "function",
+    "z": "tab-velbus-example",
+    "name": "Slider → dimmer cmd",
+    "func": "// Convert Dashboard 2 slider value to velbus-dimmer command\nconst level = Math.round(msg.payload);\nmsg.payload = { cmd: level > 0 ? 'set' : 'off', level: level };\nreturn msg;",
+    "outputs": 1,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "x": 360,
+    "y": 440,
+    "wires": [["dimmer-example"]]
+  },
+  {
+    "id": "dimmer-example",
+    "type": "velbus-dimmer-20",
+    "z": "tab-velbus-example",
+    "name": "Dimmer ch1",
+    "bridge": "bridge-example",
+    "address": "",
+    "channel": "1",
+    "x": 580,
+    "y": 440,
+    "wires": [["fn-dimmer-status"]]
+  },
+  {
+    "id": "fn-dimmer-status",
+    "type": "function",
+    "z": "tab-velbus-example",
+    "name": "Dimmer status → slider + text",
+    "func": "// Feed dimmer level back to Dashboard slider\nif (msg.payload && msg.payload.hasOwnProperty('percent')) {\n    const level = Math.round(msg.payload.percent);\n    // Update slider\n    const sliderMsg = { payload: level, topic: 'dimmer' };\n    // Update text label\n    const textMsg = { payload: level + '%', topic: 'dimmer' };\n    return [sliderMsg, textMsg];\n}\nreturn [null, null];",
+    "outputs": 2,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "x": 800,
+    "y": 440,
+    "wires": [["ui-dimmer-slider"], ["ui-dimmer-text"]]
+  },
+  {
+    "id": "ui-dimmer-text",
+    "type": "ui-text",
+    "z": "tab-velbus-example",
+    "name": "Dimmer level readout",
+    "label": "Current level",
+    "group": "ui-group-main",
+    "order": 3,
+    "width": 3,
+    "height": 1,
+    "format": "{{msg.payload}}",
+    "layout": "row-spread",
+    "style": false,
+    "className": "",
+    "x": 1060,
+    "y": 440,
+    "wires": []
+  },
+
+  {
+    "id": "comment-debug",
+    "type": "comment",
+    "z": "tab-velbus-example",
+    "name": "STEP 4 — Debug all events",
+    "info": "Wire any node output here to see raw payloads in the debug panel.",
+    "x": 200,
+    "y": 560,
+    "wires": []
+  },
+  {
+    "id": "debug-all",
+    "type": "debug",
+    "z": "tab-velbus-example",
+    "name": "All Velbus events",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 360,
+    "y": 600,
+    "wires": []
+  },
+
+  {
+    "id": "ui-group-main",
+    "type": "ui-group",
+    "name": "Velbus Control",
+    "page": "ui-page-main",
+    "width": 6,
+    "height": 1,
+    "order": 1,
+    "showTitle": true,
+    "className": "",
+    "visible": true,
+    "disabled": false
+  },
+  {
+    "id": "ui-page-main",
+    "type": "ui-page",
+    "name": "Velbus",
+    "ui": "ui-main",
+    "path": "/velbus",
+    "icon": "mdi-home-lightning-bolt",
+    "layout": "grid",
+    "theme": "ui-theme-default",
+    "order": 1,
+    "className": "",
+    "visible": true,
+    "disabled": false
+  },
+  {
+    "id": "ui-main",
+    "type": "ui-base",
+    "acceptsClientConfig": ["ui-page", "ui-control"],
+    "dialogCloseIcon": "mdi-close",
+    "showPathInSidebar": false,
+    "navigationStyle": "default",
+    "titleBarStyle": "default"
+  },
+  {
+    "id": "ui-theme-default",
+    "type": "ui-theme",
+    "name": "Default Theme",
+    "colors": {
+      "surface": "#ffffff",
+      "primary": "#0d7eb8",
+      "bgPage": "#eeeeee",
+      "groupBg": "#ffffff",
+      "groupOutline": "#cccccc"
+    },
+    "sizes": {
+      "pagePadding": "12px",
+      "groupGap": "12px",
+      "groupBorderRadius": "4px",
+      "widgetGap": "6px"
+    }
+  }
+]

package/index.js

@@ -0,0 +1,3 @@
+// node-red-contrib-velbus-2026
+// Node-RED entry point — Node-RED discovers nodes via package.json node-red.nodes
+// This file intentionally left minimal.

package/lib/blind-types-20.js

@@ -0,0 +1,26 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Blind/shutter module type registry — V2 (-20) series
+// Covered by velbus-blind-20 node.
+//
+// VMB2BLE-20 (0x61): Full V2 redesign. 8-byte 0xFF with CAN FD properties.
+//   0xEC status packet covers BOTH channels in one packet using nibble encoding.
+//   Channel identifier in commands: plain integer 1, 2, or 0xFF (all).
+//   Name request 0xEF: DB2 = channel number or 0xFF for all.
+//   No 0x00 relay event transmit — status comes via 0xEC only.
+//   0xFFFFFF NOT allowed for up/down timeout (allowed for lock/force/inhibit).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BLIND_TYPES_20 = {
+  0x61: {
+    name:        'VMB2BLE-20',
+    channels:    2,
+    minMapVer:   null,
+    series:      'v2',
+  },
+};
+
+const BLIND_TYPE_IDS_20 = new Set(Object.keys(BLIND_TYPES_20).map(k => parseInt(k)));
+
+module.exports = { BLIND_TYPES_20, BLIND_TYPE_IDS_20 };

package/lib/blind-types-s.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Blind/shutter module type registry — BLS/BLE series (VMB1BLS, VMB2BLE)
+// Covered by velbus-blind-s node.
+//
+// Full-featured blind controllers with position feedback (0-100%),
+// lock/unlock (0x1A/0x1B), forced up/down, inhibit variants, auto modes,
+// sunrise/sunset, and real-time clock. 0xFF response is 7 bytes with serial.
+//
+// channels:       number of blind channels
+// channelBits:    map of channel number to bit value used in commands
+//                 Both modules use clean bit encoding: ch1=0x01, ch2=0x02
+// hasLocalButtons: false — local button events NOT reported in 0x00
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BLIND_TYPES_S = {
+  0x2E: {
+    name:            'VMB1BLS',
+    channels:        1,
+    channelBits:     { 1: 0x01 },
+    hasLocalButtons: false,
+    minMapVer:       null,
+    series:          'bls',
+  },
+  0x1D: {
+    name:            'VMB2BLE',
+    channels:        2,
+    channelBits:     { 1: 0x01, 2: 0x02 },
+    hasLocalButtons: false,
+    minMapVer:       null,
+    series:          'ble',
+  },
+  0x4A: {
+    name:            'VMB2BLE-10',
+    channels:        2,
+    channelBits:     { 1: 0x01, 2: 0x02 },
+    hasLocalButtons: false,
+    minMapVer:       null,
+    series:          'ble-10',
+  },
+};
+
+const BLIND_TYPE_IDS_S = new Set(Object.keys(BLIND_TYPES_S).map(k => parseInt(k)));
+
+module.exports = { BLIND_TYPES_S, BLIND_TYPE_IDS_S };

package/lib/blind-types.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Blind/shutter module type registry — original series (VMB1BL, VMB2BL)
+// Covered by velbus-blind node.
+//
+// These are early modules with no position feedback, no lock/force/inhibit,
+// and dip-switch-based timeout. 0xFF response is 5 bytes (no serial number).
+//
+// channels:       number of blind channels
+// channelMasks:   map of channel number to bitmask used in 0xEC and commands
+//                 VMB1BL uses 0x03 for its single channel (historical oddity)
+//                 VMB2BL uses packed 2-bit pairs: ch1=0x03, ch2=0x0C
+// hasLocalButtons: module reports local push button events mixed into 0x00
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BLIND_TYPES = {
+  0x03: {
+    name:            'VMB1BL',
+    channels:        1,
+    channelMasks:    { 1: 0x03 },
+    hasLocalButtons: true,
+    minMapVer:       null,
+    series:          'original',
+  },
+  0x09: {
+    name:            'VMB2BL',
+    channels:        2,
+    channelMasks:    { 1: 0x03, 2: 0x0C },
+    hasLocalButtons: true,
+    minMapVer:       null,
+    series:          'original',
+  },
+};
+
+const BLIND_TYPE_IDS = new Set(Object.keys(BLIND_TYPES).map(k => parseInt(k)));
+
+module.exports = { BLIND_TYPES, BLIND_TYPE_IDS };