node-red-contrib-knx-ultimate 6.1.1 → 6.2.0

package/CHANGELOG.md

@@ -6,8 +6,18 @@
 
 # CHANGELOG
 
-**Version 6.1.1** - July 2026<br/>
-
+**Version 6.2.0** - July 2026<br/>
+
+- **KNX AI — DPT 1 command payload normalization**: fixed actuator writes being rejected when an otherwise valid AI response represented a DPT 1.xxx value as numeric `1`/`0` (including quoted values) instead of a JSON boolean. Exact safe equivalents `true`/`false`, `1`/`0`, `on`/`off` and ETS value labels are now normalized to real booleans before local validation, confirmation and Universal Mode output; other numeric values remain rejected.<br/>
+- **Sidebar package cleanup**: removed the unused **KNX Debug** and **KNX Monitor** sidebar tabs, their dedicated admin endpoints and the Debug logger's global 5,000-entry memory buffer. The independent Flow Bubbles plugin and standard Node-RED logging remain unchanged.<br/>
+- **KNX AI — conversational actuator control**: `ask` inputs can now produce a text reply on the existing AI Assistant output and separately emit locally validated `GroupValue_Write` messages on a new KNX commands output for a KNX Ultimate node in Universal Mode. Actuator control is opt-in and off by default; commands are limited to exact imported ETS group addresses classified as commands, must use the ETS DPT, pass payload/range validation and are capped per request. A second option, enabled by default, previews the exact GA/DPT/payload plan and waits up to five minutes for confirmation from the same chat session before emitting anything; cancellation, stale-plan replacement and validation immediately before output prevent an old or changed plan from reaching KNX. Recent chat turns are kept in bounded per-session RAM history, including detected Telegram chat IDs, and `clear_chat` clears both conversation and pending commands for one session without affecting traffic history. A ready-to-import conversational control example is available under `examples/`, including simulated chat input, confirmation/cancellation and the Universal Mode connection.<br/>
+- **KNX AI — fresh KNX state reads**: natural-language requests for a current value can now emit locally validated `GroupValue_Read` operations for exact objects in the imported ETS catalog, including status and read-only objects. Output 4 supplies the Universal Mode contract (`msg.destination`, exact ETS `msg.dpt`, `msg.event = "GroupValue_Read"` and `msg.readstatus = true`), waits up to six seconds for a fresh response/write telegram, and returns localized decoded values plus `msg.knxAi.readResults` on output 3. Reads are immediate and never require confirmation; the existing command-role and confirmation protections remain mandatory for writes. The conversational example now includes a live room-temperature read.<br/>
+- **KNX AI — request-language confirmation instructions**: whenever validated commands are waiting for confirmation, the assistant now always appends deterministic confirmation/cancellation instructions in the current request language. Explicit message language remains authoritative, followed by the LLM language field, local request-text detection and Telegram/configuration fallback.<br/>
+- **KNX AI — button-ready confirmation metadata**: pending confirmation replies now expose `msg.knxAi.confirmationRequest` with session, expiry, command count and localized `confirm`/`cancel` actions. Each action includes a stable `callbackData` value and a ready-to-send Node-RED message, allowing Telegram and other chat nodes to present buttons instead of requiring typed confirmation.<br/>
+- **KNX AI — input message passthrough**: every AI Assistant and KNX command output now includes an independent copy of the triggering input message in `msg.inputMessage`, preserving Telegram/chat metadata and custom flow properties for downstream routing. Message-cloning and output-dispatch failures are contained and reported so malformed custom properties or downstream runtime errors cannot produce an uncaught exception or rejection.<br/>
+- **KNX AI — streamlined vertical editor tabs**: the editor now opens on a compact **Quick setup** tab containing only the common AI choices (enable, provider, credential, model, KNX commands and confirmation). Capture, storage, detection, AI context and advanced connection controls use the same left-hand vertical tab layout and shared CSS as the Matter editors, with technical fields grouped by topic and no changes to persisted field IDs or configuration values.<br/>
+- **KNX AI — selectable chat adapters and direct Telegrambot wiring**: a new **Chat adapters** tab loads preset input/output mappings from `resources/KNXAIChatAdapterMappings.js` and inserts their editable synchronous JavaScript into two persisted, full-width text boxes. The included `windkh/node-red-contrib-telegrambot` preset accepts receiver text and callback-query events directly, preserves chat/session/language data, converts output 3 directly to the Telegram sender contract and creates localized inline confirmation buttons from `msg.knxAi.confirmationRequest`. Adapter syntax/runtime failures are contained and reported, while unrelated outputs remain protected. A ready-to-import direct receiver/event → KNX AI → sender example is included under `examples/`; the Telegram package remains an optional external dependency.<br/>
+- **KNX AI — chat model compatibility**: the refreshed OpenAI-compatible model list now excludes known legacy completion-only models such as `gpt-3.5-turbo-instruct`, `davinci-002` and `babbage-002`. If a manually entered or third-party model rejects `/v1/chat/completions`, the assistant now reports the selected model and endpoint and suggests a compatible chat model instead of forwarding the provider's opaque error unchanged. Models that accept only the default temperature are retried without the custom `temperature` field, and token-limit fallbacks can be combined in the same request without discarding the prompt or conversation.<br/>
 - **Control Matter from KNX — contextual flow PIN help**: **Node Input/Output PINs** now reveals the capability-driven **Flow input** section directly below the selector instead of adding a separate editor tab. The section remains hidden while the pins are disabled. Light endpoints now receive contextual, copyable examples for their supported top-level `msg.on`, `msg.dimming`, `msg.color_temperature` and `msg.color` contracts, while non-light endpoints retain their advertised simple and advanced Matter examples.<br/>
 - **Matter Bridge — contextual flow PIN help**: **Node Input/Output PINs** now sits outside the editor tabs and, when enabled, reveals a contextual **Flow input/output** section directly below it. Copyable Flow → Matter and Matter → Flow examples are filtered to the selected device type, covering lights, covers, thermostats, fans, sensors, alarms and the flow-only robot vacuum while documenting only the message contracts already accepted or emitted by the runtime.<br/>
 

package/examples/KNX AI - Conversational Control with Confirmation.json

@@ -0,0 +1,374 @@
+[
+  {
+    "id": "tab_knx_ai_control",
+    "type": "tab",
+    "label": "KNX AI - Conversational control",
+    "disabled": false,
+    "info": "Example of fresh KNX state reads and conversational actuator control with a mandatory confirmation step for writes."
+  },
+  {
+    "id": "cmt_knx_ai_control_setup",
+    "type": "comment",
+    "z": "tab_knx_ai_control",
+    "name": "1. Configure the KNX gateway, import the ETS CSV and configure the LLM/API key in KNX AI",
+    "info": "The AI only uses exact group addresses and DPTs found in the ETS catalog imported by the KNX gateway configuration node. Any exact object may be read; only command objects may be written.",
+    "x": 490,
+    "y": 40,
+    "wires": []
+  },
+  {
+    "id": "cmt_knx_ai_control_warning",
+    "type": "comment",
+    "z": "tab_knx_ai_control",
+    "name": "WARNING: reads are immediate; after CONFERMA output 4 writes validated commands to the real KNX bus",
+    "info": "Test with safe group addresses. Fresh reads need no confirmation. A pending write plan expires after five minutes and belongs only to the same chatId.",
+    "x": 470,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "cmt_knx_ai_control_input",
+    "type": "comment",
+    "z": "tab_knx_ai_control",
+    "name": "Telegram receiver or the demo buttons",
+    "info": "A Telegram receiver can be connected directly when its message contains the text and chat identifier. The demo inject nodes use chatId=demo-chat-1.",
+    "x": 190,
+    "y": 140,
+    "wires": []
+  },
+  {
+    "id": "inj_knx_ai_control_ask",
+    "type": "inject",
+    "z": "tab_knx_ai_control",
+    "name": "1. Richiesta: accendi la luce",
+    "props": [
+      {
+        "p": "payload",
+        "v": "Accendi la luce del soggiorno",
+        "vt": "str"
+      },
+      {
+        "p": "topic",
+        "v": "ask",
+        "vt": "str"
+      },
+      {
+        "p": "chatId",
+        "v": "demo-chat-1",
+        "vt": "str"
+      },
+      {
+        "p": "language",
+        "v": "it",
+        "vt": "str"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 190,
+    "y": 180,
+    "wires": [
+      [
+        "node_knx_ai_control"
+      ]
+    ]
+  },
+  {
+    "id": "inj_knx_ai_control_confirm",
+    "type": "inject",
+    "z": "tab_knx_ai_control",
+    "name": "2. CONFERMA (stessa chat)",
+    "props": [
+      {
+        "p": "payload",
+        "v": "CONFERMA",
+        "vt": "str"
+      },
+      {
+        "p": "topic",
+        "v": "ask",
+        "vt": "str"
+      },
+      {
+        "p": "chatId",
+        "v": "demo-chat-1",
+        "vt": "str"
+      },
+      {
+        "p": "language",
+        "v": "it",
+        "vt": "str"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 180,
+    "y": 220,
+    "wires": [
+      [
+        "node_knx_ai_control"
+      ]
+    ]
+  },
+  {
+    "id": "inj_knx_ai_control_read",
+    "type": "inject",
+    "z": "tab_knx_ai_control",
+    "name": "Lettura: temperatura attuale dal bus",
+    "props": [
+      {
+        "p": "payload",
+        "v": "Richiedi al bus KNX la temperatura attuale del soggiorno e dimmi il valore",
+        "vt": "str"
+      },
+      {
+        "p": "topic",
+        "v": "ask",
+        "vt": "str"
+      },
+      {
+        "p": "chatId",
+        "v": "demo-chat-1",
+        "vt": "str"
+      },
+      {
+        "p": "language",
+        "v": "it",
+        "vt": "str"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 200,
+    "y": 300,
+    "wires": [
+      [
+        "node_knx_ai_control"
+      ]
+    ]
+  },
+  {
+    "id": "inj_knx_ai_control_cancel",
+    "type": "inject",
+    "z": "tab_knx_ai_control",
+    "name": "Oppure ANNULLA (stessa chat)",
+    "props": [
+      {
+        "p": "payload",
+        "v": "ANNULLA",
+        "vt": "str"
+      },
+      {
+        "p": "topic",
+        "v": "ask",
+        "vt": "str"
+      },
+      {
+        "p": "chatId",
+        "v": "demo-chat-1",
+        "vt": "str"
+      },
+      {
+        "p": "language",
+        "v": "it",
+        "vt": "str"
+      }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 190,
+    "y": 260,
+    "wires": [
+      [
+        "node_knx_ai_control"
+      ]
+    ]
+  },
+  {
+    "id": "node_knx_ai_control",
+    "type": "knxUltimateAI",
+    "z": "tab_knx_ai_control",
+    "server": "cfg_knx_ai_control",
+    "name": "KNX AI with confirmation",
+    "topic": "knx-ai",
+    "notifyreadrequest": true,
+    "notifyresponse": true,
+    "notifywrite": true,
+    "analysisWindowSec": "120",
+    "historyWindowSec": "600",
+    "historyStoreToDisk": false,
+    "historyStoreRetentionDays": "10",
+    "emitIntervalSec": "0",
+    "topN": "10",
+    "maxEvents": "50000",
+    "rateWindowSec": "10",
+    "maxTelegramPerSecOverall": "0",
+    "maxTelegramPerSecPerGA": "0",
+    "flapWindowSec": "30",
+    "flapMaxChanges": "0",
+    "enablePattern": true,
+    "patternMaxLagMs": "1500",
+    "patternMinCount": "8",
+    "llmEnabled": true,
+    "llmProvider": "openai_compat",
+    "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
+    "llmModel": "gpt-5.4",
+    "llmSystemPrompt": "Sei un assistente per un impianto KNX. Rispondi in italiano e proponi solo comandi necessari e coerenti con la richiesta.",
+    "llmIncludeRaw": false,
+    "llmIncludeFlowContext": true,
+    "llmIncludeDocsSnippets": true,
+    "llmDocsLanguage": "it",
+    "llmAllowKnxCommands": true,
+    "llmRequireCommandConfirmation": true,
+    "x": 520,
+    "y": 220,
+    "wires": [
+      [
+        "dbg_knx_ai_control_summary"
+      ],
+      [
+        "dbg_knx_ai_control_anomalies"
+      ],
+      [
+        "dbg_knx_ai_control_reply"
+      ],
+      [
+        "dbg_knx_ai_control_command",
+        "node_knx_ai_control_universal"
+      ]
+    ]
+  },
+  {
+    "id": "dbg_knx_ai_control_summary",
+    "type": "debug",
+    "z": "tab_knx_ai_control",
+    "name": "1 - Summary",
+    "active": false,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 760,
+    "y": 140,
+    "wires": []
+  },
+  {
+    "id": "dbg_knx_ai_control_anomalies",
+    "type": "debug",
+    "z": "tab_knx_ai_control",
+    "name": "2 - Anomalies",
+    "active": false,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 770,
+    "y": 180,
+    "wires": []
+  },
+  {
+    "id": "dbg_knx_ai_control_reply",
+    "type": "debug",
+    "z": "tab_knx_ai_control",
+    "name": "3 - Risposta/anteprima per Telegram",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 840,
+    "y": 220,
+    "wires": []
+  },
+  {
+    "id": "dbg_knx_ai_control_command",
+    "type": "debug",
+    "z": "tab_knx_ai_control",
+    "name": "4 - Operazione KNX (lettura/scrittura)",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 820,
+    "y": 260,
+    "wires": []
+  },
+  {
+    "id": "node_knx_ai_control_universal",
+    "type": "knxUltimate",
+    "z": "tab_knx_ai_control",
+    "server": "cfg_knx_ai_control",
+    "topic": "0/0/0",
+    "dpt": "1.001",
+    "initialread": false,
+    "notifyreadrequest": false,
+    "notifyresponse": true,
+    "notifywrite": true,
+    "notifyreadrequestalsorespondtobus": false,
+    "notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized": "",
+    "listenallga": true,
+    "setTopicType": "listenAllGA",
+    "name": "KNX Ultimate - Universal Mode",
+    "outputtype": "write",
+    "outputRBE": false,
+    "inputRBE": false,
+    "x": 820,
+    "y": 340,
+    "wires": [
+      [
+        "dbg_knx_ai_control_bus"
+      ]
+    ]
+  },
+  {
+    "id": "dbg_knx_ai_control_bus",
+    "type": "debug",
+    "z": "tab_knx_ai_control",
+    "name": "Telegrammi KNX ricevuti",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 1070,
+    "y": 340,
+    "wires": []
+  },
+  {
+    "id": "cmt_knx_ai_control_output",
+    "type": "comment",
+    "z": "tab_knx_ai_control",
+    "name": "Replace Debug 3 with your Telegram sender node",
+    "info": "The third output carries the text in msg.payload. Fresh reads are returned after KNX feedback and detailed in msg.knxAi.readResults. When a write confirmation is pending, msg.knxAi.confirmationRequest contains localized button labels, callbackData values and ready-to-send confirm/cancel messages. Every message on outputs 3 and 4 also preserves the triggering input in msg.inputMessage.",
+    "x": 850,
+    "y": 100,
+    "wires": []
+  },
+  {
+    "id": "cfg_knx_ai_control",
+    "type": "knxUltimate-config",
+    "z": "",
+    "host": "224.0.23.12",
+    "port": "3671",
+    "physAddr": "15.15.202",
+    "suppressACKRequest": false,
+    "csv": "",
+    "KNXEthInterface": "Auto",
+    "KNXEthInterfaceManuallyInput": "",
+    "autoReconnect": "yes"
+  }
+]

package/examples/KNX AI - Telegrambot Direct Chat.json

@@ -0,0 +1,221 @@
+[
+  {
+    "id": "tab_knx_ai_telegram",
+    "type": "tab",
+    "label": "KNX AI - Telegrambot direct chat",
+    "disabled": false,
+    "info": "Direct chat wiring for windkh/node-red-contrib-telegrambot using the KNX AI chat-adapter preset."
+  },
+  {
+    "id": "comment_knx_ai_telegram_setup",
+    "type": "comment",
+    "z": "tab_knx_ai_telegram",
+    "name": "1. Open KNX AI → Chat adapters → select windkh/node-red-contrib-telegrambot",
+    "info": "Selecting the preset inserts the editable input and output mappings. Then configure the KNX gateway, import the ETS CSV, set the LLM credentials and configure the Telegram bot token.",
+    "x": 500,
+    "y": 40,
+    "wires": []
+  },
+  {
+    "id": "comment_knx_ai_telegram_warning",
+    "type": "comment",
+    "z": "tab_knx_ai_telegram",
+    "name": "Reads are immediate; actuator writes require the Telegram confirmation button",
+    "info": "Use safe KNX group addresses while testing. Confirmation is enabled by default and pending write plans expire after five minutes.",
+    "x": 500,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "telegram_receiver_knx_ai",
+    "type": "telegram receiver",
+    "z": "tab_knx_ai_telegram",
+    "name": "Telegram text",
+    "bot": "telegram_bot_knx_ai",
+    "saveDataDir": "",
+    "filterCommands": false,
+    "x": 170,
+    "y": 180,
+    "wires": [
+      [
+        "node_knx_ai_telegram"
+      ],
+      []
+    ]
+  },
+  {
+    "id": "telegram_callback_knx_ai",
+    "type": "telegram event",
+    "z": "tab_knx_ai_telegram",
+    "name": "Confirm / Cancel buttons",
+    "bot": "telegram_bot_knx_ai",
+    "event": "callback_query",
+    "autoanswer": true,
+    "x": 190,
+    "y": 240,
+    "wires": [
+      [
+        "node_knx_ai_telegram"
+      ]
+    ]
+  },
+  {
+    "id": "node_knx_ai_telegram",
+    "type": "knxUltimateAI",
+    "z": "tab_knx_ai_telegram",
+    "server": "cfg_knx_ai_telegram",
+    "name": "KNX AI + Telegram adapter",
+    "topic": "knx-ai",
+    "notifyreadrequest": true,
+    "notifyresponse": true,
+    "notifywrite": true,
+    "analysisWindowSec": "120",
+    "historyWindowSec": "600",
+    "historyStoreToDisk": false,
+    "historyStoreRetentionDays": "10",
+    "emitIntervalSec": "0",
+    "topN": "10",
+    "maxEvents": "50000",
+    "rateWindowSec": "10",
+    "maxTelegramPerSecOverall": "0",
+    "maxTelegramPerSecPerGA": "0",
+    "flapWindowSec": "30",
+    "flapMaxChanges": "0",
+    "enablePattern": true,
+    "patternMaxLagMs": "1500",
+    "patternMinCount": "8",
+    "llmEnabled": true,
+    "llmProvider": "openai_compat",
+    "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
+    "llmModel": "gpt-5.4",
+    "llmSystemPrompt": "Sei un assistente per un impianto KNX. Rispondi nella lingua dell'utente.",
+    "llmIncludeRaw": false,
+    "llmIncludeFlowContext": true,
+    "llmIncludeDocsSnippets": true,
+    "llmDocsLanguage": "it",
+    "llmAllowKnxCommands": true,
+    "llmRequireCommandConfirmation": true,
+    "chatAdapterPreset": "none",
+    "chatInputCode": "",
+    "chatOutputCode": "",
+    "x": 500,
+    "y": 210,
+    "wires": [
+      [],
+      [],
+      [
+        "telegram_sender_knx_ai",
+        "debug_knx_ai_telegram_reply"
+      ],
+      [
+        "node_knx_ai_telegram_universal"
+      ]
+    ]
+  },
+  {
+    "id": "telegram_sender_knx_ai",
+    "type": "telegram sender",
+    "z": "tab_knx_ai_telegram",
+    "name": "Telegram reply",
+    "bot": "telegram_bot_knx_ai",
+    "haserroroutput": false,
+    "outputs": 1,
+    "x": 790,
+    "y": 180,
+    "wires": [
+      []
+    ]
+  },
+  {
+    "id": "debug_knx_ai_telegram_reply",
+    "type": "debug",
+    "z": "tab_knx_ai_telegram",
+    "name": "Adapted Telegram msg",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 810,
+    "y": 230,
+    "wires": []
+  },
+  {
+    "id": "node_knx_ai_telegram_universal",
+    "type": "knxUltimate",
+    "z": "tab_knx_ai_telegram",
+    "server": "cfg_knx_ai_telegram",
+    "topic": "0/0/0",
+    "dpt": "1.001",
+    "initialread": false,
+    "notifyreadrequest": false,
+    "notifyresponse": true,
+    "notifywrite": true,
+    "notifyreadrequestalsorespondtobus": false,
+    "notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized": "",
+    "listenallga": true,
+    "setTopicType": "listenAllGA",
+    "name": "KNX Ultimate - Universal Mode",
+    "outputtype": "write",
+    "outputRBE": false,
+    "inputRBE": false,
+    "x": 800,
+    "y": 300,
+    "wires": [
+      [
+        "debug_knx_ai_telegram_bus"
+      ]
+    ]
+  },
+  {
+    "id": "debug_knx_ai_telegram_bus",
+    "type": "debug",
+    "z": "tab_knx_ai_telegram",
+    "name": "KNX telegrams",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 1050,
+    "y": 300,
+    "wires": []
+  },
+  {
+    "id": "telegram_bot_knx_ai",
+    "type": "telegram bot",
+    "botname": "Configure your BotFather bot",
+    "usernames": "",
+    "chatids": "",
+    "baseapiurl": "",
+    "updatemode": "polling",
+    "pollinterval": "300",
+    "usesocks": false,
+    "sockshost": "",
+    "socksport": "",
+    "socksusername": "anonymous",
+    "sockspassword": "",
+    "bothost": "",
+    "localbotport": "8443",
+    "publicbotport": "8443",
+    "privatekey": "",
+    "certificate": "",
+    "useselfsignedcertificate": false,
+    "sslterminated": false,
+    "verboselogging": false
+  },
+  {
+    "id": "cfg_knx_ai_telegram",
+    "type": "knxUltimate-config",
+    "host": "224.0.23.12",
+    "port": "3671",
+    "physAddr": "15.15.202",
+    "suppressACKRequest": false,
+    "csv": "",
+    "KNXEthInterface": "Auto",
+    "KNXEthInterfaceManuallyInput": "",
+    "autoReconnect": "yes"
+  }
+]