knx.ts 1.0.0

package/dist/connection/TPUART.js

@@ -0,0 +1,497 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TPUARTConnection = void 0;
+const serialport_1 = require("serialport");
+const KNXService_1 = require("./KNXService");
+const CEMIAdapter_1 = require("../utils/CEMIAdapter");
+const EMI_1 = require("../core/EMI");
+const KNXHelper_1 = require("../utils/KNXHelper");
+const CEMI_1 = require("../core/CEMI");
+const UART_SERVICES = {
+    RESET_REQ: 0x01,
+    RESET_IND: 0x03,
+    STATE_REQ: 0x02,
+    STATE_IND: 0x07,
+    ACTIVATE_BUSMON: 0x05,
+    LDATA_CON_POS: 0x8b,
+    LDATA_CON_NEG: 0x0b,
+    ACK_INFO: 0x10,
+    LDATA_START: 0x80,
+    LDATA_END: 0x40,
+    BUSY: 0xc0,
+};
+var TPUARTState;
+(function (TPUARTState) {
+    TPUARTState[TPUARTState["DISCONNECTED"] = 0] = "DISCONNECTED";
+    TPUARTState[TPUARTState["RESET_WAIT"] = 1] = "RESET_WAIT";
+    TPUARTState[TPUARTState["SET_ADDR_WAIT"] = 2] = "SET_ADDR_WAIT";
+    TPUARTState[TPUARTState["GET_STATE_WAIT"] = 3] = "GET_STATE_WAIT";
+    TPUARTState[TPUARTState["ONLINE"] = 4] = "ONLINE";
+    TPUARTState[TPUARTState["ERROR"] = 5] = "ERROR";
+})(TPUARTState || (TPUARTState = {}));
+class TPUARTConnection extends KNXService_1.KNXService {
+    serialPort;
+    receiver;
+    connectionState = TPUARTState.DISCONNECTED;
+    initPromise = null;
+    msgQueue = [];
+    isProcessing = false;
+    lastSentFrame = null;
+    keepaliveTimer = null;
+    confirmationTimer = null;
+    initTimer = null;
+    initRetryCount = 0;
+    isBusmonitorMode = false;
+    constructor(options) {
+        super(options);
+        this.serialPort = new serialport_1.SerialPort({
+            path: options.path,
+            baudRate: 19200,
+            dataBits: 8,
+            parity: "even",
+            stopBits: 1,
+            autoOpen: false,
+        });
+        this.receiver = new Receiver(this);
+        this.serialPort.on("data", (data) => this.receiver.handleData(data));
+        this.serialPort.on("error", (err) => {
+            this.handleFatalError(err);
+        });
+        this.on("raw_frame", (frame) => {
+            // 1. Echo Cancellation (knxd pattern: ignore repeat bit 0x20)
+            if (this.lastSentFrame && frame.length === this.lastSentFrame.length) {
+                if ((frame[0] & ~0x20) === (this.lastSentFrame[0] & ~0x20) &&
+                    frame.subarray(1).equals(this.lastSentFrame.subarray(1))) {
+                    this.lastSentFrame = null;
+                    return;
+                }
+            }
+            this.resetKeepalive();
+            // 2. Hardware ACK (knxd pattern)
+            // Only if NOT in busmonitor mode
+            if (!this.isBusmonitorMode) {
+                const options = this.options;
+                let ackByte = 0x10; // Default: No ACK
+                if (options.ackGroup || options.ackIndividual) {
+                    const isExtended = (frame[0] & 0x80) === 0;
+                    const controlByte = isExtended ? frame[1] : frame[5];
+                    const isGroup = (controlByte & 0x80) !== 0;
+                    if ((isGroup && options.ackGroup) ||
+                        (!isGroup && options.ackIndividual)) {
+                        ackByte = 0x11; // Send ACK
+                    }
+                }
+                this.writeRaw([ackByte]).catch(() => { });
+            }
+            try {
+                if (this.isBusmonitorMode) {
+                    // In Busmonitor mode, we emit L_Busmon.ind
+                    const cemi = new CEMI_1.CEMI.DataLinkLayerCEMI["L_Busmon.ind"](null, frame);
+                    this.emit("indication", cemi);
+                    this.emit("busmonitor", cemi);
+                }
+                else {
+                    const emiBuffer = Buffer.concat([Buffer.from([0x29]), frame]);
+                    const cemi = CEMIAdapter_1.CEMIAdapter.emiToCemi(emiBuffer);
+                    if (cemi) {
+                        this.emit("indication", cemi);
+                        this.emit("raw_indication", cemi.toBuffer());
+                    }
+                }
+            }
+            catch (e) { }
+        });
+    }
+    handleFatalError(err) {
+        this.stopTimers();
+        this.connectionState = TPUARTState.ERROR;
+        // Reject all pending messages
+        while (this.msgQueue.length > 0) {
+            this.msgQueue.shift()?.reject(err);
+        }
+        this.isProcessing = false;
+        this.emit("error", err);
+    }
+    stopTimers() {
+        if (this.keepaliveTimer)
+            clearTimeout(this.keepaliveTimer);
+        if (this.confirmationTimer)
+            clearTimeout(this.confirmationTimer);
+        if (this.initTimer)
+            clearTimeout(this.initTimer);
+        this.keepaliveTimer = null;
+        this.confirmationTimer = null;
+        this.initTimer = null;
+    }
+    resetKeepalive() {
+        if (this.keepaliveTimer)
+            clearTimeout(this.keepaliveTimer);
+        this.keepaliveTimer = setTimeout(() => {
+            if (this.connectionState === TPUARTState.ONLINE) {
+                this.initRetryCount = 0;
+                this.requestState();
+            }
+        }, 10000);
+    }
+    async connect() {
+        if (this.connectionState !== TPUARTState.DISCONNECTED &&
+            this.connectionState !== TPUARTState.ERROR)
+            return;
+        return new Promise((resolve, reject) => {
+            this.initPromise = { resolve, reject };
+            this.serialPort.open(async (err) => {
+                if (err) {
+                    this.initPromise = null;
+                    reject(err);
+                    return;
+                }
+                this.initRetryCount = 0;
+                this.sendResetRequest();
+            });
+        });
+    }
+    sendResetRequest() {
+        this.connectionState = TPUARTState.RESET_WAIT;
+        this.writeRaw([UART_SERVICES.RESET_REQ]).catch(() => { });
+        if (this.initTimer)
+            clearTimeout(this.initTimer);
+        this.initTimer = setTimeout(() => {
+            if (this.connectionState === TPUARTState.RESET_WAIT) {
+                this.initRetryCount++;
+                if (this.initRetryCount < 3) {
+                    this.sendResetRequest();
+                }
+                else {
+                    if (this.initPromise) {
+                        this.initPromise.reject(new Error("TPUART reset timeout"));
+                        this.initPromise = null;
+                    }
+                    this.handleFatalError(new Error("TPUART reset timeout"));
+                }
+            }
+        }, 500);
+    }
+    async disconnect() {
+        this.stopTimers();
+        this.connectionState = TPUARTState.DISCONNECTED;
+        // Clear queue
+        while (this.msgQueue.length > 0) {
+            this.msgQueue.shift()?.reject(new Error("Disconnected by user"));
+        }
+        this.isProcessing = false;
+        return new Promise((resolve) => {
+            if (this.serialPort.isOpen) {
+                this.serialPort.close(() => {
+                    this.emit("disconnected");
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    async setBusmonitor(enabled) {
+        if (this.connectionState < TPUARTState.ONLINE)
+            throw new Error("TPUART offline");
+        this.isBusmonitorMode = enabled;
+        if (enabled) {
+            await this.writeRaw([UART_SERVICES.ACTIVATE_BUSMON]);
+        }
+        else {
+            // To exit busmonitor, we usually need a reset or re-init
+            this.initRetryCount = 0;
+            this.sendResetRequest();
+        }
+    }
+    async send(data) {
+        if (this.connectionState < TPUARTState.ONLINE)
+            throw new Error("TPUART offline");
+        let frame = Buffer.isBuffer(data)
+            ? tryEmi(data) || data
+            : CEMIAdapter_1.CEMIAdapter.cemiToEmi(data)?.toBuffer().subarray(1);
+        if (!frame)
+            throw new Error("Invalid data");
+        return this.enqueueFrame(frame);
+    }
+    async enqueueFrame(frame) {
+        return new Promise((resolve, reject) => {
+            this.msgQueue.push({ frame, resolve, reject, attempts: 0 });
+            this.processQueue();
+        });
+    }
+    async processQueue() {
+        if (this.isProcessing || this.msgQueue.length === 0)
+            return;
+        this.isProcessing = true;
+        const item = this.msgQueue[0];
+        // knxd pattern: If this is a retry (attempts > 0), set the Repeat Bit (bit 5) to 0
+        // This tells the bus that this is a repetition of a previously failed frame.
+        if (item.attempts > 0 && item.frame[0] & 0x20) {
+            item.frame[0] &= ~0x20; // Set repeat bit to 0
+            // Update checksum (XOR with 0x20 since we toggled one bit)
+            item.frame[item.frame.length - 1] ^= 0x20;
+        }
+        this.lastSentFrame = item.frame;
+        // Timeout for hardware confirmation (0x8B/0x0B)
+        this.confirmationTimer = setTimeout(() => {
+            this.isProcessing = false;
+            this.lastSentFrame = null;
+            if (item.attempts < 3) {
+                item.attempts++;
+                this.processQueue();
+            }
+            else {
+                this.msgQueue.shift();
+                item.reject(new Error("TPUART confirmation timeout"));
+                this.processQueue();
+            }
+        }, 2000);
+        this.serialPort.write(this.toUartServices(item.frame), (err) => {
+            if (err) {
+                if (this.confirmationTimer)
+                    clearTimeout(this.confirmationTimer);
+                this.isProcessing = false;
+                this.lastSentFrame = null;
+                if (item.attempts < 3) {
+                    item.attempts++;
+                    setTimeout(() => this.processQueue(), 50);
+                }
+                else {
+                    this.msgQueue.shift();
+                    item.reject(err);
+                    this.processQueue();
+                }
+            }
+        });
+    }
+    toUartServices(telegram) {
+        const result = Buffer.alloc(telegram.length * 2);
+        for (let i = 0; i < telegram.length; i++) {
+            const ctrl = i === telegram.length - 1
+                ? UART_SERVICES.LDATA_END | (i & 0x3f)
+                : UART_SERVICES.LDATA_START | (i & 0x3f);
+            result[i * 2] = ctrl;
+            result[i * 2 + 1] = telegram[i];
+        }
+        return result;
+    }
+    _handleControlByte(byte) {
+        this.resetKeepalive();
+        // 1. External ACKs/NACKs from other devices
+        if (byte === 0xcc || byte === 0x0c || byte === 0xc0) {
+            this.emit("bus_ack", {
+                type: byte === 0xcc ? "ACK" : byte === 0x0c ? "NACK" : "BUSY",
+                timestamp: Date.now(),
+            });
+            return;
+        }
+        // 2. NCN5120 / TPUART2 Frame State Indication
+        if ((byte & 0x17) === 0x13) {
+            const hasError = (byte & 0x07) !== 0;
+            if (hasError) {
+                const error = byte & 0x04
+                    ? "Checksum Error"
+                    : byte & 0x02
+                        ? "Timing Error"
+                        : "Bit Error";
+                this.emit("warning", `TPUART Frame Error: ${error}`);
+            }
+            return;
+        }
+        if (byte === UART_SERVICES.RESET_IND) {
+            if (this.connectionState === TPUARTState.RESET_WAIT) {
+                if (this.initTimer)
+                    clearTimeout(this.initTimer);
+                this.initRetryCount = 0;
+                const options = this.options;
+                if (options.individualAddress) {
+                    this.connectionState = TPUARTState.SET_ADDR_WAIT;
+                    this.writeRaw(Buffer.concat([
+                        Buffer.from([0x28]),
+                        KNXHelper_1.KNXHelper.GetAddress(options.individualAddress, "."),
+                    ])).catch((e) => this.emit("error", e));
+                    // knxd immediately transitions to get state after setting address
+                    this.requestState();
+                }
+                else {
+                    this.requestState();
+                }
+            }
+            else if (this.connectionState >= TPUARTState.ONLINE) {
+                // Spurious reset (power glitch?) -> re-initialize
+                this.emit("warning", "TPUART spurious reset detected, re-initializing...");
+                this.initRetryCount = 0;
+                this.sendResetRequest();
+            }
+            return;
+        }
+        if (byte === UART_SERVICES.BUSY) {
+            if (this.confirmationTimer)
+                clearTimeout(this.confirmationTimer);
+            const item = this.msgQueue[0];
+            if (item && item.attempts < 3) {
+                item.attempts++;
+                this.isProcessing = false;
+                setTimeout(() => this.processQueue(), 50);
+            }
+            else if (item) {
+                this.msgQueue.shift();
+                this.isProcessing = false;
+                this.lastSentFrame = null;
+                item.reject(new Error("Bus Busy"));
+                this.processQueue();
+            }
+            return;
+        }
+        if (byte === UART_SERVICES.LDATA_CON_POS ||
+            byte === UART_SERVICES.LDATA_CON_NEG) {
+            if (this.confirmationTimer)
+                clearTimeout(this.confirmationTimer);
+            const item = this.msgQueue.shift();
+            this.isProcessing = false;
+            if (item) {
+                byte === UART_SERVICES.LDATA_CON_POS
+                    ? item.resolve()
+                    : item.reject(new Error("NAK"));
+            }
+            this.processQueue();
+            return;
+        }
+        if ((byte & 0x07) === UART_SERVICES.STATE_IND) {
+            if (this.initTimer)
+                clearTimeout(this.initTimer);
+            this.initRetryCount = 0;
+            // Decode error bits (knxd pattern)
+            if (byte !== 0x07 && byte !== 0x00) {
+                if (byte & 0x40)
+                    this.emit("warning", "TPUART: Hardware ACK NOT supported by this chip");
+                if (byte & 0x04)
+                    this.emit("warning", "TPUART: Slave collision detected");
+                if (byte & 0x02)
+                    this.emit("warning", "TPUART: Receive error");
+                if (byte & 0x01)
+                    this.emit("warning", "TPUART: Transmit error");
+            }
+            if (this.connectionState < TPUARTState.ONLINE) {
+                this.connectionState = TPUARTState.ONLINE;
+                if (this.initPromise) {
+                    this.initPromise.resolve();
+                    this.initPromise = null;
+                    this.emit("connected");
+                }
+            }
+        }
+    }
+    async writeRaw(data) {
+        return new Promise((resolve, reject) => {
+            this.serialPort.write(data, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    requestState() {
+        this.connectionState = TPUARTState.GET_STATE_WAIT;
+        this.writeRaw([UART_SERVICES.STATE_REQ]).catch((e) => this.emit("error", e));
+        if (this.initTimer)
+            clearTimeout(this.initTimer);
+        this.initTimer = setTimeout(() => {
+            if (this.connectionState === TPUARTState.GET_STATE_WAIT) {
+                this.initRetryCount++;
+                if (this.initRetryCount < 5) {
+                    this.requestState();
+                }
+                else {
+                    if (this.initPromise) {
+                        this.initPromise.reject(new Error("TPUART state request timeout"));
+                        this.initPromise = null;
+                    }
+                    this.handleFatalError(new Error("TPUART state request timeout"));
+                }
+            }
+        }, 500);
+    }
+}
+exports.TPUARTConnection = TPUARTConnection;
+function tryEmi(data) {
+    try {
+        return EMI_1.EMI.fromBuffer(data).toBuffer().subarray(1);
+    }
+    catch {
+        return null;
+    }
+}
+class Receiver {
+    connection;
+    buffer = Buffer.alloc(0);
+    lastRead = 0;
+    extFrame = false;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    handleData(data) {
+        for (const byte of data)
+            this.processByte(byte);
+    }
+    processByte(byte) {
+        // BUG FIX: Only handle control bytes if we are NOT in the middle of a frame
+        // This prevents data bytes (like 0x03) from being interpreted as RESET_IND
+        if (this.buffer.length === 0) {
+            if (this.isControlByte(byte)) {
+                this.connection._handleControlByte(byte);
+                return;
+            }
+            // Support for NCN5120/TPUART2: Ignore frame end (0xCB) and state indication (0x13)
+            if (byte === 0xcb || (byte & 0x17) === 0x13)
+                return;
+        }
+        const now = Date.now();
+        // Inter-byte timeout (1000ms) to reset buffer if sync is lost (matches knxd T_wait_more)
+        if (this.buffer.length > 0 && now - this.lastRead > 1000)
+            this.buffer = Buffer.alloc(0);
+        if (this.buffer.length === 0) {
+            if (this.isFrameStart(byte)) {
+                this.buffer = Buffer.from([byte]);
+                this.lastRead = now;
+            }
+        }
+        else {
+            this.buffer = Buffer.concat([this.buffer, Buffer.from([byte])]);
+            this.lastRead = now;
+            this.checkCompleteFrame();
+        }
+    }
+    isControlByte(byte) {
+        return (byte === UART_SERVICES.RESET_IND ||
+            byte === UART_SERVICES.LDATA_CON_POS ||
+            byte === UART_SERVICES.LDATA_CON_NEG ||
+            byte === UART_SERVICES.BUSY ||
+            (byte & 0x07) === UART_SERVICES.STATE_IND);
+    }
+    isFrameStart(byte) {
+        this.extFrame = (byte & 0x80) === 0;
+        return (byte & 0x50) === 0x10;
+    }
+    checkCompleteFrame() {
+        const minLength = this.extFrame ? 7 : 6;
+        if (this.buffer.length >= minLength) {
+            const payloadLen = this.extFrame ? this.buffer[6] : this.buffer[5] & 0x0f;
+            const totalLen = payloadLen + (this.extFrame ? 9 : 8);
+            if (this.buffer.length >= totalLen) {
+                const frame = this.buffer.subarray(0, totalLen);
+                if (this.validateChecksum(frame))
+                    this.connection.emit("raw_frame", frame);
+                this.buffer = Buffer.alloc(0);
+            }
+        }
+    }
+    validateChecksum(frame) {
+        let checksum = 0;
+        for (let i = 0; i < frame.length - 1; i++)
+            checksum ^= frame[i];
+        return frame[frame.length - 1] === (checksum ^ 0xff);
+    }
+}

package/dist/connection/TunnelConnection.d.ts

@@ -0,0 +1,57 @@
+import dgram from "dgram";
+import { HPAI } from "../core/KNXnetIPStructures";
+import { KNXnetIPServiceType, KNXLayer } from "../core/enum/KNXnetIPEnum";
+import { Logger } from "pino";
+/**
+ * Encapsulates a single KNXnet/IP Tunnelling or Management connection state.
+ * Handles sequence numbers, heartbeats, reliable delivery (stop-and-wait),
+ * and retransmissions according to KNX Spec Vol 3/8/4.
+ */
+export declare class TunnelConnection {
+    readonly channelId: number;
+    readonly controlHPAI: HPAI;
+    readonly dataHPAI: HPAI;
+    readonly knxAddress: number;
+    readonly knxAddressStr: string;
+    readonly knxLayer: KNXLayer;
+    private readonly socket;
+    private readonly heartbeatTimeoutMs;
+    private readonly retransmitTimeoutMs;
+    private readonly maxQueueSize;
+    private readonly onDisconnect;
+    sno: number;
+    rno: number;
+    private heartbeatTimer;
+    private pendingAck;
+    private queue;
+    private isSending;
+    rxCount: number;
+    lastRxTime: number;
+    private logger;
+    constructor(channelId: number, controlHPAI: HPAI, dataHPAI: HPAI, knxAddress: number, knxAddressStr: string, knxLayer: KNXLayer, socket: dgram.Socket, heartbeatTimeoutMs: number, retransmitTimeoutMs: number, maxQueueSize: number, onDisconnect: (channelId: number, sendDisconnect: boolean) => void, parentLogger: Logger);
+    /**
+     * Resets the heartbeat timer. Should be called on any valid activity.
+     */
+    resetHeartbeat(): void;
+    /**
+     * Enqueues a CEMI message to be sent to the client.
+     */
+    enqueue(cemiBuffer: Buffer, serviceType: KNXnetIPServiceType): void;
+    private processQueue;
+    private sendWithRetry;
+    /**
+     * Handles an incoming ACK from the client.
+     */
+    handleAck(seq: number, status: number): void;
+    /**
+     * Validates an incoming request from the client according to sequence number rules.
+     */
+    validateRequest(seq: number): {
+        action: 'process' | 'discard' | 'retransmit_ack';
+        status: number;
+    };
+    /**
+     * Closes the connection and cleans up resources.
+     */
+    close(): void;
+}