@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/MatterDevice.ts

@@ -0,0 +1,319 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Important note: This file is part of the legacy matter-node (internal) API and should not be used anymore directly!
+ * Please use the new API classes!
+ * @deprecated
+ */
+
+import {
+    Construction,
+    InternalError,
+    ObserverGroup,
+    StorageContext,
+    TransportInterface,
+    TransportInterfaceSet,
+    asyncNew,
+} from "#general";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { DeviceAdvertiser } from "#protocol/DeviceAdvertiser.js";
+import { CommissioningConfigProvider, DeviceCommissioner } from "#protocol/DeviceCommissioner.js";
+import { CommissioningOptions, FabricIndex } from "#types";
+import { FailsafeContext } from "./common/FailsafeContext.js";
+import { InstanceBroadcaster } from "./common/InstanceBroadcaster.js";
+import { Fabric } from "./fabric/Fabric.js";
+import { FabricAction, FabricManager } from "./fabric/FabricManager.js";
+import { ChannelManager } from "./protocol/ChannelManager.js";
+import { ExchangeManager } from "./protocol/ExchangeManager.js";
+import { ProtocolHandler } from "./protocol/ProtocolHandler.js";
+import { SecureChannelProtocol } from "./securechannel/SecureChannelProtocol.js";
+import { Session, SessionParameters } from "./session/Session.js";
+import { SessionManager } from "./session/SessionManager.js";
+import { PaseServer } from "./session/pase/PaseServer.js";
+
+export class MatterDevice {
+    readonly #exchangeManager;
+    readonly #fabricManager: FabricManager;
+    readonly #sessionManager: SessionManager;
+    readonly #commissioner: DeviceCommissioner;
+    readonly #advertiser: DeviceAdvertiser;
+    readonly #transportInterfaces: TransportInterfaceSet;
+    readonly #channelManager: ChannelManager;
+    readonly #observers = new ObserverGroup();
+    #isClosing = false;
+
+    #construction: Construction<MatterDevice>;
+
+    get construction() {
+        return this.#construction;
+    }
+
+    static async create(
+        sessionStorage: StorageContext,
+        fabricStorage: StorageContext,
+        getCommissioningConfig: () => CommissioningOptions.Configuration,
+        minimumCaseSessionsPerFabricAndNode = 3,
+        commissioningChangedCallback: (fabricIndex: FabricIndex, fabricAction: FabricAction) => void,
+        sessionChangedCallback: (fabricIndex: FabricIndex) => void,
+        sessionParameters?: Partial<SessionParameters>,
+    ) {
+        return asyncNew(
+            MatterDevice,
+            sessionStorage,
+            fabricStorage,
+            getCommissioningConfig,
+            minimumCaseSessionsPerFabricAndNode,
+            commissioningChangedCallback,
+            sessionChangedCallback,
+            sessionParameters,
+        );
+    }
+
+    constructor(
+        readonly sessionStorage: StorageContext,
+        readonly fabricStorage: StorageContext,
+        getCommissioningConfig: () => CommissioningOptions.Configuration,
+        minimumCaseSessionsPerFabricAndNode: number,
+        private readonly commissioningChangedCallback: (fabricIndex: FabricIndex, fabricAction: FabricAction) => void,
+        private readonly sessionChangedCallback: (fabricIndex: FabricIndex) => void,
+        sessionParameters: Partial<SessionParameters> = {},
+    ) {
+        this.#channelManager = new ChannelManager(minimumCaseSessionsPerFabricAndNode);
+
+        this.#fabricManager = new FabricManager(fabricStorage);
+
+        this.#observers.on(this.#fabricManager.events.deleted, async ({ fabricIndex }) =>
+            this.commissioningChangedCallback(fabricIndex, FabricAction.Removed),
+        );
+        this.#observers.on(this.#fabricManager.events.updated, ({ fabricIndex }) =>
+            this.commissioningChangedCallback(fabricIndex, FabricAction.Updated),
+        );
+
+        this.#sessionManager = new SessionManager({
+            fabrics: this.#fabricManager,
+            storage: sessionStorage,
+            parameters: sessionParameters,
+            owner: this,
+        });
+
+        this.#transportInterfaces = new TransportInterfaceSet();
+
+        this.#exchangeManager = new ExchangeManager({
+            transportInterfaces: this.#transportInterfaces,
+            sessionManager: this.#sessionManager,
+            channelManager: this.#channelManager,
+        });
+
+        const secureChannelProtocol = new SecureChannelProtocol(this.#sessionManager, this.#fabricManager);
+
+        this.#exchangeManager.addProtocolHandler(secureChannelProtocol);
+
+        this.#observers.on(this.#sessionManager.sessions.added, session => {
+            if (session.fabric) {
+                this.sessionChangedCallback(session.fabric.fabricIndex);
+            }
+        });
+
+        this.#observers.on(this.#sessionManager.sessions.deleted, async session => {
+            const currentFabricIndex = session.fabric?.fabricIndex;
+            if (currentFabricIndex !== undefined) {
+                this.sessionChangedCallback(currentFabricIndex);
+            }
+        });
+
+        this.#observers.on(this.#sessionManager.subscriptionsChanged, (session, _subscription) => {
+            const currentFabric = session.fabric;
+            if (currentFabric !== undefined) {
+                this.sessionChangedCallback(currentFabric.fabricIndex);
+            }
+        });
+
+        this.#advertiser = new DeviceAdvertiser({
+            fabrics: this.fabricManager,
+            sessions: this.sessionManager,
+        });
+        this.#commissioner = new DeviceCommissioner({
+            fabrics: this.fabricManager,
+            sessions: this.sessionManager,
+            advertiser: this.#advertiser,
+            secureChannelProtocol,
+            commissioningConfig: new (class extends CommissioningConfigProvider {
+                get values() {
+                    return getCommissioningConfig();
+                }
+            })(),
+        });
+
+        this.#construction = Construction(this, async () => {
+            await this.#fabricManager.construction.ready;
+
+            // Attach added events delayed because initialization from storage would else trigger it
+            this.#observers.on(this.#fabricManager.events.added, ({ fabricIndex }) =>
+                this.commissioningChangedCallback(fabricIndex, FabricAction.Added),
+            );
+
+            await this.#sessionManager.construction.ready;
+        });
+    }
+
+    get fabricManager() {
+        return this.#fabricManager;
+    }
+
+    get sessionManager() {
+        return this.#sessionManager;
+    }
+
+    get exchangeManager() {
+        return this.#exchangeManager;
+    }
+
+    get advertiser() {
+        return this.#advertiser;
+    }
+
+    get commissioner() {
+        return this.#commissioner;
+    }
+
+    get failsafeContext() {
+        return this.#commissioner.failsafeContext;
+    }
+
+    get isClosing() {
+        return this.#isClosing;
+    }
+
+    async beginTimed(failsafeContext: FailsafeContext) {
+        return this.#commissioner.beginTimed(failsafeContext);
+    }
+
+    assertFailSafeArmed(message?: string) {
+        return this.#commissioner.assertFailsafeArmed(message);
+    }
+
+    isFailsafeArmed() {
+        return this.#commissioner.isFailsafeArmed;
+    }
+
+    hasBroadcaster(broadcaster: InstanceBroadcaster) {
+        return this.#advertiser.hasBroadcaster(broadcaster);
+    }
+
+    addBroadcaster(broadcaster: InstanceBroadcaster) {
+        this.#advertiser.addBroadcaster(broadcaster);
+        return this;
+    }
+
+    async deleteBroadcaster(broadcaster: InstanceBroadcaster) {
+        return this.#advertiser.deleteBroadcaster(broadcaster);
+    }
+
+    addTransportInterface(transport: TransportInterface) {
+        this.#transportInterfaces.add(transport);
+        return this;
+    }
+
+    async deleteTransportInterface(transport: TransportInterface) {
+        this.#transportInterfaces.delete(transport);
+    }
+
+    hasProtocolHandler(protocolId: number) {
+        return this.exchangeManager.hasProtocolHandler(protocolId);
+    }
+
+    addProtocolHandler(protocol: ProtocolHandler) {
+        this.exchangeManager.addProtocolHandler(protocol);
+        return this;
+    }
+
+    async start() {
+        await this.startAnnouncement();
+    }
+
+    async startAnnouncement() {
+        return this.#advertiser.startAdvertising();
+    }
+
+    async announce(announceOnce = false) {
+        return this.#advertiser.advertise(announceOnce);
+    }
+
+    reAnnounceAsCommissionable() {
+        this.#commissioner.reactivateAdvertiser();
+    }
+
+    findFabricFromDestinationId(destinationId: Uint8Array, peerRandom: Uint8Array) {
+        return this.#fabricManager.findFabricFromDestinationId(destinationId, peerRandom);
+    }
+
+    async sendFabricAnnouncements(fabrics: Fabric[], expireCommissioningAnnouncement = false) {
+        return this.#advertiser.advertiseFabrics(fabrics, expireCommissioningAnnouncement);
+    }
+
+    getFabricByIndex(fabricIndex: FabricIndex) {
+        return this.#fabricManager.findByIndex(fabricIndex);
+    }
+
+    initiateExchange(address: PeerAddress, protocolId: number) {
+        return this.#exchangeManager.initiateExchange(address, protocolId);
+    }
+
+    getFabrics() {
+        return this.#fabricManager.getFabrics();
+    }
+
+    isCommissioned() {
+        return !!this.#fabricManager.getFabrics().length;
+    }
+
+    async allowEnhancedCommissioning(
+        discriminator: number,
+        paseServer: PaseServer,
+        commissioningEndCallback: () => void,
+    ) {
+        return this.#commissioner.allowEnhancedCommissioning(discriminator, paseServer, commissioningEndCallback);
+    }
+
+    async allowBasicCommissioning(commissioningEndCallback?: () => void) {
+        return this.#commissioner.allowBasicCommissioning(commissioningEndCallback);
+    }
+
+    async endCommissioning() {
+        return this.#commissioner.endCommissioning();
+    }
+
+    existsOpenPaseSession() {
+        return !!this.#sessionManager.getPaseSession();
+    }
+
+    async close() {
+        this.#isClosing = true;
+        this.#observers.close();
+        await this.#commissioner.close();
+        await this.#advertiser.close();
+        await this.exchangeManager.close();
+        await this.#sessionManager.close();
+        await this.#channelManager.close();
+        await this.#transportInterfaces.close();
+    }
+
+    getActiveSessionInformation() {
+        return this.#sessionManager.getActiveSessionInformation();
+    }
+
+    static of(session: Session | undefined) {
+        if (session === undefined) {
+            throw new InternalError("Device operation without session");
+        }
+        const device = session.owner;
+        if (!(device instanceof MatterDevice)) {
+            throw new InternalError("Device operation on non-device session");
+        }
+        return device;
+    }
+}

package/src/ble/Ble.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Channel, ChannelType, MatterError, NetInterface, NoProviderError, TransportInterface } from "#general";
+import { InstanceBroadcaster } from "../common/InstanceBroadcaster.js";
+import { Scanner } from "../common/Scanner.js";
+import { BLE_MAX_MATTER_PAYLOAD_SIZE } from "./BleConsts.js";
+
+export class BleError extends MatterError {}
+
+function BleDisabled(): Ble {
+    throw new NoProviderError("No provider configured");
+}
+
+// TODO - need to factor out the general platform BLE from Matter/BTP so this can move into matter.js-general
+export abstract class Ble {
+    static get = BleDisabled;
+
+    static get enabled() {
+        return this.get !== BleDisabled;
+    }
+
+    abstract getBlePeripheralInterface(): TransportInterface;
+    abstract getBleCentralInterface(): NetInterface;
+    abstract getBleBroadcaster(additionalAdvertisementData?: Uint8Array): InstanceBroadcaster;
+    abstract getBleScanner(): Scanner;
+}
+
+export abstract class BleChannel<T> implements Channel<T> {
+    readonly maxPayloadSize = BLE_MAX_MATTER_PAYLOAD_SIZE;
+    readonly isReliable = true; // BLE uses BTP which is reliable
+    readonly type = ChannelType.BLE;
+
+    abstract name: string;
+    abstract send(data: T): Promise<void>;
+    abstract close(): Promise<void>;
+}

package/src/ble/BleConsts.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MAX_UDP_MESSAGE_SIZE } from "#general";
+
+/** @see {@link MatterSpecification.v11.Core} § 4.17.3.2 */
+export const BLE_MATTER_SERVICE_UUID = "fff6";
+export const BLE_MATTER_C1_CHARACTERISTIC_UUID = "18EE2EF5-263D-4559-959F-4F9C429F9D11";
+export const BLE_MATTER_C2_CHARACTERISTIC_UUID = "18EE2EF5-263D-4559-959F-4F9C429F9D12";
+export const BLE_MATTER_C3_CHARACTERISTIC_UUID = "64630238-8772-45F2-B87D-748A83218F04";
+
+export const BLE_MINIMUM_ATT_MTU = 20; // 23-byte minimum ATT_MTU - 3 bytes for ATT operation header
+export const BLE_MAXIMUM_BTP_MTU = 244; // Maximum size of BTP segment
+
+export const BTP_MAXIMUM_WINDOW_SIZE = 255; // Server maximum window size
+
+/**
+ * The maximum amount of time after sending a BTP Session Handshake request to wait for a BTP Session Handshake response
+ * before closing the connection.
+ */
+export const BTP_CONN_RSP_TIMEOUT_MS = 5_000; // timer starts when receives handshake request & waits for a subscription request on c2
+
+/** The maximum amount of time after receipt of a segment before a stand-alone ACK must be sent. */
+export const BTP_ACK_TIMEOUT_MS = 15_000; // timer in ms before ack should be sent for a segment
+
+export const BTP_SEND_ACK_TIMEOUT_MS = BTP_ACK_TIMEOUT_MS / 3; // timer starts when we receive a packet and stops when we sends its ack
+
+/**
+ * The maximum amount of time no unique data has been sent over a BTP session before the Central Device must close the
+ * BTP session.
+ */
+export const BTP_CONN_IDLE_TIMEOUT = 30_000;
+
+/**
+ * The maximum message size that can be transported in a Matter message via BTP.
+ * Seems the chip code in BTPEngine limits the size currently to "one pbuf" which should mean one UDP message.
+ */
+export const BLE_MAX_MATTER_PAYLOAD_SIZE = MAX_UDP_MESSAGE_SIZE;