@matter/protocol 0.16.0-alpha.0-20250807-37b08c9bb → 0.16.0-alpha.0-20250810-5c91a95d2

package/src/advertisement/mdns/MdnsAdvertiser.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Advertiser } from "#advertisement/Advertiser.js";
+import { ServiceDescription } from "#advertisement/ServiceDescription.js";
+import { Bytes, Crypto, ImplementationError, InternalError, RetrySchedule, STANDARD_MATTER_PORT } from "#general";
+import type { MdnsServer } from "#mdns/MdnsServer.js";
+import { DatatypeModel, FieldElement } from "#model";
+import { MAXIMUM_COMMISSIONING_TIMEOUT_S } from "#types";
+import { CommissionableMdnsAdvertisement } from "./CommissionableMdnsAdvertisement.js";
+import { CommissionerMdnsAdvertisement } from "./CommissionerMdnsAdvertisement.js";
+import type { MdnsAdvertisement } from "./MdnsAdvertisement.js";
+import { OperationalMdnsAdvertisement } from "./OperationalMdnsAdvertisement.js";
+
+/**
+ * An {@link Advertiser} that advertises using an in-process MDNS implementation.
+ */
+export class MdnsAdvertiser extends Advertiser {
+    readonly port: number;
+    readonly omitPrivateDetails: boolean;
+
+    #schedules = new Array<{ config: MdnsAdvertiser.BroadcastSchedule; schedule?: RetrySchedule }>();
+
+    constructor(
+        readonly crypto: Crypto,
+        readonly server: MdnsServer,
+        options?: MdnsAdvertiser.Options,
+    ) {
+        super();
+
+        this.port = options?.port ?? STANDARD_MATTER_PORT;
+        this.omitPrivateDetails = options?.omitPrivateDetails ?? false;
+
+        let hasDefaultSchedule = false;
+        let hasRetransmitSchedule = false;
+        if (options?.schedules) {
+            for (const schedule of options.schedules) {
+                if (schedule.serviceKind === undefined) {
+                    if (schedule.event === undefined) {
+                        hasDefaultSchedule = true;
+                    }
+
+                    if (schedule.event === "retransmit") {
+                        hasRetransmitSchedule = true;
+                    }
+                }
+
+                this.#schedules.push({ config: schedule });
+            }
+        }
+
+        if (!hasRetransmitSchedule) {
+            this.#schedules.push({ config: MdnsAdvertiser.RetransmissionBroadcastSchedule });
+        }
+
+        if (!hasDefaultSchedule) {
+            this.#schedules.push({ config: MdnsAdvertiser.DefaultBroadcastSchedule });
+        }
+    }
+
+    /**
+     * Create an advertisement for the specific service.
+     */
+    override getAdvertisement(description: ServiceDescription): MdnsAdvertisement | undefined {
+        switch (description.kind) {
+            case "operational":
+                return (
+                    (this.advertisementForFabric(description.fabric) as MdnsAdvertisement | undefined) ??
+                    new OperationalMdnsAdvertisement(this, description)
+                );
+
+            case "commissionable":
+                return new CommissionableMdnsAdvertisement(this, description);
+
+            case "commissioner":
+                return new CommissionerMdnsAdvertisement(this, description);
+
+            default:
+                throw new ImplementationError(
+                    `Unsupported service description kind "${(description as ServiceDescription).kind}`,
+                );
+        }
+    }
+
+    /**
+     * Generate a random 8-byte Matter instance identifier.
+     */
+    createInstanceId() {
+        return Bytes.toHex(this.crypto.randomBytes(8)).toUpperCase();
+    }
+
+    /**
+     * Retrieve the broadcast schedule for a specific advertisement.
+     */
+    broadcastScheduleFor(advertisement: MdnsAdvertisement, event?: Advertiser.BroadcastEvent) {
+        const entry = this.#scheduleFor(advertisement, event);
+
+        if (entry.schedule === undefined) {
+            entry.schedule = new RetrySchedule(
+                this.crypto,
+                RetrySchedule.Configuration(MdnsAdvertiser.DefaultBroadcastSchedule, entry.config),
+            );
+        }
+
+        return entry.schedule;
+    }
+
+    /**
+     * Retrieve broadcast configuration for a specific advertisement.
+     */
+    broadcastConfigFor(advertisement: MdnsAdvertisement, event?: Advertiser.BroadcastEvent) {
+        return this.#scheduleFor(advertisement, event).config;
+    }
+
+    #scheduleFor(advertisement: MdnsAdvertisement, event?: Advertiser.BroadcastEvent) {
+        if (!event) {
+            event = "startup";
+        }
+
+        for (const entry of this.#schedules) {
+            const { serviceKind, event: event2 } = entry.config;
+
+            if (serviceKind !== undefined && serviceKind !== advertisement.description.kind) {
+                continue;
+            }
+
+            if (event2 !== undefined && event2 !== event) {
+                continue;
+            }
+
+            return entry;
+        }
+
+        throw new InternalError("Default retry schedule not present");
+    }
+}
+
+export namespace MdnsAdvertiser {
+    /**
+     * MDNS advertisement configuration options.
+     */
+    export interface Options {
+        /**
+         * The port of the Matter service to advertise.
+         *
+         * Defaults to 5540.
+         */
+        readonly port?: number;
+
+        /**
+         * Omit the vendor and product ID from announcements for privacy reasons.
+         */
+        readonly omitPrivateDetails?: boolean;
+
+        /**
+         * Broadcast schedule.
+         *
+         * These control the intervals at which the server broadcasts the advertisement.  Note that order is important;
+         * more specific schedules should appear first.
+         *
+         * By default all broadcasts are configured using {@link DefaultBroadcastSchedule}.
+         */
+        readonly schedules?: readonly BroadcastSchedule[];
+    }
+
+    /**
+     * Schedule for automatic broadcasts.
+     *
+     * Schedules apply conditionally with {@link DefaultBroadcastSchedule} as the fallback.
+     */
+    export interface BroadcastSchedule extends RetrySchedule.Configuration {
+        /**
+         * Limit this schedule to a particular service kind.
+         */
+        readonly serviceKind?: ServiceDescription["kind"];
+
+        /**
+         * Limit this schedule to initial broadcast or broadcast when reconnecting.
+         */
+        readonly event?: Advertiser.BroadcastEvent;
+
+        /**
+         * Extra time to broadcast after establishing an operational connection.
+         *
+         * Set to zero to terminate broadcast immediately after connection.  If undefined broadcasts will continue until
+         * terminated by {@link timeout} or {@link maximumCount}.
+         */
+        readonly broadcastAfterConnection?: number;
+    }
+
+    /**
+     * Default schedule for automatic broadcast.
+     */
+    export const DefaultBroadcastSchedule: BroadcastSchedule = {
+        // Mandated by MDNS specification
+        initialInterval: 1_000,
+
+        // Maximum commissioning timeout per Matter specification 5.4.2.3.1, although
+        timeout: MAXIMUM_COMMISSIONING_TIMEOUT_S * 1000,
+
+        // Minimum per MDNS specification
+        backoffFactor: 2,
+
+        // Technically this may result in us emitting more than 8 packets which is the maximum per the MDNS
+        // specification but extra packets will only come every 90 seconds
+        maximumInterval: 90_000,
+
+        // Not in any specification AFAIK but common sense to reduce thundering herd
+        jitterFactor: 0.25,
+
+        // Generally operational broadcast is unnecessary once an operational connection is established
+        broadcastAfterConnection: 0,
+    };
+
+    /**
+     * Default schedule for retransmission broadcast.
+     */
+    export const RetransmissionBroadcastSchedule: BroadcastSchedule = {
+        event: "retransmit",
+
+        // Retransmission events occur for every packet retry so limit count to 1
+        maximumCount: 1,
+    };
+
+    /**
+     * Data model for MDNS advertiser configuration.
+     */
+    export const OptionsSchema = new DatatypeModel(
+        { name: "MdnsAdvertiserOptions", type: "struct" },
+        FieldElement({ name: "omitPrivateDetails", type: "bool" }),
+        FieldElement(
+            { name: "schedules", type: "list" },
+            FieldElement(
+                { name: "entry", type: "struct" },
+                FieldElement({ name: "initialInterval", type: "uint32" }),
+                FieldElement({ name: "timeout", type: "uint32" }),
+                FieldElement({ name: "backoffFactor", type: "uint8" }),
+                FieldElement({ name: "maximumInterval", type: "uint32" }),
+                FieldElement({ name: "jitterFactor", type: "single" }),
+                FieldElement({ name: "serviceKind", type: "string" }),
+                FieldElement({ name: "event", type: "string" }),
+            ),
+        ),
+    );
+}

package/src/advertisement/mdns/OperationalMdnsAdvertisement.ts

@@ -0,0 +1,50 @@
+/**
+ * @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 { Bytes, PtrRecord } from "#general";
+import {
+    getFabricQname,
+    getOperationalDeviceQname,
+    MATTER_SERVICE_QNAME,
+    SERVICE_DISCOVERY_QNAME,
+} from "#mdns/MdnsConsts.js";
+import { NodeId } from "#types";
+import { MdnsAdvertisement } from "./MdnsAdvertisement.js";
+import type { MdnsAdvertiser } from "./MdnsAdvertiser.js";
+
+/**
+ * Advertise a node as a fabric member.
+ */
+export class OperationalMdnsAdvertisement extends MdnsAdvertisement<ServiceDescription.Operational> {
+    constructor(advertiser: MdnsAdvertiser, description: ServiceDescription.Operational) {
+        const {
+            fabric: { operationalId, nodeId },
+        } = description;
+
+        const qname = getOperationalDeviceQname(Bytes.toHex(operationalId).toUpperCase(), NodeId.toHexString(nodeId));
+
+        super(advertiser, qname, description);
+    }
+
+    override get ptrRecords() {
+        const operationalIdString = Bytes.toHex(this.description.fabric.operationalId).toUpperCase();
+        const fabricQname = getFabricQname(operationalIdString);
+
+        return [
+            PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_SERVICE_QNAME),
+            PtrRecord(SERVICE_DISCOVERY_QNAME, fabricQname),
+            PtrRecord(MATTER_SERVICE_QNAME, this.qname),
+            PtrRecord(fabricQname, this.qname),
+        ];
+    }
+
+    override isDuplicate(other: Advertisement) {
+        // There may only be one operational advertisement per service per advertiser
+        return other.isOperational() && other.service === this.service;
+    }
+}

package/src/advertisement/mdns/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./CommissionableMdnsAdvertisement.js";
+export * from "./CommissionerMdnsAdvertisement.js";
+export * from "./MdnsAdvertisement.js";
+export * from "./MdnsAdvertiser.js";
+export * from "./OperationalMdnsAdvertisement.js";

package/src/ble/Ble.ts

@@ -5,7 +5,6 @@
  */
 
 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";
 
@@ -23,10 +22,14 @@ export abstract class Ble {
         return this.get !== BleDisabled;
     }
 
-    abstract getBlePeripheralInterface(): TransportInterface;
-    abstract getBleCentralInterface(): NetInterface;
-    abstract getBleBroadcaster(additionalAdvertisementData?: Uint8Array): InstanceBroadcaster;
-    abstract getBleScanner(): Scanner;
+    abstract get peripheralInterface(): BlePeripheralInterface;
+    abstract get centralInterface(): NetInterface;
+    abstract get scanner(): Scanner;
+}
+
+export interface BlePeripheralInterface extends TransportInterface {
+    advertise(advertiseData: Uint8Array, additionalAdvertisementData?: Uint8Array, intervalMs?: number): Promise<void>;
+    stopAdvertising(): Promise<void>;
 }
 
 export abstract class BleChannel<T> implements Channel<T> {

package/src/codec/BtpCodec.ts

@@ -283,6 +283,7 @@ export class BtpCodec {
         vendorId: number,
         productId: number,
         hasAdditionalAdvertisementData = false,
+        isExtendedAnnouncement = false,
     ) {
         const writer = new DataWriter(Endian.Little);
         writer.writeUInt8(0x02);
@@ -293,9 +294,9 @@ export class BtpCodec {
         writer.writeUInt16(0xfff6);
         writer.writeUInt8(0x00);
         writer.writeUInt16(discriminator);
-        writer.writeUInt16(vendorId);
-        writer.writeUInt16(productId);
-        writer.writeUInt8(hasAdditionalAdvertisementData ? 0x01 : 0x00);
+        writer.writeUInt16(isExtendedAnnouncement ? 0 : vendorId);
+        writer.writeUInt16(isExtendedAnnouncement ? 0 : productId);
+        writer.writeUInt8((hasAdditionalAdvertisementData ? 1 : 0) | (isExtendedAnnouncement ? 2 : 0));
         return writer.toByteArray();
     }
 

package/src/common/Scanner.ts

@@ -5,25 +5,9 @@
  */
 
 import { BasicSet, ChannelType, Environment, Environmental, Lifespan, ServerAddress, ServerAddressIp } from "#general";
-import { BitFlag, BitmapSchema, DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
+import { DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
 import { Fabric } from "../fabric/Fabric.js";
 
-export const SupportedTransportsBitmap = {
-    // Bit 0 is reserved
-    /**
-     * TCP Client
-     * The advertising Node implements the TCP Client mode and MAY connect to a peer Node that is a TCP Server.
-     */
-    tcpClient: BitFlag(1),
-
-    /**
-     * TCP Server
-     * The advertising Node implements the TCP Server mode and SHALL listen for incoming TCP connections.
-     */
-    tcpServer: BitFlag(2),
-};
-export const SupportedTransportsSchema = BitmapSchema(SupportedTransportsBitmap);
-
 /**
  * All information exposed by a commissionable device via announcements.
  * The properties are named identical as in the Matter specification.

package/src/common/SupportedTransportsBitmap.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BitFlag, BitmapSchema, TypeFromBitSchema } from "@matter/types";
+
+export const SupportedTransportsBitmap = {
+    // Bit 0 is reserved
+    /**
+     * TCP Client
+     * The advertising Node implements the TCP Client mode and MAY connect to a peer Node that is a TCP Server.
+     */
+    tcpClient: BitFlag(1),
+
+    /**
+     * TCP Server
+     * The advertising Node implements the TCP Server mode and SHALL listen for incoming TCP connections.
+     */
+    tcpServer: BitFlag(2),
+};
+export const SupportedTransportsSchema = BitmapSchema(SupportedTransportsBitmap);
+
+export interface SupportedTransportsBitmap extends TypeFromBitSchema<typeof SupportedTransportsBitmap> {}

package/src/common/index.ts

@@ -8,6 +8,6 @@ export * from "../peer/PeerAddress.js";
 export * from "./ExpandedPath.js";
 export * from "./FailsafeContext.js";
 export * from "./FailsafeTimer.js";
-export * from "./InstanceBroadcaster.js";
 export * from "./OperationalCredentialsTypes.js";
 export * from "./Scanner.js";
+export * from "./SupportedTransportsBitmap.js";

package/src/fabric/Fabric.ts

@@ -214,6 +214,14 @@ export class Fabric {
         this.#sessions.delete(session);
     }
 
+    hasSessionForPeer(peerNodeId: NodeId) {
+        for (const session of this.#sessions) {
+            if (session.peerNodeId === peerNodeId) {
+                return true;
+            }
+        }
+    }
+
     addRemoveCallback(callback: () => MaybePromise<void>) {
         this.#removeCallbacks.push(callback);
     }

package/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "./action/index.js";
+export * from "./advertisement/index.js";
 export * from "./ble/index.js";
 export * from "./certificate/index.js";
 export * from "./cluster/index.js";