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.

El editor utiliza tres secciones principales en acordeón: Asistente IA contiene configuración, conocimiento/contexto y límites del proveedor; Conversaciones y hogar contiene canales de chat, hogar proactivo y memoria limitada; Análisis del tráfico KNX contiene telegramas del bus, historial/resúmenes y anomalías/patrones. Al abrir una sección principal se muestran juntas todas sus opciones. Los ID y valores guardados permanecen intactos.

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: borra el historial, los contadores y la memoria del hogar aprendida; la Educación de la IA permanece sin cambios
• 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.

Inteligencia doméstica proactiva y memoria limitada

La subsección Hogar proactivo y memoria dentro de Conversaciones y hogar activa las notificaciones proactivas de forma opcional. A partir de la jerarquía ETS, nombres, roles y DPT, el nodo crea un modelo semántico determinista para persianas, ventanas, puertas, luces, temperatura, clima, presencia y alarmas usando términos italianos, ingleses, alemanes, franceses, españoles y chinos. El primer detector proactivo vigila únicamente estados que no sean de comando de persianas/ventanas/puertas reconocidos con suficiente fiabilidad. Tras el tiempo abierto configurado y fuera de las horas silenciosas, la salida 3 emite un mensaje localizado con msg.knxAi.type = "proactive_notification". Nunca emite por la salida 4 ni modifica KNX de manera autónoma; una solicitud posterior del usuario sigue pasando por la validación y confirmación normales.

La última sesión de chat se recuerda como propietario, o Destinatario principal / ID de chat permite definirla explícitamente. Un msg.inputMessage sintético conserva el destinatario para que el adaptador de Telegram pueda enviar una notificación espontánea. El tiempo de espera y el máximo de tres notificaciones proactivas por hora evitan inundar el chat.

La referencia aprendida se carga al arrancar desde <userDir>/knxai/memory/knxai-home-memory-<node-id>.md, se reescribe atómicamente cada 15 minutos y queda estrictamente limitada entre 64 y 1.024 KB configurables (256 KB de forma predeterminada). Conserva como máximo 120 observaciones importantes, 80 hábitos agregados, 80 notificaciones y 300 objetos ETS semánticos, nunca un flujo ilimitado de telegramas raw. Los elementos antiguos y de menor prioridad se eliminan primero. Educación IA está limitada a 16.000 caracteres y siempre procede de la configuración del nodo: la IA puede leerla como instrucción autoritativa, pero no modificarla ni sobrescribirla. Si existe Educación pero el LLM no puede evaluarla, la notificación candidata se suprime en lugar de arriesgarse a contradecirla.

Ejemplo práctico de configuración

Este ejemplo crea un asistente conciso que avisa sobre aperturas importantes, pero acepta que la persiana del despacho permanezca abierta:

Ejemplo para Educación IA (aiEducation):

Llámame Alex y responde en el mismo idioma que uso.
Responde brevemente, salvo que pida detalles técnicos.
La persiana del despacho puede permanecer abierta durante el día: no me avises.
Avísame si otra persiana, ventana o puerta permanece abierta demasiado tiempo.
Si «luz del salón» es ambiguo, pregúntame a qué luz me refiero.
Nunca afirmes que un actuador cambió hasta que lo confirme un objeto de estado KNX.

Con estos ajustes, la salida 3 puede emitir una proactive_notification localizada después de 120 minutos para la persiana del salón, mientras que Educación suprime el aviso de la persiana del despacho. Si Alex pide después cerrar la persiana del salón, KNX AI prepara el comando ETS exacto, pero mantiene la validación y confirmación normales antes de la salida 4.

Usa jerarquías y nombres de objetos ETS descriptivos, con roles de estado/comando correctos. Educación personaliza decisiones y texto, pero no puede inventar una dirección de grupo, cambiar un DPT ni evitar la validación KNX.

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.

General

• Gateway: gateway/config node KNX Ultimate usado como fuente de telegramas.
• Name: nombre del nodo y título del dashboard.
• Topic: topic base usado en las salidas del nodo.
• Botón Open KNX AI Web: abre el dashboard web (/knxUltimateAI/sidebar/page).

KNX AI escucha automáticamente los telegramas GroupValue_Write, GroupValue_Response y GroupValue_Read. El análisis de patrones y anomalías siempre se inicializa con los valores predeterminados internos, por lo que no es necesario configurar los eventos del bus ni la detección.

Analysis

• Analysis window (seconds): ventana principal para resumen/rate.
• History window (seconds): ventana de retención del historial interno.
• Archivar tambien en disco los telegramas capturados: guarda los telegramas tambien en knxultimatestorage/knxai/history/<node-id>/YYYY-MM-DD.jsonl, ademas de la RAM.
• Retencion del archivo en disco (dias): numero de dias que se conservan los archivos antes de borrarse automaticamente.
• Max stored events: número máximo de telegramas en memoria.
• Auto emit summary (seconds, 0=off): intervalo periódico de resumen.
• Top list size: cantidad de group addresses/fuentes en el top.

Asistente IA

• Enable LLM assistant: habilita funciones Ask/chat.
• Provider: backend LLM (OpenAI-compatible u Ollama).
• 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.
• 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: usa Sin adaptador por defecto. Los editores JavaScript permanecen ocultos hasta seleccionar un adaptador; entonces se cargan y muestran los mapeos editables de entrada y salida.
• Mapeo de entrada (chat → KNX AI): JavaScript síncrono aplicado antes de procesar el comando de entrada en el editor JavaScript verde.
• Mapeo de salida (KNX AI → chat): JavaScript síncrono aplicado solo a los mensajes de la salida 3 en el editor JavaScript amarillo.
• Activar notificaciones proactivas del hogar: detector opcional de estados abiertos de persiana/ventana/puerta reconocidos de forma fiable; nunca escribe de manera autónoma en KNX.
• Destinatario principal / ID de chat: destino opcional de mensajes espontáneos; de lo contrario se recuerda la última sesión Ask.
• Avisar después de abierta (minutos): umbral de duración antes de considerar una notificación proactiva; 120 minutos por defecto.
• Inicio / fin de horas silenciosas: intervalo diario en el que se suprimen los mensajes proactivos.
• Educación de la IA: instrucciones vinculantes gestionadas solo por el usuario, leídas por la IA y nunca modificadas.
• Tiempo de espera de repetición (minutos): intervalo mínimo antes de que el mismo objeto pueda volver a avisar; 360 minutos por defecto.
• Archivo máximo de memoria del hogar (KB): límite estricto de 64 a 1.024 KB; 256 KB por defecto.
• 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.
• 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.
• Los fragmentos pertinentes de la ayuda, README y ejemplos se incluyen siempre de forma automática.
• Docs language: idioma preferido para los fragmentos de documentación incluidos automáticamente.
• Botón Refresh: consulta el provider y carga los modelos disponibles. El icono gira durante la carga; una finalización correcta no muestra ningún mensaje.

Advanced

• Analysis window (seconds): ventana principal para resumen/rate.
• Max stored events: número máximo de telegramas en memoria.
• Top list size: cantidad de group addresses/fuentes en el top.

Configuración rápida de Ollama (local)

• Selecciona Provider = Ollama.
• Endpoint por defecto: http://localhost:11434/api/chat.
• Si no hay modelos locales:
  • 1) Download model: abre la página Model library.
  • 2) Install it: descarga e instala el modelo localmente (p. ej. llama3.1).
• Durante refresh/instalación, KNX AI también intenta iniciar automáticamente el servidor Ollama.
• Si la instalación falla con error de conexión, verifica que Ollama esté ejecutándose (app de escritorio o ollama serve).
• 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. 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.