node-red-contrib-knx-ultimate 4.0.0-beta.0 → 4.0.1

package/CHANGELOG.md

@@ -6,8 +6,9 @@
 
 # CHANGELOG
 
-**Version 5.0.0-BETA** - September 2025<br/>
-- NEW: KNX Secure has been implemented<br/>
+**Version 4.0.1** - September 2025<br/>
+- CAUTION - MAKE A BACKUP OF YOUR FLOW BEFORE UPGRADING<br/>
+- NEW: KNX Secure has arrived!!<br/>
 - Enhancements: enancements in the UI<br/>
 - Enhancements: enancements in the help tab of node-red<br/>
 - Enhancements: added localization IT EN DE CN<br/>

package/README-WIKI.md

@@ -0,0 +1,108 @@
+Wiki Maintenance — Scripts and Workflow
+
+This document explains how to maintain the GitHub Wiki for node-red-contrib-knx-ultimate using the helper scripts included in this repo.
+
+Where things live
+- Wiki repo: ../node-red-contrib-knx-ultimate.wiki
+- Scripts: scripts/*
+- Menu config: scripts/wiki-menu.json
+
+Prerequisites
+- Node.js 20+
+- The wiki repo checked out next to this repo (as above).
+- Internet connectivity (for translation).
+
+NPM scripts
+- Validate bars: `npm run wiki:validate`
+  - Checks that every page’s first line has a correct language bar with absolute wiki URLs.
+  - Excludes `_Sidebar.md`, `_Footer.md`, and files under `samples/`.
+- Fix bars: `npm run wiki:fix-langbar`
+  - Rewrites language bars to the expected format with absolute URLs.
+- Inject header: `npm run wiki:inject-header`
+  - Inserts/updates a localized navigation header between `<!-- NAV START -->` and `<!-- NAV END -->` right after the language bar on every page.
+  - The header includes all sections and links defined in `scripts/wiki-menu.json` and uses localized labels for EN/IT/DE/zh‑CN.
+- Add menu item (interactive): `npm run wiki:menu-add`
+  - Prompts for a page (EN title, e.g., `Quick-Start`) and the target section.
+  - Optionally creates a new section; if localized labels are left empty, auto‑translates from EN.
+  - After saving, run `npm run wiki:inject-header` to propagate into all pages.
+  - Also generates/updates the localized Node‑RED help files (see below) if the page maps to a node.
+- Translate pages: `npm run translate-wiki`
+  - Scans the wiki for base EN pages (no `it-`, `de-`, `zh-CN-` prefix) and creates missing translations.
+  - Preserves code blocks, keeps URLs intact, and emits an absolute-URL language bar.
+  - After translation, run `npm run wiki:inject-header` to add the localized header.
+
+Node help migration and generation
+- One‑time migrate (existing nodes): `node scripts/migrate-node-help.js`
+  - Finds inline node help blocks in `nodes/*.html` and moves them to localized files under:
+    - `nodes/locales/en-US/<help-name>.html`
+    - `nodes/locales/it-IT/<help-name>.html`
+    - `nodes/locales/de-DE/<help-name>.html`
+    - `nodes/locales/zh-CN/<help-name>.html`
+  - Content source: corresponding wiki pages (EN/IT/DE/zh‑CN). If a page is missing, uses the inline help as fallback.
+  - Removes the inline help from the node HTML file (keeps only templates and editor JS).
+- Auto‑generate from wiki when adding menu entries: `npm run wiki:menu-add`
+  - If the selected wiki page maps to a node (see mapping), the script will create/update the localized help files as above.
+
+Page ↔ node mapping (for help generation)
+- Mapping is defined inside `scripts/manage-wiki-menu.js` (WIKI_TO_HELP/HELP_TO_WIKI).
+- Example mappings:
+  - `HUE Bridge configuration` → `hue-config`
+  - `Gateway-configuration` → `knxUltimate-config`
+  - `KNX Node Configuration` → `knxUltimate`
+  - `Logger-Configuration` → `knxUltimateLogger`
+  - … and all HUE/KNX pages listed in the script.
+- If you add a brand new node and wiki page, update the mapping in `manage-wiki-menu.js` once; after that, `wiki:menu-add` can generate localized help automatically.
+
+Key files
+- scripts/validate-wiki-languagebar.js: verifies and optionally fixes the language bar on each page.
+- scripts/inject-wiki-header.js: generates the per‑page navigation header from `wiki-menu.json` (idempotent).
+- scripts/manage-wiki-menu.js: interactive tool to edit `wiki-menu.json` (add items/sections with auto‑translation) and to generate localized node help files from wiki pages.
+- scripts/translate-wiki.js: creates IT/DE/zh‑CN pages from an EN page body.
+- scripts/wiki-menu.json: declarative definition of header sections and items. Supports `type: "page"` (localized links) and `type: "url"` (external/absolute links).
+
+Quick start — add a new page to the wiki
+1) Create the EN page in the wiki repo
+   - Path: ../node-red-contrib-knx-ultimate.wiki
+   - Filename: `Your-Page-Title.md` (use spaces as in the displayed title)
+   - Top of file: add the language bar (absolute links) or let the scripts generate it later.
+2) Generate translations
+   - Run: `npm run translate-wiki`
+   - This creates `it-Your-Page-Title.md`, `de-Your-Page-Title.md`, `zh-CN-Your-Page-Title.md` if missing.
+3) Add the page to the navigation menu
+   - Run: `npm run wiki:menu-add`
+   - Select an existing section (e.g., Overview, KNX Device, Other KNX Nodes, HUE, Samples) or create a new one.
+   - Leave localized labels empty to auto‑translate from EN, or enter your own.
+4) Inject/update headers on all pages
+   - Run: `npm run wiki:inject-header`
+   - Each page gets the full, localized header reflecting your menu changes.
+5) (Optional) Validate language bars
+   - Run: `npm run wiki:validate`
+
+How to add a new node (with localized help)
+1) Create the node as usual under `nodes/`, including editor UI and templates.
+   - If you already wrote inline help (`<script type="text/markdown" data-help-name="…">`), you can leave it temporarily; it will be migrated.
+2) Create the EN wiki page for that node (e.g., `My Node.md`) with the proper title and content.
+   - You can use `npm run translate-wiki` to generate `it-`, `de-`, `zh-CN-` variants if missing.
+3) Add the wiki → node mapping (only for brand‑new entries)
+   - Edit `scripts/manage-wiki-menu.js` and add a mapping in `HELP_TO_WIKI`, e.g.:
+     - `['myNewNode', 'My Node']`
+4) Add the page to the menu
+   - Run: `npm run wiki:menu-add`, select the section, optionally create a new section, and accept auto‑translation of labels if desired.
+   - This will also generate/update localized help files under `nodes/locales/<lang>/<help-name>.html` for the node.
+5) (If you started with inline help) Migrate and clean up
+   - Run once: `node scripts/migrate-node-help.js` to remove inline help and ensure all nodes use localized help files.
+6) Verify in Node‑RED
+   - Restart Node‑RED and switch the UI language to see the localized help under the “Info” panel for the node.
+
+Conventions and notes
+- Language bar: first line of each page. Scripts will normalize it to absolute links: EN, IT (`it-`), DE (`de-`), zh‑CN (`zh-CN-`).
+- Header placement: inserted right below the language bar. Do not edit between the NAV markers; regenerate instead.
+- Samples: most sample pages exist only in EN. The menu uses absolute URLs for these.
+- Sidebar: a minimal `_Sidebar.md` exists with only language home links; the full navigation is in the per‑page header.
+
+Troubleshooting
+- Header not updated: ensure `scripts/wiki-menu.json` contains the page (type:"page" and correct `page` title). Then run `npm run wiki:inject-header`.
+- Wrong/missing translations: re‑run `npm run translate-wiki` after adjusting the EN page. The script doesn’t overwrite existing translations; delete a specific translated file to force regeneration.
+- Language bar still relative on GitHub: run `npm run wiki:fix-langbar` and push the wiki repo.
+ - Migrate node help: `npm run wiki:help-migrate`
+   - One‑shot migration of inline help blocks from `nodes/*.html` to localized files in `nodes/locales/<lang>/<help-name>.html` using wiki content as source (fallback to inline text if wiki page is missing).

package/README.md

@@ -15,10 +15,22 @@
 
 <p align='center'>
 <img width="110px" src="https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/KNX_CERTI_MARK_RGB.jpg" ></br>
+<span style="font-size:0.7em;color:grey;">Authorized KNX logo by KNX Association*</span></br></br>
 <img width="110px" src="https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/knxsecure.png" ></br>
-<span style="font-size:0.7em;color:grey;">Authorized KNX logo by KNX Association*</span>
 </p>
 
+</br>  
+
+
+<p align='center'>
+    <img width="110px" src="https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/c/agata.png"></br>
+<center>Many thanks to <a href="https://www.agatastore.it">Agata Store - Professional store and Certified KNX Partner</a>  
+for providing me with KNX Secure stuffs to test with.</center>
+</p>
+
+
+</br>
+</br>
 </br>
 
 **You can use it immediately!**

package/examples/Logger ETS File and Telegram Count.json

@@ -0,0 +1,46 @@
+[
+  {
+    "id": "log_cfg_1",
+    "type": "knxUltimate-config",
+    "z": "",
+    "host": "224.0.23.12",
+    "port": "3671",
+    "physAddr": "15.15.204",
+    "suppressACKRequest": false,
+    "csv": "",
+    "KNXEthInterface": "Auto",
+    "KNXEthInterfaceManuallyInput": "",
+    "autoReconnect": "yes"
+  },
+  {
+    "id": "logger_1",
+    "type": "knxUltimateLogger",
+    "z": "flow5",
+    "server": "log_cfg_1",
+    "topic": "",
+    "intervalCreateETSXML": 15,
+    "name": "KNX Logger",
+    "autoStartTimerCreateETSXML": true,
+    "maxRowsInETSXML": 0,
+    "autoStartTimerTelegramCounter": true,
+    "intervalTelegramCount": 60,
+    "x": 320,
+    "y": 180,
+    "wires": [["logger_dbg_ets"],[]]
+  },
+  {
+    "id": "logger_dbg_ets",
+    "type": "debug",
+    "z": "flow5",
+    "name": "ETS diag file",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 540,
+    "y": 180,
+    "wires": []
+  }
+]

package/examples/Scene Controller Recall and Save.json

@@ -0,0 +1,76 @@
+[
+  {
+    "id": "sc_cfg_1",
+    "type": "knxUltimate-config",
+    "z": "",
+    "host": "224.0.23.12",
+    "port": "3671",
+    "physAddr": "15.15.203",
+    "suppressACKRequest": false,
+    "csv": "",
+    "KNXEthInterface": "Auto",
+    "KNXEthInterfaceManuallyInput": "",
+    "autoReconnect": "yes"
+  },
+  {
+    "id": "scene_ctrl_1",
+    "type": "knxUltimateSceneController",
+    "z": "flow4",
+    "server": "sc_cfg_1",
+    "name": "Scene Recall/Save",
+    "outputtopic": "",
+    "topic": "0/1/1",
+    "dpt": "18.001",
+    "topicTrigger": "{save_recall:0, scenenumber:2}",
+    "topicSave": "0/1/2",
+    "dptSave": "18.001",
+    "topicSaveTrigger": "{save_recall:1, scenenumber:2}",
+    "property": "payload",
+    "propertyType": "msg",
+    "rules": [],
+    "x": 410,
+    "y": 200,
+    "wires": [["sc_dbg"]]
+  },
+  {
+    "id": "inj_recall",
+    "type": "inject",
+    "z": "flow4",
+    "name": "Recall Scene 2",
+    "props": [{"p":"payload","v":"true","vt":"bool"}],
+    "repeat": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 180,
+    "y": 180,
+    "wires": [["scene_ctrl_1"]]
+  },
+  {
+    "id": "inj_save",
+    "type": "inject",
+    "z": "flow4",
+    "name": "Save Scene 2",
+    "props": [{"p":"payload","v":"true","vt":"bool"}],
+    "repeat": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 170,
+    "y": 240,
+    "wires": [["scene_ctrl_1"]]
+  },
+  {
+    "id": "sc_dbg",
+    "type": "debug",
+    "z": "flow4",
+    "name": "Scene out",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 610,
+    "y": 200,
+    "wires": []
+  }
+]

package/examples/Universal Mode Read and Write.json

@@ -0,0 +1,84 @@
+[{
+  "id": "um_cfg_1",
+  "type": "knxUltimate-config",
+  "z": "",
+  "host": "224.0.23.12",
+  "port": "3671",
+  "physAddr": "15.15.201",
+  "suppressACKRequest": false,
+  "csv": "",
+  "KNXEthInterface": "Auto",
+  "KNXEthInterfaceManuallyInput": "",
+  "autoReconnect": "yes"
+},
+{
+  "id": "um_node_all",
+  "type": "knxUltimate",
+  "z": "flow2",
+  "server": "um_cfg_1",
+  "topic": "0/0/0",
+  "dpt": "1.001",
+  "initialread": false,
+  "notifyreadrequest": false,
+  "notifyresponse": true,
+  "notifywrite": true,
+  "notifyreadrequestalsorespondtobus": false,
+  "notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized": "",
+  "listenallga": true,
+  "name": "Universal mode",
+  "outputtype": "write",
+  "outputRBE": false,
+  "inputRBE": false,
+  "x": 420,
+  "y": 280,
+  "wires": [["um_dbg"]]
+},
+{
+  "id": "um_inj_write_on",
+  "type": "inject",
+  "z": "flow2",
+  "name": "Write ON to 0/0/26",
+  "props": [
+    {"p":"payload","v":"true","vt":"bool"},
+    {"p":"destination","v":"0/0/26","vt":"str"},
+    {"p":"dpt","v":"1.001","vt":"str"}
+  ],
+  "repeat": "",
+  "once": false,
+  "onceDelay": 0.1,
+  "x": 170,
+  "y": 240,
+  "wires": [["um_node_all"]]
+},
+{
+  "id": "um_inj_read",
+  "type": "inject",
+  "z": "flow2",
+  "name": "READ 0/0/26",
+  "props": [
+    {"p":"readstatus","v":"true","vt":"bool"},
+    {"p":"destination","v":"0/0/26","vt":"str"}
+  ],
+  "repeat": "",
+  "once": false,
+  "onceDelay": 0.1,
+  "x": 150,
+  "y": 320,
+  "wires": [["um_node_all"]]
+},
+{
+  "id": "um_dbg",
+  "type": "debug",
+  "z": "flow2",
+  "name": "Universal out",
+  "active": true,
+  "tosidebar": true,
+  "console": false,
+  "tostatus": true,
+  "complete": "true",
+  "targetType": "full",
+  "x": 610,
+  "y": 280,
+  "wires": []
+}]
+

package/examples/Viewer GA Dashboard.json

@@ -0,0 +1,44 @@
+[
+  {
+    "id": "view_cfg_1",
+    "type": "knxUltimate-config",
+    "z": "",
+    "host": "224.0.23.12",
+    "port": "3671",
+    "physAddr": "15.15.202",
+    "suppressACKRequest": false,
+    "csv": "",
+    "KNXEthInterface": "Auto",
+    "KNXEthInterfaceManuallyInput": "",
+    "autoReconnect": "yes"
+  },
+  {
+    "id": "viewer_1",
+    "type": "knxUltimateViewer",
+    "z": "flow3",
+    "server": "view_cfg_1",
+    "name": "GA Viewer",
+    "output": "gadashboard",
+    "showRefreshButton": true,
+    "showSendToBus": true,
+    "showFilter": true,
+    "x": 370,
+    "y": 180,
+    "wires": [["viewer_dbg"]]
+  },
+  {
+    "id": "viewer_dbg",
+    "type": "debug",
+    "z": "flow3",
+    "name": "Viewer output",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 570,
+    "y": 180,
+    "wires": []
+  }
+]

package/examples/WatchDog Connect Disconnect.json

@@ -0,0 +1,70 @@
+[{
+  "id": "wd_cfg_1",
+  "type": "knxUltimate-config",
+  "z": "",
+  "host": "224.0.23.12",
+  "port": "3671",
+  "physAddr": "15.15.200",
+  "suppressACKRequest": false,
+  "csv": "",
+  "KNXEthInterface": "Auto",
+  "KNXEthInterfaceManuallyInput": "",
+  "autoReconnect": "no"
+},
+{
+  "id": "wd_node_1",
+  "type": "knxUltimateWatchDog",
+  "z": "flow1",
+  "server": "wd_cfg_1",
+  "checkLevel": "Ethernet",
+  "topic": "0/0/0",
+  "name": "KNX WatchDog",
+  "autoStart": false,
+  "retryInterval": 5,
+  "maxRetry": 3,
+  "x": 410,
+  "y": 160,
+  "wires": [["wd_dbg_1"]]
+},
+{
+  "id": "wd_inj_connect",
+  "type": "inject",
+  "z": "flow1",
+  "name": "Connect gateway",
+  "props": [{"p":"connectGateway","v":"true","vt":"bool"}],
+  "repeat": "",
+  "once": false,
+  "onceDelay": 0.1,
+  "x": 180,
+  "y": 120,
+  "wires": [["wd_node_1"]]
+},
+{
+  "id": "wd_inj_disconnect",
+  "type": "inject",
+  "z": "flow1",
+  "name": "Disconnect gateway",
+  "props": [{"p":"connectGateway","v":"false","vt":"bool"}],
+  "repeat": "",
+  "once": false,
+  "onceDelay": 0.1,
+  "x": 190,
+  "y": 200,
+  "wires": [["wd_node_1"]]
+},
+{
+  "id": "wd_dbg_1",
+  "type": "debug",
+  "z": "flow1",
+  "name": "WatchDog status",
+  "active": true,
+  "tosidebar": true,
+  "console": false,
+  "tostatus": true,
+  "complete": "true",
+  "targetType": "full",
+  "x": 610,
+  "y": 160,
+  "wires": []
+}]
+

package/nodes/hue-config.html

@@ -231,26 +231,4 @@
     </div>
  
 
-</script>
-<script type="text/markdown" data-help-name="hue-config">
-<H1><p align='center'>PHILIPS HUE NODES</p></H1>
-<br/>
-<p align='center'> <img src='https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/huehub.jpg' width='40%'></p>
-
-This node registers to the Hue Bridge.
-
-Just set the Bridge's IP and click **CONNECT**.  
-You can also manually set the credentials, AFTER you clicked **CONNECT**.
-
-
-**General**
-|Property|Description|
-|--|--|
-| IP | Put here the bridge's IP (the IP must be fixed) |
-| CONNECT | This button will start the registering process with HUE Bridge. The bridge ID field is automatically read from the bridge after pressing **CONNECT**. You can then choose to register new credentials, or to **SET CREDENTIALS MANUALLY**. If you choose to set credentials manually, just fill in the fields. |
-| Name | The bridge's name |
-| Reveal | Reveals the secret key pair Username and Client Key, so you can copy and use it wherever you want. |
-
-![image.png](../img/hude-config.png)
-    
 </script>