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

package/nodes/locales/de/knxUltimateMatterControllerDevice.json

@@ -17,6 +17,7 @@
     "input_help_endpoint_hint": "Der Knoten kennt Node ID und Endpoint ID bereits; einfache Nachrichten benötigen sie nicht.",
     "input_help_simple_title": "Einfache Nachrichten",
     "input_help_simple_hint": "Diese Funktionen verwenden verständliche Einheiten und werden in den Matter-Cluster, Befehl oder das Attribut des ausgewählten Endpunkts übersetzt.",
+    "input_help_light_hint": "Licht-Endpunkte akzeptieren Lichtzustands-Eigenschaften direkt in msg (nicht in msg.payload). Es werden nur die von der ausgewählten Leuchte unterstützten Steuerungen angezeigt.",
     "input_help_advanced_title": "Erweiterte Matter-Details",
     "input_help_advanced_hint": "Es werden nur angekündigte Attribute und Befehle aufgelistet. Schreibbeispiele verwenden 0 als Platzhalter; Befehlsargumente müssen eventuell an den Matter-Datentyp angepasst werden.",
     "input_help_operation": "Operation",
@@ -31,7 +32,7 @@
     "input_help_no_simple": "Dieser Endpunkt besitzt keine bekannte einfache Eingangsfunktion.",
     "input_help_no_structure": "Die Matter-Struktur ist nicht verfügbar. Aktualisiere die Geräteliste, während der Endpunkt online ist.",
     "input_functions": {
-      "onoff": "Ein / Aus", "level": "Stufe", "position": "Rollladenposition", "tiltposition": "Lamellenposition", "open": "Öffnen", "close": "Schließen", "stop": "Stopp", "setpoint": "Heizsollwert", "coolingsetpoint": "Kühlsollwert", "currenttemp": "Aktuelle Temperatur", "fanspeed": "Lüftergeschwindigkeit", "temperature": "Temperatur", "humidity": "Luftfeuchtigkeit", "illuminance": "Beleuchtungsstärke", "occupancy": "Belegung", "contact": "Kontakt", "battery": "Batterie", "activepower": "Wirkleistung", "importedenergy": "Bezogene Energie", "identify": "Identifizieren", "lock": "Verriegeln", "unlock": "Entriegeln"
+      "onoff": "Ein / Aus", "on": "Ein", "off": "Aus", "level": "Stufe", "brightness": "Helligkeit", "color_temperature": "Farbtemperatur", "xy_color": "XY-Farbe", "position": "Rollladenposition", "tiltposition": "Lamellenposition", "open": "Öffnen", "close": "Schließen", "stop": "Stopp", "setpoint": "Heizsollwert", "coolingsetpoint": "Kühlsollwert", "currenttemp": "Aktuelle Temperatur", "fanspeed": "Lüftergeschwindigkeit", "temperature": "Temperatur", "humidity": "Luftfeuchtigkeit", "illuminance": "Beleuchtungsstärke", "occupancy": "Belegung", "contact": "Kontakt", "battery": "Batterie", "activepower": "Wirkleistung", "importedenergy": "Bezogene Energie", "identify": "Identifizieren", "lock": "Verriegeln", "unlock": "Entriegeln"
     },
     "tabs": {
       "switch": "Schalten",

package/nodes/locales/en/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 This node listens to **all KNX telegrams** from the selected KNX Ultimate gateway, builds traffic statistics, detects anomalies, and can optionally query an LLM.
 
+The editor sections use the same left-hand vertical tabs as the Matter nodes. **Quick setup** contains only the common AI choices (enable, provider, credentials, model, KNX state reads/actuator control and confirmation); technical settings are grouped by topic in the other tabs.
+
 ## Outputs
 1. **Summary/Stats** (`msg.payload` JSON)
 2. **Anomalies** (`msg.payload` JSON)
 3. **AI Assistant** (`msg.payload` text, with `msg.summary`)
+4. **KNX operations** (one Universal Mode message per validated read or write)
+
+Every message emitted by outputs 3 and 4 also contains a clone of the original input message in `msg.inputMessage`. This preserves the original payload, topic, chat metadata, and any other input properties for downstream nodes. Cloning and output errors are contained and reported instead of escaping into the Node-RED runtime.
 
 ## Commands (input)
 Send `msg.topic`:
 - `summary` (or empty): emit summary immediately
 - `reset`: clear internal history/counters
 - `ask`: send a question to the configured LLM
+- `confirm` / `cancel`: confirm or cancel pending KNX commands without calling the LLM
+- `clear_chat`: clear the conversation memory for the current session
+
+For `ask`, provide the question in `msg.prompt` (preferred), `msg.payload` (string), or the common Telegram fields `msg.payload.content` / `msg.payload.text`.
+
+When KNX control is enabled, recent turns are remembered in RAM per `msg.knxAi.sessionId`, `msg.sessionId`, or a detected Telegram chat ID. Wire output 3 back to the chat sender and output 4 to a KNX Ultimate node configured in **Universal mode**. With confirmation enabled, the first reply previews every write GA, DPT, and payload without emitting writes; the same session must then reply `CONFIRM`/`CANCEL` (localized equivalents are accepted) within 5 minutes. A new request replaces any older pending plan. Each confirmed command has `msg.destination`, `msg.dpt`, `msg.payload`, and `msg.event = "GroupValue_Write"`.
+For DPT 1.xxx writes, safe AI equivalents `true`/`false`, `1`/`0`, and `on`/`off` are normalized to a real boolean before local validation and output.
+
+### Fresh KNX reads
+When the user explicitly asks for a fresh/current state, the AI may query exact objects from the imported ETS catalog, including status and other read-only objects. Output 4 emits `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"`, and `msg.readstatus = true`. The node waits up to 6 seconds for each `GroupValue_Response` or fresh write, then returns the decoded values on output 3 and exposes details in `msg.knxAi.readResults`. Reads never require confirmation and never become writes.
+
+### Confirmation request for chat buttons
+While a plan is pending, output 3 contains `msg.knxAi.confirmationRequest`. The object includes `required`, `status`, `sessionId`, `expiresAt`, `commandCount`, and two entries in `actions`. Use `action.label` as the Telegram button text, `action.callbackData` as its callback, and send `action.message` back to KNX AI to confirm or cancel without typed text.
+
+### Chat adapter presets
+The **Chat adapters** tab loads its selectable mappings from `resources/KNXAIChatAdapterMappings.js`. Selecting a preset inserts two editable synchronous JavaScript mappings in full-width text boxes: one before KNX AI processes an input and one before output 3 is emitted. Return `msg` to continue or no value to discard the message. Syntax and execution failures are caught and reported without stopping Node-RED.
+
+The included **windkh/node-red-contrib-telegrambot** preset follows the package's receiver/sender contract. Connect a `telegram receiver` directly to KNX AI, output 3 directly to a `telegram sender`, and—when inline confirmation buttons are required—connect a `telegram event` configured for `callback_query` to the same KNX AI input. The input mapping extracts `msg.payload.content`, `msg.payload.chatId`, and the Telegram language. The output mapping creates the required `msg.payload.chatId`, `type`, and `content`, adding `options.reply_markup` from `msg.knxAi.confirmationRequest` when writes await confirmation. The Telegram package remains a separate optional dependency.
 
-For `ask`, provide the question in `msg.prompt` (preferred) or `msg.payload` (string).
+## Quick workflow: KNX control
+1. Import the ETS CSV into the gateway and configure the LLM provider, model, and credentials.
+2. Enable **LLM assistant** and **KNX state reads and actuator control**; leave confirmation enabled.
+3. Connect the chat input to KNX AI while preserving a stable session/chat ID.
+4. Connect output 3 to the chat reply and output 4 to KNX Ultimate in **Universal mode**.
+5. The user sends a request; fresh state requests are read immediately, while writes first show the proposed GA, DPT, and value without writing to the bus.
+6. Within 5 minutes, the same chat replies exactly `CONFIRM` or `CANCEL`.
+7. Only `CONFIRM` revalidates and emits commands on output 4; verify execution through a KNX status GA.
 
 ## Configuration fields
 All fields exposed in the KNX AI editor are listed below.
@@ -53,7 +83,13 @@ All fields exposed in the KNX AI editor are listed below.
 - **Endpoint URL**: Chat/completions endpoint URL.
 - **API key**: API key (not required for local Ollama).
 - **Model**: Model ID/name.
+- **Chat model compatibility**: The selected model must support the configured Chat Completions endpoint. Legacy completion-only models such as `gpt-3.5-turbo-instruct` are excluded when the model list is refreshed. If the provider rejects a custom temperature or token-limit parameter, KNX AI retries after removing or replacing only that incompatible field.
 - **System prompt**: Global instruction for KNX analysis behavior (Advanced).
+- **Allow AI to read KNX states and control actuators**: Enables output 4 and is off by default. Exact ETS catalog objects may be read; writes are accepted only for objects classified as `command`. Unknown, DPT-mismatched, invalid, or excessive operations and writes to status/neutral objects are rejected locally.
+- **Ask for confirmation before sending KNX commands**: Enabled by default. Shows the validated changes first and emits no KNX command until the same chat session confirms them. Whenever commands are awaiting confirmation, the response always appends the exact confirmation/cancellation instructions in the language of the current request. Commands are validated again immediately before output.
+- **Adapter preset**: Loads an input/output mapping pair from the packaged chat-adapter file. Selecting a preset intentionally replaces both mapping text boxes; they remain editable afterwards.
+- **Input mapping (chat → KNX AI)**: Synchronous JavaScript applied before input command processing.
+- **Output mapping (KNX AI → chat)**: Synchronous JavaScript applied only to messages on output 3.
 - If disk archive is enabled, **Ask** uses the archive by default: explicit dates/ranges are honored, otherwise the assistant searches the last 24 hours plus current RAM events.
 - **Include raw payload hex**: Include raw telegram hex in prompt.
 - **Include Node-RED project inventory**: Include the whole Node-RED project inventory in the prompt, including KNX nodes and other useful nodes such as function/change/inject/template when they contain KNX-related logic or group addresses.
@@ -84,5 +120,5 @@ All fields exposed in the KNX AI editor are listed below.
 - If Node-RED runs in Docker, use `host.docker.internal` instead of `localhost` in the endpoint URL.
 
 ## Security note
-If LLM is enabled, KNX traffic context can be sent to the configured endpoint. Use local providers if you need strict on-prem data handling.
+If LLM is enabled, KNX traffic context can be sent to the configured endpoint. Use local providers if you need strict on-prem data handling. A command emitted on output 4 passed local validation and was forwarded to the flow; it is not proof that the actuator executed it. Use a KNX status GA when confirmation is required.
 </script>

package/nodes/locales/en/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Quick setup",
       "capture": "Capture",
       "storage": "Storage & Summary",
       "detection": "Detection & Alerts",
       "llmConnection": "AI Assistant Connection",
       "llmContext": "AI Assistant Context",
-      "advanced": "Advanced Tuning"
+      "chatAdapter": "Chat adapters",
+      "advanced": "Advanced AI"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Include Node-RED project inventory",
+      "llmAllowKnxCommands": "Allow AI to read KNX states and control actuators",
+      "llmRequireCommandConfirmation": "Ask for confirmation before sending KNX commands",
+      "chatAdapterPreset": "Adapter preset",
+      "chatInputCode": "Input mapping (chat → KNX AI)",
+      "chatOutputCode": "Output mapping (KNX AI → chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Summary/Stats",
       "anomalies": "Anomalies",
-      "assistant": "AI Assistant"
+      "assistant": "AI Assistant",
+      "knxCommands": "KNX operations"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "No adapter"
       }
     },
     "buttons": {
@@ -69,7 +80,9 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Choose a mapping preset to insert its input and output code. The list is loaded from the packaged chat-adapter mappings file; the generated code remains editable.",
+      "chatAdapterCodeHelp": "Mappings run synchronously. Return msg to continue or return no value to discard it. Errors are caught and reported without stopping Node-RED."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/en/knxUltimateMatterBridge.html

@@ -45,7 +45,7 @@ These options are hidden unless they apply to the selected type. Dimmable device
 
 ## Node PINs
 
-If you enable the node input/output PINs:
+The PIN selector is outside the editor tabs. Enabling it reveals a contextual **Flow input/output** section directly below, with copyable examples filtered to the selected device type:
 
 - **Input**: update the Matter state from the flow, without the KNX bus: `msg.payload = { function: "onoff", value: true }` (`function` is one of `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). Useful to expose flow-computed values (e.g. a virtual sensor) to Alexa & Co.
 - **Output**: every command received from a Matter controller is forwarded to the flow: `msg.topic` = device name, `msg.payload` = value, `msg.matter` = the raw command. A device without command GAs becomes a **flow-only device**.

package/nodes/locales/en/knxUltimateMatterBridge.json

@@ -36,6 +36,20 @@
       "mappings": "KNX mappings",
       "advanced": "Advanced options"
     },
+    "flow_help": {
+      "title": "Flow input/output",
+      "intro": "These examples match the selected device type and are available while the node input/output PINs are enabled.",
+      "input_title": "Flow → Matter (node input)",
+      "input_hint": "Send one of these messages to update the exposed Matter state without writing to KNX.",
+      "output_title": "Matter → Flow (node output)",
+      "output_hint": "Commands received from a Matter controller are emitted with the value in msg.payload and raw routing details in msg.matter.",
+      "function": "Function",
+      "message": "Example message",
+      "copy": "Copy",
+      "copied": "Message copied",
+      "no_input": "This device type has no flow state-update examples.",
+      "no_output": "This device type does not emit controller commands; its output remains silent."
+    },
     "functions": {
       "fn_onoff_cmd": "On/Off command GA",
       "fn_onoff_status": "On/Off status GA",

package/nodes/locales/en/knxUltimateMatterControllerDevice.html

@@ -19,11 +19,11 @@ It replaces the unpublished per-device Matter controller nodes and keeps the ful
 | Sensors | Sensor endpoints expose their measurement/status GA only when supported: temperature, humidity, illuminance, occupancy, contact and battery. |
 | Read at startup | Publishes the cached Matter value at deploy/startup or when the device reconnects. |
 | Update local state from KNX write | Updates the local Matter/KNX cache when a telegram is written on a configured KNX GA. |
-| Node Input/Output PINs | Shows Node-RED input/output pins. Non-light endpoints accept the simple `{function,value}` contract below as well as the advanced Matter fields; output emits state updates. The selection is preserved when the editor is reopened. |
+| Node Input/Output PINs | Shows Node-RED input/output pins and reveals the **Flow input** section directly below this field. Lights show their supported top-level light-state messages; non-light endpoints show the simple `{function,value}` contract and advanced Matter fields. The selection is preserved when the editor is reopened. |
 
 ## Flow input
 
-For a selected non-light endpoint, open the **Flow input** tab in the editor. The tab is built from the endpoint's advertised structure and provides copyable examples, the selected Endpoint ID, every readable/writable attribute and every accepted command. It remains available when the node is used only by a flow without a KNX gateway.
+Enable **Node Input/Output PINs** to reveal the **Flow input** section directly below the selector. For lights it shows copyable examples for the supported top-level properties, such as `msg.on`, `msg.dimming`, `msg.color_temperature` and `msg.color`. For non-light endpoints it is built from the advertised structure and provides the selected Endpoint ID, every readable/writable attribute and every accepted command. It remains available when the node is used only by a flow without a KNX gateway.
 
 Simple writes use `msg.payload = {function:"position",value:35}`. Omit `value` to read a supported state, for example `{function:"temperature"}`; the output uses human units and includes raw routing details in `msg.matter`. Supported functions include `onoff`, `level`, `position`, `tiltposition`, `open`, `close`, `stop`, `setpoint`, `coolingsetpoint`, `currenttemp`, `fanspeed`, sensor readings and `identify`, but only when advertised by that endpoint. Door Lock accepts `{function:"lock",value:true|false}`.
 

package/nodes/locales/en/knxUltimateMatterControllerDevice.json

@@ -17,6 +17,7 @@
     "input_help_endpoint_hint": "The node already knows the Node ID and Endpoint ID, so the simple messages do not need them.",
     "input_help_simple_title": "Simple messages",
     "input_help_simple_hint": "These functions use human units and are translated to the Matter cluster, command or attribute shown by the selected endpoint.",
+    "input_help_light_hint": "Light endpoints accept light-state properties directly on msg (not inside msg.payload). Only controls supported by the selected light are shown.",
     "input_help_advanced_title": "Advanced Matter details",
     "input_help_advanced_hint": "Only advertised attributes and commands are listed. Attribute write examples use 0 as a placeholder; command arguments may need to be adapted to the Matter data type.",
     "input_help_operation": "Operation",
@@ -31,7 +32,7 @@
     "input_help_no_simple": "This endpoint has no known simple input functions.",
     "input_help_no_structure": "The Matter structure is unavailable. Refresh the device list while the endpoint is online.",
     "input_functions": {
-      "onoff": "On / Off", "level": "Level", "position": "Cover position", "tiltposition": "Cover tilt", "open": "Open", "close": "Close", "stop": "Stop", "setpoint": "Heating setpoint", "coolingsetpoint": "Cooling setpoint", "currenttemp": "Current temperature", "fanspeed": "Fan speed", "temperature": "Temperature", "humidity": "Humidity", "illuminance": "Illuminance", "occupancy": "Occupancy", "contact": "Contact", "battery": "Battery", "activepower": "Active power", "importedenergy": "Imported energy", "identify": "Identify", "lock": "Lock", "unlock": "Unlock"
+      "onoff": "On / Off", "on": "On", "off": "Off", "level": "Level", "brightness": "Brightness", "color_temperature": "Colour temperature", "xy_color": "XY colour", "position": "Cover position", "tiltposition": "Cover tilt", "open": "Open", "close": "Close", "stop": "Stop", "setpoint": "Heating setpoint", "coolingsetpoint": "Cooling setpoint", "currenttemp": "Current temperature", "fanspeed": "Fan speed", "temperature": "Temperature", "humidity": "Humidity", "illuminance": "Illuminance", "occupancy": "Occupancy", "contact": "Contact", "battery": "Battery", "activepower": "Active power", "importedenergy": "Imported energy", "identify": "Identify", "lock": "Lock", "unlock": "Unlock"
     },
     "tabs": {
       "switch": "Switch",

package/nodes/locales/es/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Este nodo escucha **todos los telegramas KNX** del gateway KNX Ultimate seleccionado, genera estadísticas de tráfico, detecta anomalías y puede consultar opcionalmente un LLM.
 
+Las secciones del editor utilizan las mismas pestañas verticales a la izquierda que los nodos Matter. **Configuración rápida** contiene solo las opciones habituales de AI (activación, proveedor, credenciales, modelo, lectura de estados/control de actuadores KNX y confirmación); los parámetros técnicos se agrupan por tema en las demás pestañas.
+
 ## Salidas
 1. **Resumen/Estadísticas** (`msg.payload` JSON)
 2. **Anomalías** (`msg.payload` JSON)
 3. **Asistente IA** (`msg.payload` texto, con `msg.summary`)
+4. **Operaciones KNX** (un mensaje Universal Mode por cada lectura o escritura validada)
+
+Cada mensaje emitido por las salidas 3 y 4 también contiene una copia del mensaje de entrada original en `msg.inputMessage`. Así, el payload, el topic, los metadatos del chat y cualquier otra propiedad de entrada permanecen disponibles para los nodos posteriores. Los errores de clonación o envío se interceptan y notifican sin propagarse al runtime de Node-RED.
 
 ## Comandos (entrada)
 Envía `msg.topic`:
 - `summary` (o vacío): emite el resumen inmediatamente
 - `reset`: limpia historial y contadores internos
 - `ask`: envía una pregunta al LLM configurado
+- `confirm` / `cancel`: confirma o cancela los comandos KNX pendientes sin volver a llamar al LLM
+- `clear_chat`: borra la memoria de conversación de la sesión actual
+
+Para `ask`, envía la pregunta en `msg.prompt` (recomendado), `msg.payload` (string), o los campos comunes de Telegram `msg.payload.content` / `msg.payload.text`.
+
+Cuando el control KNX está habilitado, los turnos recientes se guardan en RAM por `msg.knxAi.sessionId`, `msg.sessionId` o el ID de chat Telegram detectado. Conecta la salida 3 al nodo emisor del chat y la salida 4 a un nodo KNX Ultimate en **modo universal**. Con la confirmación activa, la primera respuesta muestra GA, DPT y payload sin emitir escrituras; la misma sesión debe responder `CONFIRMAR` o `CANCELAR` en 5 minutos. Una solicitud nueva sustituye cualquier plan anterior. Cada comando confirmado contiene `msg.destination`, `msg.dpt`, `msg.payload` y `msg.event = "GroupValue_Write"`.
+Para las escrituras DPT 1.xxx, los equivalentes seguros producidos por la IA `true`/`false`, `1`/`0` y `on`/`off` se normalizan a booleanos reales antes de la validación local y la salida.
+
+### Lecturas KNX actualizadas
+Cuando el usuario solicita explícitamente un estado actual o actualizado, la IA puede consultar objetos exactos del catálogo ETS importado, incluidos objetos de estado y otros objetos de solo lectura. La salida 4 emite `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` y `msg.readstatus = true`. El nodo espera hasta 6 segundos cada `GroupValue_Response` o escritura reciente, devuelve los valores decodificados por la salida 3 y expone los detalles en `msg.knxAi.readResults`. Las lecturas nunca requieren confirmación ni se convierten en escrituras.
+
+### Solicitud de confirmación para botones de chat
+Mientras un plan está pendiente, la salida 3 contiene `msg.knxAi.confirmationRequest`. El objeto incluye `required`, `status`, `sessionId`, `expiresAt`, `commandCount` y dos elementos en `actions`. Usa `action.label` como texto del botón de Telegram, `action.callbackData` como callback y devuelve `action.message` a KNX AI para confirmar o cancelar sin escribir texto.
+
+### Preajustes del adaptador de chat
+La pestaña **Adaptadores de chat** carga sus mapeos seleccionables desde `resources/KNXAIChatAdapterMappings.js`. Al elegir un preajuste se insertan dos mapeos JavaScript síncronos y editables en cuadros de texto de ancho completo: uno antes de que KNX AI procese la entrada y otro antes de emitir por la salida 3. Devuelve `msg` para continuar o ningún valor para descartar el mensaje. Los errores de sintaxis y ejecución se capturan y notifican sin detener Node-RED.
+
+El preajuste incluido **windkh/node-red-contrib-telegrambot** sigue el contrato receiver/sender del paquete. Conecta directamente un `telegram receiver` a KNX AI y la salida 3 a un `telegram sender`. Para los botones inline de confirmación, conecta también un `telegram event` configurado como `callback_query` a la misma entrada KNX AI. El mapeo de entrada extrae `msg.payload.content`, `msg.payload.chatId` y el idioma de Telegram. El mapeo de salida crea `msg.payload.chatId`, `type` y `content`, y añade `options.reply_markup` desde `msg.knxAi.confirmationRequest` cuando una escritura espera confirmación. El paquete Telegram sigue siendo una dependencia opcional separada.
 
-Para `ask`, envía la pregunta en `msg.prompt` (recomendado) o `msg.payload` (string).
+## Flujo rápido: control KNX
+1. Importa el CSV de ETS en el gateway y configura el proveedor, el modelo y las credenciales LLM.
+2. Activa **Asistente LLM** y **lectura de estados KNX y control de actuadores**; deja activada la confirmación.
+3. Conecta la entrada del chat a KNX AI manteniendo un ID de sesión/chat estable.
+4. Conecta la salida 3 a la respuesta del chat y la salida 4 a KNX Ultimate en **modo universal**.
+5. El usuario envía una solicitud; los estados actuales se leen inmediatamente, mientras que las escrituras muestran primero GA, DPT y valor sin escribir en el bus.
+6. En un plazo de 5 minutos, el mismo chat responde exactamente `CONFIRMAR` o `CANCELAR`.
+7. Solo `CONFIRMAR` vuelve a validar y emite los comandos por la salida 4; verifica la ejecución mediante una GA de estado KNX.
 
 ## Campos de configuración
 Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
@@ -53,7 +83,13 @@ Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
 - **Endpoint URL**: URL endpoint chat/completions.
 - **API key**: clave API (no requerida con Ollama local).
 - **Model**: ID/nombre de modelo.
+- **Compatibilidad del modelo de chat**: el modelo seleccionado debe admitir el endpoint Chat Completions configurado. Los modelos antiguos disponibles solo mediante completions, como `gpt-3.5-turbo-instruct`, se excluyen al actualizar la lista. Si el proveedor rechaza un valor personalizado de temperatura o el parámetro de límite de tokens, KNX AI vuelve a intentarlo eliminando o sustituyendo únicamente el campo incompatible.
 - **System prompt**: instrucción global para análisis KNX (Advanced).
+- **Permitir que la IA lea estados KNX y controle actuadores**: habilita la salida 4 y está desactivado por defecto. Los objetos exactos del catálogo ETS se pueden leer; solo se aceptan escrituras hacia objetos clasificados como `command`. Las operaciones desconocidas, con DPT distinto, inválidas o excesivas, y las escrituras hacia objetos de estado o neutrales, se rechazan localmente.
+- **Pedir confirmación antes de enviar comandos KNX**: activado por defecto. Muestra primero los cambios validados y no emite comandos hasta que la misma sesión de chat los confirme. Cuando hay comandos pendientes, la respuesta añade siempre las instrucciones exactas para confirmar o cancelar en el idioma de la solicitud actual. Los comandos se validan de nuevo justo antes de la salida.
+- **Preajuste del adaptador**: carga una pareja de mapeos entrada/salida desde el archivo de adaptadores de chat incluido. La selección sustituye intencionadamente ambos cuadros de texto; el código sigue siendo editable.
+- **Mapeo de entrada (chat → KNX AI)**: JavaScript síncrono aplicado antes de procesar el comando de entrada.
+- **Mapeo de salida (KNX AI → chat)**: JavaScript síncrono aplicado solo a los mensajes de la salida 3.
 - Si el archivo en disco esta activo, **Ask** lo usa por defecto: respeta fechas/rangos explicitos y, si no los indicas, busca en las ultimas 24 horas mas los eventos actuales en RAM.
 - **Include raw payload hex**: incluye payload hex raw en el prompt.
 - **Incluir inventario del proyecto Node-RED**: incluye en el prompt el inventario de todo el proyecto Node-RED, con nodos KNX y otros nodos utiles como function/change/inject/template cuando contienen logica KNX o direcciones de grupo.
@@ -84,5 +120,5 @@ Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
 - Si Node-RED se ejecuta en Docker, usa `host.docker.internal` en lugar de `localhost` en el endpoint.
 
 ## Nota de seguridad
-Si el LLM está habilitado, el contexto de tráfico KNX puede enviarse al endpoint configurado. Para privacidad on-premise, usa proveedores locales.
+Si el LLM está habilitado, el contexto de tráfico KNX puede enviarse al endpoint configurado. Para privacidad on-premise, usa proveedores locales. Un comando emitido por la salida 4 superó la validación local y fue enviado al flow, pero no confirma que el actuador lo ejecutara. Usa una GA de estado KNX para confirmarlo.
 </script>

package/nodes/locales/es/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Configuracion rapida",
       "capture": "Capture",
       "storage": "Historial y Resumen",
       "detection": "Deteccion y Alertas",
       "llmConnection": "Conexion del Asistente IA",
       "llmContext": "Contexto del Asistente IA",
-      "advanced": "Ajustes Avanzados"
+      "chatAdapter": "Adaptadores de chat",
+      "advanced": "IA avanzada"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Incluir inventario del proyecto Node-RED",
+      "llmAllowKnxCommands": "Permitir que la IA lea estados KNX y controle actuadores",
+      "llmRequireCommandConfirmation": "Pedir confirmación antes de enviar comandos KNX",
+      "chatAdapterPreset": "Preajuste del adaptador",
+      "chatInputCode": "Mapeo de entrada (chat → KNX AI)",
+      "chatOutputCode": "Mapeo de salida (KNX AI → chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Resumen/Estadísticas",
       "anomalies": "Anomalías",
-      "assistant": "Asistente IA"
+      "assistant": "Asistente IA",
+      "knxCommands": "Operaciones KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Sin adaptador"
       }
     },
     "messages": {
@@ -61,7 +72,9 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Elige un preajuste para insertar su código de mapeo de entrada y salida. La lista se carga desde el archivo de adaptadores de chat incluido; el código generado sigue siendo editable.",
+      "chatAdapterCodeHelp": "Los mapeos se ejecutan de forma síncrona. Devuelve msg para continuar o ningún valor para descartarlo. Los errores se capturan y notifican sin detener Node-RED."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/es/knxUltimateMatterBridge.html

@@ -45,7 +45,7 @@ Estas opciones solo aparecen cuando tienen sentido para el tipo seleccionado. Lo
 
 ## PINes del nodo
 
-Si habilitas los PINes de entrada/salida del nodo:
+El selector de PINes está fuera de las pestañas del editor. Al activarlo aparece justo debajo una sección contextual **Entrada/salida del flow**, con ejemplos copiables filtrados según el tipo de dispositivo:
 
 - **Entrada**: actualiza el estado Matter desde el flow, sin pasar por el bus KNX: `msg.payload = { function: "onoff", value: true }` (`function` es una de `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). Útil para exponer a Alexa y cía. valores calculados en el flow (p.ej. un sensor virtual).
 - **Salida**: cada comando recibido de un controlador Matter se reenvía al flow: `msg.topic` = nombre del dispositivo, `msg.payload` = valor, `msg.matter` = el comando en bruto. Un dispositivo sin GA de comando se convierte en un **dispositivo solo-flow**.

package/nodes/locales/es/knxUltimateMatterBridge.json

@@ -36,6 +36,20 @@
       "mappings": "Asignaciones KNX",
       "advanced": "Opciones avanzadas"
     },
+    "flow_help": {
+      "title": "Entrada/salida del flow",
+      "intro": "Estos ejemplos corresponden al tipo de dispositivo seleccionado y están disponibles mientras los pines de entrada/salida del nodo están activados.",
+      "input_title": "Flow → Matter (entrada del nodo)",
+      "input_hint": "Envía uno de estos mensajes para actualizar el estado Matter expuesto sin escribir en KNX.",
+      "output_title": "Matter → Flow (salida del nodo)",
+      "output_hint": "Los comandos recibidos de un controlador Matter se emiten con el valor en msg.payload y los detalles raw en msg.matter.",
+      "function": "Función",
+      "message": "Mensaje de ejemplo",
+      "copy": "Copiar",
+      "copied": "Mensaje copiado",
+      "no_input": "Este tipo de dispositivo no tiene ejemplos de actualización de estado desde el flow.",
+      "no_output": "Este tipo de dispositivo no emite comandos del controlador; su salida permanece inactiva."
+    },
     "functions": {
       "fn_onoff_cmd": "GA comando On/Off",
       "fn_onoff_status": "GA estado On/Off",

package/nodes/locales/es/knxUltimateMatterControllerDevice.html

@@ -19,11 +19,11 @@ Sustituye a los nodos Matter separados no publicados y conserva toda la UI de lu
 | Sensores | Los endpoints de sensor muestran su GA de medida/estado solo cuando está soportado: temperatura, humedad, iluminancia, ocupación, contacto y batería. |
 | Read at startup | Publica el valor Matter en caché al desplegar/iniciar o cuando el dispositivo se reconecta. |
 | Update local state from KNX write | Actualiza la caché local Matter/KNX cuando se escribe un telegrama en una GA KNX configurada. |
-| Node Input/Output PINs | Muestra pines de entrada/salida Node-RED. Los endpoints que no son luces aceptan el formato simple `{function,value}` y los campos Matter avanzados; la salida emite estados. |
+| Node Input/Output PINs | Muestra pines de entrada/salida Node-RED y la sección **Entrada del flow** justo debajo de este campo. Las luces muestran sus mensajes de estado compatibles en el nivel superior; los demás endpoints muestran el formato simple `{function,value}` y los campos Matter avanzados. |
 
 ## Entrada del flow
 
-Para un endpoint que no sea una luz, abre la pestaña **Entrada del flow**. La pestaña se construye con la estructura anunciada y muestra ejemplos copiables, el Endpoint ID, todos los atributos legibles/escribibles y los comandos aceptados. Sigue disponible cuando el nodo se usa solo desde el flow, sin gateway KNX.
+Activa **Node Input/Output PINs** para mostrar la sección **Entrada del flow** justo debajo del selector. Para una luz, muestra ejemplos copiables de las propiedades compatibles en el nivel superior, como `msg.on`, `msg.dimming`, `msg.color_temperature` y `msg.color`. Para los demás endpoints, se construye con la estructura anunciada y muestra el Endpoint ID, todos los atributos legibles/escribibles y los comandos aceptados. Sigue disponible sin gateway KNX.
 
 Una escritura simple usa `msg.payload = {function:"position",value:35}`. Omite `value` para leer un estado, por ejemplo `{function:"temperature"}`; la salida usa unidades comprensibles e incluye los detalles raw en `msg.matter`. Las funciones `onoff`, `level`, `position`, `open`, `close`, `stop`, consignas, ventilador y sensores solo aparecen si el endpoint las anuncia. Una cerradura acepta `{function:"lock",value:true|false}`.
 

package/nodes/locales/es/knxUltimateMatterControllerDevice.json

@@ -17,6 +17,7 @@
     "input_help_endpoint_hint": "El nodo ya conoce el Node ID y el Endpoint ID; los mensajes simples no los necesitan.",
     "input_help_simple_title": "Mensajes simples",
     "input_help_simple_hint": "Estas funciones usan unidades comprensibles y se traducen al clúster, comando o atributo Matter del endpoint seleccionado.",
+    "input_help_light_hint": "Los endpoints de luz aceptan propiedades de estado directamente en msg (no dentro de msg.payload). Solo se muestran los controles compatibles con la luz seleccionada.",
     "input_help_advanced_title": "Detalles Matter avanzados",
     "input_help_advanced_hint": "Solo se muestran atributos y comandos anunciados. Los ejemplos de escritura usan 0 como marcador; los argumentos de los comandos pueden requerir adaptación al tipo Matter.",
     "input_help_operation": "Operación",
@@ -31,7 +32,7 @@
     "input_help_no_simple": "Este endpoint no tiene funciones de entrada simples conocidas.",
     "input_help_no_structure": "La estructura Matter no está disponible. Actualiza la lista de dispositivos mientras el endpoint esté en línea.",
     "input_functions": {
-      "onoff": "Encender / Apagar", "level": "Nivel", "position": "Posición de persiana", "tiltposition": "Inclinación de persiana", "open": "Abrir", "close": "Cerrar", "stop": "Detener", "setpoint": "Consigna de calefacción", "coolingsetpoint": "Consigna de refrigeración", "currenttemp": "Temperatura actual", "fanspeed": "Velocidad del ventilador", "temperature": "Temperatura", "humidity": "Humedad", "illuminance": "Iluminancia", "occupancy": "Ocupación", "contact": "Contacto", "battery": "Batería", "activepower": "Potencia activa", "importedenergy": "Energía importada", "identify": "Identificar", "lock": "Bloquear", "unlock": "Desbloquear"
+      "onoff": "Encender / Apagar", "on": "Encender", "off": "Apagar", "level": "Nivel", "brightness": "Brillo", "color_temperature": "Temperatura de color", "xy_color": "Color XY", "position": "Posición de persiana", "tiltposition": "Inclinación de persiana", "open": "Abrir", "close": "Cerrar", "stop": "Detener", "setpoint": "Consigna de calefacción", "coolingsetpoint": "Consigna de refrigeración", "currenttemp": "Temperatura actual", "fanspeed": "Velocidad del ventilador", "temperature": "Temperatura", "humidity": "Humedad", "illuminance": "Iluminancia", "occupancy": "Ocupación", "contact": "Contacto", "battery": "Batería", "activepower": "Potencia activa", "importedenergy": "Energía importada", "identify": "Identificar", "lock": "Bloquear", "unlock": "Desbloquear"
     },
     "tabs": {
       "switch": "Cambiar",

package/nodes/locales/fr/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Ce nœud écoute **tous les télégrammes KNX** du gateway KNX Ultimate sélectionné, produit des statistiques de trafic, détecte des anomalies et peut interroger un LLM de façon optionnelle.
 
+Les sections de l'éditeur utilisent les mêmes onglets verticaux à gauche que les nœuds Matter. **Configuration rapide** ne contient que les choix AI courants (activation, fournisseur, identifiants, modèle, lecture des états/commande des actionneurs KNX et confirmation) ; les paramètres techniques sont regroupés par thème dans les autres onglets.
+
 ## Sorties
 1. **Résumé/Stats** (`msg.payload` JSON)
 2. **Anomalies** (`msg.payload` JSON)
 3. **Assistant IA** (`msg.payload` texte, avec `msg.summary`)
+4. **Opérations KNX** (un message Universal Mode par lecture ou écriture validée)
+
+Chaque message émis par les sorties 3 et 4 contient également une copie du message d'entrée original dans `msg.inputMessage`. Le payload, le topic, les métadonnées du chat et toutes les autres propriétés d'entrée restent ainsi disponibles pour les nœuds suivants. Les erreurs de clonage ou d'envoi sont interceptées et signalées sans se propager au runtime Node-RED.
 
 ## Commandes (entrée)
 Envoyez `msg.topic` :
 - `summary` (ou vide) : envoie le résumé immédiatement
 - `reset` : vide l'historique/compteurs internes
 - `ask` : envoie une question au LLM configuré
+- `confirm` / `cancel` : confirme ou annule les commandes KNX en attente sans rappeler le LLM
+- `clear_chat` : efface la mémoire de conversation de la session courante
+
+Pour `ask`, mettez la question dans `msg.prompt` (recommandé), `msg.payload` (chaîne), ou les champs Telegram courants `msg.payload.content` / `msg.payload.text`.
+
+Lorsque le contrôle KNX est activé, les échanges récents sont conservés en RAM par `msg.knxAi.sessionId`, `msg.sessionId` ou ID de chat Telegram détecté. Reliez la sortie 3 au nœud d'envoi du chat et la sortie 4 à un nœud KNX Ultimate en **mode universel**. Avec la confirmation active, la première réponse affiche GA, DPT et payload sans émettre d’écriture ; la même session doit répondre `CONFIRMER` ou `ANNULER` dans les 5 minutes. Une nouvelle demande remplace tout plan précédent. Chaque commande confirmée contient `msg.destination`, `msg.dpt`, `msg.payload` et `msg.event = "GroupValue_Write"`.
+Pour les écritures DPT 1.xxx, les équivalents sûrs produits par l’IA `true`/`false`, `1`/`0` et `on`/`off` sont normalisés en véritables booléens avant la validation locale et la sortie.
+
+### Lectures KNX actualisées
+Lorsque l’utilisateur demande explicitement un état actuel ou actualisé, l’IA peut interroger les objets exacts du catalogue ETS importé, y compris les objets d’état et autres objets en lecture seule. La sortie 4 émet `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` et `msg.readstatus = true`. Le nœud attend jusqu’à 6 secondes chaque `GroupValue_Response` ou écriture récente, puis renvoie les valeurs décodées sur la sortie 3 et les détails dans `msg.knxAi.readResults`. Les lectures ne nécessitent jamais de confirmation et ne sont jamais transformées en écritures.
+
+### Demande de confirmation pour les boutons du chat
+Lorsqu'un plan est en attente, la sortie 3 contient `msg.knxAi.confirmationRequest`. L'objet comprend `required`, `status`, `sessionId`, `expiresAt`, `commandCount` et deux éléments dans `actions`. Utilisez `action.label` comme texte du bouton Telegram, `action.callbackData` comme callback et renvoyez `action.message` à KNX AI pour confirmer ou annuler sans saisir de texte.
+
+### Préréglages d’adaptateur de chat
+L’onglet **Adaptateurs de chat** charge ses mappages sélectionnables depuis `resources/KNXAIChatAdapterMappings.js`. Le choix d’un préréglage insère deux mappages JavaScript synchrones et modifiables dans des zones de texte pleine largeur : un avant le traitement de l’entrée par KNX AI et un avant l’émission sur la sortie 3. Renvoyez `msg` pour continuer ou aucune valeur pour écarter le message. Les erreurs de syntaxe et d’exécution sont interceptées et signalées sans arrêter Node-RED.
+
+Le préréglage inclus **windkh/node-red-contrib-telegrambot** suit le contrat receiver/sender du paquet. Connectez directement un `telegram receiver` à KNX AI et la sortie 3 à un `telegram sender`. Pour les boutons de confirmation inline, connectez aussi un `telegram event` configuré pour `callback_query` à la même entrée KNX AI. Le mappage d’entrée extrait `msg.payload.content`, `msg.payload.chatId` et la langue Telegram. Le mappage de sortie crée `msg.payload.chatId`, `type` et `content`, puis ajoute `options.reply_markup` depuis `msg.knxAi.confirmationRequest` lorsqu’une écriture attend confirmation. Le paquet Telegram reste une dépendance optionnelle distincte.
 
-Pour `ask`, mettez la question dans `msg.prompt` (recommandé) ou `msg.payload` (chaîne).
+## Workflow rapide : contrôle KNX
+1. Importez le CSV ETS dans la passerelle et configurez le fournisseur, le modèle et les identifiants LLM.
+2. Activez **Assistant LLM** et **lecture des états KNX et commande des actionneurs** ; laissez la confirmation activée.
+3. Connectez l'entrée du chat à KNX AI en conservant un identifiant de session/chat stable.
+4. Connectez la sortie 3 à la réponse du chat et la sortie 4 à KNX Ultimate en **mode universel**.
+5. L'utilisateur envoie une demande ; les états actuels sont lus immédiatement, tandis que les écritures affichent d'abord GA, DPT et valeur sans écrire sur le bus.
+6. Dans les 5 minutes, le même chat répond exactement `CONFIRMER` ou `ANNULER`.
+7. Seul `CONFIRMER` revalide et émet les commandes sur la sortie 4 ; vérifiez l'exécution avec une GA d'état KNX.
 
 ## Champs de configuration
 Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
@@ -53,7 +83,13 @@ Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
 - **Endpoint URL** : URL endpoint chat/completions.
 - **API key** : clé API (non requise avec Ollama local).
 - **Model** : ID/nom du modèle.
+- **Compatibilité du modèle de chat** : le modèle sélectionné doit prendre en charge l'endpoint Chat Completions configuré. Les anciens modèles réservés aux completions, comme `gpt-3.5-turbo-instruct`, sont exclus lors de l'actualisation de la liste. Si le fournisseur refuse une valeur de température personnalisée ou le paramètre de limite de tokens, KNX AI réessaie en supprimant ou remplaçant uniquement le champ incompatible.
 - **System prompt** : instruction système globale pour l'analyse KNX (Advanced).
+- **Autoriser l’IA à lire les états KNX et commander les actionneurs** : active la sortie 4 et reste désactivé par défaut. Les objets exacts du catalogue ETS peuvent être lus ; seules les écritures vers des objets classés `command` sont acceptées. Les opérations inconnues, avec DPT discordant, invalides ou trop nombreuses, ainsi que les écritures vers des objets d'état ou neutres, sont rejetées localement.
+- **Demander confirmation avant d’envoyer les commandes KNX** : activé par défaut. Affiche d'abord les modifications validées et n'émet aucune commande tant que la même session de chat ne les confirme pas. Lorsque des commandes attendent une confirmation, la réponse ajoute toujours les instructions exactes de confirmation ou d'annulation dans la langue de la demande courante. Les commandes sont à nouveau validées juste avant la sortie.
+- **Préréglage d’adaptateur** : charge une paire de mappages entrée/sortie depuis le fichier d’adaptateurs de chat fourni. La sélection remplace volontairement les deux zones de texte ; le code reste ensuite modifiable.
+- **Mappage d’entrée (chat → KNX AI)** : JavaScript synchrone exécuté avant le traitement de la commande d’entrée.
+- **Mappage de sortie (KNX AI → chat)** : JavaScript synchrone appliqué uniquement aux messages de la sortie 3.
 - Si l'archive disque est active, **Ask** l'utilise par défaut : les dates/plages explicites sont respectées, sinon l'assistant cherche sur les dernières 24 heures plus les événements RAM courants.
 - **Include raw payload hex** : inclut le payload hex brut dans le prompt.
 - **Inclure l'inventaire du projet Node-RED** : inclut dans le prompt l'inventaire de tout le projet Node-RED, avec les nœuds KNX et d'autres nœuds utiles comme function/change/inject/template lorsqu'ils contiennent de la logique KNX ou des adresses de groupe.
@@ -84,5 +120,5 @@ Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
 - Si Node-RED tourne dans Docker, utiliser `host.docker.internal` au lieu de `localhost` dans l'endpoint.
 
 ## Note sécurité
-Si le LLM est activé, le contexte trafic KNX peut être envoyé à l'endpoint configuré. Pour un usage strictement on-premise, utilisez un provider local.
+Si le LLM est activé, le contexte trafic KNX peut être envoyé à l'endpoint configuré. Pour un usage strictement on-premise, utilisez un provider local. Une commande émise en sortie 4 a passé la validation locale et a été transmise au flow, sans prouver son exécution par l'actionneur. Utilisez une GA d'état KNX pour la confirmation.
 </script>

package/nodes/locales/fr/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Configuration rapide",
       "capture": "Capture",
       "storage": "Historique et Resume",
       "detection": "Detection et Alertes",
       "llmConnection": "Connexion Assistant IA",
       "llmContext": "Contexte Assistant IA",
-      "advanced": "Reglages Avances"
+      "chatAdapter": "Adaptateurs de chat",
+      "advanced": "IA avancee"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Inclure l'inventaire du projet Node-RED",
+      "llmAllowKnxCommands": "Autoriser l’IA à lire les états KNX et commander les actionneurs",
+      "llmRequireCommandConfirmation": "Demander confirmation avant d’envoyer les commandes KNX",
+      "chatAdapterPreset": "Préréglage d’adaptateur",
+      "chatInputCode": "Mappage d’entrée (chat → KNX AI)",
+      "chatOutputCode": "Mappage de sortie (KNX AI → chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Résumé/Stats",
       "anomalies": "Anomalies",
-      "assistant": "Assistant IA"
+      "assistant": "Assistant IA",
+      "knxCommands": "Opérations KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Aucun adaptateur"
       }
     },
     "messages": {
@@ -61,7 +72,9 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Choisissez un préréglage pour insérer son code de mappage d’entrée et de sortie. La liste est chargée depuis le fichier d’adaptateurs de chat fourni ; le code généré reste modifiable.",
+      "chatAdapterCodeHelp": "Les mappages s’exécutent de façon synchrone. Renvoyez msg pour continuer ou aucune valeur pour l’écarter. Les erreurs sont interceptées et signalées sans arrêter Node-RED."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/fr/knxUltimateMatterBridge.html

@@ -45,7 +45,7 @@ Ces options ne s'affichent que lorsqu'elles s'appliquent au type sélectionné.
 
 ## PIN du nœud
 
-Si vous activez les PIN entrée/sortie du nœud :
+Le sélecteur de PIN se trouve hors des onglets de l'éditeur. Son activation affiche juste dessous une section contextuelle **Entrée/sortie du flow**, avec des exemples copiables filtrés selon le type d'appareil :
 
 - **Entrée** : mettez à jour l'état Matter depuis le flux, sans passer par le bus KNX : `msg.payload = { function: "onoff", value: true }` (`function` est l'une de `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). Utile pour exposer à Alexa & Co. des valeurs calculées dans le flux (ex. un capteur virtuel).
 - **Sortie** : chaque commande reçue d'un contrôleur Matter est transmise au flux : `msg.topic` = nom de l'appareil, `msg.payload` = valeur, `msg.matter` = la commande brute. Un appareil sans GA de commande devient un **appareil flow uniquement**.

package/nodes/locales/fr/knxUltimateMatterBridge.json

@@ -36,6 +36,20 @@
       "mappings": "Mappages KNX",
       "advanced": "Options avancées"
     },
+    "flow_help": {
+      "title": "Entrée/sortie du flow",
+      "intro": "Ces exemples correspondent au type d'appareil sélectionné et sont disponibles lorsque les broches d'entrée/sortie du nœud sont activées.",
+      "input_title": "Flow → Matter (entrée du nœud)",
+      "input_hint": "Envoyez l'un de ces messages pour mettre à jour l'état Matter exposé sans écrire sur KNX.",
+      "output_title": "Matter → Flow (sortie du nœud)",
+      "output_hint": "Les commandes reçues d'un contrôleur Matter sont émises avec la valeur dans msg.payload et les détails bruts dans msg.matter.",
+      "function": "Fonction",
+      "message": "Message d'exemple",
+      "copy": "Copier",
+      "copied": "Message copié",
+      "no_input": "Ce type d'appareil ne possède aucun exemple de mise à jour d'état depuis le flow.",
+      "no_output": "Ce type d'appareil n'émet aucune commande de contrôleur ; sa sortie reste inactive."
+    },
     "functions": {
       "fn_onoff_cmd": "GA commande On/Off",
       "fn_onoff_status": "GA état On/Off",