zigbee-herdsman 3.5.1 → 4.0.0

package/src/controller/model/entity.ts

@@ -0,0 +1,23 @@
+import events from "node:events";
+
+import type {Adapter} from "../../adapter";
+import type Database from "../database";
+
+// biome-ignore lint/suspicious/noExplicitAny: API
+type EventMap<T> = Record<keyof T, any[]> | DefaultEventMap;
+type DefaultEventMap = [never];
+
+export abstract class Entity<T extends EventMap<T> = DefaultEventMap> extends events.EventEmitter<T> {
+    protected static database?: Database;
+    protected static adapter?: Adapter;
+
+    public static injectDatabase(database: Database): void {
+        Entity.database = database;
+    }
+
+    public static injectAdapter(adapter: Adapter): void {
+        Entity.adapter = adapter;
+    }
+}
+
+export default Entity;

package/src/controller/model/group.ts

@@ -0,0 +1,333 @@
+import assert from "node:assert";
+
+import {logger} from "../../utils/logger";
+import * as Zcl from "../../zspec/zcl";
+import zclTransactionSequenceNumber from "../helpers/zclTransactionSequenceNumber";
+import type {DatabaseEntry, KeyValue} from "../tstype";
+import Device from "./device";
+import type Endpoint from "./endpoint";
+import Entity from "./entity";
+
+const NS = "zh:controller:group";
+
+interface Options {
+    manufacturerCode?: number;
+    direction?: Zcl.Direction;
+    srcEndpoint?: number;
+    reservedBits?: number;
+    transactionSequenceNumber?: number;
+}
+
+interface OptionsWithDefaults extends Options {
+    direction: Zcl.Direction;
+    reservedBits: number;
+}
+
+export class Group extends Entity {
+    private databaseID: number;
+    public readonly groupID: number;
+    private readonly _members: Endpoint[];
+    // Can be used by applications to store data.
+    public readonly meta: KeyValue;
+
+    // This lookup contains all groups that are queried from the database, this is to ensure that always
+    // the same instance is returned.
+    private static readonly groups: Map<number /* groupID */, Group> = new Map();
+    private static loadedFromDatabase = false;
+
+    /** Member endpoints with valid devices (not unknown/deleted) */
+    get members(): Endpoint[] {
+        return this._members.filter((e) => e.getDevice() !== undefined);
+    }
+
+    private constructor(databaseID: number, groupID: number, members: Endpoint[], meta: KeyValue) {
+        super();
+        this.databaseID = databaseID;
+        this.groupID = groupID;
+        this._members = members;
+        this.meta = meta;
+    }
+
+    /*
+     * CRUD
+     */
+
+    /**
+     * Reset runtime lookups.
+     */
+    public static resetCache(): void {
+        Group.groups.clear();
+        Group.loadedFromDatabase = false;
+    }
+
+    private static fromDatabaseEntry(entry: DatabaseEntry): Group {
+        // db is expected to never contain duplicate, so no need for explicit check
+        const members: Endpoint[] = [];
+
+        for (const member of entry.members) {
+            const device = Device.byIeeeAddr(member.deviceIeeeAddr);
+
+            if (device) {
+                const endpoint = device.getEndpoint(member.endpointID);
+
+                if (endpoint) {
+                    members.push(endpoint);
+                }
+            }
+        }
+
+        return new Group(entry.id, entry.groupID, members, entry.meta);
+    }
+
+    private toDatabaseRecord(): DatabaseEntry {
+        const members: DatabaseEntry["members"] = [];
+
+        for (const member of this._members) {
+            const device = member.getDevice();
+
+            if (device) {
+                members.push({deviceIeeeAddr: device.ieeeAddr, endpointID: member.ID});
+            }
+        }
+
+        return {id: this.databaseID, type: "Group", groupID: this.groupID, members, meta: this.meta};
+    }
+
+    private static loadFromDatabaseIfNecessary(): void {
+        if (!Group.loadedFromDatabase) {
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            for (const entry of Entity.database!.getEntriesIterator(["Group"])) {
+                const group = Group.fromDatabaseEntry(entry);
+                Group.groups.set(group.groupID, group);
+            }
+
+            Group.loadedFromDatabase = true;
+        }
+    }
+
+    public static byGroupID(groupID: number): Group | undefined {
+        Group.loadFromDatabaseIfNecessary();
+        return Group.groups.get(groupID);
+    }
+
+    /**
+     * @deprecated use allIterator()
+     */
+    public static all(): Group[] {
+        Group.loadFromDatabaseIfNecessary();
+        return Array.from(Group.groups.values());
+    }
+
+    public static *allIterator(predicate?: (value: Group) => boolean): Generator<Group> {
+        Group.loadFromDatabaseIfNecessary();
+
+        for (const group of Group.groups.values()) {
+            if (!predicate || predicate(group)) {
+                yield group;
+            }
+        }
+    }
+
+    public static create(groupID: number): Group {
+        assert(typeof groupID === "number", "GroupID must be a number");
+        // Don't allow groupID 0, from the spec:
+        // "Scene identifier 0x00, along with group identifier 0x0000, is reserved for the global scene used by the OnOff cluster"
+        assert(groupID >= 1, "GroupID must be at least 1");
+
+        Group.loadFromDatabaseIfNecessary();
+
+        if (Group.groups.has(groupID)) {
+            throw new Error(`Group with groupID '${groupID}' already exists`);
+        }
+
+        // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+        const databaseID = Entity.database!.newID();
+        const group = new Group(databaseID, groupID, [], {});
+        // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+        Entity.database!.insert(group.toDatabaseRecord());
+
+        Group.groups.set(group.groupID, group);
+        return group;
+    }
+
+    public async removeFromNetwork(): Promise<void> {
+        for (const endpoint of this._members) {
+            await endpoint.removeFromGroup(this);
+        }
+
+        this.removeFromDatabase();
+    }
+
+    public removeFromDatabase(): void {
+        Group.loadFromDatabaseIfNecessary();
+
+        // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+        if (Entity.database!.has(this.databaseID)) {
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            Entity.database!.remove(this.databaseID);
+        }
+
+        Group.groups.delete(this.groupID);
+    }
+
+    public save(writeDatabase = true): void {
+        // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+        Entity.database!.update(this.toDatabaseRecord(), writeDatabase);
+    }
+
+    public addMember(endpoint: Endpoint): void {
+        if (!this._members.includes(endpoint)) {
+            this._members.push(endpoint);
+            this.save();
+        }
+    }
+
+    public removeMember(endpoint: Endpoint): void {
+        const i = this._members.indexOf(endpoint);
+
+        if (i > -1) {
+            this._members.splice(i, 1);
+            this.save();
+        }
+    }
+
+    public hasMember(endpoint: Endpoint): boolean {
+        return this._members.includes(endpoint);
+    }
+
+    /*
+     * Zigbee functions
+     */
+
+    public async write(clusterKey: number | string, attributes: KeyValue, options?: Options): Promise<void> {
+        const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER);
+        const cluster = Zcl.Utils.getCluster(clusterKey, undefined, {});
+        const payload: {attrId: number; dataType: number; attrData: number | string | boolean}[] = [];
+
+        for (const [nameOrID, value] of Object.entries(attributes)) {
+            if (cluster.hasAttribute(nameOrID)) {
+                const attribute = cluster.getAttribute(nameOrID);
+                payload.push({attrId: attribute.ID, attrData: value, dataType: attribute.type});
+            } else if (!Number.isNaN(Number(nameOrID))) {
+                payload.push({attrId: Number(nameOrID), attrData: value.value, dataType: value.type});
+            } else {
+                throw new Error(`Unknown attribute '${nameOrID}', specify either an existing attribute or a number`);
+            }
+        }
+
+        const createLogMessage = (): string =>
+            `Write ${this.groupID} ${cluster.name}(${JSON.stringify(attributes)}, ${JSON.stringify(optionsWithDefaults)})`;
+        logger.debug(createLogMessage, NS);
+
+        try {
+            const frame = Zcl.Frame.create(
+                Zcl.FrameType.GLOBAL,
+                optionsWithDefaults.direction,
+                true,
+                optionsWithDefaults.manufacturerCode,
+                optionsWithDefaults.transactionSequenceNumber ?? zclTransactionSequenceNumber.next(),
+                "write",
+                cluster.ID,
+                payload,
+                {},
+                optionsWithDefaults.reservedBits,
+            );
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            await Entity.adapter!.sendZclFrameToGroup(this.groupID, frame, optionsWithDefaults.srcEndpoint);
+        } catch (error) {
+            const err = error as Error;
+            err.message = `${createLogMessage()} failed (${err.message})`;
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            logger.debug(err.stack!, NS);
+
+            throw error;
+        }
+    }
+
+    public async read(clusterKey: number | string, attributes: (string | number)[], options?: Options): Promise<void> {
+        const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER);
+        const cluster = Zcl.Utils.getCluster(clusterKey, undefined, {});
+        const payload: {attrId: number}[] = [];
+
+        for (const attribute of attributes) {
+            payload.push({attrId: typeof attribute === "number" ? attribute : cluster.getAttribute(attribute).ID});
+        }
+
+        const frame = Zcl.Frame.create(
+            Zcl.FrameType.GLOBAL,
+            optionsWithDefaults.direction,
+            true,
+            optionsWithDefaults.manufacturerCode,
+            optionsWithDefaults.transactionSequenceNumber ?? zclTransactionSequenceNumber.next(),
+            "read",
+            cluster.ID,
+            payload,
+            {},
+            optionsWithDefaults.reservedBits,
+        );
+
+        const createLogMessage = (): string =>
+            `Read ${this.groupID} ${cluster.name}(${JSON.stringify(attributes)}, ${JSON.stringify(optionsWithDefaults)})`;
+        logger.debug(createLogMessage, NS);
+
+        try {
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            await Entity.adapter!.sendZclFrameToGroup(this.groupID, frame, optionsWithDefaults.srcEndpoint);
+        } catch (error) {
+            const err = error as Error;
+            err.message = `${createLogMessage()} failed (${err.message})`;
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            logger.debug(err.stack!, NS);
+
+            throw error;
+        }
+    }
+
+    public async command(clusterKey: number | string, commandKey: number | string, payload: KeyValue, options?: Options): Promise<void> {
+        const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER);
+        const cluster = Zcl.Utils.getCluster(clusterKey, undefined, {});
+        const command = cluster.getCommand(commandKey);
+
+        const createLogMessage = (): string => `Command ${this.groupID} ${cluster.name}.${command.name}(${JSON.stringify(payload)})`;
+        logger.debug(createLogMessage, NS);
+
+        try {
+            const frame = Zcl.Frame.create(
+                Zcl.FrameType.SPECIFIC,
+                optionsWithDefaults.direction,
+                true,
+                optionsWithDefaults.manufacturerCode,
+                optionsWithDefaults.transactionSequenceNumber || zclTransactionSequenceNumber.next(),
+                command.ID,
+                cluster.ID,
+                payload,
+                {},
+                optionsWithDefaults.reservedBits,
+            );
+
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            await Entity.adapter!.sendZclFrameToGroup(this.groupID, frame, optionsWithDefaults.srcEndpoint);
+        } catch (error) {
+            const err = error as Error;
+            err.message = `${createLogMessage()} failed (${err.message})`;
+            // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+            logger.debug(err.stack!, NS);
+
+            throw error;
+        }
+    }
+
+    private getOptionsWithDefaults(options: Options | undefined, direction: Zcl.Direction): OptionsWithDefaults {
+        return {
+            direction,
+            srcEndpoint: undefined,
+            reservedBits: 0,
+            manufacturerCode: undefined,
+            transactionSequenceNumber: undefined,
+            ...(options || {}),
+        };
+    }
+}
+
+export default Group;

package/src/controller/model/index.ts

@@ -0,0 +1,4 @@
+export {Device} from "./device";
+export {Endpoint} from "./endpoint";
+export {Entity} from "./entity";
+export {Group} from "./group";

package/src/controller/touchlink.ts

@@ -0,0 +1,189 @@
+import type {Adapter} from "../adapter";
+import {wait} from "../utils";
+import {logger} from "../utils/logger";
+import {assertString} from "../utils/utils";
+import * as Zcl from "../zspec/zcl";
+
+const NS = "zh:controller:touchlink";
+const scanChannels = [11, 15, 20, 25, 12, 13, 14, 16, 17, 18, 19, 21, 22, 23, 24, 26];
+
+export class Touchlink {
+    private adapter: Adapter;
+    private locked: boolean;
+
+    public constructor(adapter: Adapter) {
+        this.adapter = adapter;
+        this.locked = false;
+    }
+
+    private lock(lock: boolean): void {
+        if (lock && this.locked) {
+            throw new Error("Touchlink operation already in progress");
+        }
+
+        this.locked = lock;
+    }
+
+    private transactionNumber(): number {
+        return Math.floor(Math.random() * 0xffffffff);
+    }
+
+    public async scan(): Promise<{ieeeAddr: string; channel: number}[]> {
+        this.lock(true);
+        const result = [];
+
+        try {
+            for (const channel of scanChannels) {
+                logger.info(`Set InterPAN channel to '${channel}'`, NS);
+                await this.adapter.setChannelInterPAN(channel);
+
+                try {
+                    // TODO: multiple responses are not handled yet.
+                    const response = await this.adapter.sendZclFrameInterPANBroadcast(this.createScanRequestFrame(this.transactionNumber()), 500);
+                    logger.debug(`Got scan response on channel '${channel}' of '${response.address}'`, NS);
+                    assertString(response.address);
+                    result.push({ieeeAddr: response.address, channel});
+                } catch (error) {
+                    logger.warning(`Scan request failed or was not answered: '${error}'`, NS);
+                }
+            }
+        } finally {
+            logger.info("Restore InterPAN channel", NS);
+            await this.adapter.restoreChannelInterPAN();
+            this.lock(false);
+        }
+
+        return result;
+    }
+
+    public async identify(ieeeAddr: string, channel: number): Promise<void> {
+        this.lock(true);
+
+        try {
+            const transaction = this.transactionNumber();
+
+            logger.info(`Set InterPAN channel to '${channel}'`, NS);
+            await this.adapter.setChannelInterPAN(channel);
+
+            await this.adapter.sendZclFrameInterPANBroadcast(this.createScanRequestFrame(transaction), 500);
+            logger.debug(`Got scan response on channel '${channel}'`, NS);
+
+            logger.debug(`Identifying '${ieeeAddr}'`, NS);
+            await this.adapter.sendZclFrameInterPANToIeeeAddr(this.createIdentifyRequestFrame(transaction), ieeeAddr);
+        } finally {
+            logger.info("Restore InterPAN channel", NS);
+            await this.adapter.restoreChannelInterPAN();
+            this.lock(false);
+        }
+    }
+
+    public async factoryReset(ieeeAddr: string, channel: number): Promise<boolean> {
+        this.lock(true);
+        try {
+            const transaction = this.transactionNumber();
+
+            logger.info(`Set InterPAN channel to '${channel}'`, NS);
+            await this.adapter.setChannelInterPAN(channel);
+
+            await this.adapter.sendZclFrameInterPANBroadcast(this.createScanRequestFrame(transaction), 500);
+            logger.debug(`Got scan response on channel '${channel}'`, NS);
+
+            logger.debug(`Identifying '${ieeeAddr}'`, NS);
+            await this.adapter.sendZclFrameInterPANToIeeeAddr(this.createIdentifyRequestFrame(transaction), ieeeAddr);
+            await wait(2000);
+
+            logger.debug(`Reset to factory new '${ieeeAddr}'`, NS);
+            await this.adapter.sendZclFrameInterPANToIeeeAddr(this.createResetFactoryNewRequestFrame(transaction), ieeeAddr);
+        } finally {
+            logger.info("Restore InterPAN channel", NS);
+            await this.adapter.restoreChannelInterPAN();
+            this.lock(false);
+        }
+
+        return true;
+    }
+
+    public async factoryResetFirst(): Promise<boolean> {
+        this.lock(true);
+        let done = false;
+
+        try {
+            for (const channel of scanChannels) {
+                logger.info(`Set InterPAN channel to '${channel}'`, NS);
+                await this.adapter.setChannelInterPAN(channel);
+
+                try {
+                    const transaction = this.transactionNumber();
+
+                    const response = await this.adapter.sendZclFrameInterPANBroadcast(this.createScanRequestFrame(transaction), 500);
+                    logger.debug(`Got scan response on channel '${channel}'`, NS);
+                    assertString(response.address);
+
+                    // Device answered (if not it will fall in the catch below),
+                    // identify it (this will make e.g. the bulb flash)
+                    logger.debug("Identifying", NS);
+                    await this.adapter.sendZclFrameInterPANToIeeeAddr(this.createIdentifyRequestFrame(transaction), response.address);
+                    await wait(2000);
+
+                    logger.debug("Reset to factory new", NS);
+                    await this.adapter.sendZclFrameInterPANToIeeeAddr(this.createResetFactoryNewRequestFrame(transaction), response.address);
+                    done = true;
+                } catch (error) {
+                    logger.warning(`Scan request failed or was not answered: '${error}'`, NS);
+                }
+
+                if (done) break;
+            }
+        } finally {
+            logger.info("Restore InterPAN channel", NS);
+            await this.adapter.restoreChannelInterPAN();
+            this.lock(false);
+        }
+
+        return done;
+    }
+
+    private createScanRequestFrame(transaction: number): Zcl.Frame {
+        return Zcl.Frame.create(
+            Zcl.FrameType.SPECIFIC,
+            Zcl.Direction.CLIENT_TO_SERVER,
+            true,
+            undefined,
+            0,
+            "scanRequest",
+            Zcl.Clusters.touchlink.ID,
+            {transactionID: transaction, zigbeeInformation: 4, touchlinkInformation: 18},
+            {},
+        );
+    }
+
+    private createIdentifyRequestFrame(transaction: number): Zcl.Frame {
+        return Zcl.Frame.create(
+            Zcl.FrameType.SPECIFIC,
+            Zcl.Direction.CLIENT_TO_SERVER,
+            true,
+            undefined,
+            0,
+            "identifyRequest",
+            Zcl.Clusters.touchlink.ID,
+            {transactionID: transaction, duration: 65535},
+            {},
+        );
+    }
+
+    private createResetFactoryNewRequestFrame(transaction: number): Zcl.Frame {
+        return Zcl.Frame.create(
+            Zcl.FrameType.SPECIFIC,
+            Zcl.Direction.CLIENT_TO_SERVER,
+            true,
+            undefined,
+            0,
+            "resetToFactoryNew",
+            Zcl.Clusters.touchlink.ID,
+            {transactionID: transaction},
+            {},
+        );
+    }
+}
+
+export default Touchlink;

package/src/controller/tstype.ts

@@ -0,0 +1,39 @@
+export interface KeyValue {
+    // biome-ignore lint/suspicious/noExplicitAny: API
+    [s: string]: any;
+}
+
+/* Send request policies:
+'bulk':             Message must be sent together with other messages in the correct sequence.
+                    No immediate delivery required.
+'queue':            Request shall be sent 'as-is' as soon as possible.
+                    Multiple identical requests shall be delivered multiple times.
+                    Not strict ordering required.
+'immediate':        Request shall be sent immediately and not be kept for later retries (e.g. response message).
+'keep-payload':     Request shall be sent as soon as possible.
+                    If immediate delivery fails, the exact same payload is only sent once, even if there were
+                    multiple requests.
+'keep-command':     Request shall be sent as soon as possible.
+                    If immediate delivery fails, only the latest command for each command ID is kept for delivery.
+'keep-cmd-undiv':   Request shall be sent as soon as possible.
+                    If immediate delivery fails, only the latest undivided set of commands is sent for each unique
+                    set of command IDs.
+*/
+export type SendPolicy = "bulk" | "queue" | "immediate" | "keep-payload" | "keep-command" | "keep-cmd-undiv";
+export type DeviceType = "Coordinator" | "Router" | "EndDevice" | "Unknown" | "GreenPower";
+
+export type EntityType = DeviceType | "Group";
+
+export interface DatabaseEntry {
+    id: number;
+    type: EntityType;
+    // biome-ignore lint/suspicious/noExplicitAny: API
+    [s: string]: any;
+}
+
+export interface GreenPowerDeviceJoinedPayload {
+    sourceID: number;
+    deviceID: number;
+    networkAddress: number;
+    securityKey?: Buffer;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/* v8 ignore start */
+
+export {Controller} from "./controller/controller";
+export type * as Events from "./controller/events";
+export type * as Types from "./controller/tstype";
+export type * as Models from "./controller/model";
+export type * as AdapterEvents from "./adapter/events";
+export type * as AdapterTypes from "./adapter/tstype";
+export * as Zcl from "./zspec/zcl";
+export * as Zdo from "./zspec/zdo";
+export * as ZSpec from "./zspec";
+export {setLogger} from "./utils/logger";

package/src/models/backup-storage-legacy.ts

@@ -0,0 +1,48 @@
+import type {ZnpVersion} from "../adapter/z-stack/adapter/tstype";
+import type {NvSystemIds} from "../adapter/z-stack/constants/common";
+
+type LegacyNvItemKey =
+    | "ZCD_NV_EXTADDR"
+    | "ZCD_NV_NIB"
+    | "ZCD_NV_PANID"
+    | "ZCD_NV_EXTENDED_PAN_ID"
+    | "ZCD_NV_NWK_ACTIVE_KEY_INFO"
+    | "ZCD_NV_NWK_ALTERN_KEY_INFO"
+    | "ZCD_NV_APS_USE_EXT_PANID"
+    | "ZCD_NV_PRECFGKEY"
+    | "ZCD_NV_PRECFGKEY_ENABLE"
+    | "ZCD_NV_CHANLIST"
+
+    /* Z-Stack 3.0.x tables */
+    | "ZCD_NV_LEGACY_TCLK_TABLE_START"
+    | "ZCD_NV_LEGACY_NWK_SEC_MATERIAL_TABLE_START"
+
+    /* SimpleLink Z-Stack 3.x.0 tables */
+    | "ZCD_NV_EX_TCLK_TABLE"
+    | "ZCD_NV_EX_NWK_SEC_MATERIAL_TABLE";
+
+/**
+ * Legacy backup format to allow for backup migration.
+ */
+export interface LegacyBackupStorage {
+    adapterType: "zStack";
+    time: string;
+    meta: {
+        product: ZnpVersion;
+    };
+    data: Record<
+        LegacyNvItemKey,
+        {
+            id: number;
+            product: ZnpVersion;
+            offset: number;
+            osal: boolean;
+            value: number[];
+            len: number;
+
+            /* System ID and Sub ID used in SimpleLink Z-Stack 3.x.0 */
+            sysid?: NvSystemIds;
+            subid?: number;
+        }
+    >;
+}