@matter/protocol 0.16.0-alpha.0-20250809-ee8375bcb → 0.16.0-alpha.0-20250812-285b75d83

package/src/advertisement/Advertiser.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Fabric } from "#fabric/Fabric.js";
+import { Advertisement } from "./Advertisement.js";
+import type { ServiceDescription } from "./ServiceDescription.js";
+
+/**
+ * A component that advertises a Matter service.
+ */
+export abstract class Advertiser {
+    #advertisements = new Set<Advertisement>();
+    #isClosed = false;
+
+    /**
+     * Begin advertising on configured schedule.
+     *
+     * Note that so long as the advertisement is installed the device will continue to respond to MDNS queries even if
+     * the advertisement schedule is elapsed.
+     *
+     * Returns undefined if the advertiser does not support this type of advertisement.
+     */
+    advertise(description: ServiceDescription, event: Advertiser.BroadcastEvent): Advertisement | undefined {
+        if (this.#isClosed) {
+            return;
+        }
+
+        const ad = this.getAdvertisement(description);
+        if (ad) {
+            ad.start(event);
+        }
+
+        return ad;
+    }
+
+    /**
+     * Create a new advertiser or retrieve existing advertiser.
+     */
+    protected abstract getAdvertisement(description: ServiceDescription): Advertisement | undefined;
+
+    /**
+     * Destroy the instance.
+     */
+    async close() {
+        this.#isClosed = true;
+        await Advertisement.closeAll(this.#advertisements);
+    }
+
+    /**
+     * The set of advertisements active for this advertiser.
+     */
+    get advertisements() {
+        return this.#advertisements;
+    }
+
+    /**
+     * Obtain the active advertisement for {@link fabric}, if any.
+     */
+    advertisementForFabric(fabric: Fabric) {
+        for (const ad of this.#advertisements) {
+            if (ad.isOperational() && ad.description.fabric === fabric) {
+                return ad;
+            }
+        }
+    }
+
+    /**
+     * Select advertisements using a predicate.
+     */
+    filter(predicate: (ad: Advertisement) => boolean) {
+        return [...this.#advertisements].filter(predicate);
+    }
+}
+
+export namespace Advertiser {
+    /**
+     * A hint for scheduling regarding why broadcast is initiated.
+     */
+    export type BroadcastEvent = "startup" | "reconnect" | "retransmit";
+}

package/src/advertisement/CommissioningMode.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export enum CommissioningMode {
+    NotCommissioning = 0,
+    Basic = 1,
+    Enhanced = 2,
+}

package/src/{common/InstanceBroadcaster.ts → advertisement/PairingHintBitmap.ts}

@@ -4,8 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BitFlag, BitmapSchema, ProductDescription, TypeFromPartialBitSchema, VendorId } from "#types";
-import { Fabric } from "../fabric/Fabric.js";
+import { BitFlag, BitmapSchema } from "@matter/types";
 
 export const PairingHintBitmap = {
     /**
@@ -128,93 +127,3 @@ export const PairingHintBitmap = {
 };
 
 export const PairingHintBitmapSchema = BitmapSchema(PairingHintBitmap);
-
-export interface CommissioningModeInstanceData extends ProductDescription {
-    /** Device discriminator for commissionable announcements. */
-    discriminator: number;
-
-    /** Session Idle Interval of the device for commissionable announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for commissionable announcements. */
-    sessionActiveInterval?: number;
-
-    /** Duration of time the node should stay active after the last network activity. **/
-    sessionActiveThreshold?: number;
-
-    /** Pairing hint of the device for commissionable announcements. */
-    pairingHint?: TypeFromPartialBitSchema<typeof PairingHintBitmap>;
-
-    /** Pairing instruction of the device for commissionable announcements. */
-    pairingInstructions?: string;
-}
-
-export type CommissionerInstanceData = {
-    /** Device name for commissionable announcements. */
-    deviceName: string;
-
-    /** Device type for commissionable announcements. */
-    vendorId: VendorId;
-
-    /** Vendor ID for commissionable announcements. */
-    productId: number;
-
-    /** Device type for commissionable announcements. */
-    deviceType?: number;
-
-    /** Session Idle Interval of the device for commissionable announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for commissionable announcements. */
-    sessionActiveInterval?: number;
-
-    /** This key defines the duration of time the node stays Active after the last network activity. **/
-    sessionActiveThreshold?: number;
-};
-
-export type OperationalInstanceData = {
-    /** Session Idle Interval of the device for operational announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for operational announcements. */
-    sessionActiveInterval?: number;
-
-    /** This key defines the duration of time the node stays Active after the last network activity. **/
-    sessionActiveThreshold?: number;
-};
-
-export enum CommissioningMode {
-    NotCommissioning = 0,
-    Basic = 1,
-    Enhanced = 2,
-}
-
-/** Interface for classes that allow to announce one Matter instance. */
-export interface InstanceBroadcaster {
-    /** Set a commissionable mode and details to announce a commissionable device. */
-    setCommissionMode(mode: CommissioningMode, deviceData: CommissioningModeInstanceData): Promise<void>;
-
-    /**
-     * Set operational details to Announce an operational device which is already commissioned.
-     * Use expireCommissioningAnnouncements = true when Fabrics are changed after a n commissioning process.
-     */
-    setFabrics(fabrics: Fabric[], expireCommissioningAnnouncements?: boolean): Promise<void>;
-
-    /** Set commissioner details to announce a commissioner service for User directed commissioning (UDC). */
-    setCommissionerInfo(commissionerData: CommissionerInstanceData): Promise<void>;
-
-    /** Send out announcements for this instance. */
-    announce(): Promise<void>;
-
-    /** Expire the announcement for this operative instance. */
-    expireFabricAnnouncement(): Promise<void>;
-
-    /** Expire the announcement for this commissioning instance. */
-    expireCommissioningAnnouncement(): Promise<void>;
-
-    /** Expire all announcements. */
-    expireAllAnnouncements(): Promise<void>;
-
-    /** Destroy the instance */
-    close(): Promise<void>;
-}

package/src/advertisement/ServiceDescription.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { PairingHintBitmap } from "#advertisement/PairingHintBitmap.js";
+import { SupportedTransportsBitmap } from "#common/SupportedTransportsBitmap.js";
+import type { Fabric } from "#fabric/Fabric.js";
+import { SessionIntervals } from "#session/SessionIntervals.js";
+import type { ProductDescription, TypeFromPartialBitSchema } from "@matter/types";
+import { IcdManagement } from "@matter/types/clusters/icd-management";
+import { CommissioningMode } from "./CommissioningMode.js";
+
+export type ServiceDescription =
+    | ServiceDescription.Operational
+    | ServiceDescription.Commissionable
+    | ServiceDescription.Commissioner;
+
+export namespace ServiceDescription {
+    export function isCommissioning(description: ServiceDescription): description is Commissionable | Commissioner {
+        return description.kind === "commissionable" || description.kind === "commissioner";
+    }
+
+    export function isOperational(description: ServiceDescription): description is Operational {
+        return description.kind === "operational";
+    }
+
+    export interface Base extends Partial<SessionIntervals> {
+        /**
+         * The IP port for the Matter protocol.
+         */
+        port?: number;
+
+        /**
+         * Indicate support for TCP.
+         */
+        tcp?: SupportedTransportsBitmap;
+
+        /**
+         * Indicate support for ICD.
+         */
+        icd?: IcdManagement.OperatingMode;
+    }
+
+    export interface Commissionable extends Base, ProductDescription {
+        readonly kind: "commissionable";
+
+        /**
+         * The commissioning mode.
+         */
+        readonly mode: CommissioningMode;
+
+        /**
+         * Device discriminator for commissionable announcements.
+         */
+        readonly discriminator: number;
+
+        /**
+         * Pairing hint of the device for commissionable announcements.
+         */
+        readonly pairingHint?: TypeFromPartialBitSchema<typeof PairingHintBitmap>;
+
+        /**
+         * Pairing instruction of the device for commissionable announcements.
+         */
+        readonly pairingInstructions?: string;
+    }
+
+    export function Commissionable(definition: Omit<Commissionable, "kind">): Commissionable {
+        return {
+            ...definition,
+            kind: "commissionable",
+        };
+    }
+
+    export interface Operational extends Base {
+        readonly kind: "operational";
+
+        /**
+         * The advertised fabric.
+         */
+        readonly fabric: Fabric;
+    }
+
+    export function Operational(definition: Omit<Operational, "kind">): Operational {
+        return {
+            ...definition,
+            kind: "operational",
+        };
+    }
+
+    export interface Commissioner extends Omit<ProductDescription, "deviceType">, Base {
+        readonly kind: "commissioner";
+
+        /**
+         * The device type.
+         *
+         * This is optional for commissioner advertisement.
+         */
+        readonly deviceType?: number;
+    }
+
+    export function Commissioner(definition: Omit<Commissioner, "kind">): Commissioner {
+        return {
+            ...definition,
+            kind: "commissioner",
+        };
+    }
+}

package/src/advertisement/ble/BleAdvertisement.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BtpCodec } from "#codec/BtpCodec.js";
+import { Advertisement } from "../Advertisement.js";
+import { ServiceDescription } from "../ServiceDescription.js";
+import type { BleAdvertiser } from "./BleAdvertiser.js";
+
+// Period for "fast" broadcast.  See core spec 5.4.2.5.3
+const EARLY_INTERVAL_SLEEP = 30_000;
+
+// Period for "medium" broadcast.  See core spec 5.4.2.5.3
+const LATE_INTERVAL_SLEEP = 15 * 60_000 - EARLY_INTERVAL_SLEEP;
+
+// Period for "extended" broadcast.  See core spec 5.4.2.5.3
+const EXTENDED_INTERVAL_SLEEP = 48 * 60 * 60_000 - LATE_INTERVAL_SLEEP;
+
+export class BleAdvertisement extends Advertisement<ServiceDescription.Commissionable> {
+    declare advertiser: BleAdvertiser;
+
+    constructor(advertiser: BleAdvertiser, description: ServiceDescription.Commissionable) {
+        super(advertiser, "ble:commissioning", description);
+    }
+
+    protected override async run(context: Advertisement.ActivityContext) {
+        const {
+            peripheral,
+            config: { earlyInterval, lateInterval, extendedInterval },
+        } = this.advertiser;
+
+        let aad = this.advertiser.config.aad;
+
+        let timeout = this.advertiser.config.timeout;
+
+        let advertisementData = this.#encodedAdvertisement;
+
+        let isExtended = false;
+
+        const intervals = [
+            { sleepTime: EARLY_INTERVAL_SLEEP, broadcastInterval: earlyInterval },
+            { sleepTime: LATE_INTERVAL_SLEEP, broadcastInterval: lateInterval },
+            { sleepTime: EXTENDED_INTERVAL_SLEEP, broadcastInterval: extendedInterval },
+        ];
+
+        try {
+            for (const { sleepTime, broadcastInterval } of intervals) {
+                // Recreate advertisement data for extended announcement
+                if (!isExtended && this.isPrivacyMasked) {
+                    isExtended = true;
+                    advertisementData = this.#encodedAdvertisement;
+                    aad = undefined;
+                }
+
+                // Configure BLE peripheral broadcasts at specified interval
+                await peripheral.advertise(advertisementData, aad, broadcastInterval);
+
+                // Wait for timeout at this broadcast interval
+                await context.sleep("BLE advertisement interval", Math.min(timeout, sleepTime));
+
+                timeout -= sleepTime;
+                if ((timeout -= sleepTime) <= 0) {
+                    break;
+                }
+            }
+        } finally {
+            await peripheral.stopAdvertising();
+        }
+    }
+
+    get #encodedAdvertisement() {
+        const { discriminator, vendorId, productId } = this.description;
+        const { isPrivacyMasked: isExtendedAnnouncement } = this;
+
+        return BtpCodec.encodeBleAdvertisementData(
+            discriminator,
+            isExtendedAnnouncement ? 0 : vendorId,
+            isExtendedAnnouncement ? 0 : productId,
+            !isExtendedAnnouncement && !!this.advertiser.config.aad?.length,
+            isExtendedAnnouncement,
+        );
+    }
+
+    isDuplicate() {
+        // We only allow a single advertisement per BLE interface
+        return true;
+    }
+}

package/src/advertisement/ble/BleAdvertiser.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BlePeripheralInterface } from "#ble/Ble.js";
+import { ImplementationError } from "#general";
+import { DatatypeModel, FieldElement } from "#model";
+import { MAXIMUM_COMMISSIONING_TIMEOUT_S } from "#types";
+import { Advertisement } from "../Advertisement.js";
+import { Advertiser } from "../Advertiser.js";
+import { CommissioningMode } from "../CommissioningMode.js";
+import { ServiceDescription } from "../ServiceDescription.js";
+import { BleAdvertisement } from "./BleAdvertisement.js";
+
+export class BleAdvertiser extends Advertiser {
+    #peripheral: BlePeripheralInterface;
+    #config: BleAdvertiser.Configuration;
+    #isClosed = false;
+
+    constructor(peripheral: BlePeripheralInterface, options?: BleAdvertiser.Options) {
+        super();
+
+        this.#peripheral = peripheral;
+        this.#config = BleAdvertiser.Configuration(options);
+    }
+
+    get peripheral() {
+        return this.#peripheral;
+    }
+
+    get config() {
+        return this.#config;
+    }
+
+    getAdvertisement(description: ServiceDescription): Advertisement | undefined {
+        this.#assertOpen();
+
+        if (description.kind !== "commissionable" || description.mode !== CommissioningMode.Basic) {
+            return;
+        }
+
+        return new BleAdvertisement(this, description);
+    }
+
+    #assertOpen() {
+        if (this.#isClosed) {
+            throw new ImplementationError("Illegal operation on closed BleBroadcaster");
+        }
+    }
+}
+
+export namespace BleAdvertiser {
+    /**
+     * Advertisement configuration.
+     *
+     * All intervals are in milliseconds.
+     */
+    export interface Configuration {
+        /**
+         * Additional advertisement data.
+         */
+        readonly aad?: Uint8Array;
+
+        /**
+         * Advertisement timeout.
+         */
+        readonly timeout: number;
+
+        /**
+         * Transmission interval for first 30 seconds.
+         *
+         * Per core spec 5.4.2.5.3 should be 20-60ms.
+         */
+        readonly earlyInterval: number;
+
+        /**
+         * Transmission interval after first 30 seconds but before 15 minutes.
+         *
+         * Per core spec 5.4.2.5.3 should be 150-1285ms.
+         */
+        readonly lateInterval: number;
+
+        /**
+         * Transmission interval after 15 minutes.
+         *
+         * Per core spec 5.4.2.5.3 should be ~1285ms.
+         */
+        readonly extendedInterval: number;
+    }
+
+    export interface Options extends Partial<Configuration> {}
+
+    export function Configuration(options?: Options) {
+        return {
+            timeout: MAXIMUM_COMMISSIONING_TIMEOUT_S,
+            earlyInterval: 20,
+            lateInterval: 150,
+            extendedInterval: 1285,
+            ...options,
+        };
+    }
+
+    /**
+     * Data model for BLE advertiser configuration.
+     */
+    export const OptionsSchema = new DatatypeModel(
+        { name: "BleAdvertiserOptions", type: "struct" },
+        FieldElement({ name: "add", type: "octstr" }),
+        FieldElement({ name: "timeout", type: "uint32" }),
+        FieldElement({ name: "earlyInterval", type: "uint32" }),
+        FieldElement({ name: "lateInterval", type: "uint32" }),
+        FieldElement({ name: "extendedInterval", type: "uint32" }),
+    );
+}

package/src/advertisement/ble/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BleAdvertisement.js";
+export * from "./BleAdvertiser.js";

package/src/advertisement/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Advertisement.js";
+export * from "./Advertiser.js";
+export * from "./ble/index.js";
+export * from "./CommissioningMode.js";
+export * from "./mdns/index.js";
+export * from "./PairingHintBitmap.js";
+export * from "./ServiceDescription.js";

package/src/advertisement/mdns/CommissionableMdnsAdvertisement.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Advertisement } from "#advertisement/Advertisement.js";
+import { PairingHintBitmapSchema } from "#advertisement/PairingHintBitmap.js";
+import { ServiceDescription } from "#advertisement/ServiceDescription.js";
+import { ImplementationError, PtrRecord } from "#general";
+import {
+    DEFAULT_PAIRING_HINT,
+    getCommissionableDeviceQname,
+    getCommissioningModeQname,
+    getDeviceTypeQname,
+    getLongDiscriminatorQname,
+    getShortDiscriminatorQname,
+    getVendorQname,
+    MATTER_COMMISSION_SERVICE_QNAME,
+    PAIRING_HINTS_REQUIRING_INSTRUCTION,
+    SERVICE_DISCOVERY_QNAME,
+} from "#mdns/MdnsConsts.js";
+import { MdnsAdvertisement } from "./MdnsAdvertisement.js";
+import type { MdnsAdvertiser } from "./MdnsAdvertiser.js";
+
+/**
+ * Advertise a node as commissionable.
+ */
+export class CommissionableMdnsAdvertisement extends MdnsAdvertisement<ServiceDescription.Commissionable> {
+    instanceId: string;
+
+    constructor(advertiser: MdnsAdvertiser, description: ServiceDescription.Commissionable) {
+        const instanceId = advertiser.createInstanceId();
+        const qname = getCommissionableDeviceQname(instanceId);
+
+        super(advertiser, qname, description);
+
+        this.instanceId = instanceId;
+
+        this.#validatePairingInstructions();
+    }
+
+    override get ptrRecords() {
+        const { discriminator, deviceType, vendorId } = this.description;
+
+        const shortDiscriminator = (discriminator >> 8) & 0x0f;
+        const vendorQname = getVendorQname(vendorId);
+        const deviceTypeQname = getDeviceTypeQname(deviceType);
+        const shortDiscriminatorQname = getShortDiscriminatorQname(shortDiscriminator);
+        const longDiscriminatorQname = getLongDiscriminatorQname(discriminator);
+        const commissionModeQname = getCommissioningModeQname();
+
+        const records = [
+            PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_COMMISSION_SERVICE_QNAME),
+            PtrRecord(SERVICE_DISCOVERY_QNAME, deviceTypeQname),
+            PtrRecord(SERVICE_DISCOVERY_QNAME, shortDiscriminatorQname),
+            PtrRecord(SERVICE_DISCOVERY_QNAME, longDiscriminatorQname),
+            PtrRecord(SERVICE_DISCOVERY_QNAME, commissionModeQname),
+            PtrRecord(MATTER_COMMISSION_SERVICE_QNAME, this.qname),
+            PtrRecord(deviceTypeQname, this.qname),
+            PtrRecord(shortDiscriminatorQname, this.qname),
+            PtrRecord(longDiscriminatorQname, this.qname),
+            PtrRecord(commissionModeQname, this.qname),
+        ];
+
+        if (!this.isPrivacyMasked) {
+            records.push(PtrRecord(SERVICE_DISCOVERY_QNAME, vendorQname), PtrRecord(vendorQname, this.qname));
+        }
+
+        return records;
+    }
+
+    override get txtValues() {
+        const {
+            vendorId,
+            productId,
+            deviceType,
+            name,
+            discriminator,
+            mode,
+            pairingHint = DEFAULT_PAIRING_HINT,
+            pairingInstructions,
+        } = this.description;
+
+        const values: Record<string, unknown> = {
+            DN: name /* Device Name */,
+            DT: deviceType /* Device Type */,
+            D: discriminator /* Discriminator */,
+            CM: mode /* Commission Mode */,
+            PH: PairingHintBitmapSchema.encode(pairingHint) /* Pairing Hint */,
+            PI: pairingInstructions /* Pairing Instruction */,
+        };
+
+        if (!this.isPrivacyMasked) {
+            values.VP = `${vendorId}+${productId}`; /* Vendor / Product */
+        }
+
+        return values;
+    }
+
+    override isDuplicate(other: Advertisement) {
+        // Only one commissioning advertisement allowed per advertiser
+        return other.isCommissioning();
+    }
+
+    #validatePairingInstructions() {
+        const { pairingHint, pairingInstructions } = this.description;
+
+        const needsInstructions =
+            pairingHint && PAIRING_HINTS_REQUIRING_INSTRUCTION.find(hint => pairingHint[hint] === true);
+
+        if (needsInstructions && !pairingInstructions) {
+            throw new ImplementationError(
+                `Pairing instructions required for pairing hint of type "${needsInstructions}"`,
+            );
+        }
+    }
+}