lm-knx-engine

lm-knx-engine es el motor profesional definitivo para conectar aplicaciones React de forma segura e independiente con el bus KNX dentro de un entorno Logic Machine.

Diseñada específicamente para eliminar la redundancia de código en visualizaciones domóticas (Visu), proporcionando Tipado Estricto (Type-Safe), gestión automática de memoria, y un simulador de desarrollo local.

Características Principales

1. Tipado Súper Estricto: Nunca más enviarás basura al bus. Soporte nativo para inferencia de tipos (ej. decirle a TypeScript que tu luz es boolean o tu clima number) y validación estricta del formato de las Direcciones de Grupo (numero/numero/numero).
2. Gestión Automática de Memoria (Zero Leaks): El hook useKnx automatiza todas las suscripciones a la Logic Machine. Cuando cambias de pantalla o desmontas un componente, el motor se desuscribe automáticamente de esa dirección de grupo.
3. Simulador de Desarrollo (Localhost): ¿Cansado de que tu app se rompa porque window.grp no existe en tu PC? La librería detecta automáticamente si estás desarrollando en local y simula las actualizaciones de estado para que puedas probar tu interfaz sin tocar la máquina real.
4. Validación Segura: Todas las direcciones de grupo pasan por una validación Regex (0-61/0-7/0-255) antes de emitirse.
5. Arquitectura Singleton: Una única "central telefónica" optimizada. Si tienes 5 componentes escuchando la dirección "1/1/1", la librería solo abre una única conexión física optimizando el ancho de banda.

Instalación

En tu proyecto de frontend (ej. Next.js, Vite, Create-React-App), instala:

npm install lm-knx-engine
# o
pnpm add lm-knx-engine

Nota: La librería requiere react como dependencia (Peer Dependency).

Cómo Implementarla Fácilmente

El 99% de las veces usarás el hook principal de React: useKnx. Funciona de manera casi idéntica al clásico useState, pero conectado físicamente a la casa.

1. Control Básico (Lectura y Escritura Simples)

Cuando tu actuador de luz reporta el estado y acepta los comandos de encendido/apagado en la misma dirección de grupo. Observa cómo le decimos explícitamente a TypeScript que esperamos un valor <boolean>.

import { useKnx } from "lm-knx-engine";

export function SwitchLuz() {
  // Conectamos a la dirección "1/1/1" especificando que es un boolean
  const [encendido, setEncendido] = useKnx<boolean>("1/1/1");

  return (
    <button onClick={() => setEncendido(!encendido)}>
      {encendido ? "💡 Apagar Luz" : "💡 Encender Luz"}
    </button>
  );
}

2. Estado y Comando Separados (Patrón KNX Avanzado)

En proyectos KNX reales, normalmente lees el "status" de una dirección, pero escribes la "acción" en otra. useKnx lo hace trivial:

import { useKnx } from "lm-knx-engine";

export function SwitchProfesional() {
  // Parametro 1: GA de Escucha (Estado)
  // Parametro 2: GA de Escritura (Acción)
  const [estadoLuz, setAccion] = useKnx<boolean>("1/1/2", "1/1/3");

  return (
    <button onClick={() => setAccion(true)}>
      Encender (Estado actual: {estadoLuz ? "On" : "Off"})
    </button>
  );
}

3. Tipado Estricto de Direcciones (KNXGroupAddress)

Desde la versión 1.0.2, la librería incluye protección TypeScript de nivel dios. Cualquier dirección de grupo que ingreses debe tener el formato X/Y/Z.

import { useKnx, KNXGroupAddress } from "lm-knx-engine";

// TypeScript arrojará un error en rojo: No cumple con el formato
const [luz] = useKnx("luz-de-sala");

// Correcto
const [luz] = useKnx<boolean>("1/1/1");

// Si traes direcciones dinámicas desde una API o Base de Datos:
const miDireccion: string = "1/1/2";
const [estado] = useKnx<number>(miDireccion as KNXGroupAddress);

🛠 Uso Avanzado (Motor fuera de React)

Si necesitas comunicarte con el bus desde Redux, funciones de utilidad, o simples scripts de JavaScript donde no puedes usar React Hooks, puedes usar el motor en bruto (el Singleton principal).

import { knxEngine } from "lm-knx-engine";

// Activar modo debug: imprime todo lo que entra y sale por consola
knxEngine.debugMode = true;

// Leer o Escribir manualmente
knxEngine.write<number>("1/2/5", 25.5); // Ajustar temperatura
knxEngine.read("1/2/5"); // Forzar petición al bus

// Escuchar un evento de forma manual
const handle = knxEngine.listen<boolean>("1/1/6", (estado) => {
  console.log("¡La luz ha cambiado a!", estado);
});

// ¡IMPORTANTE! Si escuchas manualmente, debes destruir el listener luego
knxEngine.unlisten(handle);

¿Cómo funciona internamente?

1. El Motor Central (KNXEngine.ts): Es una clase Singleton. Actúa como el portero de la casa. Envuelve de forma segura y tipada los objetos globales asíncronos que inyecta la Logic Machine (window.grp, objectStore, Scada).
2. El Hook (useKnx.ts): Automatiza el ciclo de vida de React (usando useEffect) para conectarse al Motor Central.
3. Protección: Si el Motor Central detecta que te has bajado el proyecto a tu entorno local (no hay Logic Machine conectada), no crashea, simplemente pasa al modo simulador y responde las peticiones desde memoria.

Licencia

Desarrollado para entornos Logic Machine profesionales por @juanzbdev. MIT License.