@matter/examples

@matter/examples - Usage examples / Reference implementations

This project provides a set of reference implementations to show several types of Matter device nodes or also a controller implementation.

This package supports all Node.js LTS versions starting with 18.x

To better show how to use the library we provide some reference implementations in the examples directory. They are usable as CLI scripts without changes in the first place but are very simple. They are meant to be used as a starting point for your own implementation, or to experiment with Matter at all in a first place.

For BLE usage please also see the @matter/node-ble README.md for prerequisites and limitations!

Examples Overview

The examples provided by this repository show different use cases demonstrating how to build different device types and show various ways to implement and interact with the matter.js structures. This section gives an overview regarding what the different examples demonstrate.

[!IMPORTANT] With matter.js 0.8 we introduced a new API that is not compatible with the old API. The new API is more flexible and allows for more complex use cases. The old API is still supported but will be removed in a future release. The examples for the old API are available in the NPM package @project-chip/matter-node.js-examples.

The different examples and what they do is described in the relevant README.md files in the respective directories.

Device Examples

All examples that have a name starting with device- are examples for different types of matter devices. They show how to implement a device with different features and how to interact with it. These can be paired by any ecosystem or controller that supports test devices.

Controller Examples

All examples that have a name starting with controller- are examples for different types of matter controllers. They show how to implement a controller. These can pair any matter device.

Installation

From NPM

npm i -g @matter/examples

Use from Cloned Matter.js Repository

When you clone the matter.js repository you can also use matter-node.js. To do this you need to execute npm install in the matter.js root directory once to install all dependencies and build all packages.

Then after cd packages/examples you can use npm run matter-device to run the matter-node.js server. Please see the next section for more details.

CLI usage

General CLI information

Some command line parameters, for example those used to set the level of logging or the MDNS interface are now included in the new environment processing. These can be set by generic command line arguments or by using environment variables. These parameters are processed automatically so are no longer handled by the new example code directly. These are:

• --log-level=... or environment variable MATTER_LOG_LEVEL or in code environment.vars.set('log.level', Level.DEBUG). Allowed values are: Level.FATAL ("fatal"), Level.ERROR ("error"), Level.WARN ("warn"), Level.NOTICE ("notice"), Level.INFO ("info"), Level.DEBUG ("debug")
• --log-format=... or environment variable MATTER_LOG_FORMAT or environment.vars.set('log.format', Format.PLAIN). Allowed values are: Format.PLAIN ("plain"), Format.HTML ("html"), Format.ANSI ("ansi")
• --storage-path=... or environment variable MATTER_STORAGE_PATH or environment.vars.set('storage.path', "...") allows to set the storage location. By default, it will be stored in the users home directory in .matter/.... If specified, the given path will be used relative to the current working directory.
• --storage-clear or environment variable MATTER_STORAGE_CLEAR=1 or environment.vars.set('storage.clear', true) allows to define if the storage is reset on startup.
• --mdns-networkinterface=... or environment variable MATTER_MDNS_NETWORKINTERFACE or environment.vars.set('mdns.networkInterface', "...") allows to limit the DNS announcements and scanning to one network interface. By default, all available interfaces are used. Additionally, all command line parameters now require to start with two dashes!

Common CLI parameter for all examples

The following CLI parameters are the same for all examples:

• -clearstorage: the storage location will be reset on start of the process. The sorage location is set via parameter "-store" (see concrete examples below)
• -loglevel: the log level to use (default: debug, possible values: fatal, error, warn, info, debug)
• -logformat: the log format to use (default: ansi (if executed in a shell/tty), else plain, possible values: ansi, plain, html)

Development on basis of the examples

The code of the examples is written so that you can use them as basis for your own scripts also outside of this library in your own package. If you import from @matter/main then matter.js loads platform extensions such as those for node.js automatically. If you import directly from our other packages then you should add a dependency on @matter/nodejs. The examples use @matter/main imports to ease adoption.

Development Device/Composed-device/Bridge

The code is structured by comment blocks to better see what belongs to what. It always has code which is just collecting relevant information and data, then the code which is setting up the device and then the code which is starting the device.

Building

• npm run build: Build all code and create CommonJS and ES6 variants in dist directory. This will built incrementally and only build the changed files.
• npm run build-clean: Clean the dist directory and build all code from scratch

Changelog

0.11.9 (2024-12-11)

• @matter/node

  • Enhancement: Enhances the number assertations to only allow finite numbers
  • Enhancement: WindowCovering: Adds an internal property to disable the operational state and value management by the default implementation to allow device to handle this themselves
  • BREAKING: WindowCovering: supportsCalibration is moved from state property to an internal property
  • Fix: ColorControl: Do not try to convert color mode details if they are not defined
  • Fix: ColorControl: colorMode attribute needs to be defined if HS feature is not used because the default value 0 is else invalid

• @matter/protocol

  • Fix: Also retry next discovered address when a Channel establishment error for PASE occurs
  • Fix: Optimizes MDNS cache handling to prevent too early cache invalidation

• @matter/types

  • Enhancement: Deprecated fields are now also usable and just flagged as deprecated on generated code
  • Enhancement: Removes default value from attribute ColorMode of ColorControl cluster because feature specific enum value was used

• @project-chip/matter.js

  • Feature: Introduces PairedNode#triggerReconnect() method to trigger a reconnection
  • Enhancement: Considers a node in reconnection state that should be decommissioned as already factory reset
  • Enhancement: Optimizes reconnection handling in Controller API
  • Fix: Do not try to convert color mode details if they are not defined
  • Fix: Clusters generated for extensions of base clusters such as Alarm Base and Mode Base now include full details of extended types; in particular extended enums such as Mode Tag were previously insufficiently defined
  • BREAKING: In ContentLauncher cluster ParameterEnum is renamed to Parameter and Parameter is renamed to ParameterStruct

• @matter/model

  • Feature: New Scope component analyzes scope of a model, caches analysis results, and implements algorithms that require analysis to perform efficiently
  • Enhancement: Models that define datatypes now inherit from common ScopeModel base class
  • Fix: Extended enums and other types now report the full set of members via Scope#membersOf
  • BREAKING: ClusterModel and ValueModel properties members, activeMembers and conformantMembers are removed; use Scope#membersOf instead