@matter/node 0.16.0-alpha.0-20251006-3fe1e7c57 → 0.16.0-alpha.0-20251013-89bb7099d

package/src/behavior/system/mqtt/MqttInterface.ts

@@ -0,0 +1,414 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Abort,
+    asJson,
+    Base64,
+    Bytes,
+    decamelize,
+    InternalError,
+    MqttEndpoint,
+    MqttService,
+    Mutex,
+    NotImplementedError,
+} from "#general";
+import { any, CommandModel, Metatype, Schema } from "#model";
+import { StateStream } from "#node/integration/StateStream.js";
+import { StatusResponse } from "#types";
+import { Api } from "../remote/api/Api.js";
+import { ApiPath } from "../remote/api/ApiPath.js";
+import { Envelope } from "../remote/api/Envelope.js";
+import { LocalResponse } from "../remote/api/LocalResponse.js";
+import type { RemoteRequest } from "../remote/api/RemoteRequest.js";
+import { RemoteResponse } from "../remote/api/RemoteResponse.js";
+import { RemoteInterface } from "../remote/RemoteInterface.js";
+
+const LOG_FACILITY = "MQTT";
+
+/**
+ * MQTT remote interface.
+ *
+ * Currently publishes a read-only feed.  Will address TODOs if there is real-world use.
+ *
+ * TODO - events
+ * TODO - clean out topics from previous runs that are no longer relevant, e.g. deleted endpoint, removed attrs, etc.
+ * TODO - TLV serialiation/deserialization
+ */
+export class MqttInterface extends RemoteInterface {
+    static override protocol = "mqtt";
+
+    #endpoint?: MqttEndpoint;
+    #mutex = new Mutex(this);
+    #retainedTopics = new Map<string, Map<number, Set<string>>>();
+
+    protected override async start() {
+        this.#endpoint = await this.env.get(MqttService).connect({
+            address: this.address,
+            environment: this.node.env,
+
+            will: {
+                topic: this.root.at("status").toString(),
+                payload: "offline",
+            },
+
+            onUp: endpoint => {
+                if (!this.#endpoint) {
+                    this.#endpoint = endpoint;
+                }
+
+                return this.#publish({
+                    topic: this.root.at("status").toString(),
+                    payload: "online",
+                });
+            },
+        });
+
+        this.addWorker(this.#listen(), "mqtt listener");
+        this.addWorker(this.#feed(), "mqtt feeder");
+    }
+
+    protected override async stop() {
+        await this.#mutex.then();
+        await this.#mqtt?.close();
+    }
+
+    /**
+     * A background process that handles incoming MQTT messages.
+     */
+    async #listen() {
+        await Abort.race(this.abort, this.node.construction);
+        if (Abort.is(this.abort)) {
+            return;
+        }
+
+        let topic = this.root.toString();
+        if (topic !== "") {
+            topic += "/#";
+        } else {
+            topic = "#";
+        }
+
+        for await (const message of this.#mqtt.subscribe(`${topic}`, { noLocal: true, abort: this.abort })) {
+            // We publish retained messages so ignore these; if not retained it's a write or invoke
+            if (message.retain) {
+                continue;
+            }
+
+            // This should always be true but make sure
+            const relativeTopic = this.root.subpathFor(new ApiPath(message.topic));
+            if (!relativeTopic) {
+                continue;
+            }
+
+            await this.#respond(relativeTopic, message);
+        }
+    }
+
+    async #respond(topic: ApiPath, message: MqttEndpoint.Message) {
+        let response: LocalResponse | undefined;
+
+        const via = message.correlationData ? Bytes.toHex(message.correlationData) : message.responseTopic;
+
+        try {
+            await this.node.act("MQTT listener", async agent => {
+                // Specialized topic "call" is for RPC messaging using RemoteRequest/RemoteResponse
+                if (topic.toString() === "call") {
+                    response = await this.#call(message);
+                    return;
+                }
+
+                const resource = await Api.resourceFor(agent, topic);
+                if (resource === undefined) {
+                    throw new StatusResponse.NotFoundError(`No resource at subtopic ${topic}`);
+                }
+
+                const schema = resource.schema;
+                if (!schema) {
+                    throw new NotImplementedError();
+                }
+                const input = payloadToJs(schema, message.payload);
+
+                if (resource.isInvocable) {
+                    Api.logRequest(LOG_FACILITY, via, "invoke", topic.toString());
+
+                    let value = await resource.invoke({ js: input });
+
+                    const responseSchema = (schema as CommandModel).responseModel;
+                    if (responseSchema) {
+                        value ??= new Envelope({ supervisor: resource.supervisorFor(responseSchema), js: null });
+                        response = { kind: "value", value };
+                    }
+                } else {
+                    Api.logRequest(LOG_FACILITY, via, "update", topic.toString());
+
+                    await resource.patch(input ?? { js: null });
+                }
+            });
+        } catch (e) {
+            response = Api.errorResponseOf(LOG_FACILITY, via, e);
+        }
+
+        if (!response) {
+            response = { kind: "ok" };
+        }
+
+        response.id = via;
+        Api.logResponse(LOG_FACILITY, RemoteResponse(response));
+
+        if (message.responseTopic) {
+            await this.#publish({
+                topic: message.responseTopic,
+                correlationData: message.correlationData,
+                payload: asJson(response),
+            });
+        }
+    }
+
+    /**
+     * Specialized handling for "call" topic to support full {@link RemoteRequest}/{@link RemoteResponse} interaction.
+     */
+    async #call(message: MqttEndpoint.Message) {
+        const request = parseJsonPayload(message.payload);
+        const response = await Api.execute(LOG_FACILITY, this.node, request, this.abort);
+
+        // I don't think there's any point in supporting subscriptions when MQTT offers a superior mechanism, so for now
+        // just throw if this is attempted
+        if (response.kind === "subscription") {
+            await response.stream.return?.();
+            throw new StatusResponse.InvalidSubscriptionError(
+                "Subscription via RPC is not supported, use MQTT instead",
+            );
+        }
+
+        return response;
+    }
+
+    /**
+     * A background process that continuously updates MQTT topics.
+     */
+    async #feed() {
+        const stream = StateStream(this.node, { abort: this.abort });
+
+        for await (const change of stream) {
+            await this.#mutex.produce(async () => {
+                switch (change.kind) {
+                    case "update":
+                        await this.#publishUpdate(change);
+                        break;
+
+                    case "delete":
+                        await this.#publishDelete(change);
+                }
+            });
+        }
+    }
+
+    /**
+     * Publish attribute values for state changes.
+     */
+    async #publishUpdate({ node, endpoint, behavior, changes }: StateStream.Update) {
+        let nodeTopics = this.#retainedTopics.get(node.id);
+        if (nodeTopics === undefined) {
+            this.#retainedTopics.set(node.id, (nodeTopics = new Map()));
+        }
+        let endpointTopics = nodeTopics.get(endpoint.number);
+        if (endpointTopics === undefined) {
+            nodeTopics.set(endpoint.number, (endpointTopics = new Set()));
+        }
+
+        const behaviorRoot = this.#nodeRoot(node.id).at([endpoint.number.toString(), decamelize(behavior.id)]);
+        for (const name in changes) {
+            const value = changes[name];
+            const schema = behavior.schema?.conformant.properties.for(name);
+            const payload = jsToPayload(schema ?? any, value);
+
+            const topic = behaviorRoot.at([name]).toString();
+            endpointTopics.add(topic);
+
+            await this.#publish({
+                topic,
+                payload,
+                retain: true,
+            });
+        }
+    }
+
+    /**
+     * Delete all published topics for an endpoint or node that has disappeared.
+     */
+    async #publishDelete(change: StateStream.Delete) {
+        const nodeTopics = this.#retainedTopics.get(change.node.id);
+        if (!nodeTopics) {
+            return;
+        }
+
+        const deleteEndpoint = async (endpoint: number) => {
+            const topics = nodeTopics.get(endpoint);
+            if (!topics) {
+                return;
+            }
+
+            for (const topic of topics) {
+                await this.#publish({
+                    topic,
+                    payload: null,
+                    retain: true,
+                });
+            }
+
+            nodeTopics.delete(endpoint);
+        };
+
+        if (change.endpoint === change.node) {
+            for (const number of nodeTopics.keys()) {
+                await deleteEndpoint(number);
+            }
+            this.#retainedTopics.delete(change.node.id);
+        } else {
+            await deleteEndpoint(change.endpoint.number);
+        }
+    }
+
+    /**
+     * Obtain the root path for a node.
+     *
+     * This will either be the root path for the server or a subpath for peers.
+     */
+    #nodeRoot(id: string) {
+        if (id === this.node.id) {
+            return this.root;
+        }
+
+        return this.root.at(["peers", id]);
+    }
+
+    /**
+     * Safe access to the MQTT endpoint.
+     */
+    get #mqtt() {
+        if (this.#endpoint === undefined) {
+            throw new InternalError("MQTT endpoint missing");
+        }
+        return this.#endpoint;
+    }
+
+    /**
+     * Publish a message.
+     *
+     * Default QOS is 2.
+     */
+    #publish(message: MqttEndpoint.Message) {
+        if (this.abort.aborted) {
+            throw new InternalError("MQTT publish after abort");
+        }
+        if (message.qos === undefined) {
+            message.qos = 2;
+        }
+        return this.#mqtt.publish(message);
+    }
+}
+
+function payloadToJs(schema: Schema, payload: Bytes | string | null): unknown {
+    if (payload === null) {
+        return null;
+    }
+
+    const length = typeof payload === "string" ? payload.length : payload.byteLength;
+    if (!length) {
+        return null;
+    }
+
+    let js;
+    switch (schema.effectiveMetatype) {
+        case Metatype.any:
+            js = payload;
+            break;
+
+        case Metatype.object:
+        case Metatype.array:
+        case Metatype.bitmap:
+            js = parseJsonPayload(payload);
+            break;
+
+        case Metatype.bytes:
+            if (typeof payload === "string") {
+                try {
+                    js = Base64.decode(payload);
+                } catch (e) {
+                    if (e instanceof SyntaxError) {
+                        throw new StatusResponse.InvalidDataTypeError(
+                            `Value is not binary or a base64 string: ${e.message}`,
+                        );
+                    }
+                }
+                break;
+            }
+
+            js = payload;
+            break;
+
+        default:
+            if (Bytes.isBytes(payload)) {
+                try {
+                    payload = Bytes.toString(payload);
+                } catch (e) {
+                    if (e instanceof TypeError) {
+                        throw new StatusResponse.InvalidDataTypeError(
+                            `Value is not a valid UTF-8 string: ${e.message}`,
+                        );
+                    }
+                }
+            }
+            js = payload;
+            break;
+    }
+
+    return js;
+}
+
+function jsToPayload(schema: Schema, js: unknown): Bytes | string {
+    if (js === undefined || js === null || js === "") {
+        return Bytes.empty;
+    }
+
+    switch (schema.effectiveMetatype) {
+        case Metatype.object:
+        case Metatype.array:
+        case Metatype.bitmap:
+            // TODO - serialize bitmap as number?
+            return asJson(js);
+
+        case Metatype.bytes:
+            if (Bytes.isBytes(js)) {
+                return js;
+            }
+            return Bytes.fromString(js.toString());
+
+        default:
+            if (Bytes.isBytes(js)) {
+                return js;
+            }
+            return js.toString();
+    }
+}
+
+function parseJsonPayload(payload: MqttEndpoint.Message["payload"]) {
+    if (payload === null) {
+        throw new StatusResponse.InvalidDataTypeError("Empty payload where JSON expected");
+    }
+    if (Bytes.isBytes(payload)) {
+        payload = Bytes.toString(payload);
+    }
+    try {
+        return JSON.parse(payload);
+    } catch (e) {
+        if (e instanceof SyntaxError) {
+            throw new StatusResponse.InvalidDataTypeError(`Payload is not valid JSON: ${e.message}`);
+        }
+        throw e;
+    }
+}

package/src/behavior/system/mqtt/MqttServer.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { RemoteServer } from "../remote/RemoteServer.js";
+import { MqttInterface } from "./MqttInterface.js";
+
+/**
+ * Allows control of a Matter node via an MQTT broker.
+ *
+ * The broker must support MQTT version 5.
+ */
+export class MqttServer extends RemoteServer {
+    static override readonly id = "mqtt";
+    static override readonly interfaceType = MqttInterface;
+}
+
+export namespace MqttServer {
+    export class State extends RemoteServer.State {
+        /**
+         * The MQTT broker address.
+         *
+         * Supported protocols:
+         *
+         *   - mqtt
+         *   - mqtts
+         *   - mqtt+ws (MQTT over web sockets)
+         *   - mqtt+wss
+         *   - mqtt+unix (MQTT over UNIX socket)
+         *   - mqtts+unix
+         *
+         * If present, the path portion of the address adds a prefix to the topics registered by the server.
+         */
+        override address = "mqtt:localhost/matter/{node}";
+    }
+}

package/src/behavior/system/mqtt/index.ts

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

package/src/behavior/system/network/NetworkClient.ts

@@ -4,9 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { RemoteDescriptor } from "#behavior/system/commissioning/RemoteDescriptor.js";
+import { ImplementationError, Observable, ServerAddress, ServerAddressUdp } from "#general";
 import { DatatypeModel, FieldElement } from "#model";
+import type { ClientNode } from "#node/ClientNode.js";
 import { Node } from "#node/Node.js";
-import { DEFAULT_MIN_INTERVAL_FLOOR, Subscribe } from "#protocol";
+import { ClientInteraction, DEFAULT_MIN_INTERVAL_FLOOR, PeerSet, Subscribe } from "#protocol";
 import { CaseAuthenticatedTag } from "#types";
 import { ClientNetworkRuntime } from "./ClientNetworkRuntime.js";
 import { NetworkBehavior } from "./NetworkBehavior.js";
@@ -14,33 +17,97 @@ import { NetworkBehavior } from "./NetworkBehavior.js";
 export class NetworkClient extends NetworkBehavior {
     declare internal: NetworkClient.Internal;
     declare state: NetworkClient.State;
+    declare events: NetworkClient.Events;
+
+    override initialize() {
+        this.reactTo(this.events.autoSubscribe$Changed, this.#handleSubscription);
+        this.reactTo(this.events.defaultSubscription$Changed, this.#handleChangedDefaultSubscription);
+    }
 
     override async startup() {
-        const { startupSubscription, isDisabled } = this.state;
+        const peerAddress = this.#node.state.commissioning.peerAddress;
+        if (peerAddress !== undefined) {
+            const peerSet = this.env.get(PeerSet);
+            if (!peerSet.has(peerAddress)) {
+                const udpAddresses = this.#node.state.commissioning.addresses?.filter(a => a.type === "udp") ?? [];
+                if (udpAddresses.length) {
+                    const latestUdpAddress = ServerAddress(udpAddresses[udpAddresses.length - 1]) as ServerAddressUdp;
+                    // Make sure the PeerSet knows about this peer now too
+                    await peerSet.addKnownPeer(
+                        peerAddress,
+                        latestUdpAddress,
+                        RemoteDescriptor.fromLongForm(this.#node.state.commissioning),
+                    );
+                }
+            }
+        }
+
+        await this.#handleSubscription();
+    }
 
-        if (startupSubscription === null || isDisabled) {
+    /**
+     * Manually activate the subscription for the node, if not already active. This will fail if the node is disabled.
+     *
+     * If you want to disable subscription, set the isDisabled state to true or set autoSubscribe to false.
+     */
+    subscribe() {
+        if (this.state.isDisabled) {
+            throw new ImplementationError("Cannot subscribe when node is disabled");
+        }
+        return this.#handleSubscription(true);
+    }
+
+    async #handleChangedDefaultSubscription() {
+        if (!this.internal.subscriptionActivated) {
+            return;
+        }
+
+        // Restart the subscription with the new parameters
+        await this.#handleSubscription(false);
+        await this.#handleSubscription(true);
+    }
+
+    async #handleSubscription(desiredState = this.state.autoSubscribe) {
+        const { isDisabled } = this.state;
+        const subscriptionDesired = desiredState && !isDisabled;
+
+        if (subscriptionDesired === this.internal.subscriptionActivated) {
             return;
         }
 
-        // TODO - configure subscription based on physical device properties
-        const subscribe = Subscribe({
-            fabricFilter: true,
-            minIntervalFloor: DEFAULT_MIN_INTERVAL_FLOOR,
-            maxIntervalCeiling: 0,
-            attributes: [{}],
-            events: [{ isUrgent: true }],
-            ...startupSubscription,
-        });
-
-        // First, read.  This allows us to retrieve attributes that do not support subscription
-        for await (const _chunk of this.#node.interaction.read(subscribe));
-
-        // Now subscribe for subsequent updates
-        await this.#node.interaction.subscribe(subscribe);
+        if (subscriptionDesired) {
+            // TODO - configure subscription min/max timing based on physical device properties
+            // TODO run whole process including reconnections in a "mutex" like process
+            const subscribe = Subscribe({
+                fabricFilter: true,
+                minIntervalFloor: DEFAULT_MIN_INTERVAL_FLOOR,
+                maxIntervalCeiling: 0,
+                attributes: [{}],
+                events: [{ isUrgent: true }],
+                ...this.state.defaultSubscription,
+            });
+
+            // First, read.  This allows us to retrieve attributes that do not support subscription
+            for await (const _chunk of this.#node.interaction.read(subscribe));
+
+            // Now subscribe for subsequent updates
+            const { subscriptionId } = await this.#node.interaction.subscribe(subscribe);
+
+            this.internal.subscriptionActivated = true;
+            this.internal.defaultSubscriptionId = subscriptionId;
+        } else {
+            if (this.internal.defaultSubscriptionId !== undefined) {
+                (this.#node.interaction as ClientInteraction).subscriptions
+                    .get(this.internal.defaultSubscriptionId)
+                    ?.close();
+                this.internal.defaultSubscriptionId = undefined;
+            }
+            this.internal.subscriptionActivated = false;
+        }
     }
 
     get #node() {
-        return this.env.get(Node);
+        return this.env.get(Node) as ClientNode;
     }
 
     /**
@@ -52,16 +119,25 @@ export class NetworkClient extends NetworkBehavior {
 
         children: [
             FieldElement({
-                name: "startupSubscription",
+                name: "defaultSubscription",
                 type: "any",
                 default: { type: "properties", properties: {} },
-                quality: "XN",
+                conformance: "O",
+                quality: "N",
             }),
 
             FieldElement({
                 name: "isDisabled",
                 type: "bool",
                 quality: "N",
+                default: false,
+            }),
+
+            FieldElement({
+                name: "autoSubscribe",
+                type: "bool",
+                quality: "N",
+                default: false,
             }),
 
             FieldElement({
@@ -83,24 +159,43 @@ export class NetworkClient extends NetworkBehavior {
 export namespace NetworkClient {
     export class Internal extends NetworkBehavior.Internal {
         declare runtime?: ClientNetworkRuntime;
+
+        /**
+         * Contains the subscription target state.  It will also be true if a subscription is in the process of being
+         * established, or we wait for the node to be rediscovered.
+         */
+        subscriptionActivated = false;
+
+        /** The ID of the current active default subscription, if any */
+        defaultSubscriptionId?: number;
     }
 
     export class State extends NetworkBehavior.State {
         /**
-         * A subscription installed when the node is first commissioned and when the service is restarted.
+         * This subscription defines the default set of attributes and events to which the node will automatically
+         * subscribe when started, if autoSubscribe is true.
          *
          * The default subscription is a wildcard for all attributes of the node.  You can set to undefined or filter
          * the fields and values but only values selected by this subscription will update automatically.
          *
          * Set to null to disable automatic subscription.
          */
-        startupSubscription?: Subscribe | null;
+        defaultSubscription?: Subscribe;
 
         /**
-         * If true, the matter.js will not perform network communication with the node.
+         * Represents the current operational network state of the node. When true the node is enabled and operational.
+         * When false the node is disabled and not operational.
+         *
+         * This state can be changed at any time to enable or disable the node.
          */
         isDisabled = false;
 
+        /**
+         * If true, automatically subscribe to the provided default subscription (or all attributes and events) when
+         * the node is started. If false, do not automatically subscribe.
+         */
+        autoSubscribe = false;
+
         /**
          * Case Authenticated Tags (CATs) to use for operational CASE sessions with this node.
          *
@@ -110,4 +205,9 @@ export namespace NetworkClient {
          */
         caseAuthenticatedTags?: CaseAuthenticatedTag[];
     }
+
+    export class Events extends NetworkBehavior.Events {
+        autoSubscribe$Changed = new Observable<[value: boolean, oldValue: boolean]>();
+        defaultSubscription$Changed = new Observable<[value: Subscribe | undefined, oldValue: Subscribe | undefined]>();
+    }
 }