@project-chip/matter.js

/** * @license * Copyright 2022-2025 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { ClassExtends, Crypto, Environment, NetInterfaceSet, Network, StorageContext, SyncStorage } from "#general"; import { CommissionableDevice, CommissionableDeviceIdentifiers, ControllerCommissioningFlow, DiscoveryAndCommissioningOptions, DiscoveryData, InteractionClient, MdnsBroadcaster, MdnsScanner, MessageChannel, NodeDiscoveryType, ScannerSet } from "#protocol"; import { CaseAuthenticatedTag, DiscoveryCapabilitiesBitmap, FabricId, FabricIndex, NodeId, TypeFromPartialBitSchema, VendorId } from "#types"; import { CertificateAuthority, Fabric } from "@matter/protocol"; import { CommissioningControllerNodeOptions, PairedNode } from "./device/PairedNode.js"; export type ControllerEnvironmentOptions = { /** * Environment to register the node with on start() */ readonly environment: Environment; /** * Unique id to register to node. */ readonly id: string; }; /** * Constructor options for the CommissioningController class */ export type CommissioningControllerOptions = CommissioningControllerNodeOptions & { /** * Local port number to use for the UDP interface. By default, a random port number will be generated * (strongly recommended!). */ readonly localPort?: number; /** Listening address for IPv4. By default, the interface will listen on all IPv4 addresses. */ readonly listeningAddressIpv4?: string; /** Listening address for IPv6. By default, the interface will listen on all IPv6 addresses. */ readonly listeningAddressIpv6?: string; /** * If set to false, the controller will not connect to any device on startup. You need to use connectNode() or * connect() to connect to the relevant nodes in this case. Else all nodes are connected on startup. * */ readonly autoConnect?: boolean; /** Admin Vendor ID used for all commissioning operations. Cannot be changed afterward. Default: 0xFFF1 */ readonly adminVendorId?: VendorId; /** * Controller own Fabric ID used to initialize the Controller the first time and to generate the Root certificate. * Cannot be changed afterward. * Default: 1 */ readonly adminFabricId?: FabricId; /** * Fabric Index used to initialize the Controller the first time. Cannot be changed afterward. * Default: 1 */ readonly adminFabricIndex?: FabricIndex; /** * CASE Authenticated Tags used to initialize the Controller the first time. Cannot be changed afterward. * Maximum 3 tags are supported. */ readonly caseAuthenticatedTags?: CaseAuthenticatedTag[]; /** * The Fabric Label to set for the commissioned devices. The #label is used for users to identify the admin. * The maximum length are 32 characters! * The value will automatically be checked on connection to a node and updated if necessary. */ readonly adminFabricLabel: string; /** * When used with the new API Environment set the environment here and the CommissioningServer will self-register * on the environment when you call start(). */ readonly environment?: ControllerEnvironmentOptions; /** * The NodeId of the root node to use for the controller. This is only needed if a special NodeId needs to be used * but certificates should be self-generated. By default, a random operational ID is generated. */ readonly rootNodeId?: NodeId; /** * If provided this Certificate Authority instance is used to fetch or get all relevant certificates for the * Controller. If not provided a new Certificate Authority instance is created and certificates will be self-generated. */ readonly rootCertificateAuthority?: CertificateAuthority; /** * If provided this Fabric instance is used for this controller. The instance need to be in sync with the provided * or stored certificate authority. If provided then rootFabricId, rootFabricIndex and rootFabricLabel are ignored. */ readonly rootFabric?: Fabric; }; /** Options needed to commission a new node */ export type NodeCommissioningOptions = CommissioningControllerNodeOptions & { commissioning: Omit<DiscoveryAndCommissioningOptions, "fabric" | "discovery" | "passcode">; discovery: DiscoveryAndCommissioningOptions["discovery"]; passcode: number; }; /** Controller class to commission and connect multiple nodes into one fabric. */ export declare class CommissioningController { #private; /** * Creates a new CommissioningController instance * * @param options The options for the CommissioningController */ constructor(options: CommissioningControllerOptions); get crypto(): Crypto; get nodeId(): NodeId | undefined; /** Returns the configuration data needed to create a PASE commissioner, e.g. in a mobile app. */ get paseCommissionerConfig(): { caConfig: CertificateAuthority.Configuration; fabricData: Fabric.Config; }; /** * Commissions/Pairs a new device into the controller fabric. The method returns the NodeId of the commissioned * node on success. */ commissionNode(nodeOptions: NodeCommissioningOptions, commissionOptions?: { connectNodeAfterCommissioning?: boolean; commissioningFlowImpl?: ClassExtends<ControllerCommissioningFlow>; }): Promise<NodeId>; connectPaseChannel(nodeOptions: NodeCommissioningOptions): Promise<MessageChannel>; /** * Completes the commissioning process for a node when the initial commissioning process was done by a PASE * commissioner. This method should be called to discover the device operational and complete the commissioning * process. */ completeCommissioningForNode(peerNodeId: NodeId, discoveryData?: DiscoveryData): Promise<void>; /** Check if a given node id is commissioned on this controller. */ isNodeCommissioned(nodeId: NodeId): boolean; /** * Remove a Node id from the controller. This method should only be used if the decommission method on the * PairedNode instance returns an error. By default, it tries to decommission the node from the controller but will * remove it also in case of an error during decommissioning. Ideally try to decommission the node before and only * use this in case of an error as last option. * If this method is used the state of the PairedNode instance might be out of sync, so the PairedNode instance * should be disconnected first. */ removeNode(nodeId: NodeId, tryDecommissioning?: boolean): Promise<void>; /** @deprecated Use PairedNode.disconnect() instead */ disconnectNode(nodeId: NodeId, force?: boolean): Promise<void>; /** * Returns the PairedNode instance for a given NodeId. The instance is initialized without auto connect if not yet * created. */ getNode(nodeId: NodeId, allowUnknownNode?: boolean): Promise<PairedNode>; /** * Connect to an already paired Node. * After connection the endpoint data of the device is analyzed and an object structure is created. * This call is not blocking and returns an initialized PairedNode instance. The connection or reconnection * happens in the background. Please monitor the state of the node to see if the connection was successful. * * @deprecated Use getNode() instead and call PairedNode.connect() or PairedNode.disconnect() as needed. */ connectNode(nodeId: NodeId, connectOptions?: CommissioningControllerNodeOptions, allowUnknownNode?: boolean): Promise<PairedNode>; /** * Connects to all paired nodes. * After connection the endpoint data of the device is analyzed and an object structure is created. * * @deprecated Use getCommissionedNodes() to get the list of nodes and getNode(nodeId) instead and call PairedNode.connect() or PairedNode.disconnect() as needed. */ connect(connectOptions?: CommissioningControllerNodeOptions): Promise<PairedNode[]>; /** * Set the MDNS Scanner instance. Should be only used internally * * @param mdnsScanner MdnsScanner instance * @private */ setMdnsScanner(mdnsScanner: MdnsScanner): void; /** * Set the MDNS Broadcaster instance. Should be only used internally * * @param mdnsBroadcaster MdnsBroadcaster instance * @private */ setMdnsBroadcaster(mdnsBroadcaster: MdnsBroadcaster): void; /** * Set the Storage instance. Should be only used internally * * @param storage storage context to use * @private */ setStorage(storage: StorageContext<SyncStorage>): void; /** Returns true if t least one node is commissioned/paired with this controller instance. */ isCommissioned(): boolean; /** * Creates and Return a new InteractionClient to communicate with a node. This is mainly used internally and should * not be used directly. See the PairedNode class for the public API. */ createInteractionClient(nodeIdOrChannel: NodeId | MessageChannel, discoveryType?: NodeDiscoveryType, options?: { forcedConnection?: boolean; }): Promise<InteractionClient>; /** * Returns the PairedNode instance for a given node id, if this node is connected. * @deprecated Use getNode() instead */ getPairedNode(nodeId: NodeId): PairedNode | undefined; /** Returns an array with the NodeIds of all commissioned nodes. */ getCommissionedNodes(): NodeId[]; /** Returns an arra with all commissioned NodeIds and their metadata. */ getCommissionedNodesDetails(): { nodeId: NodeId; operationalAddress: string | undefined; advertisedName: string | undefined; discoveryData: DiscoveryData | undefined; deviceData: import("./device/DeviceInformation.js").DeviceInformationData | undefined; }[]; /** * Disconnects all connected nodes and closes the network connections and other resources of the controller. * You can use "start()" to restart the controller after closing it. */ close(): Promise<void>; /** Return the port used by the controller for the UDP interface. */ getPort(): number | undefined; /** @private */ initialize(ipv4Disabled: boolean): void; /** @private */ initializeControllerStore(): Promise<void>; /** * Initialize the controller and initialize and connect to all commissioned nodes if autoConnect is not set to false. */ start(): Promise<void>; /** * Cancels the discovery process for commissionable devices started with discoverCommissionableDevices(). */ cancelCommissionableDeviceDiscovery(identifierData: CommissionableDeviceIdentifiers, discoveryCapabilities?: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap>): void; /** * Starts to discover commissionable devices. * The promise will be fulfilled after the provided timeout or when the discovery is stopped via * cancelCommissionableDeviceDiscovery(). The discoveredCallback will be called for each discovered device. */ discoverCommissionableDevices(identifierData: CommissionableDeviceIdentifiers, discoveryCapabilities?: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap>, discoveredCallback?: (device: CommissionableDevice) => void, timeoutSeconds?: number): Promise<CommissionableDevice[]>; /** * Use this method to reset the Controller storage. The method can only be called if the controller is stopped and * will remove all commissioning data and paired nodes from the controller. */ resetStorage(): Promise<void>; /** Returns active session information for all connected nodes. */ getActiveSessionInformation(): { name: string; nodeId: NodeId; peerNodeId: NodeId; fabric: import("@matter/protocol").ExposedFabricInformation | undefined; isPeerActive: boolean; secure: boolean; lastInteractionTimestamp: number | undefined; lastActiveTimestamp: number | undefined; numberOfActiveSubscriptions: number; }[]; /** @private */ validateAndUpdateFabricLabel(nodeId: NodeId): Promise<void>; /** * Updates the fabric label for the controller and all connected nodes. * The label is used to identify the controller and all connected nodes in the fabric. */ updateFabricLabel(label: string): Promise<void>; get groups(): import("@matter/protocol").FabricGroups; } export declare function configureNetwork(options: { network: Network; ipv4Disabled?: boolean; mdnsScanner?: MdnsScanner; localPort?: number; listeningAddressIpv6?: string; listeningAddressIpv4?: string; }): Promise<{ netInterfaces: NetInterfaceSet; scanners: ScannerSet; port: number; }>; //# sourceMappingURL=CommissioningController.d.ts.map