zigbee-herdsman 3.5.1 → 4.0.0

package/src/adapter/zigate/driver/ziGateObject.ts

@@ -0,0 +1,146 @@
+/* v8 ignore start */
+
+import {logger} from "../../../utils/logger";
+import BuffaloZiGate, {type BuffaloZiGateOptions} from "./buffaloZiGate";
+import {ZiGateCommand, type ZiGateCommandParameter, type ZiGateCommandType} from "./commandType";
+import type {ZiGateCommandCode, ZiGateMessageCode, ZiGateObjectPayload} from "./constants";
+import ZiGateFrame from "./frame";
+import {ZiGateMessage, type ZiGateMessageParameter} from "./messageType";
+import ParameterType from "./parameterType";
+
+type ZiGateCode = ZiGateCommandCode | ZiGateMessageCode;
+type ZiGateParameter = ZiGateCommandParameter | ZiGateMessageParameter;
+
+const NS = "zh:zigate:object";
+
+const BufferAndListTypes: ParameterType[] = [
+    ParameterType.BUFFER,
+    ParameterType.BUFFER8,
+    ParameterType.BUFFER16,
+    ParameterType.BUFFER18,
+    ParameterType.BUFFER32,
+    ParameterType.BUFFER42,
+    ParameterType.BUFFER100,
+    ParameterType.LIST_UINT16,
+    ParameterType.LIST_UINT8,
+];
+
+class ZiGateObject {
+    private readonly _code: ZiGateCode;
+    private readonly _payload: ZiGateObjectPayload;
+    private readonly _parameters: ZiGateParameter[];
+    private readonly _frame?: ZiGateFrame;
+
+    private constructor(code: ZiGateCode, payload: ZiGateObjectPayload, parameters: ZiGateParameter[], frame?: ZiGateFrame) {
+        this._code = code;
+        this._payload = payload;
+        this._parameters = parameters;
+        this._frame = frame;
+    }
+
+    get code(): ZiGateCode {
+        return this._code;
+    }
+
+    get frame(): ZiGateFrame | undefined {
+        return this._frame;
+    }
+
+    get payload(): ZiGateObjectPayload {
+        return this._payload;
+    }
+
+    get command(): ZiGateCommandType {
+        return ZiGateCommand[this._code];
+    }
+
+    public static createRequest(commandCode: ZiGateCommandCode, payload: ZiGateObjectPayload): ZiGateObject {
+        const cmd = ZiGateCommand[commandCode];
+
+        if (!cmd) {
+            throw new Error(`Command '${commandCode}' not found`);
+        }
+
+        return new ZiGateObject(commandCode, payload, cmd.request);
+    }
+
+    public static fromZiGateFrame(frame: ZiGateFrame): ZiGateObject {
+        const code = frame.readMsgCode();
+        return ZiGateObject.fromBuffer(code, frame.msgPayloadBytes, frame);
+    }
+
+    public static fromBuffer(code: number, buffer: Buffer, frame: ZiGateFrame): ZiGateObject {
+        const msg = ZiGateMessage[code];
+
+        if (!msg) {
+            throw new Error(`Message '${code.toString(16)}' not found`);
+        }
+
+        const parameters = msg.response;
+        if (parameters === undefined) {
+            throw new Error(`Message '${code.toString(16)}' cannot be a response`);
+        }
+
+        const payload = ZiGateObject.readParameters(buffer, parameters);
+
+        return new ZiGateObject(code, payload, parameters, frame);
+    }
+
+    private static readParameters(buffer: Buffer, parameters: ZiGateParameter[]): ZiGateObjectPayload {
+        const buffalo = new BuffaloZiGate(buffer);
+        const result: ZiGateObjectPayload = {};
+
+        for (const parameter of parameters) {
+            const options: BuffaloZiGateOptions = {};
+
+            if (BufferAndListTypes.includes(parameter.parameterType)) {
+                // When reading a buffer, assume that the previous parsed parameter contains
+                // the length of the buffer
+                const lengthParameter = parameters[parameters.indexOf(parameter) - 1];
+                const length = result[lengthParameter.name];
+
+                if (typeof length === "number") {
+                    options.length = length;
+                }
+            }
+
+            try {
+                result[parameter.name] = buffalo.read(parameter.parameterType, options);
+            } catch (error) {
+                // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+                logger.error((error as Error).stack!, NS);
+            }
+        }
+
+        if (buffalo.isMore()) {
+            const bufferString = buffalo.getBuffer().toString("hex");
+            logger.debug(
+                `Last bytes of data were not parsed \x1b[32m${bufferString.slice(0, buffalo.getPosition() * 2).replace(/../g, "$& ")}` +
+                    `\x1b[31m${bufferString.slice(buffalo.getPosition() * 2).replace(/../g, "$& ")}\x1b[0m `,
+                NS,
+            );
+        }
+
+        return result;
+    }
+
+    public toZiGateFrame(): ZiGateFrame {
+        const buffer = this.createPayloadBuffer();
+        const frame = new ZiGateFrame();
+        frame.writeMsgCode(this._code as number);
+        frame.writeMsgPayload(buffer);
+        return frame;
+    }
+
+    private createPayloadBuffer(): Buffer {
+        const buffalo = new BuffaloZiGate(Buffer.alloc(256)); // hardcode @todo
+
+        for (const parameter of this._parameters) {
+            const value = this._payload[parameter.name];
+            buffalo.write(parameter.parameterType, value, {});
+        }
+        return buffalo.getWritten();
+    }
+}
+
+export default ZiGateObject;

package/src/adapter/zigate/driver/zigate.ts

@@ -0,0 +1,426 @@
+/* v8 ignore start */
+
+import assert from "node:assert";
+import {EventEmitter} from "node:events";
+import net from "node:net";
+
+import {DelimiterParser} from "@serialport/parser-delimiter";
+
+import {Queue} from "../../../utils";
+import {logger} from "../../../utils/logger";
+import {Waitress} from "../../../utils/waitress";
+import * as ZSpec from "../../../zspec";
+import * as Zdo from "../../../zspec/zdo";
+import type {EndDeviceAnnounce, GenericZdoResponse, ResponseMap as ZdoResponseMap} from "../../../zspec/zdo/definition/tstypes";
+import {SerialPort} from "../../serialPort";
+import SocketPortUtils from "../../socketPortUtils";
+import type {SerialPortOptions} from "../../tstype";
+import {type ZiGateResponseMatcher, type ZiGateResponseMatcherRule, equal} from "./commandType";
+import {Status, ZDO_REQ_CLUSTER_ID_TO_ZIGATE_COMMAND_ID, ZiGateCommandCode, ZiGateMessageCode, type ZiGateObjectPayload} from "./constants";
+import ZiGateFrame from "./frame";
+import ZiGateObject from "./ziGateObject";
+
+const NS = "zh:zigate:driver";
+
+const timeouts = {
+    reset: 30000,
+    default: 10000,
+};
+
+type WaitressMatcher = {
+    ziGateObject?: ZiGateObject;
+    rules: ZiGateResponseMatcher;
+    extraParameters?: object;
+};
+
+type ZdoWaitressPayload = {
+    ziGatePayload: {
+        status: number;
+        profileID: number;
+        clusterID: number;
+        sourceEndpoint: number;
+        destinationEndpoint: number;
+        sourceAddressMode: number;
+        sourceAddress: number | string;
+        destinationAddressMode: number;
+        destinationAddress: number | string;
+        payload: Buffer;
+    };
+    zdo: GenericZdoResponse;
+};
+
+type ZdoWaitressMatcher = {
+    clusterId: number;
+    target?: number | string;
+};
+
+function zeroPad(number: number, size?: number): string {
+    return number.toString(16).padStart(size || 4, "0");
+}
+// biome-ignore lint/suspicious/noExplicitAny: API
+function resolve(path: string | [], obj: {[k: string]: any}, separator = "."): any {
+    const properties = Array.isArray(path) ? path : path.split(separator);
+    return properties.reduce((prev, curr) => prev?.[curr], obj);
+}
+
+interface ZiGateEventMap {
+    close: [];
+    zdoResponse: [Zdo.ClusterId, GenericZdoResponse];
+    received: [ZiGateObject];
+    LeaveIndication: [ZiGateObject];
+    DeviceAnnounce: [EndDeviceAnnounce];
+}
+
+export default class ZiGate extends EventEmitter<ZiGateEventMap> {
+    private path: string;
+    private baudRate: number;
+    private initialized: boolean;
+
+    private parser?: EventEmitter;
+    private serialPort?: SerialPort;
+    private socketPort?: net.Socket;
+    private queue: Queue;
+
+    public portWrite?: SerialPort | net.Socket;
+    private waitress: Waitress<ZiGateObject, WaitressMatcher>;
+    private zdoWaitress: Waitress<ZdoWaitressPayload, ZdoWaitressMatcher>;
+
+    public constructor(path: string, serialPortOptions: SerialPortOptions) {
+        super();
+        this.path = path;
+        this.baudRate = typeof serialPortOptions.baudRate === "number" ? serialPortOptions.baudRate : 115200;
+        // XXX: not used?
+        // this.rtscts = typeof serialPortOptions.rtscts === 'boolean' ? serialPortOptions.rtscts : false;
+        this.initialized = false;
+        this.queue = new Queue(1);
+
+        this.waitress = new Waitress<ZiGateObject, WaitressMatcher>(this.waitressValidator, this.waitressTimeoutFormatter);
+        this.zdoWaitress = new Waitress<ZdoWaitressPayload, ZdoWaitressMatcher>(this.zdoWaitressValidator, this.waitressTimeoutFormatter);
+    }
+
+    public async sendCommand(
+        code: ZiGateCommandCode,
+        payload?: ZiGateObjectPayload,
+        timeout?: number,
+        extraParameters?: object,
+        disableResponse = false,
+    ): Promise<ZiGateObject> {
+        const waiters: Promise<ZiGateObject>[] = [];
+        const waitersId: number[] = [];
+        return await this.queue.execute(async () => {
+            try {
+                logger.debug(
+                    () => `Send command \x1b[32m>>>> ${ZiGateCommandCode[code]} 0x${zeroPad(code)} <<<<\x1b[0m \nPayload: ${JSON.stringify(payload)}`,
+                    NS,
+                );
+                const ziGateObject = ZiGateObject.createRequest(code, payload);
+                const frame = ziGateObject.toZiGateFrame();
+                logger.debug(() => `${JSON.stringify(frame)}`, NS);
+
+                const sendBuffer = frame.toBuffer();
+                logger.debug(`<-- send command ${sendBuffer.toString("hex")}`, NS);
+                logger.debug(`DisableResponse: ${disableResponse}`, NS);
+
+                if (!disableResponse && Array.isArray(ziGateObject.command.response)) {
+                    for (const rules of ziGateObject.command.response) {
+                        const waiter = this.waitress.waitFor({ziGateObject, rules, extraParameters}, timeout || timeouts.default);
+                        waitersId.push(waiter.ID);
+                        waiters.push(waiter.start().promise);
+                    }
+                }
+
+                let resultPromise: Promise<ZiGateObject> | undefined;
+                if (ziGateObject.command.waitStatus !== false) {
+                    const ruleStatus: ZiGateResponseMatcher = [
+                        {receivedProperty: "code", matcher: equal, value: ZiGateMessageCode.Status},
+                        {receivedProperty: "payload.packetType", matcher: equal, value: ziGateObject.code},
+                    ];
+
+                    const statusWaiter = this.waitress.waitFor({ziGateObject, rules: ruleStatus}, timeout || timeouts.default).start();
+                    resultPromise = statusWaiter.promise;
+                }
+
+                // @ts-expect-error assumed proper based on port type
+                // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+                this.portWrite!.write(sendBuffer);
+
+                if (ziGateObject.command.waitStatus !== false && resultPromise) {
+                    const statusResponse: ZiGateObject = await resultPromise;
+                    if (statusResponse.payload.status !== Status.E_SL_MSG_STATUS_SUCCESS) {
+                        waitersId.map((id) => this.waitress.remove(id));
+                        return await Promise.reject(new Error(`${statusResponse}`));
+                    }
+
+                    if (waiters.length === 0) {
+                        return await Promise.resolve(statusResponse);
+                    }
+                }
+                return await Promise.race(waiters);
+            } catch (e) {
+                logger.error(`sendCommand error ${e}`, NS);
+                return await Promise.reject(new Error(`sendCommand error: ${e}`));
+            }
+        });
+    }
+
+    public async requestZdo(clusterId: Zdo.ClusterId, payload: Buffer): Promise<boolean> {
+        return await this.queue.execute(async () => {
+            const commandCode = ZDO_REQ_CLUSTER_ID_TO_ZIGATE_COMMAND_ID[clusterId];
+            assert(commandCode !== undefined, `ZDO cluster ID '${clusterId}' not supported.`);
+            const ruleStatus: ZiGateResponseMatcher = [
+                {receivedProperty: "code", matcher: equal, value: ZiGateMessageCode.Status},
+                {receivedProperty: "payload.packetType", matcher: equal, value: commandCode},
+            ];
+
+            logger.debug(() => `ZDO ${Zdo.ClusterId[clusterId]}(cmd code: ${commandCode}) ${payload.toString("hex")}`, NS);
+
+            const frame = new ZiGateFrame();
+            frame.writeMsgCode(commandCode);
+            frame.writeMsgPayload(payload);
+
+            logger.debug(() => `ZDO ${JSON.stringify(frame)}`, NS);
+
+            const sendBuffer = frame.toBuffer();
+
+            logger.debug(`<-- ZDO send command ${sendBuffer.toString("hex")}`, NS);
+
+            const statusWaiter = this.waitress.waitFor({rules: ruleStatus}, timeouts.default);
+
+            // @ts-expect-error assumed proper based on port type
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.portWrite!.write(sendBuffer);
+
+            const statusResponse: ZiGateObject = await statusWaiter.start().promise;
+
+            return statusResponse.payload.status === Status.E_SL_MSG_STATUS_SUCCESS;
+        });
+    }
+
+    public open(): Promise<void> {
+        return SocketPortUtils.isTcpPath(this.path) ? this.openSocketPort() : this.openSerialPort();
+    }
+
+    public async close(): Promise<void> {
+        logger.info("closing", NS);
+        this.queue.clear();
+
+        if (this.initialized) {
+            this.portWrite = undefined;
+            this.initialized = false;
+
+            if (this.serialPort) {
+                try {
+                    await this.serialPort.asyncFlushAndClose();
+                } catch (error) {
+                    this.emit("close");
+
+                    throw error;
+                }
+            } else {
+                this.socketPort?.destroy();
+            }
+        }
+
+        this.emit("close");
+    }
+
+    private async openSerialPort(): Promise<void> {
+        this.serialPort = new SerialPort({
+            path: this.path,
+            baudRate: this.baudRate,
+            dataBits: 8,
+            parity: "none" /* one of ['none', 'even', 'mark', 'odd', 'space'] */,
+            stopBits: 1 /* one of [1,2] */,
+            lock: false,
+            autoOpen: false,
+        });
+        this.parser = this.serialPort.pipe(new DelimiterParser({delimiter: [ZiGateFrame.STOP_BYTE], includeDelimiter: true}));
+        this.parser.on("data", this.onSerialData.bind(this));
+
+        this.portWrite = this.serialPort;
+
+        try {
+            await this.serialPort.asyncOpen();
+            logger.debug("Serialport opened", NS);
+
+            this.serialPort.once("close", this.onPortClose.bind(this));
+            this.serialPort.once("error", this.onPortError.bind(this));
+
+            this.initialized = true;
+        } catch (error) {
+            this.initialized = false;
+
+            if (this.serialPort.isOpen) {
+                this.serialPort.close();
+            }
+
+            throw error;
+        }
+    }
+
+    private async openSocketPort(): Promise<void> {
+        const info = SocketPortUtils.parseTcpPath(this.path);
+        logger.debug(`Opening TCP socket with ${info.host}:${info.port}`, NS);
+
+        this.socketPort = new net.Socket();
+        this.socketPort.setNoDelay(true);
+        this.socketPort.setKeepAlive(true, 15000);
+
+        this.parser = this.socketPort.pipe(new DelimiterParser({delimiter: [ZiGateFrame.STOP_BYTE], includeDelimiter: true}));
+        this.parser.on("data", this.onSerialData.bind(this));
+
+        this.portWrite = this.socketPort;
+        return await new Promise((resolve, reject): void => {
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.socketPort!.on("connect", () => {
+                logger.debug("Socket connected", NS);
+            });
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.socketPort!.on("ready", () => {
+                logger.debug("Socket ready", NS);
+                this.initialized = true;
+                resolve();
+            });
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.socketPort!.once("close", this.onPortClose.bind(this));
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.socketPort!.on("error", (error) => {
+                logger.error(`Socket error ${error}`, NS);
+                reject(new Error("Error while opening socket"));
+                this.initialized = false;
+            });
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            this.socketPort!.connect(info.port, info.host);
+        });
+    }
+
+    private onPortError(error: Error): void {
+        logger.error(`Port error: ${error}`, NS);
+    }
+
+    private onPortClose(): void {
+        logger.debug("Port closed", NS);
+        this.initialized = false;
+        this.emit("close");
+    }
+
+    private onSerialData(buffer: Buffer): void {
+        try {
+            // logger.debug(() => `--- parseNext ${JSON.stringify(buffer)}`, NS);
+
+            const frame = new ZiGateFrame(buffer);
+            if (!(frame instanceof ZiGateFrame)) return; // @Todo fix
+
+            const code = frame.readMsgCode();
+            const msgName = `${ZiGateMessageCode[code] ? ZiGateMessageCode[code] : ""} 0x${zeroPad(code)}`;
+
+            logger.debug(`--> parsed frame \x1b[1;34m>>>> ${msgName} <<<<\x1b[0m `, NS);
+
+            try {
+                const ziGateObject = ZiGateObject.fromZiGateFrame(frame);
+                logger.debug(() => `${JSON.stringify(ziGateObject.payload)}`, NS);
+
+                if (code === ZiGateMessageCode.DataIndication && ziGateObject.payload.profileID === Zdo.ZDO_PROFILE_ID) {
+                    const ziGatePayload: ZdoWaitressPayload["ziGatePayload"] = ziGateObject.payload;
+                    // requests don't have tsn, but responses do
+                    // https://zigate.fr/documentation/commandes-zigate/
+                    const zdo = Zdo.Buffalo.readResponse(true, ziGatePayload.clusterID, ziGatePayload.payload);
+
+                    this.zdoWaitress.resolve({ziGatePayload, zdo});
+                    this.emit("zdoResponse", ziGatePayload.clusterID, zdo);
+                } else if (code === ZiGateMessageCode.LeaveIndication && ziGateObject.payload.rejoin === 0) {
+                    // mock a ZDO response (if waiter present) as zigate does not follow spec on this (missing ZDO LEAVE_RESPONSE)
+                    const ziGatePayload: ZdoWaitressPayload["ziGatePayload"] = {
+                        status: 0,
+                        profileID: Zdo.ZDO_PROFILE_ID,
+                        clusterID: Zdo.ClusterId.LEAVE_RESPONSE, // only piece actually required for waitress validation
+                        sourceEndpoint: Zdo.ZDO_ENDPOINT,
+                        destinationEndpoint: Zdo.ZDO_ENDPOINT,
+                        sourceAddressMode: 0x03,
+                        sourceAddress: ziGateObject.payload.extendedAddress,
+                        destinationAddressMode: 0x03,
+                        destinationAddress: ZSpec.BLANK_EUI64,
+                        // @ts-expect-error not used
+                        payload: undefined,
+                    };
+
+                    // Workaround: `zdo` is not valid for LEAVE_RESPONSE, but required to pass altered waitress validation (in sendZdo)
+                    if (this.zdoWaitress.resolve({ziGatePayload, zdo: [Zdo.Status.SUCCESS, {eui64: ziGateObject.payload.extendedAddress}]})) {
+                        this.emit("zdoResponse", Zdo.ClusterId.LEAVE_RESPONSE, [
+                            Zdo.Status.SUCCESS,
+                            undefined,
+                        ] as ZdoResponseMap[Zdo.ClusterId.LEAVE_RESPONSE]);
+                    }
+
+                    this.emit("LeaveIndication", ziGateObject);
+                } else {
+                    this.waitress.resolve(ziGateObject);
+
+                    if (code === ZiGateMessageCode.DataIndication) {
+                        if (ziGateObject.payload.profileID === ZSpec.HA_PROFILE_ID) {
+                            this.emit("received", ziGateObject);
+                        } else {
+                            logger.debug(`not implemented profile: ${ziGateObject.payload.profileID}`, NS);
+                        }
+                    } else if (code === ZiGateMessageCode.DeviceAnnounce) {
+                        this.emit("DeviceAnnounce", {
+                            nwkAddress: ziGateObject.payload.shortAddress,
+                            eui64: ziGateObject.payload.ieee,
+                            capabilities: ziGateObject.payload.MACcapability,
+                        });
+                    }
+                }
+            } catch (error) {
+                logger.error(`Parsing error: ${error}`, NS);
+            }
+        } catch (error) {
+            logger.error(`Error while parsing Frame '${error}'`, NS);
+        }
+    }
+
+    private waitressTimeoutFormatter(matcher: WaitressMatcher | ZdoWaitressMatcher, timeout: number): string {
+        return `${JSON.stringify(matcher)} after ${timeout}ms`;
+    }
+
+    private waitressValidator(ziGateObject: ZiGateObject, matcher: WaitressMatcher): boolean {
+        const validator = (rule: ZiGateResponseMatcherRule): boolean => {
+            try {
+                let expectedValue: string | number;
+                if (rule.value == null && rule.expectedProperty != null) {
+                    assert(matcher.ziGateObject, "Matcher ziGateObject expected valid.");
+                    expectedValue = resolve(rule.expectedProperty, matcher.ziGateObject);
+                } else if (rule.value == null && rule.expectedExtraParameter != null) {
+                    // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+                    expectedValue = resolve(rule.expectedExtraParameter, matcher.extraParameters!); // XXX: assumed valid?
+                } else {
+                    // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+                    expectedValue = rule.value!; // XXX: assumed valid?
+                }
+                const receivedValue = resolve(rule.receivedProperty, ziGateObject);
+                return rule.matcher(expectedValue, receivedValue);
+            } catch {
+                return false;
+            }
+        };
+        return matcher.rules.every(validator);
+    }
+
+    public zdoWaitFor(matcher: ZdoWaitressMatcher): ReturnType<typeof this.zdoWaitress.waitFor> {
+        return this.zdoWaitress.waitFor(matcher, timeouts.default);
+    }
+
+    private zdoWaitressValidator(payload: ZdoWaitressPayload, matcher: ZdoWaitressMatcher): boolean {
+        return (
+            (matcher.target === undefined ||
+                (typeof matcher.target === "number"
+                    ? matcher.target === payload.ziGatePayload.sourceAddress
+                    : // @ts-expect-error checked with ?
+                      matcher.target === payload.zdo?.[1]?.eui64)) &&
+            payload.ziGatePayload.clusterID === matcher.clusterId
+        );
+    }
+}

package/src/adapter/zoh/adapter/utils.ts

@@ -0,0 +1,27 @@
+/**
+ * @param value 64-bit bigint
+ * @returns 16-length hex string in big-endian
+ */
+export function bigUInt64ToHexBE(value: bigint): string {
+    return value.toString(16).padStart(16, "0");
+}
+
+/**
+ * @param value 64-bit bigint
+ * @returns 8-bytelength buffer in little-endian
+ */
+export function bigUInt64ToBufferLE(value: bigint): Buffer {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(value, 0);
+    return b;
+}
+
+/**
+ * @param value 64-bit bigint
+ * @returns 8-bytelength buffer in big-endian
+ */
+export function bigUInt64ToBufferBE(value: bigint): Buffer {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64BE(value, 0);
+    return b;
+}