@matter/model

@matter/model - Matter Object Model

This folder contains an object model that captures Matter semantics as precisely as possible. It also includes support logic related to model manipulation and runtime validation.

Other representations of the Matter data model in matter.js offer similar representations with a different focus. The TLV models data with a focus on serialization and manipulation of instance values. The Cluster API models clusters in an operational form and in fact is partially generated from this model.

All references to Matter specification in the object model corpus refer collectively to Matter 1.3 Core Specification, Matter 1.3 Application Cluster Specification, and Matter 1.3 Device Library Specification.

Code structure

Subfolders support specific functions:

• elements/ - types describing the data model
• models/ - classes implementing an operational version of the data model
• standard/ - the full data model defined by the Matter Specification
• definitions/ - support enums and types
• aspects/ - parsers and ASTs for fields that utilize domain specific languages
• logic/ - various algorithms that operate on models

The datatypes in elements model Matter elements using TypeScript types. Elements are a formal component of the Matter specification that describe individual structures in the data model. Our element definitions are subtypes of BaseElement.

For each element definition, a class in models offers a concrete operational implementation. This is the API to use if you need to work with the data model beyond simple data modeling. Our models are all subtypes of Model.

MatterModel is the primary entrypoint to the API.

Usage

Obtain a working instance of the model:

import { MatterModel } from "@matter/model";
const matter = MatterModel.standard;

Retrieve standard definitions from the model:

import { DatatypeModel, ClusterModel } from "@matter/model";
const OnOffCluster = matter.get(ClusterModel, "OnOff");
const uint8 = matter.get(DatatypeModel, "uint8");

Iterate over attributes of a cluster:

for (const attribute of OnOffCluster.attributes) {
    // Do something
}

Implementation

The base model includes global datatypes defined by the Matter specification. We generate other elements of the standard model by merging models in the top-level models package.

To recreate the standard model files:

cd matter.js/codegen
npm run generate-model

Spec data model

Input model spec.ts is the data model defined by the Matter specification.

We generate spec.ts from the Matter specification documents. This ensures our definitions align with the specification and gives us detailed information unavailable elsewhere.

The spec generator is generate-spec.ts. To run:

cd matter.js/codegen
npm run generate-spec

Details we extract from the specification include standard element names, types and detailed documentation including cross references to specification documents. We also extract DSL-based definitions of Matter concepts such as conformance, constraints, etc.

Local data model

Input model local.ts defines elements that are unavailable (or incorrect) in the other models. This partial model is the result of editorial decisions by matter.js contributors.

CHIP data model

Model chip.ts is the CHIP data model. CHIP is Project CHIP's connectedhomeip repository. Originally this was the most robust open-source programmatic definition of Matter elements.

We generate chip.ts from CHIP definitions. This ensures our definitions align with CHIP's.

The CHIP generator is generate-chip. To run:

cd matter.js/codegen
npm run generate-chip

We still include the CHIP generator and model in our repository but no longer use it as input for the matter.js model.

Standard (final) data model

Unlike above data models, the standard data model in src/model/standard is part of the matter.js public API. This represents our best attempt at a complete Matter data model.

generate-model.ts creates this model by analyzing and combining elements from the models above.

To update the standard model:

cd matter.js/codegen
npm run generate-model

Cluster generation

One of the ways we use the Matter Object Model is to generate cluster implementations.

The cluster generator is generate-cluster.ts. To run:

cd matter.js/codegen
npm run generate

Note that this will rebuild the model (above) and the clusters. If you know the model is unchanged you can also just generate the clusters:

cd matter.js/codegen
npm run generate-clusters

This is generally only useful if you are modifying the cluster generation code or if you have already generated the model.

Ensuring correctness

Many of the scripts mentioned above generate models. It is important that these models are accurate.

To this end, there is extensive validation that every generator runs before output. Validation prints detailed information about the state of every element in the model.

Each validation error is associated with an error code. If there are errors, a summary of the errors is printed at the end of validation.

The final model is also validated during testing by MatterTest.

Automatic validation can't find every semantic error but it does ensure the resulting model is functional.

Changelog

0.11.9 (2024-12-11)

• @matter/node

  • Enhancement: Enhances the number assertations to only allow finite numbers
  • Enhancement: WindowCovering: Adds an internal property to disable the operational state and value management by the default implementation to allow device to handle this themselves
  • BREAKING: WindowCovering: supportsCalibration is moved from state property to an internal property
  • Fix: ColorControl: Do not try to convert color mode details if they are not defined
  • Fix: ColorControl: colorMode attribute needs to be defined if HS feature is not used because the default value 0 is else invalid

• @matter/protocol

  • Fix: Also retry next discovered address when a Channel establishment error for PASE occurs
  • Fix: Optimizes MDNS cache handling to prevent too early cache invalidation

• @matter/types

  • Enhancement: Deprecated fields are now also usable and just flagged as deprecated on generated code
  • Enhancement: Removes default value from attribute ColorMode of ColorControl cluster because feature specific enum value was used

• @project-chip/matter.js

  • Feature: Introduces PairedNode#triggerReconnect() method to trigger a reconnection
  • Enhancement: Considers a node in reconnection state that should be decommissioned as already factory reset
  • Enhancement: Optimizes reconnection handling in Controller API
  • Fix: Do not try to convert color mode details if they are not defined
  • Fix: Clusters generated for extensions of base clusters such as Alarm Base and Mode Base now include full details of extended types; in particular extended enums such as Mode Tag were previously insufficiently defined
  • BREAKING: In ContentLauncher cluster ParameterEnum is renamed to Parameter and Parameter is renamed to ParameterStruct

• @matter/model

  • Feature: New Scope component analyzes scope of a model, caches analysis results, and implements algorithms that require analysis to perform efficiently
  • Enhancement: Models that define datatypes now inherit from common ScopeModel base class
  • Fix: Extended enums and other types now report the full set of members via Scope#membersOf
  • BREAKING: ClusterModel and ValueModel properties members, activeMembers and conformantMembers are removed; use Scope#membersOf instead