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 uses three main accordion sections: AI assistant contains setup, knowledge/context and provider limits; Conversations & home contains chat channels, proactive home and bounded memory; KNX traffic analysis contains bus telegram input, history/summaries and anomalies/patterns. Opening a main section shows all of its related options together. Saved field IDs and values remain unchanged.

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 and learned home memory; AI Education remains unchanged
• 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.

Proactive home intelligence and bounded memory

The Proactive home & memory subsection inside Conversations & home enables opt-in proactive notifications. From ETS hierarchy, names, roles and DPTs, the node builds a deterministic semantic model for covers, windows, doors, lights, temperature, climate, occupancy and alarms using Italian, English, German, French, Spanish and Chinese terms. The first proactive detector watches only reliably recognized non-command cover/window/door states. After the configured open duration and outside quiet hours, output 3 emits a localized message with msg.knxAi.type = "proactive_notification". It never emits output 4 or changes KNX autonomously; a subsequent user request still uses the normal validation and confirmation workflow.

The most recent chat session is remembered as the owner, or Primary recipient / chat ID can set it explicitly. A synthetic msg.inputMessage preserves this recipient so the Telegram adapter can send an unsolicited notification. Cooldown and a maximum of three proactive messages per hour prevent flooding.

The learned reference is loaded at startup from <userDir>/knxai/memory/knxai-home-memory-<node-id>.md, rewritten atomically every 15 minutes and hard-capped to the configured 64–1,024 KB (256 KB by default). It stores at most 120 significant observations, 80 aggregate habits, 80 notifications and 300 semantic ETS objects—never a raw unlimited telegram stream. Older low-priority entries are removed first. AI Education is limited to 16,000 characters and always comes from the node configuration: the AI can read it as authoritative guidance but cannot modify or overwrite it. When Education is present but the LLM cannot evaluate it, the candidate notification is suppressed rather than risking a contradiction.

Practical configuration example

This example creates a concise assistant that notifies the owner about relevant openings but accepts that the office cover may stay open:

Example for AI Education (aiEducation):

Call me Alex and answer in the same language I use.
Keep replies short unless I ask for technical details.
The office cover may remain open during the day: do not notify me about it.
Notify me when another cover, window, or door remains open unusually long.
When "living-room light" is ambiguous, ask which light I mean.
Never say that an actuator changed until a KNX status object confirms it.

With these settings:

1. If the living-room cover status remains open for 120 minutes outside quiet hours, output 3 can emit a localized proactive_notification.
2. If the office cover remains open, the LLM reads Education and suppresses that candidate notification.
3. If Alex later asks to close the living-room cover, KNX AI prepares the exact ETS command and still follows normal validation and confirmation before output 4.

Use descriptive ETS hierarchy/object names and correct status/command roles. Education can personalize decisions and wording, but it cannot authorize an invented group address, change a DPT, or bypass KNX validation.

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.

General

• Gateway: KNX Ultimate gateway/config node used as telegram source.
• Name: Node label and dashboard header name.
• Topic: Base topic used in node outputs.
• Open KNX AI Web button: Opens the full KNX AI web dashboard (/knxUltimateAI/sidebar/page).

Capture

KNX AI automatically listens to GroupValue_Write, GroupValue_Response, and GroupValue_Read telegrams. Pattern and anomaly analysis is always initialized with the built-in defaults, so no bus-event or detection setup is required.

Analysis

• Analysis window (seconds): Main analysis window used for summaries/rates.
• History window (seconds): Retention window for internal telegram history.
• Also archive captured telegrams to disk: Stores captured telegrams in knxultimatestorage/knxai/history/<node-id>/YYYY-MM-DD.jsonl in addition to RAM.
• Disk archive retention (days): Number of days kept on disk before old archive files are deleted automatically.
• Max stored events: Maximum number of telegrams kept in memory.
• Auto emit summary (seconds, 0=off): Periodic summary output interval.
• Top list size: Number of top group addresses/sources in summary.

AI Assistant

• Enable LLM assistant: Enable Ask/chat assistant features.
• Provider: Select LLM backend (OpenAI-compatible or Ollama).
• 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.
• 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: Defaults to No adapter. The JavaScript mapping editors remain hidden until an adapter is selected; selecting a preset loads and reveals its editable input/output mapping pair.
• Input mapping (chat → KNX AI): Synchronous JavaScript applied before input command processing. It uses the green JavaScript editor.
• Output mapping (KNX AI → chat): Synchronous JavaScript applied only to messages on output 3. It uses the yellow JavaScript editor.
• Enable proactive home notifications: Opt-in detector for reliably recognized open cover/window/door states; it never writes autonomously to KNX.
• Primary recipient / chat ID: Optional destination for unsolicited chat messages; otherwise the most recent Ask session is remembered.
• Notify after open (minutes): Open-duration threshold before a proactive notification can be considered; 120 minutes by default.
• Quiet hours start / end: Daily interval in which proactive messages are suppressed.
• AI Education: User-only, authoritative guidance read by the AI and never modified by it.
• Repeat cooldown (minutes): Minimum interval before the same object may notify again; 360 minutes by default.
• Maximum home-memory file (KB): Hard size limit from 64 to 1,024 KB; 256 KB by default.
• 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 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.
• Relevant help, README, and example snippets are always included automatically.
• Docs language: Preferred language for the automatically included documentation snippets.
• Refresh button: Queries the provider and loads available model IDs. Its icon spins while loading; successful completion is intentionally silent.

Advanced

• Analysis window (seconds): Main analysis window used for summaries/rates.
• Max stored events: Maximum number of telegrams kept in memory.
• Top list size: Number of top group addresses/sources in summary.

Ollama quick setup (local)

• Choose Provider = Ollama.
• Default endpoint: http://localhost:11434/api/chat.
• If no local models are found, use:
  • 1) Download model: opens the Model library page.
  • 2) Install it: downloads and installs the model locally (for example llama3.1).
• During model refresh/install, KNX AI also tries to auto-start the Ollama server when possible.
• If install fails with connection errors, ensure Ollama is running (desktop app or ollama serve).
• 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. 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.