@project-chip/matter.js

matter.js

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

This is the JavaScript only Core of the Matter protocol. It is used by other projects to implement Matter Nodes and Clients and add the relevant specific implementations for Network and other elements.

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

• Network (UDP/MDNS)
• Crypto (to be split out)
• Storage
• Date/Timer
• Logger (Default uses "console")

Exported functionality

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

Export	Description
@project-chip/matter.js	Exports the API to implement a Device or a Controller.
@project-chip/matter.js/behavior	Exports Behavior classes (New API) as framework to implement all relevant Logic for clusters and internal logic. Contains auto-generated class structures and also Cluster default implementations.
@project-chip/matter.js/certificate	Exports Certificate (Root-/PAA/PAI/IAC/DA-Certificates) related functionality
@project-chip/matter.js/cluster	Exports Matter Cluster definitions and Default Cluster-Handlers
@project-chip/matter.js/codec	Exports Codecs for e.g. Matter-Messages
@project-chip/matter.js/common	Exports certain common functionalities
@project-chip/matter.js/crypto	Exports Crypto related abstract functionality that needs to be implemented platform specific!
@project-chip/matter.js/datatype	Exports Matter Data types
@project-chip/matter.js/device	Exports Matter Device relevant classes (Legacy API!)
@project-chip/matter.js/devices	Exports Matter Device type classes (NEW API!)
@project-chip/matter.js/endpoint	Exports Matter Endpoint structure classes (NEW API!)
@project-chip/matter-.js/environment	Exports environment functionalities, which handes central functions like MDNS and configuration
@project-chip/matter.js/fabric	Exports Matter-Fabric functionality
@project-chip/matter.js/interaction	Exports Matter Interaction protocol functionality
@project-chip/matter.js/log	Exports Logging functionality (based on "console")
@project-chip/matter.js/math	Exports Math functionality used by Matter
@project-chip/matter.js/mdns	Exports Basic MDNS functionality (uses Network implementation)
@project-chip/matter.js/model	Exports a JavaScript version of the Matter data model
@project-chip/matter.js/net	Exports Basic Network abstract functionality that needs to be implemented platform specific!
@project-chip/matter.js/node	Exports Matter Node functionality which is used as basis for a device or controller (NEW API!). It also contains Matter Interaction model abstractions for the new API.
@project-chip/matter.js/protocol	Exports Basic Matter protocol functionality
@project-chip/matter.js/schema	Exports Schema definitions and functionality
@project-chip/matter.js/securechannel	Exports Secure Channel functionality
@project-chip/matter.js/session	Exports Session and Secure-Session functionality
@project-chip/matter.js/spec	Exports Matter Specification References
@project-chip/matter.js/storage	Exports Basic Storage abstract functionality that needs to be implemented platform specific!
@project-chip/matter.js/time	Exports Basic Time/Timer abstract functionality that needs to be implemented platform specific!
@project-chip/matter.js/tlv	Exports Matter TLV type definitions
@project-chip/matter.js/util	Exports Basic Utility functionality

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

For more details please refer to the API Documentation.

Included Cluster default implementations

Each cluster that has commands also needs to have them implemented based on the chosen feature set.

Matter.js provides a specification-compliant implementation of all Matter 1.1 clusters. For many clusters our implementations perform high-level business logic. For other clusters you provide the needed business logic by extending the Matter.js implementation. In all cases Matter.js takes care of details like the Matter protocol, input and output validation and persistence. The developer can then decide if own functionality needs to be developed and can overwrite and extend these implementations or just use them.

Matter.js allows the following clusters to be used directly with a default implementation for all relevant commands - or the clusters do not need any commands and so the standard feature set of Matter.js for attributes is sufficient. All clusters contained in this list are also verified using the CI YAML project-chip certification tests (if the PICS code is in brackets then no tests are available).

PICS	Cluster name	Features	Matter-Version	Additional Information
(ACL)	Access Control	None	1.1	No command implementations needed, but ACL checks still pending in matter.js
CADMIN	Administrator Commissioning	None, Basic	1.1	Internal Root cluster implemented, no need to customize
APBSC	Application Basic	None	1.1	No command implementations needed
BC	Ballast Configuration	None	1.1	No command implementations needed, Cluster provisional
BINFO	Basic Information	None	1.1	Internal Root cluster implemented, no need to customize, all events are automatically emitted by matter.js
	Binding	None	1.1	No command implementations needed, support of bindings pending in matter.js
BOOL	Boolean State	None	1.1	No command implementations needed. If the StateChanged event is enabled it is emitted automatically on state change.
BRBINFO	Bridged Device Basic Information	None	1.1	Internal Root cluster implemented, no need to customize, reachabilityChanged event is automatically emitted by matter.js
DESC	Descriptor	None	1.1	Internal Root cluster implemented, no need to customize, data are automatically manabed by matter.js
CNET	Ethernet Network Diagnostics	None	1.1	No command implementations needed when used without any features
FLABEL	Fixed Label	None	1.1	No command implementations needed
FLW	Flow Measurement	None	1.1	No command implementations needed
CGEN	General Commissioning	None	1.1	Internal Root cluster implemented, no need to customize
DGGEN	General Diagnostics	None	1.1	Implements all needed functionality like upTime and totalOperationalHours counters. Additionally, provides convenience methods to register or clear faults including sending the relevant events if the optional events got enabled. Network interface types reported can be defined by Environment variables (see Environment.ts).
I	Identify	None, IdentifyQuery	1.1	All mandatory commands implemented. Additionally, state isIdentifying and events start/stopIdentifying are available to easiely extend the server.
ILL	Illuminance Measurement	None	1.1	No command implementations needed
(RH)	Leaf Wetness Measurement	None	1.1	No command implementations needed
LVL	Level Control	OnOff, Lighting	1.1	Default implementation sets currentLevel and remainingTime attributes by respecting the feature requirements on best-effort basis. Use managedTransitionTimeHandling state to true to use transitions managed by matter.js.
LCFG	Localization Configuration	None	1.1	No command implementations needed
LOWPOWER	Low Power	None	1.1	The default implementation emits the internal event enterLowPowerMode that an implementation can listen too. Alternatively, you can override the sleep command by extending the cluster.
CNET	Network Commissioning	None	1.1	No command implementations needed when using with Ethernet network, needs custom implementation for Wi-Fi or Thread, see examples
MOD	Mode Select	OnOff	1.1	Default implementation sets the new mode when change command is used and automatically handles StartUpMode and OnMode.
OCC	Occupancy Sensing	None	1.1	No command implementations needed
OO	OnOff	None, LevelControl-For-Lighting	1.1	LevelControl-For-Lighting feature is enabled automatically in default implementation. offWithEffect currently ignores requested effects and turns off. onWithRecallGlobalScene currently ignores the global scene and turns on.
	OnOff Switch Configuration	None	1.1	No command implementations needed
OPCREDS	Operational Credentials	None	1.1	Internal Root cluster implemented, no need to customize
PS	Power Source	None	1.1	No command implementations needed. Optional events needs to be emitted by the developer if needed
(PSCFG)	Power Source Configuration	None	1.1	No command implementations needed
PRS	Pressure Measurement	None	1.1	No command implementations needed
(PXCFG)	Proxy Configuration	None	1.1	No command implementations needed
PCC	Pump Configuration and Control	None	1.1	No command implementations needed, Relevant Events need to be enabled and emitted by the developer when needed, Cluster client dependencies are not yet possible with matter.js
RH	Relative Humidity Measurement	None	1.1	No command implementations needed
(RH)	Soil Moisture Measurement	None	1.1	No command implementations needed
SWTCH	Switch	None	1.1	Matter.js provides a full implementation with all features in a configurable way including release, long- and multi-press detection. Just set currentPosition state and all events will be triggered automatically. Alternatively, an additional state rawPosition is available which will be debounced based on a defined debounce delay. Check the SwitchCluster documentation for the details and additional state values.
TMP	Temperature Measurement	None	1.1	No command implementations needed
TSUIC	Thermostat User Interface	None	1.1	No command implementations needed
LTIME	Time Format Localization	None	1.1	No command implementations needed
LUNIT	Unit Localization	None	1.1	No command implementations needed
ULABEL	User Label	None	1.1	No command implementations needed
WAKEONLAN	WakeOnLan	None	1.1	No command implementations needed
WNCV	Window Covering	None	1.1	All commands for all feature sets are implemented. Movements will by default be executed as fast as possible by just setting the new value, so own movement logic needs to be implemented.

More will come over time and can also be contributed by the community!

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.

matter.js usage

matter.js is used at the core of those two projects:

• matternode: a light-weight node.js implementation of a Matter Node
• matter-node.js: a Matter client / server running on node.js compatible with HA (Android / iOs support in progress)

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