@matter/main

@matter/main

Implementation of Matter protocol in typescript with no native dependencies (and very limited dependencies).

This is a convenient single-dependency for applications build on matter.js and have automatic registrations for Node.js and react-native as platforms.

This package supports all Node.js LTS versions starting with 18.x (when Node.js is used).

The following features are abstracted away to allow to be implemented environment specific:

• Network (UDP/MDNS)
• Crypto
• Storage
• Date/Timer
• Logger (Default uses "console")
• Environment (Process and Configuration handling)

Exported functionality

[!IMPORTANT] All exports here are for the current API. Legacy Cluster implementations are only exported via @project-chip/matter.js!

This library exports the Matter protocol functionality as well as some helper functions as named exports:

Export	Description
@matter/main	Re-Exports all functionality from @matter/general, @matter/node, Environment class, Matter model class and the datatypes from @matter/types
@matter/main/behaviors	Exports Behavior classes as framework to implement all relevant Logic for clusters and internal logic. Contains auto-generated class structures and also Cluster default implementations.
@matter/main/behaviors/*	Exports Behavior classes as framework to implement all relevant Logic for clusters and internal logic. Contains auto-generated class structures and also Cluster default implementations as cluster-name export
@matter/main/clusters	Exports all Matter Cluster definitions
@matter/main/clusters/*	Exports Matter Cluster definitions as cluster-name export
@matter/main/devices	Exports Matter Device type classes
@matter/main/devices/*	Exports Matter Device type classes as cluster-name export
@matter/main/endpoints	Exports Matter Endpoint structure classes
@matter/main/endpoints/*	Exports Matter Endpoint structure classes as cluster-name export
@matter/main/model	Exports a JavaScript version of the Matter data model. Re-exports @matter/model package.
@matter/main/node	Exports the matter node specific classes. Re-exports @matter/node package.
@matter/main/protocol	Exports Basic Matter protocol functionality. Re-exports @matter/protocol package.
@matter/main/types	Exports all Types (includes Clusters and Matter datatypes and matter.js own datatypes. Re-exports @matter/types package.

Both exports and the typings are exported as CommonJS and ES6 modules.

For more details please refer to the API Documentation.

Typescript note

To have Typescript and your IDE know all the relevant exported functionality you need to use the following in your tsconfig.json:

{
    compilerOptions: {
        moduleResolution: "node16", // Required to support package.json exports
        module: "node16", // Required to make sure all imports are js
    },
}

Additionally, we recommend using "strictNullChecks": true or better for code quality "strict": true to make sure that all types are correctly determined.

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

Tests

• npm run test-node: Run tests in node.js
• npm run test-web: Run tests in the browser
• npm run test: Run all tests

test-web will create a /coverage directory containing the test code coverage

Changelog

0.11.0 (2024-10-29)

• IMPORTANT: As of 0.10.0 the @project-chip/matter.js module has grown quite large. This release includes major refactoring that moves functional areas into independent NPM packages under the "@matter" org. We have added exports to maintain backwards compatibility but these are not exhaustive. In some cases you may need to update imports to reference new code locations.

• Cross-module changes

  • Info: Matter.js now uses aliases via package.json "imports" field. This is an internal change that simplifies imports but should not affect consumers
  • Info: Previously we used a mix of snake-case and CamelCase for sub-package exports. We have now standardized on snake case. Compatibility packages (see below) continue to support the original module names

• @matter/general:

  • Info: General functionality that is not Matter specific previously resided in @project-chip/matter.js. It now lives in @matter/general
  • BREAKING: The "ByteArray" type is removed, replaced with native-JS Uint8Array and a small collection of utility functions in the "Bytes" namespace
  • Feature: The default "Time" implementation is now fully functional across all standard JS runtimes
  • Enhancement: Network transports can now self select which the protocols and addresses they support
  • Feature: A new ObserverGroup class simplifies binding management for multiple observables
  • Feature: Introduced a new Async Disk key/Value-Storage compatible with the sync one driven by node-localstorage and uses it by default in new API and controller instances

• @matter/main:

  • Info: This package is a new "one-and-done" dependency for applications. It automatically loads platform specialization and reexports packages above as appropriate

• @matter/model:

  • Info: The Matter object model previously exported as @project-chip/matter.js/model now resides in @matter/model
  • Info: Individual elements exported by name are now models (fully functional classes) rather than elements (raw JSON data). This should be backwards compatible but makes them more useful operationally

• @matter/node:

  • Info: The high-level APIs previously defined in @project-chip/matter.js now reside in @matter/node. The Node API includes node management, behavior definitions and endpoint definitions
  • Info: We export behaviors under @matter/node/behaviors or individually (e.g. @matter/node/behaviors/on-off)
  • Info: We export device type definitions for system endpoints and devices under @matter/node/endpoints and @matter/node/devices respectively. You may also import these via index or individually

• @matter/nodejs:

  • Info: Node.js specialization is moved here. @project-chip/matter-node.js remains as a compatibility import.
  • BREAKING: The previously deprecated re-exports in matter-node.js from matter.js are removed.

• @matter/nodejs-ble

  • Info: The BLE specialization for Node.js is moved here. @project-chip/matter-node-ble.js remains as a compatibility import.
  • Info: The noble and bleno dependencies got updated to also support Ubuntu 24

• @matter/nodejs-shell:

  • Breaking: The Shell Storage was moved to the new approach. Please use "--legacyStorage" on startup to connect with the old storage to get into your old shell history and commissioned devices. Storage migration guide see in the README.md.
  • Feature: Added new shell command "tlv" with TLV decoding and structure logging tooling
  • Enhancement: Added option to specify if attributes are loaded from remote or locally
  • Enhancement: The shell now saves a 100 history of commands and restores this on startup
  • Enhancement: Add a "nodes status" command to show the status of all nodes

• @matter/protocol:

  • Info: Low-level Matter logic previously defined in @project-chip/matter.js now resides in @matter/protocol. This includes network communication, fabric management and cluster invocation, read/write, events, etc.
  • BREAKING: Various types that were previously specialized with template parameters are no longer generic. This should be largely transparent to API consumers. Compatibility exports still support the generic parameters in some, but not all, cases.
  • BREAKING: We have done some reorganization of lower-level implementation classes to improve implementation flexibility. You probably do not use these classes directly so will be unaffected.
  • Feature: New functional components including DeviceCommissioner, DeviceAdvertiser, NodeFinder and Subscription now perform functions that previously were in the (deprecated) MatterDevice class
  • Enhancement: To simplify low-level configuration, many components in the protocol module now optionally retrieve dependencies from an Environment
  • Enhancement: Limits the number of parallel exchanges to 5
  • Enhancement: Uses the session timing details to calculate the timeout for subscription messages when received as client additionally to the subscription maxInterval
  • Enhancement: Internal restructuring of Controller logic and setup. Introducing "peers" (commissioned node on a shared fabric)
  • Fix: When subscribing with keepSubscriptions === false the existing subscriptions need to be removed earlier in the flow
  • Fix: Clear resumption records also when fabric gets updated or deleted

• @matter/types:

  • Info: Various definitions previously defined in @project-chip/matter.js now reside in @matter/types. This includes most TLV structures, cluster definitions, and various support types
  • Info: Clusters are not exported in @project-chip/matter.js. You can import via @project-chip/types/clusters or individually (e.g. @project-chip/types/clusters/window-covering)

• @matter/examples:

  • Enhancement: Adds a new example to show a PlugIn-Socket with Energy and Power measurement

• @matter/cli-tool:

  • Feature: This new package offers a specialized JS environment for interacting with Matter and matter.js
  • The "matter" command supports standard JS syntax and a "shell" style syntax that emulates common shell commands
  • The virtual filesystem exposed by the tool allows you to navigate matter.js's packages and active subsystems
  • This is an alpha feature. We'll add command line control and additional functionality over time

• @matter/create

  • Feature: This new package bootstraps matter.js-based projects.
  • For usage run npm init @matter help anywhere you have Node.js installed

• Matter-Core functionality:

  • Enhancement: Allow to discover VendorId + ProductId together optionally

• matter.js clusters:

  • Adds convenience helper method for ElectricalEnergyMeasurement cluster (usage see new example MeasuredSocketDevice) to set measurements and also trigger the needed events when imported and exported values changed in the measurement and events are required by specification

• matter.js Controller API:

  • Breaking: PairedNode instances are now created and directly returned also when the node is not et connected. This do not block code flows anymore for offline devices
  • Breaking: Because of this "getConnectedNode()" got renamed to "getPairedNode()"
  • Breaking: "nodeState" property on PairedNode got renamed to "state"
  • Breaking: Removed SupportedEventClient and UnknownSupportedEventClient and replaced by EventClient because EventList is provisional and was removed now (was not working for many devices anyway)
  • Breaking: Removed ClusterClient methods isEventSupported and isEventSupportedByName because event lists are no longer available
  • Deprecation: The attributeChangedCallback, eventTriggeredCallback and nodeStateChangedCallbacks are deprecated and replaced by new events "attributeChanged", "eventTriggered" and "stateChanged", "structureChanged" and "decommissioned" on PairedNode
  • Feature: Some more data (like Network interfaces, PowerSources, Thread details) are collected and used when connecting to the nodes
  • Feature: Based on device type the minimum and maximum subscription interval is now automatically set based on certain best practices. When multiple nodes are subscribed all Thread based devices are initialized by a "4 in parallel queue" to limit the used thread bandwidth.
  • Feature: Subscribed attribute data are cached for each node and used on reconnects by utilizing dataVersionFilters on read and subscribes to reduce bandwidth on reconnects. The data are no (yet) persisted, so after Controller restart the data are collected anew.
  • Feature: Low level InteractionClient API allows to enrich the attribute data that are not returned because of dataVersionFilters.
  • Feature: Properly announces the controller node on start for devices to find the controller if needed and to utilize persisted subscriptions on device side
  • Enhancement: Only recreate PairedNode internal objects when structure really changed also on reconnects.
  • Enhancement: Utilize more information (beside partList changes now also feature, serverList, attributeList, generatedCommandLists) as structure change to reinitialize objects.
  • Enhancement: Huge refactoring in internal logic, optimized reconnection and rediscovery