@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/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/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/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.

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
    }
}

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

Changelog

0.7.0 (2023-11-13)

• General
  • Breaking: Changed ES target from ES5 to ES2018 (affected environments probably already didn't support matter.js)
  • Feature (vilic): Added project references and additional tsconfigs to support standard tsc development workflows
  • Enhance: Optimizing build speed
  • Enhance: matter-node-ble.js is published as CJS/ESM hybrid package
  • Enhance: matter-node.js-examples is published as ESM module
• Matter-Core functionality:
  • Breaking: QrCodes are not longer pre-rendered, but can be generated by QrCode.get() (from schema export),see examples
  • Fix: Handles event data correctly on subscription initially and also on updates to trigger the listeners
  • Fix (vilic): Adjust network interface handling for Windows to use the zone id instead of network interface name
  • Enhance (vilic): Added MDNS Memberships to sockets for better operation on Windows and other platforms
  • Enhance: Refactor session management and make sure also controller handle session close requests from devices
  • Enhance: Refactor close handing for exchanges and channels to make sure they are closed correctly
  • Feature: Added detection of missing Subscription updates from a device and allow to react to such a timeout with callback
  • Feature: Added generation method for random passcodes to PaseClient
  • Feature: Generalized Discovery logic and allow discoveries via different methods (BLE+IP) in parallel
  • Feature: Added functionality to clear session contexts including data in sub-contexts or not
  • Feature: Enhance discovery methods to allow continuous discovery for operational devices
• matter.js API:
  • Breaking: Rename resetStorage() on CommissioningServer to factoryReset() and add logic to restart the device if currently running
  • Breaking: Restructure the CommissioningController to allow pairing with multiple nodes
    • Adjusts some property and structure namings to be more consistent
    • Introducing class PairedNode with the High level API for a paired Node
    • Restructured CommissioningController to handle multiple nodes and offer new high level API
    • Changed name of the unique storage id for servers or controllers added to MatterServer to "uniqueStorageKey"
    • Adjusted subscription callbacks to also provide the nodeId of the affected device reporting the changes to allow callbacks to be used generically when connecting to all nodes
    • Introduces a node state information callback to inform about the connection status but also when the node structure changed (for bridges) or such.
  • Breaking: Deprecated the option "mdnsAnnounceInterface" and replaced by "mdnsInterface" and now used to limit announcements and scanning to a specific interface
  • Breaking: Makes sure that also nodes added to a MatterServer after it was started are also started to behave the same. "add" methods are now async.
  • Feature: Enhanced CommissioningServer API and CommissioningController for improved practical usage
  • Feature: Makes Port for CommissioningServer optional and add automatic port handling in MatterServer
  • Feature: Allows removal of Controller or Server instances from Matter server, optionally with deleting the storage
  • Enhance: Makes passcode and discriminator for CommissioningServer optional and randomly generate them if not provided
• matter-node-shell.js
  • Feature: Completely refactored and enhances shell to support commissioning, identify and many more new commands. See Readme, try it
• matter-node.js-examples
  • Breaking: Rename parameter -announceinterface to -netinterface and use for announcements and scanning