Release 0.10.0 from 31.08.2024

[Apollon77]

We are excited to announce the release of matter.js 0.10, marking a significant milestone in the ongoing implementation of the Matter IoT standard in JavaScript.

What's New in Version 0.10

This new release significantly enhances the library by upgrading the supported Matter version from 1.1 to 1.3.0.1, bringing full support for all clusters, device types, and namespaces defined in the latest standard. Along with these updates, several new protocol features introduced in Matter 1.2 and 1.3 have been incorporated. These new functionalities have been thoroughly tested against the official Project CHIP certification tests, ensuring full compliance. Additionally, we have made numerous optimizations, fixes, and enhancements across the library, resulting in improved robustness and stability.

Breaking Changes

Given the substantial update to the Matter version, there are some minor breaking changes, particularly in the clusters, their usage, and other areas of the API and types. We strongly recommend reviewing the changelog and checking for any build errors in your applications.

Important: We have dropped support for Node.js 16, which reached its end-of-life nearly a year ago. Going forward, we will support all LTS versions of Node.js starting from Node.js 18.

Experimental Features

We’ve made significant strides towards running matter.js in a React Native environment, with a new package added for this purpose. While it is not yet fully functional, progress is promising.

Legacy API Notice

If you're still using the "Legacy Device Building API," we encourage you to consider upgrading. The new API offers numerous benefits and will be the focus of all future feature developments. If you need support, just contact us.

Get Involved

matter.js 0.10 is available as latest version on npm. We invite you to update your applications and share your feedback, issues, and success stories on GitHub or Discord. Our team is always here to answer your questions!

For a comprehensive list of changes, please refer to the Release Notes below.

0.10.0 (2024-08-31)

• IMPORTANT: This release upgrades Matter support from Matter 1.1 to the latest release, Matter 1.3.0.1. This includes BREAKING CHANGES in a number of areas due to specification changes and some improvements in how we define datatypes. For the most part these changes are transparent because they involve low-level APIs, implicit type names, or Matter features that were never adopted elsewhere. However, some small code changes may be necessary depending on how you use Matter.js.

• Matter.js Parser and Code generator:

  • Feature: We now generate all Matter datatypes and elements. This includes some we defined by hand previously and those introduced by the Matter 1.2 and Matter 1.3 specifications.
  • Feature: We now generate some datatypes that are not officially global or part of a specific cluster but are nevertheless defined in Matter specifications.
  • Enhancement: Expanded dialect for conformance, constraint and "other quality" DSLs.
  • Enhancement: Includes numerous code generation improvements.

• Matter.js Matter Definition, Clusters, Schemas and Device-Types (independent of the used API)

  • Breaking: Cluster revisions have increased and there are new mandatory elements for a few clusters. We have implemented these in places where we provide non-skeletal cluster implementations.
  • Breaking: Previously we generated redundant definitions for struct, enum and bitmap types in *Interface.ts and *Cluster.ts files. We've eliminated those in the interface files.
  • Breaking: Previously we generated redundant TLV and types for datatypes used by multiple clusters. We now only provide these types in their canonical location (globally or in the ClusterName namespace for the base cluster).
  • Breaking: Some datatype names have changed to align with changes in the Matter specification and to make names more logical.
  • Breaking: We've removed a few deprecated definitions for unused Matter elements such as the Scenes cluster.
  • Breaking: Globals.ts previously defined core datatypes for the Matter object model. These are now generated and individually importable.
  • Breaking: We've removed a few old draft datatypes defined in connectedhomeip that were abandoned, renamed or are still "draft" as of Matter 1.3.
  • Breaking: Some types related to ClusterServer are simplified. This should be largely transparent but the template arguments are slightly different
  • Feature: Adds all elements (clusters, attributes, events, commands, device types and datatypes) introduced in Matter 1.2 and Matter 1.3.
  • Feature: Adds all Standard Namespaces defined by Matter 1.3

• Matter-Core functionality:

  • Breaking: Removes the discovery capability "softAccessPoint" as it was removed from the Matter specification
  • Breaking: Matter.js now requires node.js 18+
  • Breaking: We now target ES 2022 for transpiled output. We have not adopted new language features but this does mean that we generate true class properties now
  • Breaking: We've removed the APIs tryCatch and tryCatchAsync. These were used internally -- not part of any Matter related API -- but were exported
  • Feature: Increase Data Model revision to 17 (introduced by Matter 1.2)
  • Feature: Added Base64 encoding/decoding support to ByteArray
  • Feature: Added WildcardPathFlagsBitmap to Attribute expansion for read/subscribe Interactions
  • Feature: Added Matter 1.3 session params
  • Feature: Added support for Multi-Invokes for Matter 1.3 (default for now are 10 invokes till we have a better value)
  • Enhancement: Update Session parameters in PASE/CASE to match Matter 1.3 specification
  • Enhancement: Removes TCP and ICD TXT records from MDNS responses because both currently not supported and optional to reduce the size of the MDNS responses
  • Enhancement: Adds encoding and decoding of custom TlvData in QR-Codes including extensible Schema support for the defined Matter fields
  • Enhancement: Optimizes Read and Subscribe handling for clients/controller to better match with specification
  • Enhancement: Adds encoding/decoding support for multiple device information in one QR-Code
  • Enhancement: Makes processing of manual Pairing codes more robust directly on decoding level
  • Enhancement: Refactored Message size handling to dynamically calculate payload size based on transport capabilities
  • Enhancement: Refactored and cleanup CASE and PASE and corrected handling in some places
  • Enhancement: Added BTP Idle timeout as defined in Matter specification
  • Enhancement: Enhanced default implementation of GeneralDiagnostics cluster with new convenience methods
  • Enhancement: Many more protocol and functionality syncs with matter specification 1.3
  • Enhancement: The Network methods that handles NetworkInterfaces are now "MaybePromise" to allow async implementations
  • Enhancement/Fix: Several fixes and optimizations in Session and Message Exchange handling
  • Enhancement/Fix: Adjusted MRP behavior with chip and only use/expect MRP ion unreliable channels (UDP). Fixes BLE commissioning
  • Fix: Adjusted ValidationErrors to be more specific if they should return "InvalidAction" ot "ConstraintError".
  • Fix: Adjusted some returned errors to be more specific and to the specification (e.g. InvalidAction instead of Failure)
  • Fix: Fixed StandaloneAck handling to use an outstanding ack number as piggybacked ack number
  • Fix: Makes sure subscription maxInterval cannot exceed the matter defined maximum of 60mins
  • Fix: Synced attMtu handling with chip to always use MTU-3 bytes for BLE connections

• matter.js API:

  • Breaking: Node.start() is now asynchronous and returns when the node is online. This is only breaking in that lack of await will result in an unhandled rejection. Node.bringOnline() is deprecated.
  • Feature: Adds default implementations for i18n clusters including Localization, Time Format Localization and Unit Localization.
  • Feature: Adds interactionBegin and interactionEnd events for ClusterBehaviors to demarcate online interactions that mutate state.
  • Feature: Any state value defined with schema is now configurable via the environment.
  • Feature: You may now mark endpoints as "non-essential" to prevent errors from incapacitating a node.
  • Feature: Utility device types are added automatically to the endpoints when the relevant clusters (like PowerSource or ElectricalSensor) are existing on the endpoint
  • Feature: Adds DescriptorServer#addTag to make adding tags more convenient
  • Feature: Modifies DescriptorServer#addDeviceType to accept device type name to simplify avoidance of cyclical dependencies
  • Enhancement: Various Endpoint methods throw the root cause when there is an error rather than logging the root cause and throwing a less descriptive error.
  • Enhancement: Explicitly defines DescriptorServer as an endpoint requirement so attributes are configurable in TS directly

• matter.js Controller API:

  • Breaking: commissionNode() in CommissioningController now returns the Node-ID and not the PairedNode instance.
  • Breaking: AttributeClient now throws an exception when an attribute should be subscribed which is not reporting updates via subscriptions
  • Feature: Adds PaseCommissioner to allow to execute the initial (PASE based) commissioning process separately from the operational completion of the commissioning process, also allowed to be BLE only.
  • Feature: Allows to complete the commissioning process for a node where this process was started by a PASE commissioner
  • Feature: Allows to commission a node without directly connecting to it
  • Enhancement: Always read attributes that do not report changes via subscriptions (including all unknown Attributes)
  • Fix: Skips network commissioning during commissioning when the commissioning is already using an IP based channel (like UDP)
  • Fix: Fixes Node reconnection when disconnected before
  • Fix: Makes sure to always use the BLE scanner when required
  • Fix: Prevents reading subscribed attributes from remote if not requested and needed
  • Fix: (digitaldan) Makes sure to re-use the same callbacks and options for a re-subscription of a Paired Node

• matter.js Legacy API:

  • Deprecation: We've deprecated the hand-generated device type definitions used by the pre-0.8.0 API in DeviceTypes.ts. These device type definitions remain at Matter 1.1.
  • Removal: We removed old Scenes cluster implementation which was never fully implemented or used by any Matter controller

• matter.js-react-native:

  • Feature: Introduces new package to provides a React Native compatible platform Implementations for Matter.js. This package is still in development and not fully working and should be considered experimental for now! Currently it tries to support UDP, BLE, AsyncStorage and Crypto platform features. See README for more information.

• matter.js chip and python Testing:

  • Includes updates and infrastructure improvements for Matter.js use of tests defined in connectedhomeip