@willieee802/zigbee-herdsman 0.48.3 → 0.49.0

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+    - name: Zigbee2MQTT issue tracker
+      url: https://github.com/Koenkk/zigbee2mqtt/issues/new/choose
+      about: Preferably create an issue in the Zigbee2MQTT issue tracker. Only click on "Open a blank issue" below if you are conviced it really belongs in this issue tracker.

package/.github/copilot-instructions.md

@@ -0,0 +1,689 @@
+# GitHub Copilot Instructions for zigbee-herdsman
+
+## Priority Guidelines
+
+When generating code for this repository:
+
+1. **Version Compatibility**: Always respect the exact versions of Node.js, TypeScript, and libraries used in this project
+2. **Codebase Patterns**: Scan the codebase for established patterns before generating code
+3. **Architectural Consistency**: Maintain the layered architecture and established module boundaries
+4. **Code Quality**: Prioritize maintainability, type safety, and consistency with existing patterns
+5. **Testing**: Follow the established Vitest testing patterns
+
+## Technology Stack & Versions
+
+### Core Technologies
+
+- **Runtime**: Node.js (CommonJS module system)
+- **Language**: TypeScript 5.9.2
+  - Target: ES2022
+  - Module: NodeNext
+  - Strict mode enabled (`strict: true`, `noImplicitAny: true`, `noImplicitThis: true`)
+- **Package Manager**: pnpm 10.12.1
+
+### Key Dependencies
+
+- **Serial Communication**: `@serialport/stream` (^13.0.0), `@serialport/bindings-cpp` (^13.0.1)
+- **Network Discovery**: `bonjour-service` (^1.3.0)
+- **Utilities**: `fast-deep-equal` (^3.1.3), `debounce` (^2.2.0), `mixin-deep` (^2.0.1)
+- **Zigbee Adapters**: Support for Z-Stack, EZSP/EmberZNet, deCONZ, Zigate, ZBOSS, ZOH
+
+### Development Tools
+
+- **Testing**: Vitest 3.2.4 with @vitest/coverage-v8
+- **Code Quality**: Biome 2.2.5 (formatting, linting)
+- **Build**: TypeScript compiler with incremental compilation
+
+## Project Architecture
+
+### Layered Structure
+
+```
+src/
+├── index.ts                 # Public API exports
+├── adapter/                 # Hardware adapter layer (Z-Stack, EZSP, etc.)
+├── buffalo/                 # Binary data serialization/deserialization
+├── controller/              # Core business logic
+│   ├── controller.ts       # Main controller orchestration
+│   ├── database.ts         # Persistence layer
+│   ├── helpers/            # Shared utilities
+│   └── model/              # Domain models (Device, Endpoint, Group)
+├── models/                  # Backup and configuration models
+├── utils/                   # Cross-cutting utilities
+└── zspec/                   # Zigbee specification implementation
+    ├── zcl/                # Zigbee Cluster Library
+    └── zdo/                # Zigbee Device Objects
+```
+
+### Key Architectural Principles
+
+1. **Separation of Concerns**: Adapter layer handles hardware communication, controller handles business logic
+2. **Entity Pattern**: Device, Endpoint, Group, Entity form a hierarchy
+3. **Event-Driven**: Controller extends EventEmitter for loose coupling
+4. **Static Caching**: Device and Group use static Maps for singleton-like behavior
+5. **Database Abstraction**: All persistence goes through `database.ts`
+
+## Code Style & Formatting
+
+### Biome Configuration
+
+The project uses Biome for code quality enforcement. Key settings:
+
+- **Indentation**: 4 spaces
+- **Line Width**: 150 characters
+- **Bracket Spacing**: false (e.g., `{foo}` not `{ foo }`)
+- **Naming Conventions**: Flexible (camelCase, PascalCase, snake_case, CONSTANT_CASE allowed based on context)
+- **No Non-Null Assertions**: Discouraged except in test files (use `!` sparingly)
+- **Unused Imports**: Error level
+
+### Import Organization
+
+Follow this pattern observed in the codebase:
+
+```typescript
+// 1. Node.js built-ins
+import assert from "node:assert";
+import events from "node:events";
+
+// 2. External dependencies
+import mixinDeep from "mixin-deep";
+
+// 3. Internal imports (relative paths, grouped by layer)
+import {Adapter, type Events as AdapterEvents} from "../adapter";
+import {logger} from "../utils/logger";
+import * as Zcl from "../zspec/zcl";
+import * as Zdo from "../zspec/zdo";
+
+// 4. Relative imports from same layer
+import Database from "./database";
+import {Device, Entity} from "./model";
+```
+
+## Naming Conventions
+
+### Variables and Properties
+
+- **Private fields**: Use `#` prefix for true private fields: `#customClusters`, `#genBasic`
+- **Internal properties**: Use `_` prefix: `_members`, `_endpoints`, `_ieeeAddr`
+- **Public properties**: camelCase: `groupID`, `networkAddress`, `interviewState`
+- **Constants**: SCREAMING_SNAKE_CASE in dedicated files or modules
+- **Static members**: camelCase for methods, PascalCase for types
+
+### Functions and Methods
+
+- **Public methods**: camelCase: `addMember()`, `removeFromNetwork()`, `getDevice()`
+- **Private methods**: camelCase: `toDatabaseRecord()`, `fromDatabaseEntry()`
+- **Static factory methods**: camelCase: `byGroupID()`, `byIeeeAddr()`
+- **Iterators**: Suffix with `Iterator`: `allIterator()`, `getDevicesIterator()`
+
+### Classes and Types
+
+- **Classes**: PascalCase: `Controller`, `Device`, `Endpoint`, `Group`
+- **Interfaces**: PascalCase: `Options`, `DatabaseEntry`, `ConfigureReportingItem`
+- **Type Aliases**: PascalCase for complex types, camelCase for simple unions
+- **Enums**: PascalCase with CONSTANT_CASE or PascalCase members
+
+### Files
+
+- **Source files**: camelCase: `controller.ts`, `zclFrameConverter.ts`
+- **Test files**: camelCase with `.test.ts` suffix: `controller.test.ts`
+- **Type definition files**: camelCase: `tstype.ts`, `tstypes.ts`
+
+## TypeScript Patterns
+
+### Type Safety
+
+Always use explicit types for public APIs:
+
+```typescript
+// ✅ Good: Explicit return type
+public async write<Cl extends number | string>(
+    clusterKey: Cl,
+    attributes: PartialClusterOrRawWriteAttributes<Cl>,
+    options?: Options,
+): Promise<void> {
+    // ...
+}
+
+// ✅ Good: Explicit parameter types
+private constructor(databaseID: number, groupID: number, members: Endpoint[], meta: KeyValue) {
+    // ...
+}
+```
+
+### Generic Constraints
+
+Use constrained generics for cluster-related operations:
+
+```typescript
+public async command<
+    Cl extends number | string,
+    Co extends number | string,
+    Custom extends TCustomCluster | undefined = undefined
+>(
+    clusterKey: Cl,
+    commandKey: Co,
+    payload: ClusterOrRawPayload<Cl, Co, Custom>,
+    options?: Options,
+): Promise<undefined> {
+    // ...
+}
+```
+
+### Type Guards and Assertions
+
+```typescript
+// Use typeof checks
+if (typeof source === "number") {
+    // Handle number case
+}
+
+// Use assert for preconditions
+assert(typeof groupID === "number", "GroupID must be a number");
+assert(groupID >= 1, "GroupID must be at least 1");
+
+// Avoid non-null assertions except in tests
+// biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+logger.debug(err.stack!, NS);
+```
+
+### Readonly Properties
+
+Use `readonly` for immutable properties:
+
+```typescript
+public readonly groupID: number;
+public readonly meta: KeyValue;
+private readonly _members: Endpoint[];
+private static readonly groups: Map<number, Group> = new Map();
+```
+
+## Async/Await Patterns
+
+### Consistent Async Usage
+
+```typescript
+// ✅ Good: Always return Promise<void> or Promise<Type>
+public async removeFromNetwork(): Promise<void> {
+    for (const endpoint of this._members) {
+        await endpoint.removeFromGroup(this);
+    }
+    this.removeFromDatabase();
+}
+
+// ✅ Good: Sequential awaits when order matters
+const startResult = await this.adapter.start();
+const coordinatorIEEE = await this.adapter.getCoordinatorIEEE();
+
+// ✅ Good: Parallel awaits when independent
+// (Use sparingly, most operations in this codebase are sequential)
+```
+
+### Error Handling
+
+Follow this pattern for async methods:
+
+```typescript
+const createLogMessage = (): string =>
+    `Write ${this.groupID} ${cluster.name}(${JSON.stringify(attributes)}, ${JSON.stringify(optionsWithDefaults)})`;
+logger.debug(createLogMessage, NS);
+
+try {
+    // Operation logic
+    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;
+}
+```
+
+## Class Design Patterns
+
+### Entity Hierarchy
+
+```typescript
+// Base entity class
+export abstract class Entity<EventMap> {
+    protected static adapter: Adapter;
+    protected static database: Database;
+    // ...
+}
+
+// Zigbee-specific entity
+export abstract class ZigbeeEntity extends Entity<ControllerEventMap> {
+    protected getOptionsWithDefaults(...): OptionsWithDefaults {
+        // Shared logic
+    }
+}
+
+// Concrete implementations
+export class Group extends ZigbeeEntity { }
+export class Device extends Entity<ControllerEventMap> { }
+```
+
+### Static Factory Pattern
+
+```typescript
+export class Group extends ZigbeeEntity {
+    private static readonly groups: Map<number, Group> = new Map();
+    private static loadedFromDatabase = false;
+
+    // Private constructor
+    private constructor(databaseID: number, groupID: number, members: Endpoint[], meta: KeyValue) {
+        super();
+        // ...
+    }
+
+    // Static factory methods
+    public static byGroupID(groupID: number): Group | undefined {
+        Group.loadFromDatabaseIfNecessary();
+        return Group.groups.get(groupID);
+    }
+
+    public static create(groupID: number): Group {
+        assert(typeof groupID === "number", "GroupID must be a number");
+        // Validation, creation, and caching logic
+    }
+}
+```
+
+### Lazy Loading Pattern
+
+```typescript
+private static loadFromDatabaseIfNecessary(): void {
+    if (!Group.loadedFromDatabase) {
+        for (const entry of Entity.database.getEntriesIterator(["Group"])) {
+            const group = Group.fromDatabaseEntry(entry);
+            Group.groups.set(group.groupID, group);
+        }
+        Group.loadedFromDatabase = true;
+    }
+}
+```
+
+### Iterator Pattern
+
+Prefer generators over returning full arrays:
+
+```typescript
+// ✅ Modern: Use generator
+public static *allIterator(predicate?: (value: Group) => boolean): Generator<Group> {
+    Group.loadFromDatabaseIfNecessary();
+    for (const group of Group.groups.values()) {
+        if (!predicate || predicate(group)) {
+            yield group;
+        }
+    }
+}
+
+// ⚠️ Deprecated but still present
+public static all(): Group[] {
+    Group.loadFromDatabaseIfNecessary();
+    return Array.from(Group.groups.values());
+}
+```
+
+## Logging Patterns
+
+### Logger Usage
+
+Always use the logger utility with namespace:
+
+```typescript
+import {logger} from "../../utils/logger";
+
+const NS = "zh:controller:group";
+
+// Debug logging (most common)
+logger.debug(`Device announce from '${payload.eui64}:${payload.nwkAddress}'`, NS);
+
+// Lambda for deferred computation
+logger.debug(() => `Expensive computation: ${JSON.stringify(complexObject)}`, NS);
+
+// Info for important state changes
+logger.info(`Install code was adjusted for reason '${adjusted}'.`, NS);
+
+// Warning for recoverable issues
+logger.warning(`Ignoring unknown attribute ${attribute} in cluster ${cluster.name}`, NS);
+
+// Error for failures
+logger.error(`Failed to disable join on stop: ${error}`, NS);
+```
+
+### Log Message Patterns
+
+```typescript
+// ✅ Create reusable log message function
+const createLogMessage = (): string =>
+    `Write ${this.groupID} ${cluster.name}(${JSON.stringify(attributes)}, ${JSON.stringify(optionsWithDefaults)})`;
+
+logger.debug(createLogMessage, NS);
+
+// Later in catch block
+err.message = `${createLogMessage()} failed (${err.message})`;
+```
+
+## Error Handling
+
+### Type-Safe Error Handling
+
+```typescript
+try {
+    await operation();
+} catch (error) {
+    // Always cast to Error type
+    const err = error as Error;
+    err.message = `Operation failed (${err.message})`;
+    logger.debug(err.stack!, NS);
+    throw error;  // Re-throw the original error
+}
+```
+
+### Validation with Assertions
+
+```typescript
+// Use node:assert for precondition checks
+assert(typeof groupID === "number", "GroupID must be a number");
+assert(groupID >= 1, "GroupID must be at least 1");
+
+// Throw Error for business logic violations
+if (Group.groups.has(groupID)) {
+    throw new Error(`Group with groupID '${groupID}' already exists`);
+}
+```
+
+## Testing Patterns
+
+### Test Structure
+
+```typescript
+import {describe, expect, it, vi, beforeEach, afterAll} from "vitest";
+
+describe("Feature Name", () => {
+    beforeEach(() => {
+        // Setup
+    });
+
+    it("should do something specific", async () => {
+        // Arrange
+        const mockLogger = {
+            debug: vi.fn(),
+            info: vi.fn(),
+            warning: vi.fn(),
+            error: vi.fn(),
+        };
+
+        // Act
+        const result = await operation();
+
+        // Assert
+        expect(result).toBe(expectedValue);
+        expect(mockLogger.debug).toHaveBeenCalledWith(expect.stringContaining("expected message"));
+    });
+});
+```
+
+### Mocking Patterns
+
+```typescript
+// Mock with vi.fn()
+const mockAdapterStart = vi.fn().mockReturnValue("resumed");
+const mockAdapter = {
+    start: mockAdapterStart,
+    getCoordinatorIEEE: vi.fn().mockReturnValue("0x0000012300000000"),
+};
+
+// Mock logger
+const mockLogger = {
+    debug: vi.fn((messageOrLambda) => {
+        if (typeof messageOrLambda === "function") messageOrLambda();
+    }),
+    info: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+};
+```
+
+## Database Patterns
+
+### CRUD Operations
+
+```typescript
+// Create
+const databaseID = Entity.database.newID();
+const group = new Group(databaseID, groupID, [], {});
+Entity.database.insert(group.toDatabaseRecord());
+
+// Read
+for (const entry of Entity.database.getEntriesIterator(["Group"])) {
+    const group = Group.fromDatabaseEntry(entry);
+}
+
+// Update
+public save(writeDatabase = true): void {
+    Entity.database.update(this.toDatabaseRecord(), writeDatabase);
+}
+
+// Delete
+public removeFromDatabase(): void {
+    if (Entity.database.has(this.databaseID)) {
+        Entity.database.remove(this.databaseID);
+    }
+    Group.groups.delete(this.groupID);
+}
+```
+
+### Serialization Pattern
+
+```typescript
+// To database
+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};
+}
+
+// From database
+private static fromDatabaseEntry(entry: DatabaseEntry): Group {
+    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);
+}
+```
+
+## Zigbee-Specific Patterns
+
+### ZCL Frame Creation
+
+```typescript
+const frame = Zcl.Frame.create(
+    Zcl.FrameType.GLOBAL,  // or SPECIFIC
+    optionsWithDefaults.direction,
+    true,  // disableDefaultResponse
+    optionsWithDefaults.manufacturerCode,
+    optionsWithDefaults.transactionSequenceNumber ?? zclTransactionSequenceNumber.next(),
+    "write",  // command name
+    cluster,
+    payload,
+    customClusters,
+    optionsWithDefaults.reservedBits,
+);
+```
+
+### Cluster Resolution
+
+```typescript
+const customClusters = this.#customClusters[
+    options?.direction === Zcl.Direction.SERVER_TO_CLIENT ? 1 : 0
+];
+const cluster = Zcl.Utils.getCluster(clusterKey, options?.manufacturerCode, customClusters);
+```
+
+### Options with Defaults Pattern
+
+```typescript
+private getOptionsWithDefaults(
+    options: Options | undefined,
+    direction: Zcl.Direction,
+    manufacturerCode: number | undefined,
+): OptionsWithDefaults {
+    return {
+        direction,
+        srcEndpoint: undefined,
+        reservedBits: 0,
+        manufacturerCode,
+        transactionSequenceNumber: undefined,
+        ...(options || {}),
+    };
+}
+```
+
+## Documentation Patterns
+
+### JSDoc Comments
+
+Use JSDoc for public APIs:
+
+```typescript
+/**
+ * Create a controller
+ *
+ * To auto detect the port provide `null` for `options.serialPort.path`
+ */
+public constructor(options: Options) {
+    // ...
+}
+
+/**
+ * @deprecated use allIterator()
+ */
+public static all(): Group[] {
+    // ...
+}
+
+/**
+ * @noInheritDoc
+ */
+export class Controller extends events.EventEmitter<ControllerEventMap> {
+    // ...
+}
+```
+
+### Inline Comments
+
+Use comments sparingly for complex logic:
+
+```typescript
+// 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");
+
+// Use default direction if not specified
+const customClusters = this.#customClusters[options?.direction === Zcl.Direction.SERVER_TO_CLIENT ? 1 : 0 /* default to CLIENT_TO_SERVER */];
+```
+
+## Performance Patterns
+
+### Avoid Premature Array Creation
+
+```typescript
+// ✅ Good: Use iterator for filtering
+get members(): Endpoint[] {
+    return this._members.filter((e) => e.getDevice() !== undefined);
+}
+
+// ✅ Good: Generator for large collections
+public static *allIterator(predicate?: (value: Group) => boolean): Generator<Group> {
+    for (const group of Group.groups.values()) {
+        if (!predicate || predicate(group)) {
+            yield group;
+        }
+    }
+}
+```
+
+### Cache Invalidation
+
+```typescript
+public addMember(endpoint: Endpoint): void {
+    if (!this._members.includes(endpoint)) {
+        this._members.push(endpoint);
+        this.save();
+        // Invalidate derived cache
+        this.#customClusters = this.#identifyCustomClusters();
+    }
+}
+```
+
+## Version Control & Project Management
+
+### Semantic Versioning
+
+The project follows semantic versioning (current: 6.2.0):
+- Major: Breaking API changes
+- Minor: New features, backward compatible
+- Patch: Bug fixes
+
+### Breaking Changes
+
+Document breaking changes in CHANGELOG.md:
+
+```markdown
+## 0.14.0 breaking changes
+- `sendWhenActive` has been replaced with `sendWhen: 'active'`
+```
+
+## Common Patterns Checklist
+
+When implementing new features, ensure:
+
+- [ ] Private fields use `#` prefix for encapsulation
+- [ ] Public methods have explicit return types
+- [ ] Async methods return `Promise<Type>`
+- [ ] Error messages include context from `createLogMessage()`
+- [ ] Logger calls include the appropriate namespace constant
+- [ ] Static caches are invalidated when data changes
+- [ ] Database operations go through `save()`, not direct access
+- [ ] Type assertions use `as` not angle brackets
+- [ ] Iterators are preferred over array methods for large collections
+- [ ] Tests use Vitest with mocks via `vi.fn()`
+- [ ] Options objects have a `getOptionsWithDefaults()` method
+- [ ] Assertions validate input parameters early
+- [ ] Import statements follow the ordering convention
+
+## Anti-Patterns to Avoid
+
+- ❌ Don't use `any` type (use `unknown` then narrow)
+- ❌ Don't bypass static factory methods with `new` for entities
+- ❌ Don't mutate readonly properties after construction
+- ❌ Don't log sensitive data (use `HIDDEN` placeholder or lambdas)
+- ❌ Don't use `console.log` (use logger utility)
+- ❌ Don't ignore errors (always catch, log, and re-throw or handle)
+- ❌ Don't create circular dependencies between layers
+- ❌ Don't use non-null assertions outside of tests without biome-ignore comment
+
+## Additional Resources
+
+- [Official API Documentation](https://koenkk.github.io/zigbee-herdsman)
+- [GitHub Repository](https://github.com/Koenkk/zigbee-herdsman)
+- Related Project: [Zigbee2MQTT](https://www.zigbee2mqtt.io/)
+
+---
+
+**Remember**: When in doubt, scan similar files in the codebase for patterns. Consistency with existing code is more important than external best practices that don't match the project's established style.

package/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+    - package-ecosystem: npm
+      versioning-strategy: increase
+      directory: /
+      schedule:
+          interval: weekly
+      groups:
+          minor-patch:
+              applies-to: version-updates
+              update-types:
+                  - minor
+                  - patch
+      commit-message:
+        prefix: fix(ignore)
+      ignore:
+          # https://github.com/Koenkk/zigbee-herdsman/pull/1471
+          - dependency-name: typescript
+    - package-ecosystem: github-actions
+      directory: /
+      schedule:
+        interval: weekly