Jak zintegrować protokół KNX z nowoczesną aplikacją webową w TypeScript

Systemy Smart Home oparte na KNX są niezwykle stabilne i odporne na awarie, ale z natury nie są zaprojektowane do pracy z nowoczesnymi aplikacjami webowymi. Żeby wyświetlić stan rolet czy temperatury w aplikacji React, potrzebujemy mostu między światem magistrali KNX a światem HTTP/WebSocket.

Architektura integracji

W większości realizacji stosuję trzywarstwowy model:

1. Magistrala KNX — urządzenia, aktuatory, czujniki.
2. Bramka KNX/IP — punkt wejścia do sieci IP (np. przez knxd lub komercyjny interfejs IP).
3. Serwis integracyjny (Node.js) — tłumaczy telegramy KNX na zdarzenia zrozumiałe dla aplikacji webowej.

Nasłuchiwanie zdarzeń KNX w Node.js

Do komunikacji z magistralą wykorzystuję biblioteki takie jak knx lub własny klient oparty na knxd. Kluczowy jest moment odbioru telegramu i jego bezpieczne przetworzenie:

import { Connection, DataPoint } from 'knx';

interface KnxEvent {
  groupAddress: string;
  value: number | boolean;
  timestamp: Date;
}

function onKnxTelegram(raw: RawTelegram): KnxEvent {
  const dpt = new DataPoint(raw.dpt);

  return {
    groupAddress: raw.destination,
    value: dpt.decode(raw.payload),
    timestamp: new Date(),
  };
}

Otypowanie KnxEvent już na tym etapie eliminuje całą klasę błędów, które w projektach IoT zwykle wychodzą dopiero na produkcji — np. pomylenie typu danych punktu (DPT) przesyłanego po magistrali.

Publikacja zdarzeń do aplikacji webowej

Zdarzenia z magistrali trafiają do brokera MQTT, a stamtąd — przez WebSocket — do klienta:

import mqtt from 'mqtt';

const client = mqtt.connect('mqtt://broker.local:1883');

client.on('message', (topic, payload) => {
  const event: KnxEvent = JSON.parse(payload.toString());
  websocketServer.broadcast({ topic, event });
});

Po stronie frontendu (React + TypeScript) wystarczy prosty hook subskrybujący WebSocket i mapujący zdarzenia na stan interfejsu:

function useKnxDevice(groupAddress: string) {
  const [value, setValue] = useState<number | boolean | null>(null);

  useEffect(() => {
    const unsubscribe = knxSocket.subscribe(groupAddress, setValue);
    return unsubscribe;
  }, [groupAddress]);

  return value;
}

Na co zwrócić szczególną uwagę

• Idempotencja — telegramy KNX mogą się powtarzać (np. przy retransmisji), logika po stronie aplikacji powinna być odporna na duplikaty.
• Mapowanie DPT → typ TypeScript — warto trzymać jedną, wspólną definicję typów punktów danych, współdzieloną między backendem a frontendem.
• Bezpieczeństwo sieci — bramka KNX/IP nie powinna być bezpośrednio wystawiona do internetu; cała komunikacja z aplikacją webową powinna przechodzić przez kontrolowany serwis pośredniczący.

Połączenie solidnej instalacji KNX z dobrze zaprojektowaną warstwą integracyjną w TypeScript pozwala budować interfejsy Smart Home, które są zarówno responsywne, jak i tak niezawodne, jak sama magistrala.