@project-chip/matter-node.js-examples 0.11.0-alpha.0-20240911-db8f7c80 → 0.11.0-alpha.0-20241007-547af42a8

package/src/examples/IlluminatedRollerShade.ts

@@ -1,96 +0,0 @@
-#!/usr/bin/env node
-/**
- * @license
- * Copyright 2022-2024 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import "@project-chip/matter.js-nodejs";
-
-import {
-    MovementDirection,
-    MovementType,
-    WindowCoveringServer,
-} from "@project-chip/matter.js/behaviors/window-covering";
-import { OnOffLightDevice, OnOffLightRequirements } from "@project-chip/matter.js/devices/OnOffLightDevice";
-import { WindowCoveringDevice } from "@project-chip/matter.js/devices/WindowCoveringDevice";
-import { ServerNode } from "@project-chip/matter.js/node";
-
-/**
- * This example demonstrates implementation of a "composed" device comprising multiple sub-devices
- *
- * Our example device, the Excelsior 1000 EZ-Nite™, is a roller shade with an illuminated valance.
- */
-
-const LiftingWindowCoveringServer = WindowCoveringServer.with("Lift", "AbsolutePosition", "PositionAwareLift");
-
-/**
- * Implementation of the Matter WindowCovering cluster for the shade motor.
- */
-class RollerShade extends LiftingWindowCoveringServer {
-    override async handleMovement(
-        type: MovementType,
-        reversed: boolean,
-        direction: MovementDirection,
-        targetPercent100ths?: number,
-    ) {
-        console.log(
-            "Move window shade",
-            direction === MovementDirection.Open ? "Open" : "Close",
-            targetPercent100ths !== undefined ? `${targetPercent100ths / 100}%` : "",
-        );
-
-        // Updates the shade position
-        await super.handleMovement(type, reversed, direction, targetPercent100ths);
-    }
-}
-
-/**
- * Implementation of the OnOff cluster for our valance light.
- */
-class ValanceLight extends OnOffLightRequirements.OnOffServer {
-    override initialize() {
-        this.reactTo(this.events.onOff$Changed, this.#stateChanged);
-    }
-
-    #stateChanged(value: boolean) {
-        console.log(`Valance is now ${value ? "illuminated" : "dark"}`);
-    }
-}
-
-/**
- * Our Matter node.
- */
-const node = new ServerNode({
-    id: "excelsior1000",
-
-    productDescription: {},
-
-    commissioning: {
-        passcode: 20202021,
-        discriminator: 3840,
-    },
-
-    basicInformation: {
-        vendorName: "Acme Corporation",
-        productName: "Excelsior 1000 EZ-Nite™",
-        vendorId: 0xfff1,
-        productId: 0x8000,
-        serialNumber: "1234-12345-123",
-    },
-
-    parts: [
-        {
-            type: WindowCoveringDevice.with(RollerShade),
-            id: "shade",
-        },
-
-        {
-            type: OnOffLightDevice.with(ValanceLight),
-            id: "valance",
-        },
-    ],
-});
-
-await node.run();

package/src/examples/LightDevice.ts

@@ -1,61 +0,0 @@
-#!/usr/bin/env node
-/**
- * @license
- * Copyright 2022-2024 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-// This demonstrates bringing a "light" device online with matter.js.
-
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import "@project-chip/matter.js-nodejs";
-
-import { OnOffLightDevice, OnOffLightRequirements } from "@project-chip/matter.js/devices/OnOffLightDevice";
-import { ServerNode } from "@project-chip/matter.js/node";
-
-// Matter exposes functionality in groups called "clusters".  For this example device we override the matter.js "On/Off"
-// cluster implementation to print status to the console.
-class ReportingOnOffServer extends OnOffLightRequirements.OnOffServer {
-    // Intercept the "on" command to the Matter On/Off cluster to print a log message.
-    override async on() {
-        console.log("Turning light ON");
-        await super.on();
-    }
-
-    // This is the functional inverse of on() above.
-    //
-    // For demonstration purposes we update state ourselves rather than deferring to matter.js's default "off" handler
-    // via super.off().
-    override off() {
-        console.log("Turning light OFF");
-        this.state.onOff = false;
-    }
-
-    // Use event handlers to log on/off state reactively, after it changes.
-    override initialize() {
-        this.events.onOff$Changed.on(value => {
-            console.log(`Light is now ${value ? "ON" : "OFF"}`);
-        });
-    }
-}
-
-// Devices are compositions of behaviors like OnOffServer above.  To extend an existing device you use builder methods.
-//
-// In this case we are using with() to install our On/Off cluster behavior.
-const ExampleLight = OnOffLightDevice.with(ReportingOnOffServer);
-
-// Physical devices appear as "nodes" on a Matter network.  As a device implementer you use a NodeServer to bring a
-// device online.
-//
-// Note there are a large number of options to NodeServer that we are allowing to take default values here.  See
-// IlluminatedRollerShade.ts for a more detailed example.
-const node = await ServerNode.create();
-
-// Nodes are a composition of endpoints.  Add a single endpoint to the node, our example light device.
-await node.add(ExampleLight);
-
-// Our device is now built and we can bring the node online.
-//
-// Note that you may serve multiple nodes from a single process.  We only have one, however, so we can use the run()
-// method of the node.
-await node.run();

package/src/examples/MultiDeviceNode.ts

@@ -1,208 +0,0 @@
-#!/usr/bin/env node
-/**
- * @license
- * Copyright 2022-2024 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * This example shows how to create a new device node that is composed of multiple devices.
- * It creates multiple endpoints on the server. For information on how to add a composed device to a bridge please
- * refer to the bridge example!
- * It can be used as CLI script and starting point for your own device node implementation.
- */
-
-/**
- * Import needed modules from @project-chip/matter-node.js
- */
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import { requireMinNodeVersion } from "@project-chip/matter.js-nodejs";
-
-import { Time } from "@project-chip/matter.js-general";
-import { DeviceTypeId, VendorId } from "@project-chip/matter.js/datatype";
-import { logEndpoint } from "@project-chip/matter.js/device";
-import { OnOffLightDevice } from "@project-chip/matter.js/devices/OnOffLightDevice";
-import { OnOffPlugInUnitDevice } from "@project-chip/matter.js/devices/OnOffPlugInUnitDevice";
-import { Endpoint, EndpointServer } from "@project-chip/matter.js/endpoint";
-import { Environment, StorageService } from "@project-chip/matter.js/environment";
-import { ServerNode } from "@project-chip/matter.js/node";
-import { execSync } from "child_process";
-
-requireMinNodeVersion(16);
-
-const devices = await getConfiguration();
-for (let idx = 1; idx < devices.length; idx++) {
-    const {
-        isSocket,
-        deviceName,
-        vendorName,
-        passcode,
-        discriminator,
-        vendorId,
-        productName,
-        productId,
-        port,
-        uniqueId,
-    } = devices[idx];
-    const i = idx + 1;
-
-    /**
-     * Create a Matter ServerNode, which contains the Root Endpoint and all relevant data and configuration
-     */
-    const server = await ServerNode.create({
-        // Required: Give the Node a unique ID which is used to store the state of this node
-        id: uniqueId,
-
-        // Provide Network relevant configuration like the port
-        // Optional when operating only one device on a host, Default port is 5540
-        network: {
-            port,
-        },
-
-        // Provide Commissioning relevant settings
-        // Optional for development/testing purposes
-        commissioning: {
-            passcode,
-            discriminator,
-        },
-
-        // Provide Node announcement settings
-        // Optional: If Ommitted some development defaults are used
-        productDescription: {
-            name: deviceName,
-            deviceType: DeviceTypeId(isSocket ? OnOffPlugInUnitDevice.deviceType : OnOffLightDevice.deviceType),
-        },
-
-        // Provide defaults for the BasicInformation cluster on the Root endpoint
-        // Optional: If Omitted some development defaults are used
-        basicInformation: {
-            vendorName,
-            vendorId: VendorId(vendorId),
-            nodeLabel: productName,
-            productName,
-            productLabel: productName,
-            productId,
-            serialNumber: `matterjs-${uniqueId}`,
-            uniqueId,
-        },
-    });
-
-    console.log(
-        `Added device ${i} on port ${port} and unique id ${uniqueId}: Passcode: ${passcode}, Discriminator: ${discriminator}`,
-    );
-
-    const endpoint = new Endpoint(isSocket ? OnOffPlugInUnitDevice : OnOffLightDevice, { id: "onoff" });
-    await server.add(endpoint);
-
-    /**
-     * Register state change handlers of the node for identify and onoff states to react to the commands.
-     * If the code in these change handlers fail then the change is also rolled back and not executed and an error is
-     * reported back to the controller.
-     */
-    endpoint.events.identify.startIdentifying.on(() => {
-        console.log(`Run identify logic for device ${i}, ideally blink a light every 0.5s ...`);
-    });
-
-    endpoint.events.identify.stopIdentifying.on(() => {
-        console.log(`Stop identify logic for device ${i}...`);
-    });
-
-    endpoint.events.onOff.onOff$Changed.on(value => {
-        executeCommand(value ? `on${i}` : `off${i}`);
-        console.log(`OnOff ${i} is now ${value ? "ON" : "OFF"}`);
-    });
-
-    /**
-     * Log the endpoint structure for debugging reasons and to allow to verify anything is correct
-     */
-    logEndpoint(EndpointServer.forEndpoint(server));
-
-    console.log("----------------------------");
-    console.log(`QR Code for Device ${i} on port ${port}:`);
-    console.log("----------------------------");
-
-    /**
-     * In order to start the node and announce it into the network we use the run method which resolves when the node goes
-     * offline again because we do not need anything more here. See the Full example for other starting options.
-     * The QR Code is printed automatically.
-     */
-    await server.start();
-}
-
-/*********************************************************************************************************
- * Convenience Methods
- *********************************************************************************************************/
-
-/**
- * Defines a shell command from an environment variable and execute it and log the response
- */
-function executeCommand(scriptParamName: string) {
-    const script = Environment.default.vars.string(scriptParamName);
-    if (script === undefined) return undefined;
-    console.log(`${scriptParamName}: ${execSync(script).toString().slice(0, -1)}`);
-}
-
-async function getConfiguration() {
-    const environment = Environment.default;
-
-    const storageService = environment.get(StorageService);
-    console.log(`Storage location: ${storageService.location} (Directory)`);
-    console.log(
-        '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.',
-    );
-    const deviceStorage = (await storageService.open("device")).createContext("data");
-
-    let defaultPasscode = 20202021;
-    let defaultDiscriminator = 3840;
-    let defaultPort = 5550;
-
-    const devices = [];
-    const numDevices = environment.vars.number("num") ?? 2;
-    for (let i = 1; i <= numDevices; i++) {
-        const isSocket = await deviceStorage.get(`isSocket${i}`, environment.vars.string(`type${i}`) === "socket");
-        if (await deviceStorage.has(`isSocket${i}`)) {
-            console.log(`Device type ${isSocket ? "socket" : "light"} found in storage. --type parameter is ignored.`);
-        }
-        const deviceName = `Matter ${environment.vars.string(`type${i}`) ?? "light"} device ${i}`;
-        const vendorName = "matter-node.js";
-        const passcode =
-            environment.vars.number(`passcode${i}`) ?? (await deviceStorage.get(`passcode${i}`, defaultPasscode++));
-        const discriminator =
-            environment.vars.number(`discriminator${i}`) ??
-            (await deviceStorage.get(`discriminator${i}`, defaultDiscriminator++));
-        // product name / id and vendor id should match what is in the device certificate
-        const vendorId = environment.vars.number(`vendorid${i}`) ?? (await deviceStorage.get(`vendorid${i}`, 0xfff1));
-        const productName = `node-matter OnOff-Device ${i}`;
-        const productId =
-            environment.vars.number(`productid${i}`) ?? (await deviceStorage.get(`productid${i}`, 0x8000));
-
-        const port = environment.vars.number(`port${i}`) ?? defaultPort++;
-
-        const uniqueId =
-            environment.vars.string(`uniqueid${i}`) ??
-            (await deviceStorage.get(`uniqueid${i}`, `${i}-${Time.nowMs()}`));
-
-        // Persist basic data to keep them also on restart
-        await deviceStorage.set(`passcode${i}`, passcode);
-        await deviceStorage.set(`discriminator${i}`, discriminator);
-        await deviceStorage.set(`vendorid${i}`, vendorId);
-        await deviceStorage.set(`productid${i}`, productId);
-        await deviceStorage.set(`isSocket${i}`, isSocket);
-        await deviceStorage.set(`uniqueid${i}`, uniqueId);
-
-        devices.push({
-            isSocket,
-            deviceName,
-            vendorName,
-            passcode,
-            discriminator,
-            vendorId,
-            productName,
-            productId,
-            port,
-            uniqueId,
-        });
-    }
-
-    return devices;
-}

package/src/examples/SensorDeviceNode.ts

@@ -1,247 +0,0 @@
-#!/usr/bin/env node
-/**
- * @license
- * Copyright 2022-2024 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * This example shows how to create a simple Sensor Matter device as temperature or humidity device.
- * It can be used as CLI script and starting point for your own device node implementation.
- * This example is CJS conform and do not use top level await's.
- */
-
-/**
- * Import needed modules from @project-chip/matter-node.js
- */
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import { requireMinNodeVersion } from "@project-chip/matter.js-nodejs";
-
-import { Time } from "@project-chip/matter.js-general";
-import { DeviceTypeId, VendorId } from "@project-chip/matter.js/datatype";
-import { logEndpoint } from "@project-chip/matter.js/device";
-import { HumiditySensorDevice } from "@project-chip/matter.js/devices/HumiditySensorDevice";
-import { TemperatureSensorDevice } from "@project-chip/matter.js/devices/TemperatureSensorDevice";
-import { Endpoint, EndpointServer } from "@project-chip/matter.js/endpoint";
-import { Environment, StorageService } from "@project-chip/matter.js/environment";
-import { ServerNode } from "@project-chip/matter.js/node";
-import { execSync } from "child_process";
-
-requireMinNodeVersion(16);
-
-async function main() {
-    /** Initialize configuration values */
-    const {
-        isTemperature,
-        interval,
-        deviceName,
-        vendorName,
-        passcode,
-        discriminator,
-        vendorId,
-        productName,
-        productId,
-        port,
-        uniqueId,
-    } = await getConfiguration();
-
-    /**
-     * Create a Matter ServerNode, which contains the Root Endpoint and all relevant data and configuration
-     */
-    const server = await ServerNode.create({
-        // Required: Give the Node a unique ID which is used to store the state of this node
-        id: uniqueId,
-
-        // Provide Network relevant configuration like the port
-        // Optional when operating only one device on a host, Default port is 5540
-        network: {
-            port,
-        },
-
-        // Provide Commissioning relevant settings
-        // Optional for development/testing purposes
-        commissioning: {
-            passcode,
-            discriminator,
-        },
-
-        // Provide Node announcement settings
-        // Optional: If Ommitted some development defaults are used
-        productDescription: {
-            name: deviceName,
-            deviceType: DeviceTypeId(
-                isTemperature ? TemperatureSensorDevice.deviceType : HumiditySensorDevice.deviceType,
-            ),
-        },
-
-        // Provide defaults for the BasicInformation cluster on the Root endpoint
-        // Optional: If Omitted some development defaults are used
-        basicInformation: {
-            vendorName,
-            vendorId: VendorId(vendorId),
-            nodeLabel: productName,
-            productName,
-            productLabel: productName,
-            productId,
-            serialNumber: `matterjs-${uniqueId}`,
-            uniqueId,
-        },
-    });
-
-    /**
-     * Matter Nodes are a composition of endpoints. Create and add a single endpoint to the node. This example uses the
-     * OnOffLightDevice or OnOffPlugInUnitDevice depending on the value of the type parameter. It also assigns this Part a
-     * unique ID to store the endpoint number for it in the storage to restore the device on restart.
-     * In this case we directly use the default command implementation from matter.js. Check out the DeviceNodeFull example
-     * to see how to customize the command handlers.
-     */
-    let endpoint: Endpoint<TemperatureSensorDevice | HumiditySensorDevice>;
-    if (isTemperature) {
-        endpoint = new Endpoint(TemperatureSensorDevice, {
-            id: "tempsensor",
-            temperatureMeasurement: {
-                // Use this to initialize the measuredValue with the most uptodate value.
-                // If you do not know the value and also cannot request it, best use "null" (if allowed by the cluster).
-                measuredValue: getIntValueFromCommandOrRandom("value"),
-            },
-        });
-    } else {
-        endpoint = new Endpoint(HumiditySensorDevice, {
-            id: "humsensor",
-            relativeHumidityMeasurement: {
-                // Use this to initialize the measuredValue with the most uptodate value.
-                // If you do not know the value and also cannot request it, best use "null" (if allowed by the cluster).
-                measuredValue: getIntValueFromCommandOrRandom("value", false),
-            },
-        });
-    }
-
-    await server.add(endpoint);
-
-    /**
-     * Log the endpoint structure for debugging reasons and to allow to verify anything is correct
-     */
-    logEndpoint(EndpointServer.forEndpoint(server));
-
-    const updateInterval = setInterval(() => {
-        let setter: Promise<void>;
-        if (isTemperature) {
-            setter = endpoint.set({
-                temperatureMeasurement: {
-                    measuredValue: getIntValueFromCommandOrRandom("value"),
-                },
-            });
-        } else {
-            setter = endpoint.set({
-                relativeHumidityMeasurement: {
-                    measuredValue: getIntValueFromCommandOrRandom("value", false),
-                },
-            });
-        }
-        setter.catch(error => console.error("Error updating measured value:", error));
-    }, interval * 1000);
-
-    // Cleanup our update interval when node goes offline
-    server.lifecycle.offline.on(() => clearTimeout(updateInterval));
-
-    /**
-     * In order to start the node and announce it into the network we use the run method which resolves when the node goes
-     * offline again because we do not need anything more here. See the Full example for other starting options.
-     * The QR Code is printed automatically.
-     */
-    await server.run();
-}
-
-main().catch(error => console.error(error));
-
-/*********************************************************************************************************
- * Convenience Methods
- *********************************************************************************************************/
-
-/** Defined a shell command from an environment variable and execute it and log the response. */
-
-function getIntValueFromCommandOrRandom(scriptParamName: string, allowNegativeValues = true) {
-    const script = Environment.default.vars.string(scriptParamName);
-    if (script === undefined) {
-        if (!allowNegativeValues) return Math.round(Math.random() * 100);
-        return (Math.round(Math.random() * 100) - 50) * 100;
-    }
-    let result = execSync(script).toString().trim();
-    if ((result.startsWith("'") && result.endsWith("'")) || (result.startsWith('"') && result.endsWith('"')))
-        result = result.slice(1, -1);
-    console.log(`Command result: ${result}`);
-    let value = Math.round(parseFloat(result));
-    if (!allowNegativeValues && value < 0) value = 0;
-    return value;
-}
-
-async function getConfiguration() {
-    /**
-     * Collect all needed data
-     *
-     * This block collects all needed data from cli, environment or storage. Replace this with where ever your data come from.
-     *
-     * Note: This example uses the matter.js process storage system to store the device parameter data for convenience
-     * and easy reuse. When you also do that be careful to not overlap with Matter-Server own storage contexts
-     * (so maybe better not do it ;-)).
-     */
-    const environment = Environment.default;
-
-    const storageService = environment.get(StorageService);
-    console.log(`Storage location: ${storageService.location} (Directory)`);
-    console.log(
-        '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.',
-    );
-    const deviceStorage = (await storageService.open("device")).createContext("data");
-
-    const isTemperature = await deviceStorage.get("isTemperature", environment.vars.get("type") !== "humidity");
-    if (await deviceStorage.has("isTemperature")) {
-        console.log(
-            `Device type ${isTemperature ? "temperature" : "humidity"} found in storage. --type parameter is ignored.`,
-        );
-    }
-    let interval = environment.vars.number("interval") ?? (await deviceStorage.get("interval", 60));
-    if (interval < 1) {
-        console.log(`Invalid Interval ${interval}, set to 60s`);
-        interval = 60;
-    }
-
-    const deviceName = "Matter test device";
-    const vendorName = "matter-node.js";
-    const passcode = environment.vars.number("passcode") ?? (await deviceStorage.get("passcode", 20202021));
-    const discriminator = environment.vars.number("discriminator") ?? (await deviceStorage.get("discriminator", 3840));
-    // product name / id and vendor id should match what is in the device certificate
-    const vendorId = environment.vars.number("vendorid") ?? (await deviceStorage.get("vendorid", 0xfff1));
-    const productName = `node-matter OnOff ${isTemperature ? "Temperature" : "Humidity"}`;
-    const productId = environment.vars.number("productid") ?? (await deviceStorage.get("productid", 0x8000));
-
-    const port = environment.vars.number("port") ?? 5540;
-
-    const uniqueId =
-        environment.vars.string("uniqueid") ?? (await deviceStorage.get("uniqueid", Time.nowMs().toString()));
-
-    // Persist basic data to keep them also on restart
-    await deviceStorage.set({
-        passcode,
-        discriminator,
-        vendorid: vendorId,
-        productid: productId,
-        interval,
-        isTemperature,
-        uniqueid: uniqueId,
-    });
-
-    return {
-        isTemperature,
-        interval,
-        deviceName,
-        vendorName,
-        passcode,
-        discriminator,
-        vendorId,
-        productName,
-        productId,
-        port,
-        uniqueId,
-    };
-}