@matter/protocol 0.16.0-alpha.0-20250809-ee8375bcb → 0.16.0-alpha.0-20250810-5c91a95d2

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}"`,
+            );
+        }
+    }
+}

package/src/advertisement/mdns/CommissionerMdnsAdvertisement.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Advertisement } from "#advertisement/Advertisement.js";
+import { ServiceDescription } from "#advertisement/ServiceDescription.js";
+import { PtrRecord } from "#general";
+import {
+    getCommissionerDeviceQname,
+    MATTER_COMMISSIONER_SERVICE_QNAME,
+    SERVICE_DISCOVERY_QNAME,
+} from "#mdns/MdnsConsts.js";
+import { MdnsAdvertisement } from "./MdnsAdvertisement.js";
+import type { MdnsAdvertiser } from "./MdnsAdvertiser.js";
+
+/**
+ * Advertise a node as a commissioner service.
+ */
+export class CommissionerMdnsAdvertisement extends MdnsAdvertisement<ServiceDescription.Commissioner> {
+    instanceId: string;
+
+    constructor(advertiser: MdnsAdvertiser, description: ServiceDescription.Commissioner) {
+        const instanceId = advertiser.createInstanceId();
+        const qname = getCommissionerDeviceQname(instanceId);
+
+        super(advertiser, qname, description);
+
+        this.instanceId = instanceId;
+    }
+
+    override get ptrRecords() {
+        const { deviceType, vendorId } = this.description;
+
+        const vendorQname = `_V${vendorId}._sub.${MATTER_COMMISSIONER_SERVICE_QNAME}`;
+
+        const records = [
+            PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_COMMISSIONER_SERVICE_QNAME),
+            PtrRecord(MATTER_COMMISSIONER_SERVICE_QNAME, vendorQname),
+            PtrRecord(vendorQname, this.qname),
+        ];
+
+        if (deviceType !== undefined) {
+            const deviceTypeQname = `_T${deviceType}._sub.${MATTER_COMMISSIONER_SERVICE_QNAME}`;
+
+            records.push(PtrRecord(SERVICE_DISCOVERY_QNAME, deviceTypeQname));
+            records.push(PtrRecord(deviceTypeQname, this.qname));
+        }
+
+        return records;
+    }
+
+    override get txtValues() {
+        const { vendorId, productId, deviceType, name: deviceName } = this.description;
+
+        const values: Record<string, unknown> = {
+            DN: deviceName /* Device Name */,
+            DT: deviceType /* Device Type */,
+        };
+
+        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();
+    }
+}

package/src/advertisement/mdns/MdnsAdvertisement.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Advertisement } from "#advertisement/Advertisement.js";
+import type { Advertiser } from "#advertisement/Advertiser.js";
+import type { ServiceDescription } from "#advertisement/ServiceDescription.js";
+import { SupportedTransportsSchema } from "#common/SupportedTransportsBitmap.js";
+import { AAAARecord, ARecord, DnsRecord, Logger, NetworkInterfaceDetails, SrvRecord, Time, TxtRecord } from "#general";
+import type { MdnsServer } from "#mdns/MdnsServer.js";
+import { SessionIntervals } from "#session/SessionIntervals.js";
+import type { MdnsAdvertiser } from "./MdnsAdvertiser.js";
+
+const logger = Logger.get("MdnsAdvertisement");
+
+/**
+ * Base class for MDNS advertisements.
+ *
+ * Individual classes specialize for each type of service.
+ */
+export abstract class MdnsAdvertisement<T extends ServiceDescription = ServiceDescription> extends Advertisement<T> {
+    declare advertiser: MdnsAdvertiser;
+
+    /**
+     * The device qname.
+     */
+    qname: string;
+
+    #isPrivacyMasked: boolean;
+    #stopAt?: number;
+
+    constructor(advertiser: MdnsAdvertiser, qname: string, description: T) {
+        description = {
+            ...description,
+            ...SessionIntervals(description),
+        };
+        super(advertiser, `mdns:${qname}`, description, { omitPrivateDetails: advertiser.omitPrivateDetails });
+        this.qname = qname;
+        this.#isPrivacyMasked = this.isPrivacyMasked;
+    }
+
+    protected abstract ptrRecords: DnsRecord[];
+
+    protected get txtValues(): Record<string, unknown> {
+        return {};
+    }
+
+    override async run(context: Advertisement.ActivityContext, event: Advertiser.BroadcastEvent = "startup") {
+        this.#stopAt = undefined;
+        let number = 0;
+        for (const retryInterval of this.advertiser.broadcastScheduleFor(this, event)) {
+            if (this.#stopAt !== undefined && this.#stopAt <= Time.nowMs()) {
+                break;
+            }
+
+            number++;
+            logger.debug("Broadcast", this.dict({ number, next: retryInterval }));
+            await this.broadcast();
+            await context.sleep("MDNS repeat", retryInterval);
+        }
+    }
+
+    /**
+     * Broadcast a single announcement immediately.
+     */
+    async broadcast() {
+        if (!this.#isPrivacyMasked && this.isPrivacyMasked) {
+            this.#isPrivacyMasked = true;
+            await this.advertiser.server.setRecordsGenerator(this.service, this.#recordsGenerator);
+        }
+
+        await this.advertiser.server.broadcast(this.service);
+    }
+
+    /**
+     * Broadcast expiration announcement immediately.
+     */
+    async expire() {
+        logger.info("Unpublishing", this.dict({ time: this.duration }));
+        await this.advertiser.server.expireAnnouncements(this.service);
+    }
+
+    override serviceConnected() {
+        const { broadcastAfterConnection } = this.advertiser.broadcastConfigFor(this);
+
+        if (broadcastAfterConnection === undefined) {
+            return;
+        }
+
+        if (broadcastAfterConnection <= 0) {
+            this.stop();
+            return;
+        }
+
+        this.#stopAt = Time.nowMs() + broadcastAfterConnection;
+    }
+
+    override serviceDisconnected() {
+        this.start("reconnect");
+    }
+
+    protected override async onCreate() {
+        // Use Promise.resolve() to initialize on next microtick so the constructor completes before invocation
+        await Promise.resolve().then(() => {
+            // Install the records generator.  This will be used for broadcast and to respond to queries
+            logger.info("Publishing", this.dict());
+            return this.advertiser.server.setRecordsGenerator(this.service, this.#recordsGenerator);
+        });
+    }
+
+    protected override async onClose() {
+        // The MDNS server doesn't currently track which answers have been sent so just expire unconditionally
+        await this.expire();
+    }
+
+    get #recordsGenerator(): MdnsServer.RecordGenerator {
+        return (_intf, addrs) => this.#recordsFor(addrs);
+    }
+
+    #recordsFor(addrs: NetworkInterfaceDetails) {
+        const hostname = addrs.mac.replace(/:/g, "").toUpperCase() + "0000.local";
+
+        const records: DnsRecord[] = [
+            ...this.ptrRecords,
+            SrvRecord(this.qname, { priority: 0, weight: 0, port: this.advertiser.port, target: hostname }),
+            TxtRecord(
+                this.qname,
+                Object.entries(this.#txtValues)
+                    .filter(([, v]) => v !== undefined)
+                    .map(([k, v]) => `${k}=${v}`),
+            ),
+        ];
+
+        for (const addr of addrs.ipV6) {
+            records.push(AAAARecord(hostname, addr));
+        }
+
+        if (this.advertiser.server.supportsIpv4) {
+            for (const addr of addrs.ipV4) {
+                records.push(ARecord(hostname, addr));
+            }
+        }
+
+        return records;
+    }
+
+    get #txtValues() {
+        const values: Record<string, unknown> = {
+            SII: this.description.idleIntervalMs /* Session Idle Interval */,
+            SAI: this.description.activeIntervalMs /* Session Active Interval */,
+            SAT: this.description.activeThresholdMs /* Session Active Threshold */,
+            ...this.txtValues,
+        };
+
+        if (this.description.tcp !== undefined) {
+            values.T = SupportedTransportsSchema.encode(this.description.tcp); /* TCP support */
+        }
+
+        if (this.description.icd !== undefined) {
+            values.ICD = this.description.icd; /* ICD support */
+        }
+
+        return values;
+    }
+}