zigbee-herdsman

The library provides several utility types to programmatically access cluster definitions, attributes, and commands based on a cluster ID or name. This is useful when building generic drivers or handling dynamic ZCL messages.

• TClusterAttributeKeys<Cl>: Gets valid attribute keys for a cluster.
• TClusterAttributes<Cl>: Gets the attribute definitions for a cluster.
• TClusterCommandKeys<Cl>: Gets valid command keys for a cluster.
• TClusterCommandPayload<Cl, Co>: Gets the payload type for a specific command Co in cluster Cl.
• TClusterPayload<Cl, Co>: A helper that resolves the payload type, whether it's a command or a command response.

export type TClusterAttributeKeys<Cl extends number | string> = Cl extends keyof TClusters
    ? (keyof TClusters[Cl]["attributes"])[]
    : (string | number)[];

export type TClusterCommandPayload<Cl extends number | string, Co extends number | string> = Cl extends keyof TClusters
    ? Co extends keyof TClusters[Cl]["commands"]
        ? TClusters[Cl]["commands"][Co]
        : Co extends keyof TClusters[Cl]["commandResponses"]
          ? TClusters[Cl]["commandResponses"][Co]
          : never
    : never;

The Ember adapter provides specific types for managing standard Zigbee networks and Zigbee Light Link (ZLL) networks.

Standard Zigbee Network

EmberZigbeeNetwork defines the core network state:

• panId: 16-bit PAN ID.
• channel: Radio channel.
• allowingJoin: Boolean indicating if joining is permitted.
• extendedPanId: Extended PAN ID.
• stackProfile: Stack profile identifier.
• nwkUpdateId: Network update ID.

Zigbee Light Link (ZLL)

EmberZllNetwork provides details for ZLL-specific devices:

• zigbeeNetwork: The underlying EmberZigbeeNetwork.
• securityAlgorithm: EmberZllSecurityAlgorithmData containing transaction and response IDs.
• eui64: The device's EUI64.
• nodeId: The device's Node ID.
• state: The EmberZllState.
• nodeType: The EmberNodeType.
• numberSubDevices: Count of sub-devices.
• totalGroupIdentifiers: Count of group identifiers.
• rssiCorrection: RSSI correction value.

When initializing or querying a Zigbee network using the Ember adapter, use the EmberNetworkParameters type to manage core network settings.

Key fields include:

• extendedPanId: The network's extended PAN identifier.
• panId: The network's PAN identifier.
• radioTxPower: Power setting in dBm.
• radioChannel: The specific radio channel to use.
• joinMethod: The protocol messages used to establish an initial parent (e.g., EmberJoinMethod).
• nwkManagerId: The ID of the network manager (only settable during joining with EMBER_USE_CONFIGURED_NWK_STATE).
• nwkUpdateId: The Zigbee nwkUpdateId used to track network instances after PAN/channel changes.
• channels: A bitmask of preferred channels for the NWK manager.

export type EmberNetworkParameters = {
    extendedPanId: ExtendedPanId;
    panId: PanId;
    radioTxPower: number;
    radioChannel: number;
    joinMethod: EmberJoinMethod;
    nwkManagerId: NodeId;
    nwkUpdateId: number;
    channels: number;
};

Use EmberInitialSecurityState to define security requirements for forming or joining a network. This structure uses a bitmask to indicate which features are present.

Important fields:

• bitmask: Enumerates security features (see EmberInitialSecurityBitmask).
• preconfiguredKey: A EmberKeyData object used if EMBER_HAVE_PRECONFIGURED_KEY is set in the bitmask.
• networkKey: The Network Key used when forming the network (required if EMBER_HAVE_NETWORK_KEY is set).
• networkKeySequenceNumber: The sequence number for the network key.
• preconfiguredTrustCenterEui64: The long address of the Trust Center (required for commissioning mode; must be in little-endian format).

export type EmberInitialSecurityState = {
    bitmask: number;
    preconfiguredKey: EmberKeyData;
    networkKey: EmberKeyData;
    networkKeySequenceNumber: number;
    preconfiguredTrustCenterEui64: Eui64;
};

The closuresDoorLock cluster manages smart lock security, user codes, and event masking.

Key Attributes

• lockState (ENUM8): Current state of the lock.
• lockType (ENUM8): Type of lock.
• doorState (ENUM8): Current state of the door.
• maxPinLen / minPinLen: Constraints for PIN codes.
• autoRelockTime (UINT32): Time before automatic relocking.
• enableLocalProgramming (BOOLEAN): Whether local programming is allowed.
• alarmMask (BITMAP16): Mask for triggering alarms.
• keypadOperationEventMask (BITMAP16): Mask for keypad events.
• rfOperationEventMask (BITMAP16): Mask for RF events.

Key Commands

• lockDoor: Locks the door using a pincodevalue.
• unlockDoor: Unlocks the door using a pincodevalue.
• toggleDoor: Toggles the lock state.
• unlockWithTimeout: Unlocks for a specific timeout period.
• setPinCode: Sets a PIN for a specific userid and usertype.
• getPinCode: Retrieves the PIN for a userid.
• clearPinCode: Removes a PIN for a userid.
• clearAllPinCodes: Removes all stored PIN codes.

// Example: Unlocking a door
doorLockCluster.commands.unlockDoor({
  pincodevalue: Buffer.from([0x01, 0x02, 0x03, 0x04])
});