zigbee-herdsman 3.5.1 → 4.0.0

package/src/adapter/z-stack/structs/struct.ts

@@ -0,0 +1,367 @@
+import assert from "node:assert";
+
+import type {SerializableMemoryObject} from "./serializable-memory-object";
+
+/* Helper Types */
+type StructMemberType = "uint8" | "uint16" | "uint32" | "uint8array" | "uint8array-reversed" | "struct";
+type StructBuildOmitKeys = "member" | "method" | "padding" | "build" | "default";
+type StructChild = {offset: number; struct: Struct};
+export type BuiltStruct<T = Struct> = Omit<T, StructBuildOmitKeys>;
+export type StructFactorySignature<T = Struct> = (data?: Buffer) => T;
+
+export type StructMemoryAlignment = "unaligned" | "aligned";
+
+/**
+ * Struct provides a builder-like interface to create Buffer-based memory
+ * structures for read/write interfacing with data structures from adapters.
+ */
+export class Struct implements SerializableMemoryObject {
+    /**
+     * Creates an empty struct. Further calls to `member()` and `method()` functions will form the structure.
+     * Finally call to `build()` will type the resulting structure appropriately without internal functions.
+     */
+    public static new(): Struct {
+        return new Struct();
+    }
+
+    // @ts-expect-error initialized in `build()`
+    private buffer: Buffer;
+    private defaultData: Buffer | undefined;
+    private members: {key: string; offset: number; type: StructMemberType; length?: number}[] = [];
+    private childStructs: {[key: string]: StructChild} = {};
+    private length = 0;
+    private paddingByte = 0x00;
+
+    private constructor() {}
+
+    /**
+     * Returns raw contents of the structure as a sliced Buffer.
+     * Mutations to the returned buffer will not be reflected within struct.
+     */
+    public serialize(alignment: StructMemoryAlignment = "unaligned", padLength = true, parentOffset = 0): Buffer {
+        switch (alignment) {
+            case "unaligned": {
+                /* update child struct values and return as-is (unaligned) */
+                for (const key of Object.keys(this.childStructs)) {
+                    const child = this.childStructs[key];
+                    this.buffer.set(child.struct.serialize(alignment), child.offset);
+                }
+                return Buffer.from(this.buffer);
+            }
+            case "aligned": {
+                /* create 16-bit aligned buffer */
+                const aligned = Buffer.alloc(this.getLength(alignment, padLength, parentOffset), this.paddingByte);
+                let offset = 0;
+                for (const member of this.members) {
+                    switch (member.type) {
+                        case "uint8":
+                            aligned.set(this.buffer.slice(member.offset, member.offset + 1), offset);
+                            offset += 1;
+                            break;
+                        case "uint16":
+                            offset += offset % 2;
+                            aligned.set(this.buffer.slice(member.offset, member.offset + 2), offset);
+                            offset += 2;
+                            break;
+                        case "uint32":
+                            offset += offset % 2;
+                            aligned.set(this.buffer.slice(member.offset, member.offset + 4), offset);
+                            offset += 4;
+                            break;
+                        case "uint8array":
+                        case "uint8array-reversed":
+                            assert(member.length !== undefined);
+                            aligned.set(this.buffer.slice(member.offset, member.offset + member.length), offset);
+                            offset += member.length;
+                            break;
+                        case "struct": {
+                            const structData = this.childStructs[member.key].struct.serialize(alignment, false, offset);
+                            aligned.set(structData, offset);
+                            offset += structData.length;
+                            break;
+                        }
+                    }
+                }
+                return aligned;
+            }
+        }
+    }
+
+    /**
+     * Returns total length of the struct. Struct length is always fixed and configured
+     * by calls to `member()` methods.
+     */
+    public getLength(alignment: StructMemoryAlignment = "unaligned", padLength = true, parentOffset = 0): number {
+        switch (alignment) {
+            case "unaligned": {
+                /* return actual length */
+                return this.length;
+            }
+            case "aligned": {
+                /* compute aligned length and return */
+                let length = this.members.reduce((offset, member) => {
+                    switch (member.type) {
+                        case "uint8":
+                            offset += 1;
+                            break;
+                        case "uint16":
+                            offset += ((parentOffset + offset) % 2) + 2;
+                            break;
+                        case "uint32":
+                            offset += ((parentOffset + offset) % 2) + 4;
+                            break;
+                        case "uint8array":
+                        case "uint8array-reversed":
+                            assert(member.length !== undefined);
+                            offset += member.length;
+                            break;
+                        case "struct":
+                            offset += this.childStructs[member.key].struct.getLength(alignment, false);
+                            break;
+                    }
+                    return offset;
+                }, 0);
+                if (padLength) {
+                    length += length % 2;
+                }
+                return length;
+            }
+        }
+    }
+
+    /**
+     * Returns structure contents in JS object format.
+     */
+    public toJSON() {
+        return this.members.reduce((a, c) => {
+            // biome-ignore lint/suspicious/noExplicitAny: API
+            a[c.key] = (this as any)[c.key];
+            return a;
+            // biome-ignore lint/suspicious/noExplicitAny: API
+        }, {} as any);
+    }
+
+    /**
+     * Adds a numeric member of `uint8`, `uint16` or `uint32` type.
+     * Internal representation is always little endian.
+     *
+     * *This method is stripped from type on struct `build()`.*
+     *
+     * @param type Underlying data type (uint8, uint16 or uint32).
+     * @param name Name of the struct member.
+     */
+    public member<T extends number, N extends string, R extends this & Record<N, T>>(type: "uint8" | "uint16" | "uint32", name: N): R;
+
+    /**
+     * Adds an uint8 array (byte array) as a struct member.
+     *
+     * *This method is stripped from type on struct `build()`.*
+     *
+     * @param type Underlying data type. Must be `uint8array`.
+     * @param name Name of the struct member.
+     * @param length Length of the byte array.
+     */
+    public member<T extends Buffer, N extends string, R extends this & Record<N, T>>(
+        type: "uint8array" | "uint8array-reversed",
+        name: N,
+        length: number,
+    ): R;
+
+    /**
+     * Adds another struct type as a struct member. Struct factory is provided
+     * as a child struct definition source.
+     *
+     * *This method is stripped from type on struct `build()`.*
+     *
+     * @param type Underlying data type. Must be `struct`.
+     * @param name Name of the struct member.
+     * @param structFactory Factory providing the wanted child struct.
+     */
+    public member<T extends BuiltStruct, N extends string, R extends this & Record<N, T>>(
+        type: "struct",
+        name: N,
+        structFactory: StructFactorySignature<T>,
+    ): R;
+
+    public member<T extends number | BuiltStruct, N extends string, R extends this & Record<N, T>>(
+        type: StructMemberType,
+        name: N,
+        lengthOrStructFactory?: number | StructFactorySignature<T>,
+    ): R {
+        const offset = this.length;
+        const structFactory = type === "struct" ? (lengthOrStructFactory as StructFactorySignature<T>) : undefined;
+        const length = structFactory ? (structFactory() as unknown as Struct).length : (lengthOrStructFactory as number);
+
+        switch (type) {
+            case "uint8": {
+                Object.defineProperty(this, name, {
+                    enumerable: true,
+                    get: () => this.buffer.readUInt8(offset),
+                    set: (value: number) => this.buffer.writeUInt8(value, offset),
+                });
+                this.length += 1;
+                break;
+            }
+            case "uint16": {
+                Object.defineProperty(this, name, {
+                    enumerable: true,
+                    get: () => this.buffer.readUInt16LE(offset),
+                    set: (value: number) => this.buffer.writeUInt16LE(value, offset),
+                });
+                this.length += 2;
+                break;
+            }
+            case "uint32": {
+                Object.defineProperty(this, name, {
+                    enumerable: true,
+                    get: () => this.buffer.readUInt32LE(offset),
+                    set: (value: number) => this.buffer.writeUInt32LE(value, offset),
+                });
+                this.length += 4;
+                break;
+            }
+            case "uint8array":
+            case "uint8array-reversed": {
+                /* v8 ignore start */
+                if (!length) {
+                    throw new Error("Struct builder requires length for `uint8array` and `uint8array-reversed` type");
+                }
+                /* v8 ignore stop */
+                Object.defineProperty(this, name, {
+                    enumerable: true,
+                    get: () =>
+                        type === "uint8array-reversed"
+                            ? Buffer.from(this.buffer.slice(offset, offset + length)).reverse()
+                            : Buffer.from(this.buffer.slice(offset, offset + length)),
+                    set: (value: Buffer) => {
+                        if (value.length !== length) {
+                            throw new Error(`Invalid length for member ${name} (expected=${length}, got=${value.length})`);
+                        }
+                        if (type === "uint8array-reversed") {
+                            value = Buffer.from(value).reverse();
+                        }
+                        for (let i = 0; i < length; i++) {
+                            this.buffer[offset + i] = value[i];
+                        }
+                    },
+                });
+                this.length += length;
+                break;
+            }
+            case "struct": {
+                assert(structFactory);
+                this.childStructs[name] = {offset, struct: structFactory() as unknown as Struct};
+                Object.defineProperty(this, name, {
+                    enumerable: true,
+                    get: () => this.childStructs[name].struct,
+                });
+                this.length += length;
+            }
+        }
+        this.members.push({key: name, offset, type, length});
+        return this as unknown as R;
+    }
+
+    /**
+     * Adds a custom method to the struct.
+     *
+     * *This method is stripped from type on struct `build()`.*
+     *
+     * @param name Name of the method to be appended.
+     * @param _returnType Return type (eg. `Buffer.prototype`).
+     * @param body Function implementation. Takes struct as a first and single input parameter.
+     */
+    public method<T, N extends string, R extends this & Record<N, () => T>>(name: N, _returnType: T, body: (struct: R) => T): R {
+        Object.defineProperty(this, name, {
+            enumerable: true,
+            configurable: false,
+            writable: false,
+            // @ts-expect-error ignore because we are using `this`
+            value: () => body.bind(this)(this),
+        });
+        return this as unknown as R;
+    }
+
+    /**
+     * Sets default data to initialize empty struct with.
+     *
+     * @param data Data to initialize empty struct with.
+     */
+    public default(data: Buffer): this {
+        /* v8 ignore start */
+        if (data.length !== this.length) {
+            throw new Error("Default value needs to have the length of unaligned structure.");
+        }
+        /* v8 ignore stop */
+        this.defaultData = Buffer.from(data);
+        return this;
+    }
+
+    /**
+     * Sets byte to use for padding.
+     *
+     * @param padding Byte to use for padding
+     */
+    public padding(padding = 0x00): this {
+        this.paddingByte = padding;
+        return this;
+    }
+
+    /**
+     * Creates the struct and optionally fills it with data. If data is provided, the length
+     * of the provided buffer needs to match the structure length.
+     *
+     * *This method is stripped from type on struct `build()`.*
+     */
+    public build(data?: Buffer): BuiltStruct<this> {
+        if (data) {
+            if (data.length === this.getLength("unaligned")) {
+                this.buffer = Buffer.from(data);
+                for (const key of Object.keys(this.childStructs)) {
+                    const child = this.childStructs[key];
+                    child.struct.build(this.buffer.slice(child.offset, child.offset + child.struct.length));
+                }
+            } else if (data.length === this.getLength("aligned")) {
+                this.buffer = Buffer.alloc(this.length, this.paddingByte);
+                let offset = 0;
+                for (const member of this.members) {
+                    switch (member.type) {
+                        case "uint8":
+                            this.buffer.set(data.slice(offset, offset + 1), member.offset);
+                            offset += 1;
+                            break;
+                        case "uint16":
+                            offset += offset % 2;
+                            this.buffer.set(data.slice(offset, offset + 2), member.offset);
+                            offset += 2;
+                            break;
+                        case "uint32":
+                            offset += offset % 2;
+                            this.buffer.set(data.slice(offset, offset + 4), member.offset);
+                            offset += 4;
+                            break;
+                        case "uint8array":
+                        case "uint8array-reversed":
+                            assert(member.length !== undefined);
+                            this.buffer.set(data.slice(offset, offset + member.length), member.offset);
+                            offset += member.length;
+                            break;
+                        case "struct": {
+                            const child = this.childStructs[member.key];
+                            child.struct.build(data.slice(offset, offset + child.struct.length));
+                            this.buffer.set(child.struct.serialize(), member.offset);
+                            offset += child.struct.length;
+                            break;
+                        }
+                    }
+                }
+            } else {
+                const expectedLengths = `${this.getLength("unaligned")}/${this.getLength("aligned")}`;
+                throw new Error(`Struct length mismatch (expected=${expectedLengths}, got=${data.length})`);
+            }
+        } else {
+            this.buffer = this.defaultData ? Buffer.from(this.defaultData) : Buffer.alloc(this.length);
+        }
+        return this;
+    }
+}

package/src/adapter/z-stack/structs/table.ts

@@ -0,0 +1,198 @@
+import assert from "node:assert";
+
+import type {SerializableMemoryObject} from "./serializable-memory-object";
+import type {BuiltStruct, StructFactorySignature, StructMemoryAlignment} from "./struct";
+
+type TableBuildOmitKeys = "struct" | "header" | "occupancy" | "load" | "build" | "inlineHeader";
+export type BuiltTable<R extends BuiltStruct, T = Table<R>> = Omit<T, TableBuildOmitKeys>;
+export type TableFactorySignature<R extends BuiltStruct, T = Table<R>> = (data?: Buffer) => T;
+
+/**
+ * Table structure wraps `Struct`-based entries for tables present within ZNP NV memory.
+ */
+export class Table<R extends BuiltStruct> implements SerializableMemoryObject {
+    /**
+     * Create a new table builder.
+     */
+    public static new<R extends BuiltStruct>(): Table<R> {
+        return new Table();
+    }
+
+    // @ts-expect-error initialized in `build()`
+    private data: R[];
+    // @ts-expect-error initialized in `struct()`
+    private emptyEntry: R;
+    private hasInlineLengthHeader = false;
+    // @ts-expect-error initialized in `struct()`
+    private entryStructFactory: StructFactorySignature<R>;
+    private entryOccupancyFunction: ((entry: R) => boolean) | undefined;
+
+    private constructor() {}
+
+    /**
+     * Return total capacity of the table.
+     */
+    public get capacity(): number {
+        return this.data.length;
+    }
+
+    /**
+     * Returns all entries within table.
+     */
+    public get entries(): R[] {
+        return this.data;
+    }
+
+    /**
+     * Returns all used entries.
+     */
+    public get used(): R[] {
+        assert(this.entryOccupancyFunction, "Table usage cannot be determined without occupancy function when header is not present.");
+        const fun = this.entryOccupancyFunction;
+        return this.entries.filter((e) => fun(e));
+    }
+
+    /**
+     * Returns all unused entries.
+     */
+    public get free(): R[] {
+        assert(this.entryOccupancyFunction, "Table usage cannot be determined without occupancy function when header is not present.");
+        const fun = this.entryOccupancyFunction;
+        return this.entries.filter((e) => !fun(e));
+    }
+
+    /**
+     * Return number of records marked as free.
+     */
+    public get freeCount(): number {
+        return this.free.length;
+    }
+
+    /**
+     * Return number of records marked as used.
+     */
+    public get usedCount(): number {
+        return this.used.length;
+    }
+
+    /**
+     * Return next free entry or `null` if no entries are free within the table.
+     */
+    public getNextFree(): R {
+        return this.free[0] ?? null;
+    }
+
+    /**
+     * Returns index of element in table.
+     *
+     * @param entry Entry to resolve index for.
+     */
+    public indexOf(entry: R): number | null {
+        return this.entries.findIndex((e) => e.serialize().equals(entry.serialize())) ?? /* v8 ignore next */ null;
+    }
+
+    /**
+     * Export the table in target platform format.
+     *
+     * @param alignment Memory alignment to use for export.
+     */
+    public serialize(alignment: StructMemoryAlignment = "unaligned"): Buffer {
+        const entryLength = this.emptyEntry.getLength(alignment);
+        const output = Buffer.alloc((this.hasInlineLengthHeader ? 2 : 0) + this.capacity * entryLength, 0x00);
+        let offset = 0;
+        if (this.hasInlineLengthHeader) {
+            output.writeUInt16LE(this.usedCount);
+            offset += 2;
+        }
+        for (const e of this.data) {
+            output.set(e.serialize(alignment), offset);
+            offset += e.getLength(alignment);
+        }
+        return output;
+    }
+
+    /**
+     * Applies function to determine table entry occupancy. This function is invoked with an entry instance
+     * and returns `boolean` indicating if the entry is occupied or not.
+     *
+     * @param fn Function to determine entry occupancy.
+     */
+    public occupancy(fn: (entry: R) => boolean): this {
+        this.entryOccupancyFunction = fn;
+        return this;
+    }
+
+    /**
+     * Defines a struct factory for entries contained within table.
+     *
+     * @param entryStructFactory Struct factory.
+     */
+    public struct(entryStructFactory: StructFactorySignature<R>): this {
+        this.entryStructFactory = entryStructFactory;
+        this.emptyEntry = this.entryStructFactory();
+        return this;
+    }
+
+    /**
+     * Sets whether the table has a table header containing a 16-bit unsigned used table length.
+     *
+     * @param hasInlineHeader Sets whether table has record count header.
+     */
+    public inlineHeader(hasInlineHeader = true): this {
+        this.hasInlineLengthHeader = hasInlineHeader;
+        return this;
+    }
+
+    /**
+     * Builds the table from existing buffer or buffers representing entries.
+     *
+     * @param data Buffer to populate table from.
+     * @param alignment Memory alignment of the source platform.
+     */
+    public build(data: Buffer | Buffer[], alignment?: StructMemoryAlignment): BuiltTable<R>;
+
+    /**
+     * Creates an empty table with set capacity.
+     *
+     * @param capacity Capacity to create the table with.
+     */
+    public build(capacity: number): BuiltTable<R>;
+
+    public build(dataOrCapacity: Buffer | Buffer[] | number, alignment: StructMemoryAlignment = "unaligned"): BuiltTable<R> {
+        /* v8 ignore start */
+        if (!this.entryStructFactory) {
+            throw new Error("Table requires an entry struct factory.");
+        }
+        /* v8 ignore stop */
+        if (Array.isArray(dataOrCapacity) && dataOrCapacity.every((e) => Buffer.isBuffer(e))) {
+            /* create table from given entries */
+            const data = dataOrCapacity;
+            if (!data.every((e) => e.length === data[0].length)) {
+                throw new Error("All table entries need to be the same length");
+            }
+            this.data = data.map((buffer) => this.entryStructFactory(buffer));
+        } else if (Buffer.isBuffer(dataOrCapacity)) {
+            /* create table from inline structure */
+            const data = dataOrCapacity;
+            const entryLength = this.emptyEntry.getLength(alignment);
+            const dataLength = this.hasInlineLengthHeader ? data.length - 2 : data.length;
+            if (dataLength % entryLength !== 0) {
+                throw new Error(
+                    `Table length not divisible by entry length (alignment=${alignment}, data_length=${data.length}, entry_length=${entryLength})`,
+                );
+            }
+            const capacity = dataLength / entryLength;
+            const entriesStart = this.hasInlineLengthHeader ? data.slice(2, data.length) : data.slice();
+            this.data = [...Array(capacity)].map((_, i) =>
+                this.entryStructFactory(entriesStart.slice(i * entryLength, i * entryLength + entryLength)),
+            );
+        } else if (typeof dataOrCapacity === "number") {
+            /* create empty table of given capacity */
+            const capacity = dataOrCapacity;
+            this.data = [...Array(capacity)].map(() => this.entryStructFactory());
+        } else {
+            throw new Error("Unsupported table data source");
+        }
+        return this;
+    }
+}

package/src/adapter/z-stack/unpi/constants.ts

@@ -0,0 +1,33 @@
+enum Type {
+    POLL = 0,
+    SREQ = 1,
+    AREQ = 2,
+    SRSP = 3,
+}
+
+enum Subsystem {
+    RESERVED = 0,
+    SYS = 1,
+    MAC = 2,
+    NWK = 3,
+    AF = 4,
+    ZDO = 5,
+    SAPI = 6,
+    UTIL = 7,
+    DEBUG = 8,
+    APP = 9,
+    APP_CNF = 15,
+    GREENPOWER = 21,
+}
+
+const DataStart = 4;
+const SOF = 0xfe;
+
+const PositionDataLength = 1;
+const PositionCmd0 = 2;
+const PositionCmd1 = 3;
+
+const MinMessageLength = 5;
+const MaxDataSize = 250;
+
+export {Type, Subsystem, DataStart, SOF, PositionDataLength, MinMessageLength, PositionCmd0, PositionCmd1, MaxDataSize};

package/src/adapter/z-stack/unpi/frame.ts

@@ -0,0 +1,62 @@
+import {DataStart, PositionCmd0, PositionCmd1, SOF, type Subsystem, type Type} from "./constants";
+
+export class Frame {
+    public readonly type: Type;
+    public readonly subsystem: Subsystem;
+    public readonly commandID: number;
+    public readonly data: Buffer;
+
+    public readonly length?: number;
+    public readonly fcs?: number;
+
+    public constructor(type: Type, subsystem: Subsystem, commandID: number, data: Buffer, length?: number, fcs?: number) {
+        this.type = type;
+        this.subsystem = subsystem;
+        this.commandID = commandID;
+        this.data = data;
+        this.length = length;
+        this.fcs = fcs;
+    }
+
+    public toBuffer(): Buffer {
+        const length = this.data.length;
+        const cmd0 = ((this.type << 5) & 0xe0) | (this.subsystem & 0x1f);
+
+        let payload = Buffer.from([SOF, length, cmd0, this.commandID]);
+        payload = Buffer.concat([payload, this.data]);
+        const fcs = Frame.calculateChecksum(payload.slice(1, payload.length));
+
+        return Buffer.concat([payload, Buffer.from([fcs])]);
+    }
+
+    public static fromBuffer(length: number, fcsPosition: number, buffer: Buffer): Frame {
+        const subsystem: Subsystem = buffer.readUInt8(PositionCmd0) & 0x1f;
+        const type: Type = (buffer.readUInt8(PositionCmd0) & 0xe0) >> 5;
+        const commandID = buffer.readUInt8(PositionCmd1);
+        const data = buffer.subarray(DataStart, fcsPosition);
+        const fcs = buffer.readUInt8(fcsPosition);
+
+        // Validate the checksum to see if we fully received the message
+        const checksum = Frame.calculateChecksum(buffer.subarray(1, fcsPosition));
+
+        if (checksum === fcs) {
+            return new Frame(type, subsystem, commandID, data, length, fcs);
+        }
+
+        throw new Error("Invalid checksum");
+    }
+
+    private static calculateChecksum(values: Buffer): number {
+        let checksum = 0;
+
+        for (const value of values) {
+            checksum ^= value;
+        }
+
+        return checksum;
+    }
+
+    public toString(): string {
+        return `${this.length} - ${this.type} - ${this.subsystem} - ${this.commandID} - [${[...this.data]}] - ${this.fcs}`;
+    }
+}

package/src/adapter/z-stack/unpi/index.ts

@@ -0,0 +1,4 @@
+export * as Constants from "./constants";
+export {Frame} from "./frame";
+export {Parser} from "./parser";
+export {Writer} from "./writer";