knx.ts 1.0.2 → 1.0.4

package/dist/core/KNXnetIPStructures.d.ts

@@ -55,6 +55,10 @@ export declare abstract class DIB {
 }
 export declare class DeviceInformationDIB extends DIB {
     knxMedium: KNXMedium;
+    /**
+     * 1 = Device is programmed
+     * 0 = Device is not programmed
+     */
     deviceStatus: 1 | 0 | number;
     individualAddress: number;
     projectInstallationId: number;
@@ -62,7 +66,12 @@ export declare class DeviceInformationDIB extends DIB {
     routingMulticastAddress: string;
     macAddress: string;
     friendlyName: string;
-    constructor(knxMedium: KNXMedium, deviceStatus: 1 | 0 | number, individualAddress: number, projectInstallationId: number, serialNumber: Buffer, routingMulticastAddress: string, macAddress: string, friendlyName: string);
+    constructor(knxMedium: KNXMedium, 
+    /**
+     * 1 = Device is programmed
+     * 0 = Device is not programmed
+     */
+    deviceStatus: 1 | 0 | number, individualAddress: number, projectInstallationId: number, serialNumber: Buffer, routingMulticastAddress: string, macAddress: string, friendlyName: string);
     toBuffer(): Buffer;
     static fromBuffer(buffer: Buffer): DeviceInformationDIB;
 }

package/dist/core/KNXnetIPStructures.js

@@ -20,10 +20,7 @@ class HPAI {
         return this._hostProtocol;
     }
     set port(port) {
-        if (isNaN(port) ||
-            typeof port !== 'number' ||
-            port < 0 ||
-            port > 65535) {
+        if (isNaN(port) || typeof port !== "number" || port < 0 || port > 65535) {
             throw new Error(`Invalid port ${port}`);
         }
         this._port = port;
@@ -33,7 +30,7 @@ class HPAI {
     }
     set ipAddress(host) {
         if (host == null) {
-            throw new Error('Host undefined');
+            throw new Error("Host undefined");
         }
         const m = host.match(/(\d+)\.(\d+)\.(\d+)\.(\d+)/);
         if (m === null) {
@@ -233,7 +230,12 @@ class DeviceInformationDIB extends DIB {
     routingMulticastAddress;
     macAddress;
     friendlyName;
-    constructor(knxMedium, deviceStatus, individualAddress, projectInstallationId, serialNumber, routingMulticastAddress, macAddress, friendlyName) {
+    constructor(knxMedium, 
+    /**
+     * 1 = Device is programmed
+     * 0 = Device is not programmed
+     */
+    deviceStatus, individualAddress, projectInstallationId, serialNumber, routingMulticastAddress, macAddress, friendlyName) {
         super(KNXnetIPEnum_2.DescriptionType.DEVICE_INFO);
         this.knxMedium = knxMedium;
         this.deviceStatus = deviceStatus;
@@ -259,6 +261,7 @@ class DeviceInformationDIB extends DIB {
         buffer.writeUInt8(mcast[1], 15);
         buffer.writeUInt8(mcast[2], 16);
         buffer.writeUInt8(mcast[3], 17);
+        // eslint-disable-next-line no-useless-escape
         const mac = this.macAddress.replace(/[:\-]/g, "");
         Buffer.from(mac, "hex").copy(buffer, 18);
         nameBuf.copy(buffer, 24, 0);
@@ -367,7 +370,7 @@ class IPCurrentConfigDIB extends DIB {
 exports.IPCurrentConfigDIB = IPCurrentConfigDIB;
 class StatusTunnelingSlot {
     _value;
-    constructor(initialValue = 0xFFF8) {
+    constructor(initialValue = 0xfff8) {
         this._value = initialValue;
     }
     get value() {
@@ -435,7 +438,7 @@ class TunnellingInfoDIB extends DIB {
         for (let i = 4; i < buffer.length; i += 4) {
             slots.push({
                 address: buffer.readUInt16BE(i),
-                status: new StatusTunnelingSlot(buffer.readUInt16BE(i + 2))
+                status: new StatusTunnelingSlot(buffer.readUInt16BE(i + 2)),
             });
         }
         return new TunnellingInfoDIB(apduLength, slots);
@@ -589,7 +592,9 @@ class UnknownDIB extends DIB {
         super(type);
         this.rawData = rawData;
     }
-    toBuffer() { return this.rawData; }
+    toBuffer() {
+        return this.rawData;
+    }
 }
 exports.UnknownDIB = UnknownDIB;
 class SRP {
@@ -616,7 +621,7 @@ class SRP {
         const len = buffer.readUInt8(0);
         const type = buffer.readUInt8(1);
         const data = buffer.subarray(2, len);
-        return new SRP(type & 0x7F, data, (type & 0x80) !== 0);
+        return new SRP(type & 0x7f, data, (type & 0x80) !== 0);
     }
 }
 exports.SRP = SRP;

package/dist/core/MessageCodeField.d.ts

@@ -1,7 +1,7 @@
 /**
  * The default destination is the layer where the system shall direct the message to if no redirection is set.
  */
-declare enum DefaultDestination {
+declare const enum DefaultDestination {
     Data_Link_Layer = "DLL",
     Network_Layer = "NL",
     Transport_Layer = "TL",

package/dist/core/cache/GroupAddressCache.d.ts

@@ -0,0 +1,57 @@
+import { CEMIInstance } from "../CEMI";
+import { KNXService } from "../../connection/KNXService";
+export interface CacheEntry {
+    cemi: CEMIInstance;
+    timestamp: Date;
+    groupAddress: string;
+    decodedValue?: any;
+}
+export declare class GroupAddressCache {
+    private static instance;
+    private enabled;
+    /**
+     * Maximum number of group addresses to cache. Default is 65535 (all possible group addresses).
+     */
+    private maxAddresses;
+    /**
+     * Maximum number of messages to cache per group address. Default is 10.
+     */
+    private maxMessagesPerAddress;
+    private cache;
+    private dptConfig;
+    private constructor();
+    static getInstance(): GroupAddressCache;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    configure(maxAddresses: number, maxMessagesPerAddress?: number): void;
+    setAddressDPT(address: string, dpt: string | number): void;
+    getAddressDPT(address: string): string | number | undefined;
+    encodeValue(address: string, value: any): Buffer | null;
+    /**
+     * Processes an incoming CEMI message. If caching is enabled, saves the last messages
+     * indicating a GroupValue_Read or GroupValue_Response targeted to a Group Address.
+     */
+    processCEMI(cemi: CEMIInstance): void;
+    /**
+     * Clears the entire cache map.
+     */
+    clear(): void;
+    /**
+     * Deletes a specific address from the cache.
+     * @param address KNX Group Address e.g. '1/2/3'
+     */
+    deleteAddress(address: string): boolean;
+    /**
+     * Core query method to retrieve messages for given address(es) within a time range.
+     * If dates aren't specified, retrieves all currently cached items depending on the query payload.
+     * By default, it retrieves the absolute latest if neither startDate nor endDate are applied.
+     */
+    query(addresses: string | string[], startDate?: Date, endDate?: Date, returnOnlyLatest?: boolean): CacheEntry[];
+    /**
+     * Prompts the KNXService to issue an A_GroupValue_Read to the bus on the specified address
+     * and awaits an A_GroupValue_Response. The response is automatically processed via standard
+     * listeners (if processCEMI is hooked properly), but this method attaches an event
+     * one-off listener or handles resolving it.
+     */
+    readDirectAsync(address: string, serviceContext: KNXService, timeoutMs?: number): Promise<CacheEntry | null>;
+}

package/dist/core/cache/GroupAddressCache.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupAddressCache = void 0;
+const APCIEnum_1 = require("../enum/APCIEnum");
+const KNXDataDecode_1 = require("../data/KNXDataDecode");
+const KNXDataEncode_1 = require("../data/KNXDataEncode");
+class GroupAddressCache {
+    static instance;
+    enabled = false;
+    /**
+     * Maximum number of group addresses to cache. Default is 65535 (all possible group addresses).
+     */
+    maxAddresses = 65535;
+    /**
+     * Maximum number of messages to cache per group address. Default is 10.
+     */
+    maxMessagesPerAddress = 10;
+    cache = new Map();
+    dptConfig = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!GroupAddressCache.instance) {
+            GroupAddressCache.instance = new GroupAddressCache();
+        }
+        return GroupAddressCache.instance;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    configure(maxAddresses, maxMessagesPerAddress = 10) {
+        this.maxAddresses = maxAddresses;
+        this.maxMessagesPerAddress = maxMessagesPerAddress;
+    }
+    setAddressDPT(address, dpt) {
+        this.dptConfig.set(address, dpt);
+    }
+    getAddressDPT(address) {
+        return this.dptConfig.get(address);
+    }
+    encodeValue(address, value) {
+        const dpt = this.dptConfig.get(address);
+        if (!dpt)
+            return null;
+        try {
+            return KNXDataEncode_1.KnxDataEncoder.encodeThis(dpt, value);
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (err) {
+            return null;
+        }
+    }
+    /**
+     * Processes an incoming CEMI message. If caching is enabled, saves the last messages
+     * indicating a GroupValue_Read or GroupValue_Response targeted to a Group Address.
+     */
+    processCEMI(cemi) {
+        if (!("controlField2" in cemi) || !("TPDU" in cemi))
+            return;
+        if (!this.enabled)
+            return;
+        if (cemi.controlField2?.addressType !== 1) {
+            return; // Not a group address
+        }
+        const apciObj = cemi.TPDU.apdu.apci;
+        if (!apciObj)
+            return;
+        const apci = apciObj;
+        if (apci.value !== APCIEnum_1.APCIEnum.A_GroupValue_Read_Protocol_Data_Unit &&
+            apci.value !== APCIEnum_1.APCIEnum.A_GroupValue_Response_Protocol_Data_Unit) {
+            return;
+        }
+        const targetAddress = cemi.destinationAddress;
+        if (!targetAddress)
+            return;
+        // Initialize list if needed
+        if (!this.cache.has(targetAddress)) {
+            if (this.cache.size >= this.maxAddresses) {
+                // Enforce max addresses limit (naive approach: evict oldest entry by insertion order)
+                const firstKey = this.cache.keys().next().value;
+                if (firstKey !== undefined) {
+                    this.cache.delete(firstKey);
+                }
+            }
+            this.cache.set(targetAddress, []);
+        }
+        const entries = this.cache.get(targetAddress);
+        let decodedValue = undefined;
+        const dpt = this.dptConfig.get(targetAddress);
+        if (dpt && cemi.TPDU.apdu.data) {
+            try {
+                decodedValue = KNXDataDecode_1.KnxDataDecode.decodeThis(dpt, cemi.TPDU.apdu.data);
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            }
+            catch (err) {
+                // failed to decode
+            }
+        }
+        // Create new entry
+        const entry = {
+            cemi: cemi,
+            timestamp: new Date(),
+            groupAddress: targetAddress,
+            decodedValue: decodedValue,
+        };
+        // Insert at front
+        entries.unshift(entry);
+        // Trim length
+        if (entries.length > this.maxMessagesPerAddress) {
+            entries.length = this.maxMessagesPerAddress;
+        }
+    }
+    /**
+     * Clears the entire cache map.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Deletes a specific address from the cache.
+     * @param address KNX Group Address e.g. '1/2/3'
+     */
+    deleteAddress(address) {
+        return this.cache.delete(address);
+    }
+    /**
+     * Core query method to retrieve messages for given address(es) within a time range.
+     * If dates aren't specified, retrieves all currently cached items depending on the query payload.
+     * By default, it retrieves the absolute latest if neither startDate nor endDate are applied.
+     */
+    query(addresses, startDate, endDate = new Date(), returnOnlyLatest = true) {
+        const addressArray = Array.isArray(addresses) ? addresses : [addresses];
+        const results = [];
+        for (const address of addressArray) {
+            const entries = this.cache.get(address) || [];
+            if (entries.length === 0)
+                continue;
+            if (!startDate) {
+                // If no start date, we return the very latest (index 0) if default or requested
+                if (returnOnlyLatest) {
+                    results.push(entries[0]);
+                }
+                else {
+                    // Or return everything relative to the endDate
+                    results.push(...entries.filter((e) => e.timestamp <= endDate));
+                }
+            }
+            else {
+                // Filter by date range
+                const validEntries = entries.filter((e) => e.timestamp >= startDate && e.timestamp <= endDate);
+                if (returnOnlyLatest && validEntries.length > 0) {
+                    results.push(validEntries[0]);
+                }
+                else {
+                    results.push(...validEntries);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Prompts the KNXService to issue an A_GroupValue_Read to the bus on the specified address
+     * and awaits an A_GroupValue_Response. The response is automatically processed via standard
+     * listeners (if processCEMI is hooked properly), but this method attaches an event
+     * one-off listener or handles resolving it.
+     */
+    async readDirectAsync(address, serviceContext, timeoutMs = 3000) {
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line prefer-const
+            let timer;
+            // Listener context reference to intercept indications specifically for this read call
+            const listener = (cemi) => {
+                if (cemi.controlField2?.addressType === 1 && cemi.destinationAddress === address) {
+                    const apciObj = cemi.TPDU.apdu.apci;
+                    if (apciObj && apciObj.value === APCIEnum_1.APCIEnum.A_GroupValue_Response_Protocol_Data_Unit) {
+                        // Clean up
+                        clearTimeout(timer);
+                        serviceContext.off("indication", listener);
+                        // Ensure caching happens if not processed previously (if processCEMI wasn't hooked at higher layer for some reason)
+                        this.processCEMI(cemi);
+                        // Find in cache
+                        const entries = this.cache.get(address);
+                        if (entries && entries.length > 0 && entries[0].cemi === cemi) {
+                            resolve(entries[0]);
+                        }
+                        else {
+                            // Return mock CacheEntry if cache processing was disabled or failed
+                            let decodedValue = undefined;
+                            const dpt = this.dptConfig.get(address);
+                            if (dpt && cemi.TPDU.apdu.data) {
+                                try {
+                                    decodedValue = KNXDataDecode_1.KnxDataDecode.decodeThis(dpt, cemi.TPDU.apdu.data);
+                                    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                                }
+                                catch (e) {
+                                    // empty
+                                }
+                            }
+                            resolve({
+                                cemi: cemi,
+                                timestamp: new Date(),
+                                groupAddress: address,
+                                decodedValue: decodedValue,
+                            });
+                        }
+                    }
+                }
+            };
+            // Set explicit listener on the service context
+            serviceContext.on("indication", listener);
+            // Start the timer to abort request
+            timer = setTimeout(() => {
+                serviceContext.off("indication", listener);
+                reject(new Error(`Timeout of ${timeoutMs}ms exceeded while waiting for GroupValue_Response on ${address}`));
+            }, timeoutMs);
+            // Issue the command to the bus
+            serviceContext.read(address).catch((err) => {
+                clearTimeout(timer);
+                serviceContext.off("indication", listener);
+                reject(err);
+            });
+        });
+    }
+}
+exports.GroupAddressCache = GroupAddressCache;

package/dist/core/data/KNXDataDecode.d.ts

@@ -5,7 +5,7 @@ import { KNXData } from "./KNXData";
  */
 export declare class KnxDataDecode extends KNXData {
     private constructor();
-    static decodeThis<T extends typeof KnxDataDecode.dptEnum[number] | string>(dpt: T, buffer: Buffer): DecodedDPTType<T>;
+    static decodeThis<T extends (typeof KnxDataDecode.dptEnum)[number] | string>(dpt: T, buffer: Buffer): DecodedDPTType<T>;
     static get dptEnum(): readonly [1, 2, 3007, 3008, 4001, 4002, 5, 5001, 5002, 6, 6001, 6010, 6020, 7, 7001, 7002, 7003, 7004, 7005, 7006, 7007, 7011, 7012, 7013, 8, 9, 10001, 11001, 12001, 12002, 13, 13001, 13002, 13010, 13011, 13012, 13013, 13014, 13015, 13016, 13100, 14, 15000, 16, 16002, 20, 20001, 20002, 20003, 20004, 20005, 20006, 20007, 20008, 20011, 20012, 20013, 20014, 20017, 20020, 20021, 20022, 27001, 28001, 29, 29010, 29011, 29012, 232600, 238600, 245600, 250600, 251600];
     private static toPercentage;
     private static toAngle;
@@ -187,7 +187,7 @@ export declare class KnxDataDecode extends KNXData {
      *
      * @returns Un objeto con el valor sin signo y la unidad seleccionada.
      */
-    static asDpt12002(buffer: Buffer, variant?: 'sec' | 'min' | 'hrs'): {
+    static asDpt12002(buffer: Buffer, variant?: "sec" | "min" | "hrs"): {
         value: number;
         unit: string;
     };