Release 0.11 from 29.10.2024

[Apollon77]

Enhanced Controllers, Project Skeleton Generator, and New Package Structure

We’re excited to announce the release of matter.js 0.11!

What’s New in Version 0.11

This release brings significant upgrades, particularly in improving the Matter Controller APIs. Here’s a quick overview:

• Subscription Data Persistence: Minimize data transfers on device reconnections or Controller restarts, with intelligent handling based on network type, power source, and other device specifics. This upgrade optimizes stability across Thread, WiFi, and Ethernet devices.
• Project Skeleton Generator: Quickly spin up your own project with pre-configured TypeScript settings and ready-to-go build options. Simply execute npm init @matter help if you have Node.js installed!
• Updated Package Structure: Introducing @matter/main as the primary NPM package, streamlining dependencies for Matter device development. Previous packages, like @project-chip/matter.js, remain available for compatibility and Controller-specific features, though future updates will migrate these.

Additionally, improvements across the library ensure enhanced stability and robustness.

Breaking Changes

Some minor breaking changes exist, particularly in types (e.g. ByteArray removal and adjustments to generic types). We recommend reviewing the changelog and resolving any build errors.

In line with the upcoming Matter 1.4, we have removed the EventList global attribute and certain methods in ClusterClient.

Users of the Shell application should also review the updated storage information.

Legacy API Notice

If you’re still using the “Legacy Device Building API,” we encourage you to upgrade. The new API is faster, feature-rich, and will be the focus of future enhancements. Reach out if you need support with the migration.

Get Involved

Update to matter.js 0.11 on npm, and share your experiences, feedback, and questions on GitHub or Discord. Our team is here to help!

For a complete list of changes, see the Release Notes below.

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