@matter-server/ws-controller 0.2.0-alpha.0-00000000-000000000

package/src/example/send-command.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Simple CLI script to send a command via WebSocket and log responses.
+ *
+ * Usage: npx ts-node send-command.ts <url> <command> [args-json]
+ *
+ * Example:
+ *   npx ts-node send-command.ts ws://localhost:5580/ws server_info
+ *   npx ts-node send-command.ts ws://localhost:5580/ws get_node '{"node_id": 1}'
+ */
+
+import WebSocket from "ws";
+
+const [, , url, command, argsJson] = process.argv;
+
+if (!url || !command) {
+    console.error("Usage: send-command <url> <command> [args-json]");
+    console.error("");
+    console.error("Examples:");
+    console.error("  npx ts-node send-command.ts ws://localhost:5580/ws server_info");
+    console.error("  npx ts-node send-command.ts ws://localhost:5580/ws get_node '{\"node_id\": 1}'");
+    console.error("  npx ts-node send-command.ts ws://localhost:5580/ws start_listening");
+    process.exit(1);
+}
+
+let args: unknown = undefined;
+if (argsJson) {
+    try {
+        args = JSON.parse(argsJson);
+    } catch (e) {
+        console.error("Error parsing args JSON:", (e as Error).message);
+        process.exit(1);
+    }
+}
+
+console.log(`Connecting to ${url}...`);
+
+const ws = new WebSocket(url);
+
+ws.on("open", () => {
+    console.log("Connected!");
+
+    const message = {
+        message_id: `cmd-${Date.now()}`,
+        command,
+        ...(args !== undefined && { args }),
+    };
+
+    console.log("Sending:", JSON.stringify(message, null, 2));
+    ws.send(JSON.stringify(message));
+});
+
+ws.on("message", (data: WebSocket.Data) => {
+    try {
+        const parsed = JSON.parse(data.toString());
+        console.log("\n--- Received ---");
+        console.log(JSON.stringify(parsed, null, 2));
+    } catch {
+        console.log("\n--- Received (raw) ---");
+        console.log(data.toString());
+    }
+});
+
+ws.on("error", (error: Error) => {
+    console.error("WebSocket error:", error.message);
+});
+
+ws.on("close", (code: number, reason: Buffer) => {
+    console.log(`\nDisconnected (code: ${code}, reason: ${reason.toString() || "none"})`);
+    process.exit(0);
+});
+
+// Handle Ctrl+C gracefully
+process.on("SIGINT", () => {
+    console.log("\nClosing connection...");
+    ws.close();
+});

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @matter-server/ws-controller - Matter controller Websocket library
+ */
+
+// Export controller components
+export * from "./controller/ControllerCommandHandler.js";
+export * from "./controller/LegacyDataInjector.js";
+export * from "./controller/MatterController.js";
+
+// Export model
+export * from "./model/ModelMapper.js";
+
+// Export server handlers and types
+export * from "./server/ConfigStorage.js";
+export * from "./server/Converters.js";
+export * from "./server/WebSocketControllerHandler.js";
+export * from "./types/WebServer.js";
+
+// Export message types
+export * from "./types/CommandHandler.js";
+export * from "./types/WebSocketMessageTypes.js";
+
+// Export utilities
+export * from "./util/matterVersion.js";
+
+// Re-Export classes from matter.js
+export { Crypto, Environment, LogDestination, LogFormat, LogLevel, Logger } from "@matter/main";

package/src/model/ModelMapper.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterId } from "@matter/main";
+import {
+    AcceptedCommandList,
+    AttributeList,
+    AttributeModel,
+    ClusterModel,
+    ClusterRevision,
+    CommandModel,
+    EventModel,
+    FeatureMap,
+    GeneratedCommandList,
+    MatterModel,
+} from "@matter/model";
+
+type AttributeDetails = { readonly [key: string]: AttributeModel | undefined };
+
+/** Metadata for Global attributes */
+export const GlobalAttributes: AttributeDetails = Object.freeze({
+    clusterRevision: ClusterRevision,
+    featureMap: FeatureMap,
+    attributeList: AttributeList,
+    acceptedCommandList: AcceptedCommandList,
+    generatedCommandList: GeneratedCommandList,
+});
+
+/**
+ * Metadata for all clusters collected in an optimized form for direct access with the incoming websocket requests.
+ * All names are just lowercased to prevent differences in camelize and decamelize handling.
+ */
+export type ClusterMapEntry = {
+    readonly clusterId: ClusterId;
+    readonly model: ClusterModel;
+    readonly commands: { readonly [key: string]: CommandModel | undefined };
+    readonly attributes: AttributeDetails;
+    readonly events: { readonly [key: string]: EventModel | undefined };
+};
+
+export type ClusterMapType = {
+    readonly [key: string]: ClusterMapEntry | undefined;
+};
+
+// Build the cluster map at module load time
+const clusterMapBuilder: { [key: string]: ClusterMapEntry | undefined } = {};
+
+MatterModel.standard.clusters.forEach(cluster => {
+    if (cluster.id === undefined) {
+        return;
+    } // Skip clusters without an ID
+    const aces = cluster.allAces;
+    const commands: { [key: string]: CommandModel | undefined } = {};
+    const attributes: { [key: string]: AttributeModel | undefined } = {};
+    const events: { [key: string]: EventModel | undefined } = {};
+
+    aces.forEach(ace => {
+        const name = ace.name.toLowerCase();
+        if (ace instanceof CommandModel) {
+            commands[name] = ace;
+            commands[ace.id] = ace;
+        } else if (ace instanceof AttributeModel) {
+            attributes[name] = ace;
+            attributes[ace.id] = ace;
+        } else if (ace instanceof EventModel) {
+            events[name] = ace;
+            events[ace.id] = ace;
+        }
+    });
+
+    const clusterData: ClusterMapEntry = Object.freeze({
+        clusterId: ClusterId(cluster.id),
+        model: cluster,
+        commands: Object.freeze(commands),
+        attributes: Object.freeze(attributes),
+        events: Object.freeze(events),
+    });
+
+    clusterMapBuilder[cluster.name.toLowerCase()] = clusterData;
+    clusterMapBuilder[cluster.id] = clusterData;
+});
+
+/** Readonly map of all clusters frozen after initialization */
+export const ClusterMap: ClusterMapType = Object.freeze(clusterMapBuilder);

package/src/server/ConfigStorage.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment, Logger, StorageContext, StorageManager, StorageService } from "@matter/main";
+
+const logger = new Logger("ConfigStorage");
+
+interface ConfigData {
+    fabricLabel: string;
+    nextNodeId: number; // formally wrong, should be bigint
+    wifiSsid?: string;
+    wifiCredentials?: string;
+    threadDataset?: string;
+}
+
+export class ConfigStorage {
+    #env: Environment;
+    #storageService?: StorageService;
+    #storage?: StorageManager;
+    #configStore?: StorageContext;
+    readonly #data: ConfigData = {
+        nextNodeId: 2, // 2 because controller is Node Id 1
+        fabricLabel: "HomeAssistant",
+        wifiSsid: undefined,
+        wifiCredentials: undefined,
+        threadDataset: undefined,
+    };
+
+    static async create(env: Environment) {
+        const instance = new ConfigStorage(env);
+        await instance.open();
+        return instance;
+    }
+
+    constructor(env: Environment) {
+        this.#env = env;
+    }
+
+    get service() {
+        if (this.#storageService === undefined) {
+            throw new Error("Storage not open");
+        }
+        return this.#storageService;
+    }
+
+    async open() {
+        this.#storageService = this.#env.get(StorageService);
+        // Use the parameter "--storage-path=NAME-OR-PATH" to specify a different storage location
+        // in this directory, use --storage-clear to start with an empty storage.
+        // Or Env vars like MATTER_STORAGE_PATH and MATTER_STORAGE_CLEAR
+        logger.info(`Storage location: ${this.#storageService.location} (Directory)`);
+        this.#storage = await this.#storageService.open("config");
+        this.#configStore = this.#storage.createContext("values");
+
+        const fabricLabel = (await this.#configStore.has("fabricLabel"))
+            ? await this.#configStore.get<string>("fabricLabel")
+            : (this.#env.vars.string("fabricLabel") ?? this.#data.fabricLabel);
+        const nextNodeId = await this.#configStore.get<number>("nextNodeId", this.#data.nextNodeId);
+
+        const wifiSsid = (await this.#configStore.has("wifiSsid"))
+            ? await this.#configStore.get<string>("wifiSsid", "")
+            : undefined;
+        const wifiCredentials = (await this.#configStore.has("wifiCredentials"))
+            ? await this.#configStore.get<string>("wifiCredentials", "")
+            : undefined;
+        const threadDataset = (await this.#configStore.has("threadDataset"))
+            ? await this.#configStore.get<string>("threadDataset", "")
+            : undefined;
+        await this.set({ fabricLabel, nextNodeId, wifiSsid, wifiCredentials, threadDataset });
+    }
+
+    get fabricLabel() {
+        return this.#data.fabricLabel;
+    }
+    get nextNodeId() {
+        return this.#data.nextNodeId;
+    }
+    get wifiSsid() {
+        return this.#data.wifiSsid;
+    }
+    get wifiCredentials() {
+        return this.#data.wifiCredentials;
+    }
+    get threadDataset() {
+        return this.#data.threadDataset;
+    }
+
+    async set(data: Partial<ConfigData>) {
+        if (!this.#configStore) {
+            throw new Error("Storage not open");
+        }
+
+        for (const key of Object.keys(data)) {
+            if (!(key in this.#data)) {
+                throw new Error(`Invalid key: ${key}`);
+            }
+            // @ts-expect-error key is a valid key and TS make sure about the type
+            this.#data[key] = data[key];
+            logger.info(`Set config key ${key} to ${data[key as keyof ConfigData]}`);
+            await this.#configStore.set(key, data[key as keyof ConfigData]);
+        }
+    }
+
+    async close() {
+        if (this.#storage) {
+            await this.#storage.close();
+        }
+    }
+}