matterbridge 3.4.7-dev-20260112-bd9e311 → 3.4.7

package/dist/devices/waterHeater.js

@@ -1,3 +1,26 @@
+/**
+ * @description This file contains the WaterHeater class.
+ * @file src/devices/waterHeater.ts
+ * @author Luca Liguori
+ * @contributor Ludovic BOUÉ
+ * @created 2025-05-18
+ * @version 1.1.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 import { ModeBase } from '@matter/types/clusters/mode-base';
 import { WaterHeaterManagement } from '@matter/types/clusters/water-heater-management';
 import { WaterHeaterMode } from '@matter/types/clusters/water-heater-mode';
@@ -8,6 +31,29 @@ import { MatterbridgeServer } from '../matterbridgeBehaviors.js';
 import { electricalSensor, powerSource, waterHeater } from '../matterbridgeDeviceTypes.js';
 import { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js';
 export class WaterHeater extends MatterbridgeEndpoint {
+    /**
+     * Creates an instance of the WaterHeater class.
+     *
+     * @param {string} name - The name of the water heater.
+     * @param {string} serial - The serial number of the water heater.
+     * @param {number} [waterTemperature] - The current water temperature. Defaults to 50.
+     * @param {number} [targetWaterTemperature] - The target water temperature. Defaults to 55.
+     * @param {number} [minHeatSetpointLimit] - The minimum heat setpoint limit. Defaults to 20.
+     * @param {number} [maxHeatSetpointLimit] - The maximum heat setpoint limit. Defaults to 80.
+     * @param {{ immersionElement1?: boolean; immersionElement2?: boolean; heatPump?: boolean; boiler?: boolean; other?: boolean }} [heaterTypes] - Indicates the heat sources that the water heater can call on for heating. Defaults to { immersionElement1: true }.
+     * @param {boolean} heaterTypes.immersionElement1 - Indicates if the water heater has an immersion element 1. Defaults to true.
+     * @param {boolean} heaterTypes.immersionElement2 - Indicates if the water heater has an immersion element 2.
+     * @param {boolean} heaterTypes.heatPump - Indicates if the water heater has a heat pump.
+     * @param {boolean} heaterTypes.boiler - Indicates if the water heater has a boiler.
+     * @param {boolean} heaterTypes.other - Indicates if the water heater has other types of heating sources.
+     * @param {number} [tankPercentage] - The current tank percentage of the WaterHeaterManagement cluster. Defaults to 90.
+     * @param {number} [voltage] - The voltage value in millivolts. Defaults to null if not provided.
+     * @param {number} [current] - The current value in milliamperes. Defaults to null if not provided.
+     * @param {number} [power] - The power value in milliwatts. Defaults to null if not provided.
+     * @param {number} [energy] - The total consumption value in mW/h. Defaults to null if not provided.
+     * @param {number} [absMinPower] - Indicate the minimum electrical power in mw that the ESA can consume when switched on. Defaults to `0` if not provided.
+     * @param {number} [absMaxPower] - Indicate the maximum electrical power in mw that the ESA can consume when switched on. Defaults to `0` if not provided.
+     */
     constructor(name, serial, waterTemperature = 50, targetWaterTemperature = 55, minHeatSetpointLimit = 20, maxHeatSetpointLimit = 80, heaterTypes = { immersionElement1: true }, tankPercentage = 90, voltage = null, current = null, power = null, energy = null, absMinPower = 0, absMaxPower = 0) {
         super([waterHeater, powerSource, electricalSensor], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
         this.createDefaultIdentifyClusterServer()
@@ -22,15 +68,42 @@ export class WaterHeater extends MatterbridgeEndpoint {
             .createDefaultDeviceEnergyManagementClusterServer(DeviceEnergyManagement.EsaType.WaterHeating, true, DeviceEnergyManagement.EsaState.Online, absMinPower, absMaxPower)
             .createDefaultDeviceEnergyManagementModeClusterServer();
     }
+    /**
+     * Creates a default WaterHeaterManagement Cluster Server.
+     *
+     * @param {{ immersionElement1?: boolean; immersionElement2?: boolean; heatPump?: boolean; boiler?: boolean; other?: boolean }} [heaterTypes] - Indicates the heat sources that the water heater can call on for heating. Defaults to { immersionElement1: true }.
+     * @param {boolean} heaterTypes.immersionElement1 - Indicates if the water heater has an immersion element 1. Defaults to true.
+     * @param {boolean} heaterTypes.immersionElement2 - Indicates if the water heater has an immersion element 2.
+     * @param {boolean} heaterTypes.heatPump - Indicates if the water heater has a heat pump.
+     * @param {boolean} heaterTypes.boiler - Indicates if the water heater has a boiler.
+     * @param {boolean} heaterTypes.other - Indicates if the water heater has other types of heating sources.
+     * @param {{ immersionElement1?: boolean; immersionElement2?: boolean; heatPump?: boolean; boiler?: boolean; other?: boolean }} [heatDemand] - Indicates if the water heater is heating water. Defaults to all heat sources unset.
+     * @param {boolean} heatDemand.immersionElement1 - Indicates if the water heater is heating water with immersion element 1. Defaults to false.
+     * @param {boolean} heatDemand.immersionElement2 - Indicates if the water heater is heating water with immersion element 2.
+     * @param {boolean} heatDemand.heatPump - Indicates if the water heater is heating water with a heat pump.
+     * @param {boolean} heatDemand.boiler - Indicates if the water heater is heating water with a boiler.
+     * @param {boolean} heatDemand.other - Indicates if the water heater is heating water with other types of heating sources.
+     * @param {number} [tankPercentage] - The current tank percentage of the WaterHeaterManagement cluster. Defaults to 100.
+     * @param {WaterHeaterManagement.BoostState} [boostState] - The current boost state of the WaterHeaterManagement cluster. Defaults to Inactive.
+     * @returns {this} The current MatterbridgeEndpoint instance for chaining.
+     */
     createDefaultWaterHeaterManagementClusterServer(heaterTypes, heatDemand, tankPercentage, boostState) {
         this.behaviors.require(MatterbridgeWaterHeaterManagementServer.with(WaterHeaterManagement.Feature.TankPercent), {
-            heaterTypes: heaterTypes ?? { immersionElement1: true },
+            heaterTypes: heaterTypes ?? { immersionElement1: true }, // Fixed attribute
             heatDemand: heatDemand ?? {},
             tankPercentage: tankPercentage ?? 100,
             boostState: boostState ?? WaterHeaterManagement.BoostState.Inactive,
         });
         return this;
     }
+    /**
+     * Creates a default WaterHeaterMode Cluster Server.
+     *
+     * @param {number} [currentMode] - The current mode of the WaterHeaterMode cluster. Defaults to mode 1 (WaterHeaterMode.ModeTag.Auto).
+     * @param {WaterHeaterMode.ModeOption[]} [supportedModes] - The supported modes for the WaterHeaterMode cluster. Defaults all cluster modes.
+     *
+     * @returns {this} The current MatterbridgeEndpoint instance for chaining.
+     */
     createDefaultWaterHeaterModeClusterServer(currentMode, supportedModes) {
         this.behaviors.require(MatterbridgeWaterHeaterModeServer, {
             supportedModes: supportedModes ?? [
@@ -47,7 +120,7 @@ export class WaterHeater extends MatterbridgeEndpoint {
                 { label: 'Off', mode: 11, modeTags: [{ value: WaterHeaterMode.ModeTag.Off }] },
                 { label: 'Manual', mode: 12, modeTags: [{ value: WaterHeaterMode.ModeTag.Manual }] },
                 { label: 'Timed', mode: 13, modeTags: [{ value: WaterHeaterMode.ModeTag.Timed }] },
-            ],
+            ], // Fixed attribute
             currentMode: currentMode ?? 1,
         });
         return this;
@@ -60,6 +133,9 @@ export class MatterbridgeWaterHeaterManagementServer extends WaterHeaterManageme
         device.commandHandler.executeHandler('boost', { request, cluster: WaterHeaterManagementServer.id, attributes: this.state, endpoint: this.endpoint });
         device.log.debug(`MatterbridgeWaterHeaterManagementServer boost called with: ${JSON.stringify(request)}`);
         this.state.boostState = WaterHeaterManagement.BoostState.Active;
+        // The implementation is responsible for setting the device accordingly with the boostInfo of the boost command
+        // super.boost({ boostInfo });
+        // boost is not implemented in matter.js
     }
     cancelBoost() {
         const device = this.endpoint.stateOf(MatterbridgeServer);
@@ -67,6 +143,9 @@ export class MatterbridgeWaterHeaterManagementServer extends WaterHeaterManageme
         device.commandHandler.executeHandler('cancelBoost', { request: {}, cluster: WaterHeaterManagementServer.id, attributes: this.state, endpoint: this.endpoint });
         device.log.debug(`MatterbridgeWaterHeaterManagementServer cancelBoost called`);
         this.state.boostState = WaterHeaterManagement.BoostState.Inactive;
+        // The implementation is responsible for setting the device accordingly with the cancelBoost command
+        // super.cancelBoost();
+        // cancelBoost is not implemented in matter.js
     }
 }
 export class MatterbridgeWaterHeaterModeServer extends WaterHeaterModeServer {
@@ -84,3 +163,4 @@ export class MatterbridgeWaterHeaterModeServer extends WaterHeaterModeServer {
         return { status: ModeBase.ModeChangeStatus.Success, statusText: 'Success' };
     }
 }
+//# sourceMappingURL=waterHeater.js.map

package/dist/devices/waterHeater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterHeater.js","sourceRoot":"","sources":["../../src/devices/waterHeater.ts"],"names":[],"mappings":"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"}

package/dist/dgram/coap.d.ts

@@ -1,13 +1,141 @@
+/**
+ * @description This file contains the class Coap.
+ * @file src/dgram/coap.ts
+ * @author Luca Liguori
+ * @created 2025-03-22
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 import dgram from 'node:dgram';
 import { Multicast } from './multicast.js';
+/**
+ * Represents a CoAP message.
+ *
+ * A CoAP message is structured with a fixed header, an optional token, a series of options,
+ * and an optional payload. The header consists of version, type, token length, code, and message ID.
+ * The token is used to match responses with requests, options provide additional metadata, and
+ * the payload carries the message content.
+ */
 export interface CoapMessage {
+    /**
+     * The CoAP protocol version.
+     * Typically, this is 1.
+     * (Stored in the top 2 bits of the first header byte.)
+     */
     version: number;
+    /**
+     * The message type.
+     * It indicates whether the message is Confirmable, Non-confirmable, Acknowledgement, or Reset.
+     * (Stored in bits 5-4 of the first header byte.)
+     * 0: Confirmable (CON)
+     * 1: Non-confirmable (NON)
+     * 2: Acknowledgement (ACK)
+     * 3: Reset (RST)
+     */
     type: number;
+    /**
+     * The token length.
+     * This value (0-8) specifies the length of the token field.
+     * (Stored in the lower 4 bits of the first header byte.)
+     */
     tokenLength: number;
+    /**
+     * The message code.
+     * It indicates the method or response code, e.g., GET, POST, or a success/error response.
+     * (Stored in the second header byte.)
+     * CoAP uses an 8‑bit Code field divided into a 3‑bit class and a 5‑bit detail. The code can be represented as X.XX (e.g. 0.01) and is defined in RFC 7252. Here are the standard CoAP codes:
+     * Request Codes (Class 0)
+     * 0.01 – 1-GET
+     * Retrieve a resource.
+     * 0.02 – 2-POST
+     * Create a resource or trigger an action.
+     * 0.03 – 3-PUT
+     * Update or create a resource.
+     * 0.04 – 4-DELETE
+     * Remove a resource.
+     * Success Response Codes (Class 2)
+     * 2.00 – Empty / Success
+     * Indicates an empty message or a successful request with no payload.
+     * 2.01 – Created
+     * The request resulted in a new resource being created.
+     * 2.02 – Deleted
+     * The resource was successfully deleted.
+     * 2.03 – Valid
+     * The response indicates that the resource is still valid (used with caching).
+     * 2.04 – Changed
+     * The resource was successfully modified.
+     * 2.05 – Content
+     * The response contains the requested content.
+     * Client Error Response Codes (Class 4)
+     * 4.00 – Bad Request
+     * The request was malformed.
+     * 4.01 – Unauthorized
+     * The request requires authentication.
+     * 4.02 – Bad Option
+     * An option in the request was not understood or is unacceptable.
+     * 4.03 – Forbidden
+     * The server refuses to fulfill the request.
+     * 4.04 – Not Found
+     * The requested resource was not found.
+     * 4.05 – Method Not Allowed
+     * The request method is not supported for the target resource.
+     * 4.06 – Not Acceptable
+     * The server cannot generate a response matching the list of acceptable values.
+     * 4.12 – Precondition Failed
+     * A precondition given in the request evaluated to false.
+     * 4.13 – Request Entity Too Large
+     * The request payload is too large.
+     * 4.15 – Unsupported Content-Format
+     * The server does not support the content format of the request payload.
+     * Server Error Response Codes (Class 5)
+     * 5.00 – Internal Server Error
+     * The server encountered an unexpected condition.
+     * 5.01 – Not Implemented
+     * The server does not support the requested method.
+     * 5.02 – Bad Gateway
+     * The server, while acting as a gateway or proxy, received an invalid response.
+     * 5.03 – Service Unavailable
+     * The server is currently unable to handle the request.
+     * 5.04 – Gateway Timeout
+     * The server did not receive a timely response from an upstream server.
+     * 5.05 – Proxying Not Supported
+     * The server does not support proxying for the requested resource.
+     */
     code: number;
+    /**
+     * The message identifier.
+     * This 16-bit field is used to match messages of type Acknowledgement/Reset with their corresponding requests.
+     * (Stored in bytes 2-3 of the header.)
+     */
     messageId: number;
+    /**
+     * The token.
+     * A variable-length sequence (0-8 bytes) that helps match a request with its response.
+     */
     token: Buffer;
+    /**
+     * An array of options.
+     * Options carry additional information such as URI path, content format, etc., and are encoded using a delta mechanism.
+     */
     options: CoapOption[];
+    /**
+     * The payload.
+     * The actual content of the message, if present. It follows a payload marker (0xFF) if non-empty.
+     */
     payload?: Buffer;
 }
 interface CoapOption {
@@ -24,11 +152,54 @@ export declare class Coap extends Multicast {
     constructor(name: string, multicastAddress: string, multicastPort: number, socketType: 'udp4' | 'udp6', reuseAddr?: boolean | undefined, interfaceName?: string, interfaceAddress?: string);
     onCoapMessage(message: CoapMessage, rinfo: dgram.RemoteInfo): void;
     onMessage(msg: Buffer, rinfo: dgram.RemoteInfo): void;
+    /**
+     * Decodes a CoAP message from a Buffer.
+     *
+     * @param {Buffer} msg - The Buffer containing the raw CoAP message.
+     * @returns {CoapMessage} A parsed CoAP message object.
+     * @throws {Error} if the message is malformed.
+     */
     decodeCoapMessage(msg: Buffer): CoapMessage;
+    /**
+     * Encodes a CoAP message into a Buffer.
+     *
+     * @param {CoapMessage} msg - The CoAP message to encode.
+     * @returns {Buffer} A Buffer representing the encoded CoAP message.
+     * @throws {Error} if the message is malformed.
+     */
     encodeCoapMessage(msg: CoapMessage): Buffer;
+    /**
+     * Converts a CoAP message type numeric value to its string representation.
+     *
+     * CoAP message types are:
+     *  - 0: Confirmable (CON)
+     *  - 1: Non-confirmable (NON)
+     *  - 2: Acknowledgement (ACK)
+     *  - 3: Reset (RST)
+     *
+     * @param {number} type - The numeric CoAP message type.
+     * @returns {string} The string representation of the message type.
+     */
     coapTypeToString(type: number): string;
+    /**
+     * Converts a CoAP code numeric value to its string representation.
+     *
+     * The CoAP code is split into a 3-bit class and a 5-bit detail.
+     * For example:
+     *   - 0.01: GET
+     *   - 0.02: POST
+     *   - 0.03: PUT
+     *   - 0.04: DELETE
+     *   - 2.05: Content (success response)
+     *   - 4.04: Not Found (client error)
+     *   - 5.00: Internal Server Error (server error)
+     *
+     * @param {number} code - The numeric CoAP code.
+     * @returns {string} The string representation of the code.
+     */
     coapCodeToString(code: number): string;
     sendRequest(messageId: number, options: CoapOption[], payload: Record<string, any> | undefined, token: string | undefined, address: string | undefined, port: number | undefined): void;
     logCoapMessage(msg: CoapMessage): void;
 }
 export {};
+//# sourceMappingURL=coap.d.ts.map

package/dist/dgram/coap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coap.d.ts","sourceRoot":"","sources":["../../src/dgram/coap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,MAAM,YAAY,CAAC;AAM/B,OAAO,EAAoD,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE7F;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAC7C,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AAElD,qBAAa,IAAK,SAAQ,SAAS;gBACrB,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,GAAE,OAAO,GAAG,SAAgB,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM;IAIhM,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI;IAIzD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI;IAW9D;;;;;;OAMG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAwG3C;;;;;;OAMG;IACH,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM;IA6F3C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAetC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQtC,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,EAAE,EAErB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACxC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,IAAI;IAeP,cAAc,CAAC,GAAG,EAAE,WAAW;CAuDhC"}

package/dist/dgram/coap.js

@@ -1,4 +1,28 @@
+/**
+ * @description This file contains the class Coap.
+ * @file src/dgram/coap.ts
+ * @author Luca Liguori
+ * @created 2025-03-22
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// AnsiLogger imports
 import { BLUE, db, GREEN, MAGENTA, nf } from 'node-ansi-logger';
+// Net imports
 import { COAP_MULTICAST_IPV4_ADDRESS, COAP_MULTICAST_PORT, Multicast } from './multicast.js';
 export const COAP_OPTION_URI_PATH = 11;
 export const COIOT_OPTION_DEVID = 3332;
@@ -24,16 +48,26 @@ export class Coap extends Multicast {
             this.log.error(`Error decoding CoAP message: ${error instanceof Error ? error.message : error}`);
         }
     }
+    /**
+     * Decodes a CoAP message from a Buffer.
+     *
+     * @param {Buffer} msg - The Buffer containing the raw CoAP message.
+     * @returns {CoapMessage} A parsed CoAP message object.
+     * @throws {Error} if the message is malformed.
+     */
     decodeCoapMessage(msg) {
+        // A valid CoAP message must have at least 4 bytes for the header.
         if (msg.length < 4) {
             throw new Error('Message too short to be a valid CoAP message');
         }
-        const version = (msg[0] & 0xc0) >> 6;
-        const type = (msg[0] & 0x30) >> 4;
-        const tokenLength = msg[0] & 0x0f;
-        const code = msg[1];
-        const messageId = msg.readUInt16BE(2);
+        // Parse the 4-byte fixed header.
+        const version = (msg[0] & 0xc0) >> 6; // Bits 7-6: Version
+        const type = (msg[0] & 0x30) >> 4; // Bits 5-4: Type
+        const tokenLength = msg[0] & 0x0f; // Bits 3-0: Token Length
+        const code = msg[1]; // 8-bit Code
+        const messageId = msg.readUInt16BE(2); // 16-bit Message ID
         let offset = 4;
+        // Parse token if present.
         let token = Buffer.alloc(0);
         if (tokenLength > 0) {
             if (msg.length < offset + tokenLength) {
@@ -42,16 +76,20 @@ export class Coap extends Multicast {
             token = msg.slice(offset, offset + tokenLength);
             offset += tokenLength;
         }
+        // Parse options.
         const options = [];
         let currentOptionNumber = 0;
         while (offset < msg.length) {
+            // Payload marker: 0xFF indicates the beginning of the payload.
             if (msg[offset] === 0xff) {
-                offset++;
+                offset++; // Skip the marker.
                 break;
             }
+            // Read the option header byte.
             const optionHeader = msg[offset++];
-            let delta = (optionHeader & 0xf0) >> 4;
-            let length = optionHeader & 0x0f;
+            let delta = (optionHeader & 0xf0) >> 4; // High nibble: option delta.
+            let length = optionHeader & 0x0f; // Low nibble: option length.
+            // Extended delta handling.
             if (delta === 13) {
                 if (offset >= msg.length) {
                     throw new Error('Invalid extended option delta');
@@ -68,6 +106,7 @@ export class Coap extends Multicast {
             else if (delta === 15) {
                 throw new Error('Reserved option delta value encountered');
             }
+            // Extended length handling.
             if (length === 13) {
                 if (offset >= msg.length) {
                     throw new Error('Invalid extended option length');
@@ -84,7 +123,9 @@ export class Coap extends Multicast {
             else if (length === 15) {
                 throw new Error('Reserved option length value encountered');
             }
+            // Calculate the actual option number.
             currentOptionNumber += delta;
+            // Ensure that the option's value fits in the remaining message.
             if (offset + length > msg.length) {
                 throw new Error('Option length exceeds message length');
             }
@@ -95,6 +136,7 @@ export class Coap extends Multicast {
                 value: optionValue,
             });
         }
+        // Parse payload if any remains.
         const payload = offset < msg.length ? msg.slice(offset) : undefined;
         return {
             version,
@@ -107,23 +149,38 @@ export class Coap extends Multicast {
             payload,
         };
     }
+    /**
+     * Encodes a CoAP message into a Buffer.
+     *
+     * @param {CoapMessage} msg - The CoAP message to encode.
+     * @returns {Buffer} A Buffer representing the encoded CoAP message.
+     * @throws {Error} if the message is malformed.
+     */
     encodeCoapMessage(msg) {
         const parts = [];
+        // Determine token length (ensure it's consistent with msg.token)
         const token = msg.token || Buffer.alloc(0);
         const tokenLength = token.length;
         if (tokenLength > 8) {
             throw new Error('Token length cannot exceed 8 bytes');
         }
+        // Create header (4 bytes):
+        //   Byte 0: Version (2 bits), Type (2 bits), Token Length (4 bits)
+        //   Byte 1: Code (8 bits)
+        //   Bytes 2-3: Message ID (16 bits)
         const header = Buffer.alloc(4);
         header[0] = ((msg.version & 0x03) << 6) | ((msg.type & 0x03) << 4) | (tokenLength & 0x0f);
         header[1] = msg.code;
         header.writeUInt16BE(msg.messageId, 2);
         parts.push(header);
+        // Append token if present.
         if (tokenLength > 0) {
             parts.push(token);
         }
+        // Sort options by option number in ascending order.
         const sortedOptions = msg.options.slice().sort((a, b) => a.number - b.number);
         let previousOptionNumber = 0;
+        // Encode each option.
         for (const option of sortedOptions) {
             const optionDelta = option.number - previousOptionNumber;
             const optionValueLength = option.value.length;
@@ -131,6 +188,7 @@ export class Coap extends Multicast {
             let deltaExtended = null;
             let lengthNibble;
             let lengthExtended = null;
+            // Determine option delta nibble and extended delta field.
             if (optionDelta < 13) {
                 deltaNibble = optionDelta;
             }
@@ -143,6 +201,7 @@ export class Coap extends Multicast {
                 deltaExtended = Buffer.alloc(2);
                 deltaExtended.writeUInt16BE(optionDelta - 269, 0);
             }
+            // Determine option length nibble and extended length field.
             if (optionValueLength < 13) {
                 lengthNibble = optionValueLength;
             }
@@ -155,24 +214,42 @@ export class Coap extends Multicast {
                 lengthExtended = Buffer.alloc(2);
                 lengthExtended.writeUInt16BE(optionValueLength - 269, 0);
             }
+            // Option header byte: high nibble is delta, low nibble is length.
             const optionHeader = Buffer.alloc(1);
             optionHeader[0] = (deltaNibble << 4) | (lengthNibble & 0x0f);
             parts.push(optionHeader);
+            // Append extended delta if needed.
             if (deltaExtended) {
                 parts.push(deltaExtended);
             }
+            // Append extended length if needed.
             if (lengthExtended) {
                 parts.push(lengthExtended);
             }
+            // Append the option value.
             parts.push(option.value);
+            // Update previous option number.
             previousOptionNumber = option.number;
         }
+        // If a payload is present, add the payload marker (0xFF) followed by the payload.
         if (msg.payload && msg.payload.length > 0) {
-            parts.push(Buffer.from([0xff]));
+            parts.push(Buffer.from([0xff])); // Payload marker.
             parts.push(msg.payload);
         }
         return Buffer.concat(parts);
     }
+    /**
+     * Converts a CoAP message type numeric value to its string representation.
+     *
+     * CoAP message types are:
+     *  - 0: Confirmable (CON)
+     *  - 1: Non-confirmable (NON)
+     *  - 2: Acknowledgement (ACK)
+     *  - 3: Reset (RST)
+     *
+     * @param {number} type - The numeric CoAP message type.
+     * @returns {string} The string representation of the message type.
+     */
     coapTypeToString(type) {
         switch (type) {
             case 0:
@@ -187,18 +264,37 @@ export class Coap extends Multicast {
                 return `Unknown Type (${type})`;
         }
     }
+    /**
+     * Converts a CoAP code numeric value to its string representation.
+     *
+     * The CoAP code is split into a 3-bit class and a 5-bit detail.
+     * For example:
+     *   - 0.01: GET
+     *   - 0.02: POST
+     *   - 0.03: PUT
+     *   - 0.04: DELETE
+     *   - 2.05: Content (success response)
+     *   - 4.04: Not Found (client error)
+     *   - 5.00: Internal Server Error (server error)
+     *
+     * @param {number} code - The numeric CoAP code.
+     * @returns {string} The string representation of the code.
+     */
     coapCodeToString(code) {
+        // Split the code: the upper 3 bits form the class and the lower 5 bits form the detail.
         const cls = code >> 5;
         const detail = code & 0x1f;
         const codeStr = `${cls}.${detail.toString().padStart(2, '0')}`;
         return codeStr;
     }
-    sendRequest(messageId, options, payload, token, address, port) {
+    sendRequest(messageId, options, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    payload, token, address, port) {
         const coapMessage = {
             version: 1,
-            type: 1,
+            type: 1, // e.g., Confirmable
             tokenLength: token ? Buffer.from(token).length : 0,
-            code: 1,
+            code: 1, // e.g., GET
             messageId,
             token: token ? Buffer.from(token) : Buffer.alloc(0),
             options,
@@ -217,6 +313,10 @@ export class Coap extends Multicast {
                 this.log.info(`Option: COAP_OPTION_URI_PATH => ${GREEN}${option.value}${nf}`);
             }
             else if (option.number === COIOT_OPTION_DEVID) {
+                /*
+                 * First defined option is COIOT_OPTION_GLOBAL_DEVID. This is a global option and must be present in all CoIoT packages with request or payload.
+                 * Its value is a string in format <devtype>#<devid>#<version> for example SHSEN-1#4B3F9E#1 The whole option should be less than 50 bytes.
+                 */
                 const parts = option.value.toString().split('#');
                 const deviceModel = parts[0];
                 const deviceMac = parts[1];
@@ -224,10 +324,22 @@ export class Coap extends Multicast {
                 this.log.info(`Option: COIOT_OPTION_DEVID => ${option.value} => Model: ${GREEN}${deviceModel}${nf}, MAC: ${GREEN}${deviceMac}${nf}, Protocol: ${GREEN}${protocolRevision}${nf}`);
             }
             else if (option.number === COIOT_OPTION_SERIAL) {
+                /*
+                 * This option is mandatory in status response and publishes. It is a uint16_t in network byte order which indicates a change in the status report.
+                 * When a new status report is handled, all payload processing can be skipped if the serial number does not change from the last processed payload.
+                 * The value 0 is reserved and should not be sent. This allows easy initialization in the receiving devices.
+                 */
                 const serial = option.value.readUInt16BE(0);
                 this.log.info(`Option: COIOT_OPTION_SERIAL => 0x${option.value.toString('hex')} => serial: ${GREEN}${serial}${nf}`);
             }
             else if (option.number === COIOT_OPTION_VALIDITY) {
+                /*
+                 * COIOT_OPTION_STATUS_VALIDITY is a uint16_t in network byte order (big endian) that states the maximal time between this and the next status publish.
+                 * This way a device can state its report interval. If a report is not received from this device after the interval has passed the device should be considered offline.
+                 * The LS bit of this option controls how the value is scaled:
+                 * - If the LS bit is 0, the value is number of 1/10 of seconds in the validity period, so 2 is 0.2 seconds, 10 is a second, 600 is a minute, 65534 is 109 minutes and 13 seconds.
+                 * - If the LS bit is 1, the value is number of 4 seconds interval in the whole interval. So 3 is 12 seconds, 11 is 44 seconds and 65535 is more than 3 days.
+                 */
                 const validity = option.value.readUInt16BE(0);
                 let validFor = 0;
                 if ((validity & 0x1) === 0) {
@@ -242,7 +354,7 @@ export class Coap extends Multicast {
                 this.log.info(`Option: ${option.number} - ${option.value
                     .toString('hex')
                     .match(/.{1,2}/g)
-                    ?.join(' ')}`);
+                    ?.join(' ')}`); // Split into pairs of hex characters
         });
         if (msg.payload && msg.payload.length > 0)
             this.log.info(`Payload:`, JSON.parse(msg.payload.toString()), '\n');
@@ -250,3 +362,4 @@ export class Coap extends Multicast {
             this.log.info(`No payload`, '\n');
     }
 }
+//# sourceMappingURL=coap.js.map