CHANGELOG.md

Changelog for matter.js

This page shows a detailed overview of the changes between versions without the need to look into code, especially to see relevant changes while interfaces and features are still in flux.

The main work (all changes without a GitHub username in brackets in the below list) is done by the core team of this project completely in their free time (see their individual profiles for sponsoring options): @Apollon77 and @lauckhart

WORK IN PROGRESS

• @matter/testing

  • Enhancement: A certification step whose check could not be evaluated ends "unverified" and fails the run, unless the check states why the claim cannot be observed
  • Enhancement: Per-step certification PICS is evaluated on chip device flavors too, and result.json reports how many steps their PICS excluded
  • Fix: A certification run's result.json no longer reports a passing verdict for a run that failed
  • Fix: A failure to attach a certification run's device logs fails the run instead of only warning

• @matter/protocol

  • Enhancement: An interaction can be abandoned by the caller: ClientRequest.abort takes an AbortSignal, honored for read, write, invoke and subscribe

• @project-chip/matter.js

  • Enhancement: InteractionClient's read, write, invoke and subscribe options take an abort signal, forwarded to the interaction

• @matter/general

  • Enhancement: Transaction.lock() takes an exclusive lock on resources without a promise where they are free, and waits instead of throwing where another transaction holds them
  • Breaking: DnssdNames.Context.goodbyeProtectionWindow and DnssdNames.defaults.goodbyeProtectionWindow are now evictionDelay, and DnssdName.deleteRecord no longer takes an ifOlderThan argument
  • Enhancement: New MatterAggregateError.settleSeries() runs tasks in order, continuing past a failure, and reports the accumulated errors
  • Enhancement: A storage driver states how long a consumer may buffer dirty values via StorageDriver.writeCoalescingInterval, defaulting to 20 minutes; MemoryStorageDriver reports Instant
  • Enhancement: Transaction.Participant gains settled(), invoked once after every participant's pre-commit reports no further mutation and before any of them writes; throwing there rejects the commit, and writes and further participants are refused while it runs
  • Enhancement: Transaction.Participant gains conclusion(outcome), which runs once per commit cycle or rollback — including the commit phase two failure that skips both postCommit and rollback — and states whether the transaction committed, rolled back, or ended inconsistent; it runs with the transaction's locks released and further writes refused
  • Fix: A post-commit handler that rejects no longer detaches the remaining participants' post-commit work from the transaction
  • Adjustment: postCommit and the new conclusion reach the participants commit phase two dispatched, so a participant that joins while its values are written — as a store does — is now told the outcome; one that joins after phase two has passed it is not, having run no phase at all
  • Adjustment: A rollback completes once its participants have been told the outcome; where a participant reports asynchronously, a rollback that failed now rejects instead of throwing synchronously
  • Fix: Opening a namespace whose driver.json names an unregistered storage driver now throws NoProviderError instead of silently opening the existing data with a mismatched driver
  • Fix: DNS-SD ignores SRV records with port 0, an empty target or an out-of-range port
  • Fix: DNS-SD honors a goodbye that arrives shortly after the same record was re-announced
  • Fix: DNS-SD honors the mDNS cache-flush bit
  • Fix: DNS-SD resolution queries A/AAAA for the SRV target host instead of the service instance name
  • Fix: The Symbol.metadata polyfill no longer conflicts with lib.esnext.decorators in the published declarations

• @matter/model

  • Fix: A device type requiring several instances of one component, such as BatteryStorage with two electrical sensors and two power sources, no longer reports each instance as a duplicate of the others
  • Enhancement: The model build reports an instance number stated on a requirement other than a component device type, where the specification numbers nothing
  • Enhancement: A model element's extend() can remove an inherited quality, stated as !N in the quality definition; the removal survives further extension, and a definition that extends one carrying a removal may state the quality again
  • Fix: A quality definition given as an array of flags, such as ["N", "T"], loads those flags instead of reading as empty
  • Fix: A quality states which of its flags are not qualities, so a definition another rewrites still carries the flags it could not parse and the errors they raise
  • Fix: A value whose type derives from an enum, as a status code does, is judged by the integer type that holds it, so the numeric definition rules no longer skip it and a scene-capable attribute of such a type is no longer refused
  • Breaking: A provisional element is no longer mandatory; conformance following a P describes the conformance intended once the element leaves provisional state
  • Enhancement: FeatureSelectionErrors() assesses a cluster's selected features against the combinations its FeatureMap conformance disallows
  • Enhancement: FeatureSet.resolve() resolves a feature short code, title or camelized title to a short code
  • Enhancement: New EncodedConstraint() restates every bound of a constraint in the units the value is encoded in
  • Enhancement: New EncodedConstraint.bounds() reports which of a constraint's bounds state a number in encoding units and which state a unit with no known scale
  • Fix: The model build rejects a value stating a unit with no known scale, a fraction an integer type cannot hold, or a negative an unsigned type cannot hold
  • Fix: The model build rejects a bound or default stating a number outside the range of the integer type that carries it, such as the 300 of a 0 to 300 constraint on a uint8
  • Fix: The model build rejects a bound or default stating a magnitude beyond the range of the float type that carries it, such as the 1e300 of a single
  • Fix: A constraint bound keeps the magnitude it states: the parser accumulated digits as a number, so max 18446744073709551615 became 18446744073709552000 and a uint64 bound admitted values above the type. A bound a number cannot state exactly is now a bigint
  • Fix: A bitmap or enum value states its magnitude exactly, so a map64 value no longer loses precision passing through FieldValue.cast()
  • Breaking: FieldValue.numericValue() returns a bigint for a magnitude a number cannot state exactly, so a 64 bit bound and default keep what they say. FieldValue.countValue() is the number-valued form, for a length, a bit position or a count
  • Fix: Metatype.cast() to a float reads a number stated as text instead of refusing it
  • Fix: A default stating a number no integer form matches, such as 1e-3, is rejected instead of stored as the digits preceding the exponent
  • Fix: FieldValue.cast() treats "no value" as a value of every type, so an override removes a default rather than making the value invalid
  • Fix: A rejected default is reported as the value it states and the type that rejected it
  • Fix: FieldValue.cast() reads a duration, which it previously rejected whatever the value stated
  • Fix: ValidateModel() no longer writes a normalized default to a final model, which threw because a final model is frozen; it reports on such a model without normalizing it
  • Fix: A percentage on a type other than percent or percent100ths no longer resolves to the printed number as though it were already encoded
  • Fix: A constraint bound's unit takes its scale from the types the value derives from, not from its own type name alone
  • Enhancement: New Scope.isMandatory() tells whether a member is mandatory under a schema's supported features, and the new MandatoryDefaultValue() computes the value such a member assumes when no real value exists (schema default, else the specification's fallback value, recursing into structs) — the basis for what an unreported client node attribute reads, usable wherever schema-derived fallback values are needed; SelectDefaultValue() exposes the shallow variant used for server state seeding
  • Fix: A cluster's feature table no longer selects features; a feature the specification makes unconditionally mandatory is always selected
  • Fix: Feature selection records against operationalIsSupported so a feature's default conveys only the specification's fallback value
  • Fix: A feature mandated by any of several alternatives, such as DoorLock.User, is now reported as required
  • Fix: A feature conformance that is a bracketed disjunction, such as [VDO | SNP], is illegal only when none of its alternatives is selected
  • Fix: A choice set whose members are gated on a conformance expression, such as [!PA].a or [PS].b, requires a selection only where the gate admits a member, and rejects a member the gate excludes
  • Fix: An entry of an otherwise conformance applies only where the entries preceding it do not, and a feature is disallowed where no entry applies
  • Fix: A choice set whose members are all provisional, such as the Groupcast and AmbientContextSensing feature sets, no longer requires a selection
  • Fix: A boolean whose specification default is 0 now defaults to false instead of true
  • Fix: A fractional temperature or percentage default keeps its fraction
  • Fix: The bits of a bitmap carry the conformance the specification states for them
  • Fix: An event of a derived cluster takes the priority of the event it derives from
  • Fix: A derived cluster's changes to the fields of an inherited struct now apply correctly
  • Fix: An element whose access states a privilege but neither read nor write, such as JointFabricAdministrator.AdministratorFabricIndex, is read-only (but formally Spec-incompliant)
  • Fix: A constraint that bounds a value by a field named like a constraint keyword, such as the Min of ClosureDimension's range structs, survives serialization

• @matter/node

  • Fix: Stop and StopWithOnOff set RemainingTime to zero and report it, including where the application manages transitions and stated an end time
  • Fix: StopMoveStep and MoveColor with both rates zero set Color Control's RemainingTime to zero and report it, and clear the end time stated where the application manages transitions. StopMoveStep leaves the remaining time alone while a color loop runs, since a color loop ends only on ColorLoopSet
  • Fix: A Color Control color mode switch no longer discards the promise from stopAllColorMovement(), so an asynchronous override of it completes before the color values are converted
  • Breaking: The transitionEndTimeMs state field on LevelControlServer and ColorControlServer is now transitionEndTime, a Timestamp; the value is unchanged but the name and type are not
  • Fix: MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff build their options from the Options attribute and the request's mask and override, so CoupleColorTempToLevel couples color temperature to the level for them as it already did for MoveToLevel, Move and Step
  • Fix: StopWithOnOff stops a transition on a device that is off; the ExecuteIfOff option gates the commands without On/Off only
  • Fix: MoveWithOnOff and StepWithOnOff turn the device off when the level they reach is the minimum, and leave a device that is off alone when the level moves down
  • Fix: A level change that couples On/Off or color temperature waits for a transaction holding those clusters instead of failing
  • Behavior: LevelControlServer.couple() takes the target level as a third argument, which is what decides whether the device turns off; an override that omits it loses that decision
  • Breaking: Default server exports no longer inherit the features their base implementation enables internally.
    • ColorControlServer, DoorLockServer, ElectricalEnergyMeasurementServer, LevelControlServer, ModeSelectServer, PowerSourceServer, PowerTopologyServer, SmokeCoAlarmServer, SwitchServer, ThermostatServer and WindowCoveringServer now select no features. Select the features your device supports with .with(...) or use the DeviceType specific Requirement definitions of these clusters which automatically enable the needed features for the device type
    • PowerSourceServer, PowerTopologyServer, SmokeCoAlarmServer, SwitchServer, ThermostatServer, WindowCoveringServer and ElectricalEnergyMeasurementServer now require a selection to be added to an endpoint at all. The DoorLockDevice, SpeakerDevice and ModeSelectDevice device types alias these exports, so their clusters also select no features and advertise a different FeatureMap.
    • Verify the feature set of every device you compose. Persisted cluster state resets once for affected devices because it is keyed by feature selection
  • Breaking: Discovery.Options.scannerFilter is removed; state the transports to discover on with discoveryCapabilities
  • Breaking: discoveryCapabilities moved from CommissioningClient.CommissioningOptions to Discovery.Options; it reaches discovery through ServerNode.peers.commission() and peers.discover(), and never had an effect on ClientNode.commission(). Code that declares its commissioning options as CommissioningClient.CommissioningOptions and sets discoveryCapabilities no longer compiles - declare them as CommissioningDiscovery.Options instead
  • Breaking: A LongIdleTimeSupport ICD must select CheckInProtocolSupport and UserActiveModeTrigger
  • Breaking: A node that accepts more than one path per invoke must select the General Diagnostics DataModelTest feature
  • Breaking: An unreported client node attribute reads its schema default, else the specification's fallback value for its type, when the attribute is mandatory under the peer's supported features, and undefined otherwise — regardless of the peer's AttributeList (an enum attribute reads undefined, as the specification defines its fallback as manufacturer-specific). The value is a detached copy, so mutating a struct or list read from an unreported attribute does not write through
  • Breaking: Configured options, environment variables, and state-class field initializers no longer seed a client node's cluster state; the peer's reports are the only source of values
  • Breaking: Adding a server cluster to an endpoint fails when its selected features violate the conformance of its FeatureMap
  • Breaking: A local write or invoke rejects a bitmap bit whose conformance the cluster's selected features do not satisfy, wherever the bitmap appears — an attribute, a command field, a struct member or an event field. So LevelControl.Options.ExecuteIfOff (also as the optionsMask or optionsOverride of MoveToLevel, Move, Step and Stop) needs Lighting or OnOff, a ColorControl.ColorCapabilities bit needs its color feature, a WindowCovering.ConfigStatus position or encoder bit needs the matching position-aware feature, Thermostat.RemoteSensing.Occupancy needs Occupancy, a closure's latch control mode needs Latching, and a Messages.MessageControl bit needs its messaging feature. Only a bit the value sets is judged, only what the conformance decides without a record around it, and a write or invoke carrying a remote subject stays permissive
  • Breaking: Provisional elements are no longer implemented by default; supply a state value or use ClusterBehavior.enable() to implement one
  • Breaking: SoftwareUpdateManager.addUpdateConsent() and forceUpdate() take the update as an object instead of three positional arguments, so it can carry per-update options
  • Breaking: Ensure that changing any attribute of a client node sends a write to the peer; an attribute the peer's cluster type cannot express, including the global attributes, is declined locally with UnsupportedWrite or UnsupportedAttribute
  • Breaking: A commissionable advertisement stating vendor or product ID 0 now reports it absent (undefined)
  • Removed: StructManager.assertDirectReadAuthorized() and the direct-read authorization it backed, unused since the legacy cluster API was dropped
  • Deprecation: ClientNodeInteraction.localStateFor() is scheduled for removal in 0.19 together with the legacy controller API
  • Feature: Added ServerNode.peers.commissioned returning the commissioned ClientNodes
  • Feature: Added ClientNode.disable()/enable() to persistently disable/enable a commissioned peer
  • Feature: Added a ClientNode connection-state engine — lifecycle.connectionState/connectionStateChanged/isConnected and the NodeConnectionState enum
  • Feature: Added ClientNodeLifecycle.isSeeded and the seeded event, indicating a peer node's structure has been read from the device at least once
  • Feature: Added Behaviors.forCluster(clusterId) to resolve a cluster behavior type by numeric cluster id
  • Feature: A behavior reports an attribute it computes on read via the new protected Behavior.markChanged()
  • Feature: Added openBasicCommissioningWindow/openEnhancedCommissioningWindow on CommissioningClient/ClientNode to open a commissioning window on a commissioned peer
  • Feature: Added split/delegated commissioning — CommissioningClient.CommissioningOptions.finalizeCommissioning plus ServerNode.peers.completeCommissioning(nodeId, discoveryData?, options?)
  • Feature: Added NetworkServer.autoStartCommissionedPeers (default true) to opt out of auto-starting commissioned peers when the node goes online
  • Enhancement: Commissioning accepts caseConnectionTimeout, bounding how long it waits for the operational CASE connection that follows it
  • Enhancement: SoftwareUpdateManager caps the BDX block size for OTA transfers via maxBdxBlockSize and overrides their MRP retransmission margin via bdxAdditionalMrpDelay, either generally in its state or per update when giving consent
  • Enhancement: network.profiles accepts bdxAdditionalMrpDelay
  • Enhancement: A node's commissioning state records the hostname the device's SRV record names, alongside its addresses
  • Enhancement: Discovery reports at notice level, naming an installed BLE scanner it was not asked to use, and reports a discovery that asks for BLE where BLE is not enabled
  • Enhancement: Discovery warns where no scanner takes part in it at all
  • Enhancement: Discovery.Options accepts discoveryCapabilities to select the transports to discover on, so a caller no longer builds a scannerFilter for it
  • Adjustment: A node with commissioning disabled (e.g. a controller) now binds an ephemeral operational port instead of the standard Matter port (5540) when NetworkServer.port is unset; commissionable nodes still default to 5540 and an explicit port is always honored
  • Adjustment: A device commissioning passes over because its advertised vendor or product contradicts the onboarding payload is reported at notice level
  • Adjustment: A commissioned peer's fabric label is new reconciled to the controller's once after its subscription is first established on start by ClientNode
  • Adjustment: NetworkServer.State.clientCacheFlushInterval defaults to the storage driver's writeCoalescingInterval instead of a fixed 20 minutes; set it to Instant to persist every change immediately
  • Adjustment: A SoftwareUpdateManager.State.announcementInterval of Instant disables OTA provider announcements
  • Fix: A constraint whose bound carries a unit, such as the 0.01% to 100.00% of a percent100ths value, is enforced in the units the value is encoded in
  • Fix: A window covering with no Lift feature no longer states a lift movement direction in ConfigStatus
  • Fix: Struct validation resolves a member stored under its TLV tag number, so a constraint violation there is caught and a mandatory member present only at its id no longer raises a conformance error
  • Fix: Thermostat.Presets reports to subscribers and advances the cluster's data version when the presets change
  • Fix: A local write of Thermostat.Presets is stored instead of silently discarded, and an invalid one rejects the caller's write
  • Fix: Thermostat.Presets is validated and staged for an atomic write on every endpoint that selects the Presets feature, not only where the application passed a presets value; presets such an endpoint stored before are ignored
  • Fix: A preset write is refused for referencing the active preset only when it removes that preset; a thermostat starting with an ActivePresetHandle that names no preset stores null instead of refusing to start
  • Fix: A preset write that would store a preset without a handle is refused, including where an application observer removed the handle the thermostat issued
  • Fix: A preset handle the thermostat generates is persisted, so it still addresses the preset after a restart
  • Fix: Two presets sharing a scenario and carrying no name are refused on an atomic write, as they already were on a local one
  • Fix: A state class serving an attribute from an accessor sees the values of the writing transaction
  • Fix: A write refused by pre-commit validation is announced again when the same value is written a second time on one transaction
  • Fix: A report for a quieter attribute a behavior computes on read carries an advanced cluster data version, so a subscription no longer discards it as one it already has
  • Fix: LevelControl.RemainingTime and ColorControl.RemainingTime report the time left in a transition; the attribute read 0 on any endpoint whose application did not itself pass a remainingTime value
  • Fix: endpoints.size no longer double-counts the root endpoint
  • Fix: The log line for an opened commissioning window states the timeout as a duration, not as a millisecond count labelled seconds
  • Fix: A commissioned peer's connection state leaves Connected as soon as its last operational session is lost
  • Fix: ChangeNotificationService event occurrences carry a timestampKind naming which of the four wire variants the timestamp is (epoch, system, epoch-delta, system-delta), so a consumer forwarding an event no longer has to guess its clock or whether it is absolute or a delta from the previous event
  • Fix: IdentifyServer no longer offers the optional TriggerEffect command unless the device type requires it, an own command implementation has been added via an override or suppression is disabled; IdentifyServer.enable({ commands: { triggerEffect: true } }), IdentifyServer.alter({ commands: { triggerEffect: { optional: false } } }) and an override of suppressTriggerEffect() also offer it
  • Fix: ClusterBehavior.with() rejects a feature the cluster does not define
  • Fix: Client node values persisted under property names by earlier versions are migrated to their attribute id on load, so they stay readable
  • Fix: Writing a fabric-scoped list entry that stems from a cluster whose schema could not be resolved no longer produces two conflicting fabricIndex fields
  • Fix: A rejected write to an attribute served by dynamic properties restores the previous value instead of deleting the property, and a rejected write to a previously absent attribute leaves no slot behind instead of one holding undefined
  • Fix: Factory reset removes commissioned peers and the certificate authority's key material; a peer that cannot be torn down no longer blocks the reset
  • Fix: A client node's storage metadata no longer surfaces as state: a peer report that only bumps the data version emits no change notification, and __version__ no longer appears among the changed properties or in cluster state
  • Fix: A peer that cannot be loaded, such as one whose fabric is missing locally, is reported with its actual cause instead of escaping as an unhandled rejection
  • Fix: Commissioning passes over a discovered device whose advertised vendor or product ID disagrees with the onboarding payload's
  • Fix: A level change that couples to On/Off no longer leaves the coupling blocked when its transaction rolls back
  • Fix: A cluster's feature selection is recorded as persisted only once the store accepted the values it travels with, so a failed write no longer leaves a later feature change undetected
  • Fix: Validating a state class that serves properties dynamically passes it the endpoint, as every other caller does
  • Fix: A peer that reports a cluster ID outside the ranges the specification allows no longer fails node initialization
  • Adjustment: A cluster ID is validated when a server behavior is created rather than when a cluster namespace is built, so a peer's ID stays as reported
  • Fix: Two peer clusters whose attribute or command IDs differ by 32 no longer share one generated behavior

• @matter/matter.js

  • Adjustment: The duplicate "BLE is not enabled" log lines are gone; a node reports missing BLE support once, where it decides on it

• @matter/nodejs

  • Breaking: FileStorageDriver's constructor no longer accepts a clear argument; clearing is handled by StorageService
  • Adjustment: SqliteStorageDriver and JsonFileStorageDriver report a writeCoalescingInterval of Instant, so client cache data is no longer held back for 20 minutes on these drivers
  • Fix: Ensure that --storage-clear/MATTER_STORAGE_CLEAR is honored again and clears the storage on start

• @matter/nodejs-ble

  • Enhancement: Waiting for the Bluetooth adapter to power on before scanning or advertising is reported at notice level, naming what to check, and its start is reported once the adapter is up
  • Fix: A connection attempt that BLE reports as failed is retried instead of failing commissioning on the first try
  • Fix: A peripheral whose connection attempt failed is no longer rejected as unusable for the lifetime of the process
  • Fix: Giving up on a peripheral reports the last connection failure as cause
  • Fix: A disconnect that never completes no longer leaves the channel request pending forever
  • Fix: Aborting a BLE connection attempt now stops its retries and releases a link the attempt already established
  • Fix: Stopping an advertisement that was still waiting for the Bluetooth adapter retracts it, so the adapter powering on no longer starts an advertisement that was already given up on

• @matter/nodejs-shell

  • Fix: A cluster whose ID lies outside the ranges the specification allows is addressable instead of raising an error
  • Feature: Added --cleanup-legacy-storage to irreversibly remove the leftover pre-0.16 storage artifacts once they have been migrated to the current format
  • Fix: Attribute changes log one line per attribute, naming the attribute, instead of one line per cluster report carrying every changed attribute of that report
  • Fix: Attribute, event and connection-state log lines are recognized by the web UI again, so node tiles and device values update; event lines name the peer and render their timestamp according to the wire variant the device sent

• @matter/protocol

  • Deprecation: The legacy DecodedDataReport / Decoded{Attribute,Event}Report* types and the normalize* / normalizeAndDecode* helpers now announce removal in 0.19 instead of 0.18
  • Deprecation: The legacy ClusterType command request surface (Invoke.LegacyCommandRequest, Specifier.ClusterTypeCommand) and SessionManager.owner are scheduled for removal in 0.19
  • Enhancement: Network profiles accept a separate bdxAdditionalMrpDelay for bulk transfer, defaulting to the profile's messaging margin
  • Enhancement: New CertificateAuthority.erase() discards the authority's key material, persisted and in memory
  • Enhancement: A discovered commissionable device reports the hostname its SRV record names
  • Enhancement: Commissioning accepts caseConnectionTimeout, bounding how long it waits for the operational CASE connection that follows it; defaults to the previous fixed 4m15s
  • Fix: Cancelling BLE commissioning aborts the in-flight channel open
  • Fix: A concrete subscription path is reported only when that attribute changed; it was previously reported whenever any other attribute of the same cluster changed
  • Fix: A subscription's maxIntervalCeiling is transmitted exactly as requested; jitter now applies only when we derive the ceiling ourselves
  • Fix: mDNS advertisements set the cache-flush bit on the SRV, TXT and address records unique to the node
  • Fix: mDNS known-answer suppression compares what identifies a record
  • Fix: mDNS known-answer suppression only applies while more than half the known answer's lifetime remains
  • Fix: an mDNS response drops the cache-flush bit where it no longer carries the whole record set
  • Fix: a unicast mDNS response does not carry the cache-flush bit

• @matter/react-native

  • Fix: The storage.clear variable now clears the storage on start as it does on Node.js

• @matter/types

  • Adjustment: ClusterType() no longer validates the cluster ID of the model it is given
  • Breaking: ModelBounds.createNumberBounds() states a bound as a bigint where it lies beyond the safe integers, and states both min and max where it previously omitted an absent bound; createLengthBounds() still states a number, as a length counts what a message can carry
  • Breaking: TlvNumericSchema.bound() states the base type of the schema it bounds in baseTypeMin and baseTypeMax, where it previously stated the bound; the bound is stated by min and max. The class gains a protected constrain()
  • Breaking: A bounded 64 bit schema states its datatype again, so a legacy ClusterType() cluster derives the type and constraint of such an attribute instead of neither, and enforces a range it previously left open
  • Fix: A nullable 64 bit integer reserves the value that encodes null from its type rather than from its constraint, so it neither refuses the extreme its constraint states nor admits the sentinel. ElectricalPowerMeasurement's Frequency and PowerFactor refused their own maximum and minimum
  • Breaking: TlvNumericSchema.bound() refuses a bound stated as a number that the number holds only approximately, such as 9223372036854775807 on a uint64, which rounded to 2^63 and admitted a value above the stated maximum. State such a bound as a bigint
  • Breaking: Provisional cluster elements are now typed as optional rather than always present
  • Breaking: An onboarding payload's vendor and product ID are reported absent (undefined) where it states none instead of 0
  • Feature: Added the ClusterLookup namespace for cluster/attribute/command/event name↔id resolution (optional MatterModel for custom clusters)
  • Deprecation: The ClusterType() factory compat layer (RetiredClusterType, RetiredElements, the TLV element reverse mapping) is scheduled for removal in 0.19
  • Deprecation: The generated Cluster, Complete and <Name>Cluster aliases and the ClusterType.WithCompat with() shim are scheduled for removal in 0.19
  • Fix: Cluster.with() rejects a feature the cluster does not define and returns one frozen namespace per selection
  • Fix: An onboarding payload carrying a vendor ID past the last test vendor, or a product ID of 0 beside a real vendor ID, is now rejected
  • Fix: Fixes Base38 decoding which rejected payloads whose length was a multiple of three bytes
  • Fix: A manual pairing code whose VID_PID_PRESENT bit disagrees with its length is now rejected

• @matter/testing

  • Enhancement: certTest() defines controller-side certification tests with per-step PICS gating, device-log expectations, and evidence recording; devices run as chip apps (docker or local binary) or matter.js test apps, selected via MATTER_CERT_DEVICE
  • Enhancement: A cert test step can declare itself notApplicable, recording it as skipped with a reason instead of running it
  • Enhancement: PromptDrivenPythonTest drives chip python test scripts that prompt for manual commissioning steps
  • Enhancement: matter-test's post-test clean-exit grace period is overridable via MATTER_TEST_SHUTDOWN_TIMEOUT_MS
  • Enhancement: MATTER_CHIP_BINS_SOURCE=cert-bins selects project-chip's official connectedhomeip/chip-cert-bins binaries for the classic yaml/python tests and chip-local cert-test subjects
  • Enhancement: A cert test's attached device/controller logs now carry a banner marking each step's start and end, alongside its verdict
  • Enhancement: Certification controller tests run against a controller × device matrix, adding chip-tool as a second controller alongside matter.js's own
  • Breaking: Removed the unused PicsFile.Values type; use PicsValues
  • Enhancement: New PicsFile.with() returns a copy of a PICS file with values overridden
  • Fix: PromptDrivenPythonTest now fails a run in which none of its prompt handlers fired, instead of trusting the script's own verdict
  • Enhancement: A python-wrapped cert test's evidence attaches the script's own output alongside the controller log
  • Fix: A composite PicsSource no longer patches the PICS file cached for its first source
  • Fix: TC-SC-3.5 turns off PICS_SDK_CI_ONLY so the script prompts for commissioning instead of acting as its own commissioner, and drives whichever controller MATTER_CERT_CONTROLLER selects
  • Enhancement: A cert test's controller reads and subscribes to events via CertNodeApi.readEvents()/subscribeEvents(), on both the matter.js and the chip-tool controller
  • Enhancement: A cert test's controller sends an invoke or attribute write as a timed interaction via CertNodeApi's timedInteractionTimeoutMs, on both the matter.js and the chip-tool controller
  • Enhancement: A cert test's controller invokes several commands in one request via CertNodeApi.invokeBatch(), which reports each answer in arrival order
  • Enhancement: certTest() accepts appVariant to run a variant of the device app CHIP builds as its own binary, such as nlfaultinject
  • Enhancement: A cert test declares a cluster outside the Matter specification with the model annotations and registerCertCustomCluster(), and both controllers then address it
  • Fix: A cert test's own PICS expression now gates the test, which previously only tinted its label in the report; a controller declares the client capabilities the device's PICS file cannot, and those overlay it
  • Enhancement: certTest() accepts test-level flavors, skipping a test whose device cannot exist on the run's flavor before the device starts
  • Enhancement: A cert test's controller commissions from a QR onboarding payload via CommissioningTarget.qrPairingCode, on both the matter.js and the chip-tool controller

• @project-chip/matter.js

  • Deprecation: Every class, type, and function of the legacy controller API is now marked deprecated and scheduled for removal in 0.19; use the ServerNode.peers / ClientNode API of @matter/node instead
  • Feature: CommissioningController accepts clientCacheFlushInterval to override how long node state is buffered before it is written to storage

0.17.9 (2026-08-06)

• @matter/protocol

  • Enhancement: A BDX exchange retransmits its pending message early when a duplicate proves the peer is awake and still waiting for it
  • Fix: The peer's medium-specific MRP retransmission margin now applies to peer-initiated exchanges (e.g. subscription data reports) and to exchanges created without peer context
  • Fix: BDX retransmission intervals are capped so the whole MRP schedule fits inside the peer's BDX response budget, which acknowledgements do not extend; the peer's idle cadence does not raise the cap, since a peer holding an open exchange is in active mode
  • Fix: A retransmission timer is no longer armed for a message that was acknowledged while an earlier transmission of it was still in flight, which left the timer running unreferenced
  • Fix: Grouped PeerTimingParameters (kickRestartCooldown, addressChangeProbeCooldown) merge field-wise, so overriding one member keeps its siblings
  • Fix: Ensure that an unsecured session created for an inbound message is discarded when no protocol handler adopts it
  • Fix: Ensure that closed exchanges are removed from their session for all session types
  • Fix: Ensure that a session releases its message channel when the transport owns the underlying channel, so the channel address observer of PASE, CASE and discarded inbound sessions is removed
  • Fix: Ensure that the end of a session is logged also when its channel was detached before; channel detach is now logged as debug

• @matter/node

  • Enhancement: network.timing accepts the kick and address-change parameters
  • Enhancement: Managed state derives a member's container key through one shared implementation (no functional change)
  • Fix: Client node state reads and writes struct- and list-valued fields nested inside an attribute value
  • Fix: Client node state reads struct- and list-valued attributes of a cluster implementation that supplies properties dynamically

0.17.8 (2026-08-02)

• @matter/general

  • Fix: isIPv4 no longer misclassifies a link-local IPv6 address as IPv4 when its zone index contains a dot, e.g. a Linux VLAN interface name like eth0.100

• @matter/node

  • Fix: Closing a session from the stack of an in-flight subscription report no longer deadlocks the session in its closing state
  • Fix: A subscription report that goes unanswered abandons the subscription instead of declaring the controller lost and closing every session with it
  • Fix: Subscriptions now give up after repeated send failures; the check never matched the error MRP exhaustion raises
  • Fix: Re-establishing former subscriptions stops for a peer that is unreachable instead of spending a full retransmission window on each of its subscriptions
  • Fix: The exchange opened to re-establish a former subscription is now closed

• @matter/nodejs-ble

  • Enhancement: BLE disconnect logs now include the noble disconnect reason with its HCI status text

• @matter/node

  • Enhancement: SoftwareUpdateManager.queuedUpdates reports transferred bytes and transfer size of a running BDX transfer
  • Fix: OTA updates are no longer reset as stalled while their BDX transfer is still moving data
  • Fix: The in-progress entry of an OTA download is no longer dropped while its BDX transfer is still running
  • Fix: A BDX session opened for a retry within the same query cycle is tracked like the first one

• @matter/protocol

  • Enhancement: BdxSession exposes transferredBytes and dataLength

• @matter/nodejs-shell

  • Fix: nodes ota check|download|apply and ota download now default to a --mode auto that follows the config ota-test-images setting instead of always querying the production DCL only
  • Fix: config ota-test-images set applies immediately instead of requiring a shell restart
  • Fix: ota add accepts http(s) URLs instead of rejecting them before its download path was reached

• @matter/protocol

  • Enhancement: Subscription.isCanceledByPeer is now isTerminated, covering both a peer cancellation and our own giving up
  • Enhancement: MessageExchange.Options.suppressPeerLoss waives peer-loss inference for every operation on an exchange
  • Fix: Peer loss reported for a commissioned peer now conveys the exchange that failed
  • Fix: A session nearing message counter rollover now winds down as its own task instead of on the stack of the send that consumed the counter
  • Fix: A peer that keeps establishing sessions no longer accumulates them without bound; the least recently used beyond five are closed

0.17.7 (2026-07-27)

• @matter/general

  • Fix: Heap now stores each item at most once and maintains its position index eagerly, so deleting an item added after an earlier deletion works reliably

• @matter/model

  • Enhancement: MatterModel.withClusters() returns a copy of a model with clusters added or replaced by ID

• @matter/node

  • Enhancement: Controllers accept a custom Matter model via the matter option so a commissioned peer's custom or extended cluster elements resolve to real names instead of synthetic attr$…/command$… identifiers
  • Enhancement: SoftwareUpdateManager.checkForUpdates() forces an immediate OTA update check and cleanup of obsolete stored updates
  • Enhancement: Custom server session intervals (idle/active interval, active threshold) are now configurable via sessions.intervals
  • Fix: Optimize Cluster data updates when structures change for ClientNodes
  • Fix: Prevent subscriptions from being activated on a closing session
  • Fix: Thermostat adjusts the coupled setpoint limit to preserve the AutoMode deadband instead of rejecting the write
  • Fix: Choice conformance no longer requires a member gated by an inapplicable condition (e.g. [ICTL].b+ when the feature is unsupported)
  • Fix: Support the != (not-equal) operator in value conformance expressions
  • Fix: Ensure FabricAuthority is fully constructed before it is used in the WebRTC Transport Requestor, OTA Software Update Provider, and Software Update clusters
  • Fix: Consider existing node IDs when determining the next node ID to commission
  • Fix: Determine the network medium of nodes without a Network Commissioning cluster from the WiFi or Thread Network Diagnostics cluster on their root endpoint

• @matter/nodejs

  • Fix: Ensure the namespace directory exists before the sqlite storage driver opens the database

• @matter/protocol

  • Enhancement: Connect to a newly discovered address as soon as it supersedes the previously cached address instead of waiting out the connection retry delay
  • Fix: Ensure the commissioning failsafe timer stays within the device's maximum cumulative failsafe
  • Fix: Parallel PASE commissioning now uses the won session immediately instead of blocking on losing attempts' cleanup, which could let the won session expire at the device failsafe before use
  • Fix: A device dropped during parallel PASE for invalid credentials no longer accepts a slower successful attempt on another of its addresses
  • Fix: Extend the handling of non-compliant devices that drop the commissioning connection when network details are added (AddOrUpdateWiFi/AddOrUpdateThread), not only on ConnectNetwork, treating them as non-concurrent and proceeding directly to operational discovery
  • Fix: Clear group message reception (replay) state when a group key set is removed or rewritten, so valid messages are not rejected as replays after a key set is re-provisioned with a reused epoch key
  • Fix: A subscription reaching its timeout at the current instant now expires instead of rescheduling a zero-length timeout repeatedly

• @matter/testing

  • Fix: Mock timers implement the Timer.interval accessor, so assignments take effect on the next start, reads no longer return undefined and out-of-range intervals are rejected as in production
  • Fix: Mock timers report isPeriodic correctly and restart instead of double-arming when started while running
  • Fix: MockTime.advance() fails with a diagnostic instead of spinning when a timer rearms without letting mock time advance

0.17.6 (2026-07-16)

• @matter/general

  • Fix: Observable.detachObservers() now disarms the source observable (including active async iteration) and attachObservers() preserves once-semantics of the transferred observers
  • Fix: Async iteration over an Observable now delivers emitted values (previously it ended immediately) and terminates cleanly on dispose instead of spinning

• @matter/node

  • Enhancement: After an approved OTA update, the controller re-subscribes to a rebooted device that does not persist subscriptions within ~30s instead of waiting out the previous subscription's timeout
  • Fix: Attributes added when a peer cluster gains features at runtime are now readable
  • Fix: Event listeners now survive a behavior drop/re-inject cycle (observer transplant was silently dropping them) and the rebuilt events surface is correctly wired for event reporting

• @matter/nodejs-ble

  • Fix: Update noble dependency to fix some DBUS related issues

• @matter/protocol

  • Fix: Peer session selection now prefers the session the peer was last heard from and skips peer-lost sessions, so a dead session still retransmitting no longer outranks a freshly established one
  • Fix: BleScanner.close() no longer orphans a timeout-less continuous discovery, which previously blocked shutdown when a BLE commission was in flight
  • Fix: Do not drop reordered unsecured/PASE messages with a counter just below the first one seen as duplicates

• @matter/thread-br-client

  • Fix: Use the correct MeshCoP commissioner keep-alive URI (c/ca) and resign the session with a rejecting keep-alive instead of a nonexistent c/cr release URI that Border Routers answered with 4.04

• @matter/types

  • Fix: ObjectSchema.injectField/removeField no longer crash on fabric-scoped commands that omit an optional nested struct field

0.17.5 (2026-07-13)

• @matter/*:

  • Upgraded to Matter specification version 1.6.0. Newly-mandatory attributes are seeded with conservative defaults, and new/provisional clusters stay behind feature guards, so existing code should remain backward compatible

• @matter/general

  • Enhancement: deepCopy now clones Set and Map values instead of turning them into empty objects
  • Enhancement: Added Timestamp.toMicroseconds and clarified Time.nowUs as a high-resolution millisecond timestamp (now sub-millisecond precise), not a microsecond value

• @matter/model

  • Enhancement: Added cluster-variance rules for the Matter 1.6 conformance idioms
  • Fix: Initialize class metadata via Object.defineProperty so importing matter.js no longer throws when Function.prototype[Symbol.metadata] is non-writable (TC39 decorator-metadata / core-js polyfill, reported by Sylvan86)

• @matter/node

  • Feature: Server-side Intermittently Connected Device (ICD) support via the IcdManagement cluster: client registration/unregistration, StayActiveRequest, SIT/LIT operating modes with DSLS, and Check-In delivery to registered clients
  • Feature: Controller-side ICD support: automatic client registration with multi-admin protection, Check-In handling, and peer wakefulness/availability tracking for sleepy LIT devices
  • Feature: Implemented the newly-mandatory Matter 1.6 diagnostics attributes
  • Feature: Enabled the BooleanState StateChange event by default via the new feature
  • Feature: Emit the OccupancySensing OccupancyChanged event automatically when the OccupancyEvent feature is enabled
  • Feature: Advertise the BasicInformation CapabilityMinima defaults and enforce the read/subscribe path-count ceiling
  • Feature: Added a ConfigurationVersion increment convenience API and reject ConfigurationVersion bumps on bridged devices that do not enable the attribute
  • Feature: Added a configurationVersionChanged endpoint/node lifecycle event that fires when a client peer's ConfigurationVersion changes (BasicInformation on the node, BridgedDeviceBasicInformation on bridged endpoints)
  • Feature: Preparations for Groupcast support (still provisional in Matter 1.6.0)
  • Feature: Adds a default WebRtcTransportRequestorServer implementation with session tracking, fabric/peer identity checks on commands, transport events, and ACL auto-install for the requestor cluster
  • Fix: Prune GroupKeyMap entries when a key set is removed
  • Fix: Tag manufacturer-extension (MEI) attributes with WildcardSkipCustomElements so wildcard reads skip them
  • Fix: Manufacturer-specific attributes in standard clusters are now filtered by the WildcardSkipCustomElements flag instead of WildcardSkipGlobalAttributes during wildcard path expansion
  • Fix: Signal subscription "alive" when a sustained subscription (re)establishes so peer structure changes are surfaced immediately instead of at the next periodic report
  • Fix: Signal subscription "alive" on empty max-interval keepalive reports, so a quiet peer keeps refreshing its liveness signal
  • Fix: Bound node shutdown so an interaction parked awaiting an MRP ack from an unresponsive peer (e.g. a restarted ICD) can no longer hang close
  • Fix: Also respect local (imported/stored) OTA images when checking for available updates, not only the DCL
  • Fix: Harden endpoint structure processing against non-compliant peers that omit mandatory Descriptor list attributes, treating an absent list as empty instead of crashing

• @matter/nodejs-shell

  • Feature: Added icd shell commands to register/unregister/stay-active ICD clients and inspect/watch node wakefulness and availability
  • Fix: Close a path-containment gap in the optional web server that let requests reach sibling directories sharing the web-root name prefix, and resolve symlinks before serving (reported by tonghuaroot)
  • Fix: Bind the WebSocket/web server to loopback (127.0.0.1) by default instead of all interfaces; added a --webAddress option to choose the listen address

• @matter/protocol

  • Feature: ICD Check-In protocol: CheckInMessage codec with counter-validation and replay protection, Check-In sender, and controller-side peer wakefulness scheduling
  • Enhancement: Worst-case MRP response-time now accounts for the sender's fixed-backoff/additional-delay pad
  • Enhancement: WiFi peers now use a dedicated network profile with a 1s additive MRP retransmission margin, selected by operational medium for dual-stack nodes
  • Feature: Preparations for Groupcast support (provisional in Matter 1.6.0)
  • Feature: Source the client read path-count hint from the peer's advertised CapabilityMinima floors
  • Feature: Added a Thread operational dataset codec (OperationalDataset, SecurityPolicy, MeshCoP TLV helpers)
  • Feature: Thread commissioning derives the network name from the operational dataset when none is supplied, and declines when a supplied name contradicts the dataset
  • Enhancement: Optimized Subscription minIntervalFloor: now defaults to 0s; only Thread devices older than Matter 1.3.0 keep a 1s floor, and any node with a Generic Switch endpoint opts back into 0s for faster switch events
  • Fix: Single-command invokes no longer sending a commandRef on the wire nor require one echoed in the response
  • Fix: Single commands skip auto-batching when the peer accepts only one path per invoke or the response is suppressed
  • Fix: Closing a client interaction aborts an in-flight command batch instead of awaiting its response
  • Fix: Ensures group messaging works correctly when multiple key sets share a group session id
  • Fix: Cap a peer-negotiated BDX block size to the transport payload size, so OTA blocks no longer exceed the UDP message limit
  • Fix: Report a sustained subscription's fallback maxInterval in seconds instead of a millisecond value while no subscription is established

• @matter/thread-br-client

  • Feature: Added as new package to support communication with Thread Border Routers through CoAP and with OpenThread Border Routers via REST (if exposed)

• @matter/types

  • Enhancement: Added the NFC Transport Layer (NTL, bit 4) capability to the onboarding payload Discovery Capabilities bitmap

• @project-chip/matter.js

  • Fix: Harden endpoint structure processing against non-compliant peers that omit mandatory Descriptor list attributes; treat an absent list as empty and warn-and-ignore missing device types instead of crashing

0.17.4 (2026-07-01)

• @matter/general

  • Enhancement: Inbound mDNS packets are dropped before a full decode when none of the names any subscriber registered appear in them, reducing CPU usage on busy networks

• @matter/node

  • Enhancement: Optimizes incoming DataReport processing
  • Enhancement: Frees a behavior's persisted seed values from memory once the datasource has loaded them
  • Adjustment: Rejects an invalid Basic Information VendorID (0 or above 0xFFF4) or ProductID (0) as a device identity
  • Adjustment: A client write interaction to a peer no longer rejects conformance violations locally; the value is forwarded so the device decides, while value-range and datatype errors still fail fast
  • Fix: A peer's mDNS advertisement at the 1-hour SII/SAI cap no longer lowers a higher CASE-negotiated idle/active interval already on record
  • Fix: Ensures that a peer's FeatureMap change rebuilds the affected client cluster behavior
  • Fix: A peer reporting an empty AttributeList no longer breaks client cluster schema generation; the discovered schema falls back to the attributes actually received
  • Fix: A client cluster the peer still serves data for but omits from its descriptor server list is no longer dropped when subsequent endpoint data is processed
  • Fix: Ensures that fabric-scoped attribute data (e.g. stale AccessControl ACL entries) is always sanitized at node startup
  • Fix: A misconfigured environment/configuration value for a behavior (unknown property or unconvertible value) is now logged and skipped instead of crashing endpoint initialization
  • Fix: An invoke with SuppressResponse still returns the Invoke Response when a command produces response data, instead of suppressing it unconditionally
  • Fix: Aligned Thermostat atomic-write handling with the Matter specification
  • Fix: Ensures that client clusters are never exposed to incoming interactions
  • Fix: The generated manual pairing code now reflects the configured commissioning flow, including Vendor ID and Product ID for non-Standard flows
  • Fix: Ensures that a rejected SetRegulatoryConfig leaves BasicInformation.location unchanged, instead of writing the country code before validating the regulatory config
  • Fix: Diagnostics now log endpoint number 0 instead of "(unassigned)"

• @matter/nodejs

  • Fix: On process.exit, verifies all storages were properly closed and removes orphaned lock files otherwise, so a forgotten close no longer blocks the next startup

• @matter/protocol

  • Enhancement: Caches attribute/event schema resolution while decoding incoming data reports to reduce decode time
  • Enhancement: Incoming read/subscription data reports now tolerate signed/unsigned integer encoding mismatches within defined bounds. Such cases are still non-compliant and are logged
  • Enhancement: Unified peer device-probing across the mDNS address-change and subscription-liveness cases so they no longer probe independently
  • Adjustment: A GitHub rate-limit response while downloading certificates now skips the remaining GitHub fetches for that run, and is logged at debug instead of info when matching test certificates are already cached
  • Fix: CASE/PASE session parameters with idle/active intervals above one hour are now accepted instead of declining the session; the one-hour cap is applied only when advertising over DNS-SD like in CHIP SDK
  • Fix: A local Session Active Threshold above its 65535ms (uint16) maximum is now rejected up front with a clear error instead of failing later during message encoding
  • Fix: The operational (fallback) address now updates when the session channel follows a peer's new source address, instead of going stale
  • Fix: Certificate SubjectKeyIdentifier and AuthorityKeyIdentifier are derived as 160-bit SHA-1
  • Fix: Certificates are rejected on decode when exceeding the size limits (400 bytes TLV for the NOC chain and VVSC, 600 bytes DER for the NOC and DAC chains)
  • Fix: OTA image digest type identifiers follow the IANA Named Information Hash Algorithm Registry (RFC 6920), and the digest algorithm is validated when reading an image
  • Fix: Fabric-sensitive events are now always filtered to the accessing fabric on read and subscribe
  • Fix: A stray StatusReport arriving as an exchange's initial message (e.g. a retransmitted CASE/PASE completion) is now ignored instead of logging an "Unhandled error"
  • Fix: An invoke client now reports NoCommandResponse for sent commands that receive no response, and discards unexpected/unmatched response entries instead of throwing
  • Fix: The BLE Extended-Announcement flag is only set during the extended-announcement period, no longer when private details are omitted outside that window
  • Fix: Fixes encoding and decoding of a message payload header carrying a vendor Protocol ID
  • Fix: Does not send error status messages when the message before was never delivered for PASE/CASE
  • Fix: Clamps the outer interaction-model status to SUCCESS/FAILURE when a cluster-specific status is present
  • Fix: Rejects a DataVersion on a group or wildcard write path
  • Fix: Ensures that DataReports always contain data or a status for attributes and never the IsUrgent flag in event data

• @matter/types

  • Fix: TLV character strings are truncated at the first Information Separator 1 (0x1F) on decode, and a character string containing IS1 is rejected on validation
  • Fix: Onboarding-payload version is validated on decode — a reserved QR version (≠ 0) or manual pairing code first digit (≥ 8) is rejected instead of being mis-parsed
  • Fix: The manual pairing code codec now requires Vendor ID and Product ID for non-Standard commissioning flows
  • Fix: The onboarding-payload TLV codec rejects reserved tags (0x05–0x7F; manufacturer-specific tags must use 0x80–0xFF) and requires the PBKDF iteration count and salt to be both present or both absent

• @project-chip/matter.js

  • Fix: PairedNode.connect() now applies the subscription interval options passed to it, instead of ignoring them

0.17.3 (2026-06-17)

• @matter/general

  • Fix: log.level (e.g. MATTER_LOG_LEVEL) now accepts string level names like info again, not just numeric values
  • Fix: A failed UDP multicast send now evicts and rebuilds the broadcast channel instead of caching a dead socket
  • Fix: SPAKE2+ now samples the ephemeral scalar bounded by the group order n instead of the field prime p

• @matter/model

  • Fix: Changed interaction model revision back to 12 because revision 13 only includes a provisional feature
  • Fix: The conformance parser now rejects invalid choice and optionality constructs instead of mis-parsing them

• @matter/node

  • Fix: Reading CommissioningServer pairing codes before commissioning is initialized now throws a clear error instead of emitting a placeholder code
  • Fix: Ensures that the negotiated subscription MaxInterval stays at or above the requested MinIntervalFloor when the floor exceeds the 60-minute publisher limit
  • Fix: Ensures that a repeated atomic-write BeginWrite from the same client on a cluster/endpoint returns INVALID_IN_STATE for any attributes

• @matter/protocol

  • Fix: Ensures that the peer-medium-specific additionalMrpDelay is also used for executed commands, and added an optional per-request additionalMrpDelay override
  • Adjustment: MRP now selects the active/idle retransmission interval by peer activity for every transmission including the first, instead of forcing the first transmission to the idle interval
  • Fix: Prevents a crash when a PASE pairing timeout fires while a previous message is still awaiting acknowledgement
  • Fix: A discovery kick no longer restarts an in-flight CASE handshake when a restart would barely shorten the next retransmission, avoiding needless teardown of a sleepy peer's exchange
  • Fix: The MRP retransmission interval is no longer capped below the peer's idle interval
  • Fix: The connection fallback address is now compared by value, so a rediscovered last-known address is no longer mistaken for an address change
  • Fix: Ensures that subscriptions established through an interaction are closed when the interaction closes (e.g. node disable/disconnect or decommission)
  • Fix: Ensures spec-compliant read/subscribe/write/invoke responses for a model-known but absent high-privilege attribute, event, or command
  • Fix: Decodes VendorID/ProductID from the "fallback method" (Mvid:/Mpid: in the commonName) of attestation certificates

• @matter/types

  • Enhancement: Added isValidPasscode()/assertValidPasscode() for onboarding passcode validation
  • Fix: Ensure that passcodes are valid when encoding or decoding pairing codes
  • Fix: Ensures that the most-significant bit of a nullable bitmap is reserved for NULL as defined in the Matter specification

• @project-chip/matter.js

  • Fix: Ensure that PairedNode.connect() reconnects a node that was previously disconnected

0.17.2 (2026-06-09)

• @matter/general

  • Fix: An empty mDNS TXT record is now encoded as a single zero byte as required by RFC 6763 §6.1
  • Fix: AES-CCM encryption now honors the byteOffset of subarray inputs for plaintext and AAD
  • Fix: Ensure that variable name sanitization does not throw on special characters adjacent to dots (e.g. node IDs like Dyson360VisNav™)

• @matter/node

  • Fix: Ensure that Self-bindings also detect cluster servers added to an endpoint at runtime via behaviors.require and ignore client clusters on the endpoint
  • Fix: OnOff timed-off handling now honors the 0xFFFF "hold indefinitely" value for OnTime/OffWaitTime
  • Fix: Peers commissioned with a custom id via commission({ id }) are now restored correctly from storage on restart
  • Fix: Writing a bitmap attribute with reserved (undefined) bits set now returns ConstraintError instead of being silently accepted
  • Fix: A TCP-enabled server now reports TCP support in its session parameters (not only in mDNS), so peers learn it during PASE/CASE
  • Fix: Claim the peer node ID only once a candidate wins PASE, to avoid spurious "peer address already in use" conflicts across parallel commissioning attempts
  • Fix: Refreshing a discovered node's metadata while it is being commissioned no longer crashes the process with a synchronous transaction conflict
  • Fix: Ensure that decommissioning removes a node locally even when the device drops the RemoveFabric response after closing the session, and no longer stalls shutdown
  • Fix: Ensure that probing a node during teardown reports it unreachable instead of throwing

• @matter/protocol

  • Enhancement: Implemented Matter message privacy (header obfuscation) for group messages; receiving is always supported, sending is opt-in per session and off by default. Unicast messages carrying the privacy flag are dropped like in CHIP SDK
  • Enhancement: SII/SAI/SAT keys are now omitted from advertised DNS-SD TXT records when at their default values, matching CHIP SDK behavior
  • Enhancement: MRP retransmission additive delay is now a tunable per-NetworkProfile.additionalMrpDelay instead of a fixed constant
  • Enhancement: Subscription maxIntervalCeiling now lengthens by up to +max(10%, 10s) one-sided jitter for all device types (previously only Thread-active devices)
  • Enhancement: Prefer TCP for operational connections when the peer advertises TCP-server support via its session parameters or mDNS; a negotiated TCP session is declined only on an explicit no-TCP report
  • Enhancement: Lengthened the BTP handshake-response timeout (5s → 15s) and central idle timeout (30s → 60s) to match CHIP
  • Enhancement: Added PeerMessageMissingError (subtype of PeerUnresponsiveError) thrown when an expected message does not arrive on an active exchange, distinguishing it from a request that was never acknowledged
  • Fix: Ignore announced TCP support for peers reporting Matter spec version < 1.5.0
  • Fix: Corrected the Session Active Threshold limit to 65535 milliseconds (was wrongly checked against 65535 seconds)
  • Fix: Invalid or out-of-range SII/SAI/SAT values in discovered DNS-SD TXT records are now ignored so MRP defaults apply, as required by the Matter spec
  • Fix: Added size checks for Message Extensions and Secured Extensions length fields on message decode
  • Fix: MRP retransmissions now use the idle interval when the peer left its active window mid-exchange, matching CHIP SDK behavior
  • Fix: A failed operational reconnect caused by a network-layer send error (e.g. ENETUNREACH on a stale persisted address) now triggers mDNS rediscovery instead of retrying the unreachable address indefinitely
  • Fix: TcpChannel now closes the connection on a zero-length stream frame instead of silently skipping it, preventing a peer from holding a connection slot open indefinitely
  • Fix: A forward message-counter jump of exactly the window size no longer retains stale replay-bitmap bits, which could wrongly reject a later legitimate message as duplicate
  • Fix: When the per-session concurrent-exchange limit is exceeded, the least-recently-active exchange is now closed instead of the oldest-created one
  • Fix: A Sigma1 carrying only one of resumptionId/initiatorResumeMic is now rejected with INVALID_PARAMETER instead of being treated as a fresh handshake
  • Fix: Group-send epoch-key selection no longer fails when a future-dated epoch key is installed during key rotation
  • Fix: Group data message counters are now a single node-global counter (per Matter spec) instead of per operational key; former per-key counters are properly migrated to prevent nonce reuse
  • Fix: Ensure that the default regulatoryCountryCode ("XX") is applied when commissioning a Wi-Fi/Thread device without an explicit value
  • Fix: BTP central now advertises the negotiated ATT_MTU minus the 3-byte GATT header as its segment size, so a peer no longer selects fragments that overflow the link
  • Fix: BTP window accounting now counts outstanding packets by modular distance, fixing a miscount across the sequence-number wrap
  • Fix: BTP now reserves the remote receive window's last slot for an acknowledgement and sends a stand-alone ack proactively once its own receive window runs low
  • Fix: BTP now resumes a stalled send queue when an incoming acknowledgement reopens the window
  • Fix: BTP now closes the session if reassembly exceeds the declared message length
  • Fix: BTP commits the acknowledged sequence number before awaiting the write so a stand-alone ack and a concurrent data send no longer acknowledge the same sequence twice (a duplicate ack is rejected by spec-compliant peers)
  • Fix: BTP no longer issues a stand-alone ack into a full remote receive window or concurrently with an in-flight fragment write
  • Fix: A corrupted PAA in the local DCL certificate cache is now re-fetched from DCL once before failing, recovering from broken storage
  • Fix: Unexpected errors during device attestation validation (e.g. an unrecoverably corrupt trust-store certificate) are now surfaced as an attestation finding for the onAttestationFailure policy to judge, instead of aborting commissioning outside the findings mechanism

• @matter/node

  • Enhancement: Added network.ownNetworkProfileId to set the local network's MRP additive margin, and exposed additionalMrpDelay and probeAddress in network profile config

• @matter/nodejs-shell

  • Fix: Stored Wi-Fi/Thread credentials are only applied during commissioning when their values are non-empty, so an empty operational dataset no longer fails commissioning of IP-only devices
  • Fix: config wifi/thread set now rejects empty credential values

0.17.1 (2026-06-03)

• @matter/*

  • Enhancement: Standardized log levels across all packages against a new logging guideline (see docs/LOGGING.md)

• @matter/general

  • Fix: causedBy/asError/errorOf/repackErrorAs no longer crash with "undefined is not an object" when invoked with undefined/null as error object
  • Fix: IpService now also emits changed event when the TXT reconrd changes to ensure updates of the descriptor

• @matter/model

  • Fix: Remove invalid FabricIndex field from four commands
  • Fix: Correct the Device type revision of Room Air Conditioner

• @matter/node

  • Fix: Roll back assigned Fabric from PASE session on AddNOC/UpdateNOC failure

• @matter/nodejs-shell

  • Feature: Added --fabric-filtered flag (default true) to the attribute read commands to control fabric filtering

• @matter/protocol

  • Feature: New TrustedAsTestCertificate attestation finding lets onAttestationFailure decide whether to accept devices whose PAA is only in the trust store as a test certificate; previously these failed with PaaNotTrusted. Adds per-call considerTestCertificates and a separate acceptTestCertificates trust policy on DclCertificateService
  • Feature: OnAttestationFailure callback may return a string (wraps the underlying error as cause of a new CommissioningError) or throw to propagate verbatim
  • Adjustment: Default-accept policies (onAttestationFailure === true/undefined) now commission test-PAA-only devices that previously failed; upgrade the policy to keep rejecting
  • Deprecation: Internally used DecodedDataReport, DecodedAttributeReport{Value,Status,Entry}, DecodedEventReport{Value,Status,Entry}, DecodedEventData, and the normalize* / normalizeAndDecode* helpers moved to @project-chip/matter.js/cluster. Scheduled for removal in 0.19
  • Enhancement: ReadResult.EventValue exposes the four wire timestamp variants (epochTimestamp, systemTimestamp, deltaEpochTimestamp, deltaSystemTimestamp) alongside the existing collapsed timestamp: number
  • Adjustment: ReadResult.Chunk may now be an async iterable (InputChunk is an async generator); consumers iterate chunk contents with for await … of chunk. Mainly internal
  • Fix: Fixes message counter rollover logic
  • Fix: Event reports are now decoded in wire (EventNumber) order
  • Fix: Allows CSRs with an empty subject as per Matter spec
  • Fix: Corrects BTP handshake decoding of version field

• @matter/types

  • Fix: Remove invalid FabricIndex field from four commands

0.17.0 (2026-05-20)

• Breaking: Matter 1.5/1.5.1 specification introduces some changes, as always with new Matter specification versions. You might need to adjust your code.

  • Some Namespaces were renamed and now have a "Common*" prefix
  • Several previous "Zigbee only" features, attributes, and commands were removed because they were never allowed for Matter

• @matter/*

  • Upgraded to Matter specification version 1.5/1.5.1
  • 20%–50% RAM usage reductions and improvements

• @matter/general

  • Breaking: Blob/File-related storage methods were removed from the normal Storage implementation
  • Breaking: DnsCodec.decodeTxtRecord/encodeTxtRecord and the TxtRecord factory now operate on Bytes[] per RFC 6763 §6 so binary TXT values (e.g. Thread MeshCoP xa, xp, at, pt, sb, dd) survive encode/decode losslessly; encodeTxtRecord and TxtRecord accept (Bytes | string)[] so ASCII-only senders are unchanged
  • Feature: Added a new wal-based storage engine (not yet the default) to optimize persistence
  • Feature: DnssdName.parameters and IpService.parameters now return a DnssdParameters instance — a ReadonlyMap<string, string> plus a .raw(key): Bytes accessor for binary TXT consumers (e.g. Thread Border Router enrichment)
  • Enhancement: Added locking to storage implementations to prevent concurrent access issues and data corruption
  • Enhancement: Split out Blob-Storage into its own dir-based BlobStorage implementation
  • Enhancement: Added Storage Migration logic that can generically migrate between different storage engines
  • Enhancement: LogFormat.format renders any Diagnostic-loggable value to a string in the specified format (defaults to plain text)

• @matter/main

  • Feature: Added version string export that exposes the published matter.js version

• @matter/model

  • Breaking: Type-specific Model subfields such as "clusters" and "attributes" no longer support array-like positional access; use Matter.clusters.at(4) instead of Matter.clusters[4]
  • Breaking: Attributes declared by decorators (@attribute(...)) now default to read-only (R V); apply the writable decorator to attributes that must accept writes
  • Enhancement: Model preparations for Matter 1.5 and 1.5.1
  • Enhancement: The fluent API for manipulating the Matter data model is improved
  • Enhancement: Enhances decorator capabilities for attributes, clusters, and (matter and non-matter) commands

• @matter/node

  • Feature: (@adeepn) Added DclBehavior for centralized DCL configuration via environment variables (MATTER_DCL_*), config files, or programmatic setup
  • Feature: CommissioningClient.BaseCommissioningOptions now accepts wifiNetwork, threadNetwork, regulatoryLocation, and regulatoryCountryCode for passing network credentials and regulatory configuration during commissioning
  • Feature: onAttestationFailure commissioning option for controlling attestation validation policy (true/false/callback with typed findings)
  • Feature: ServerNode Network behavior options allow to set tcp (boolean) to enable TCP support for the server node
  • Feature: ServerNode Network behavior options allow to set transportPreference ("udp"/"tcp") to define the preferred connection type when peers support both. "udp" is the default and fallback
  • Feature: DoorLockServer is fully implemented except for Aliro features
  • Feature: The new Supervision() factory allows for fine-grained control of validation for state, commands, and arbitrary JS values
  • Feature: Added Endpoint.get() and Endpoint.getStateOf() — async read API with optional fabricFilter control; on a client endpoint issues a single batched Matter Read; on a server endpoint returns a snapshot of local state
  • Feature: Added Endpoint.featuresOf() / maybeFeaturesOf() — typed access to a cluster behavior's active feature flags
  • Feature: Added Endpoint.globalsOf() / maybeGlobalsOf() — exposes the global cluster attribute state
  • Feature: Allows ServerNode endpoints to declare client clusters via e.g. OnOffLightDevice.with(OccupancySensingClient). Mandatory clients are auto-registered
  • Feature: Added support for Cluster client bindings: BindingServer events established / removed are emitted for defined bindings with Node references preinstalled on the materialized endpoint. See the new OccupancyBindingDevice example. To receive attribute changes from a bound peer set resolution.node.set({ network: { defaultSubscription: Read(Read.Attribute({ ... })), autoSubscribe: true } })
  • Enhancement: Behavior events interactionEnd and interactionBegin now also fire for local act() writes, to be in sync with wire-driven interactions
  • Enhancement: Added string-id overloads to commandsOf(), eventsOf(), stateOf()/maybeStateOf()
  • Enhancement: Re-establish subscriptions in parallel per peer on device/bridge startup
  • Enhancement: Added more warnings on invalid values for BasicInformation cluster
  • Adjustment: Because we saw devices in the wild that needed up to 2 minutes to respond to mDNS queries, we increased the discovery time for commissioning targets to 3 minutes (previously 1 minute)
  • Fix: Ensures that attribute changes which happened during an initial subscription seeding with dataVersion filtering are still reported afterwards
  • Fix: Only exports atomic-commands in Thermostat cluster server when relevant features are supported
  • Fix: Properly cancels subscriptions that were canceled by the peer but were still in resubmission state
  • Fix: Preserves clusters in the structure even if they are not specified in the serverList of the endpoint but are reported in data ("Schrödinger's cluster")
  • Fix: You can now assign bare objects composed of managed values to state properties
  • Fix: ClientNode setStateOf accepts FabricIndex.OMIT_FABRIC for fabric-scoped struct entries (Matter §7.13.6) and substitutes the peer's assigned fabric index so the local cache mirrors what the peer stores

• @matter/nodejs-ble

  • Fix: Fixes several crash or blocking cases around BLE and the usage in commissioning

• @matter/nodejs-shell

  • Feature: Added cert check-revoked command for checking certificate revocation data
  • Enhancement: Allows configuring whether test OTA images are also accepted when devices query for updates

• @matter/protocol

  • Breaking: Removed automatic retry-logic for interactions on node-reachability issues; a new session will be initialized automatically afterward
  • Breaking: Some of the lower-level APIs in @matter/protocol have changed. This will be transparent to most users
  • Feature: We have rewritten the logic for establishing operational connections to other nodes. The new implementation should be faster, more resilient, and offers more knobs for tuning
  • Feature: A new "network profile" feature allows you to tune parallelism and other interaction parameters based on categories including transport type and thread channel
  • Feature: matter.js now responds immediately to IP changes advertised via MDNS
  • Feature: (@adeepn) DclConfig is now an interface with namespace defaults instead of a singleton; DclClient accepts DclConfig for configurable endpoints
  • Feature: (@adeepn) DclCertificateService and DclOtaUpdateService accept custom DCL endpoint configuration via options
  • Feature: Device attestation validation during commissioning per Matter spec 6.2.3.1 — certificate chain verification, attestation signature/nonce, Certification Declaration validation, and certificate revocation checks via CRL
  • Feature: Attestation findings model with error/warning/info levels and configurable policy callback for custom commissioning decisions
  • Feature: CRL revocation support in DclCertificateService — fetches from production DCL on demand, validates the signer chain against trusted PAAs, verifies CRL signature and integrity
  • Feature: CertificationDeclaration.parse() for CMS/PKCS#7 signed CD extraction and signature verification
  • Feature: Enhances DclVendorInfoService and DclCertificateService with an option to seed data to support cases where no internal connection is available (@matter/dcl-data package gets published daily)
  • Enhancement: Attestation local checks (nonce, signature, VendorID, CD fields) run even without DclCertificateService; DCL-dependent checks (PAA trust, chain, revocation) require it
  • Enhancement: Server-side DeviceCertification validates DAC/PAI VendorID and ProductID against product description at startup
  • Enhancement: Enhances the strategy when multiple devices are discovered for the same commissioning target
  • Enhancement: When multiple IP addresses are available for a device during commissioning, all are tried in parallel for faster connection
  • Enhancement: An AbortSignal can now be passed to cancel an in-progress commissioning attempt; the PASE layer sends InvalidParameter to avoid a 60-second device lockout
  • Enhancement: Several enhancements around session management when nodes reconnect or new sessions get pushed by the device
  • Enhancement: Several enhancements around OTA updates and transfers, also when nodes restart in the middle of the process
  • Enhancement: Add Product-Info API to VendorInfoService to expose DCL information for a given VendorId and ProductId
  • Enhancement: Probes discovered addresses and potentially updates session addresses when they change even when we have a valid working session
  • Enhancement: Optimizes operational connection logic during commissioning when multiple IPs are discovered
  • Enhancement: Uses a minimum of 60 seconds for thread/wifi network scan or connect timeouts even if devices announce lower values
  • Enhancement: WiFi/Thread network scan failures are no longer fatal during commissioning; scan failures are logged as warnings
  • Enhancement: Buffers storage of client state changes for up to 20 minutes to reduce I/O pressure
  • Adjustment: No longer ignores overly long incoming Matter messages, but still logs a warning
  • Adjustment: Tolerate operational certificates with 21-octet serial numbers (spec limit is 20, but seen in the wild with some LG TVs) and log a warning; longer serial numbers are still rejected
  • Adjustment: Refactor MdnsClient to also use the new DNS-SD-names logic
  • Fix: Ensure the incoming order of attribute changes is preserved when processing them even though no one should rely on any order
  • Fix: Better handle errors when the BLE connection is disconnected during a write action
  • Fix: Ensures that multiple discovered devices are tried when PASE establishment to the first device fails (e.g., because of a wrong passcode)
  • Fix: Do not announce devices as commissionable before the factory reset when the last fabric is removed
  • Fix: Fixes expiry logic where cached records for Commissionable devices could potentially never expire
  • Fix: For BDX cases also give the device the defined timeout of 5 minutes to ack/request the next packet
  • Fix: Accept SecureChannel StatusReport messages on any protocol exchange (e.g. BDX)
  • Fix: Ensures the Matter port on IPv4 is the same as on IPv6

• @matter/react-native

  • Breaking: We updated to @react-native-async-storage/async-storage v3. A v2-compatible class is available. See the package readme.

• @matter/tools

  • Breaking: This package is no longer published and replaced in internal usage

• @matter/types

  • Breaking: We have removed the deprecated device type definitions in DeviceTypes that have not received updates since Matter 1.1
  • Breaking: A number of semi-internal implementation details of cluster metadata have changed. The general API shape remains the same but some advanced use cases may require updates
  • Breaking: Removed some special pre-bound TLV string/byte-string schema exports, including TlvHardwareAddress
  • Feature: We've rewritten the typing system for clusters to simplify types, consume less runtime memory and work better with IDEs
  • Enhancement: Increases Matter TlvString/TlvByteString default maximum length to 65536 to cover WebRTC cases
  • Fix: NodeId.fromGroupId now produces a full 16-hex Group Node ID per Matter spec
  • Fix: (@snabb) TlvTaggedList now ensures schema/tag ordering when encoding (Matter Core §10.6.1). Added TlvTaggedListPreservingOrder for cases where ordering needs to be data driven (e.g. signed certificate sub-lists).

• @project-chip/matter.js

  • Feature: CommissioningController allows to set tcp (boolean) to enable TCP support for the controller
  • Feature: CommissioningController allows to set transportPreference ("udp"/"tcp") to define the preferred connection type when devices support both. "udp" is the default and fallback
  • Feature: CommissioningOptions when commission a new device allows to set an onAttestationFailure callback that gets called with attestation validation options and allows decisions to continue or block the commissioning. Default accepts but logs all failures.
  • Enhancement: CommissioningController.commissionNode() now uses the parallel PASE commissioning path for pre-discovered devices; WiFi/Thread/regulatory credentials and abort signal are fully propagated
  • Enhancement: Legacy Endpoint and PairedNode wrappers expose featuresOf() / maybeFeaturesOf() and globalsOf() / maybeGlobalsOf() matching the modern client endpoint
  • Enhancement: Legacy Endpoint and PairedNode wrappers now also expose get(), getStateOf(), eventsOf(), maybeStateOf() and string-id overloads on existing accessors for parity with the modern client endpoint
  • Adjustment: The "Waiting for device discovery" node state is now bound to the availability of IP announcements from MDNS
  • Fix: Fixes inverted autoConnect logic in CommissioningController

0.16.11 (2026-04-10)

• @project-chip/matter.js
  • Fix: (Pierre-Gilles) Added fallback discoveredAt to node migration in case discoveryData doesn't have one

0.16.10 (2026-02-22)

• @matter/create

  • Fix: Fixes generated npm run app entrypoint path (dist/src/... → dist/...) (#3228)

• @matter/model

  • Fix: Constraint evaluation for expressions with negative exponentiation bases (e.g. -2^62 to 2^62) and improves precision for large exponent arithmetic by using BigInt when results exceed the safe integer range

• @matter/node

  • Breaking: ControllerBehavior is no longer present in the EndpointType of ServerNode by default

• @matter/nodejs-ble

  • Fix: Fix crash when BLE peripheral disconnects during service/characteristic discovery
  • Fix: Fix cancelCommissionableDeviceDiscovery not working when called from the discovery callback

• @matter/nodejs-shell

  • Adjustment: ota add stores files as "local" mode; ota list, ota delete, and ota copy support "local" mode filter

• @matter/protocol

  • Enhancement: Ignore known addresses when current MDNS results do not include them anymore
  • Adjustment: OTA update files are now stored per software version, allowing different updates to be served to different nodes simultaneously. Former files are migrated.
  • Enhancement: Optimize MRP timings when sending retransmissions to address expected network congestion
  • Adjustment: Remove ICAC workaround added in 0.16.0
  • Fix: Ensures that production certificates are always stored correctly
  • Fix: Ensures trying different IPs when we have a timeout-based reconnection process
  • Fix: Fix cancelCommissionableDeviceDiscovery not working when called from the MDNS discovery callback
  • Fix: Ensure correct random MRP retransmission intervals are used
  • Fix: Ensure we do not batch the same command path twice in the same invoke-request
  • Fix: Ensures that queued interactions are done before releasing the slot

• @matter/react-native

  • Fix: Bring BleScanner cancel support in line with nodejs-ble, fixing cancelCommissionableDeviceDiscovery not working when called from the discovery callback

• @project-chip/matter.js

  • Fix: Fixes crash when decommissioning a node while a reconnection is in progress
  • Fix: Keep an active reconnection timer running when we detect a node shutdown

0.16.9 (2026-02-16)

• @matter/general

  • Fix: Fixes Duration string parsing

• @matter/model

  • Enhancement: Re-parsed the Matter 1.4.2 specification to improve captured details. No functional changes
  • Enhancement: Adds "writable" as decorator to mark attributes writable

• @matter/node

  • Feature: We now allocate node IDs as sequential numbers; the old behavior of randomized node behavior is available if you set ControllerBehavior state property nodeIdAssignment to "random"
  • Feature: HttpServer and WebSocketServer now optionally support SSL; matter.js will generate a self-signed certificate if you do not provide one
  • Enhancement: Also export Matter events via ChangeNotificationService
  • Enhancement: Added updateFailed event to the OTA behavior
  • Enhancement: Allows to access the update queue
  • Adjustment: Ignore invalid VendorIds or DeviceTypeIds when processing MDNS data
  • Fix: Added missing export for ColorControlClient
  • Fix: Prevents duplicate change events for Client behaviors when attributes are Quieter
  • Fix: Ensures to use correct intervals when resuming persisted subscriptions
  • Fix: Ensures stalled or canceled OTA updates do not block additional tries
  • Fix: Ensures that the OTA update queue is not blocked and handles stalled/errored entries correctly
  • Fix: Improves OTA success and failure detections

• @matter/nodejs

  • Fix: Also handle ENETUNREACH as a non-critical network error that triggers the retry logic and MDNS lookup

• @matter/nodejs-ble

  • Fix: Fixes the parsing of combined "VendorId+ProductId" discovery keys

• @matter/protocol

  • Enhancement: Added some jitter to the subscription max ceiling to spread out subscription responses from devices
  • Fix: Initializes the Message Reception state counter correctly as defined by the Matter specification
  • Fix: Ensures that BDX sessions inform upper layers correctly in all canceled cases
  • Fix: Fixes Session mapping for PASE/CASE messages
  • Fix: When we have sent out the success for a session resumption ensure the session is registered even if we do not get the ack
  • Fix: Ensures processing of received messages that lead to earlier Standalone Acks for previous messages

• @matter/react-native

  • Dependency: Updated to @react-native-community/netinfo which requires "Access Wi-Fi Information Entitlement" for iOS!

• @matter/types

  • Enhancement: Re-Parsed the Matter 1.4.2 specification to improve captured details. No functional changes

• @project-chip/matter.js

  • Fix: Prevent PairedNode from updating its structure when the node is already decommissioned
  • Fix: Ensures that reconnection triggers always stop the timer when a timer is already running to prevent duplicate triggers

• Other

  • Enhancement: For dev-server users, we now prepare the container for claude-code usage by default

0.16.8 (2026-01-30)

• @matter/node

  • Enhancement: Added automatic Command batching for non-root-endpoint commands when a node supports it and commands come in within the same macro-tick
  • Fix: Prevent error when writing Thermostat systemMode attribute

• @matter/protocol

  • Feature: Automatically decides if multiple invokes can be sent in one or multiple messages depending on the device capabilities
  • Enhancement: Add protection against out-of-order mDNS goodbye packets (TTL=0) that could incorrectly remove recently discovered devices
  • Enhancement: Add minimum TTL protection for PTR records to prevent DoS attacks with very short TTLs
  • Enhancement: Add RFC 6762 §7.3 compliant duplicate question suppression to MdnsServer
  • Enhancement: When forcing an MDNS update for an operational device, ensure we also get new IP addresses
  • Enhancement: Updates the session network address based on the address from the last opened exchange
  • Enhancement: Ensures to update the persisted last known network address when addresses change on new sessions or exchanges
  • Enhancement: When getting new IP addresses for a device while in resubmissions directly use them for the next message
  • Enhancement: Ignores OTA update-file size issues when checksum validation passes
  • Fix: Correctly handle multi-message write interactions (server and client) according to Matter specification
  • Fix: Correctly handle multi-message invoke responses (server and client) according to Matter specification
  • Fix: Sort out matching local OTA versions that are not applicable considering the current device version
  • Fix: Ensures to correctly stores and updates the "last known address" from the current session
  • Fix: Reuse sessions that are pushed by devices themselves, even when we are in a reconnection cycle
  • Fix: Handle new sessions that devices pushed during a reconnection cycle as successful reconnections in more places
  • Fix: Allows correctly handling multiple parallel mDNS queries for the same device

• @project-chip/matter.js

  • Enhancement: Allows specifying the BasicInformation attributes for the started Server node for a Controller
  • Adjustment: Skip the full read before the subscription in the first two reconnection tries
  • Fix: Ensures to fire decommissioning events for all situations where a node is decommissioned

0.16.7 (2026-01-22)

• @matter/node

  • Fix: Allow querying for updates even when we do not announce us as a default provider

• @project-chip/matter.js

  • Fix: Prevent error when receiving attribute changes for behaviors that are not yet supported by an endpoint

0.16.6 (2026-01-22)

• @matter/general

  • Enhancement: When generally discovering for operational targets, send one initial query for them to fill the cache
  • Enhancement: (@craftingmod) Storage migration utility function
  • Fix: Store operational devices matching operational scan targets also when not explicitly discovered
  • Fix: Split mDNS Query message that are too big to fit into one mDNS message
  • Fix: Fix some mDNS handling issues
  • Fix: Add some protection to better ignore invalid mDNS packets

• @matter/node

  • Fix: Ignore startup definitions for bridged devices (affects OnOff, LevelControl, and ColorControl clusters)
  • Fix: Fixes the collection of IPv6 addresses in the GeneralDiagnostics cluster

• @matter/nodejs

  • Feature: (@craftingmod) SQLite storage support with storage driver selection
  • Feature: (@craftingmod) Auto-migration between storages(file, sqlite)
  • Enhancement: (@craftingmod) Optimizing Bun support

• @matter/protocol

  • Adjustment: Change the default value of "announceAsDefaultProvider" to false, which avoids device race conditions for now
  • Fix: Ignore errors for closed sessions on resubmissions on already closed exchanges. Were false positive logs before.

• @project-chip/matter.js

  • Enhancement: Initialize ClusterClient-based structure for PairedNode only when needed
  • Fix: Correctly handle node decommissioning by other controllers
  • Fix: Prevent creation of new peers when decommissioning of a node was working
  • Fix: Extend error handling when persisting legacy node details

0.16.5 (2026-01-16)

• @matter/protocol
  • Fix: Correctly handle local found production OTA files as "from production"

0.16.4 (2026-01-15)

• @project-chip/matter.js
  • Fix: Preventing crash on removing a node

0.16.3 (2026-01-15)

• @matter/model

  • Fix: Adjust a Enum conformance in FanControl which can never be validated and so lead to errors

• @matter/node

  • Fix: Always trust unknown attribute-ids and command-ids delivered by devices and do not validate them (only affects controller usage)

• @matter/protocol

  • Enhancement: Exclude invoking commands from using the Interaction queue because users should know what they are doing and commands are usually smaller packages

• @project-chip/matter.js

  • Fix: Report attribute changes also for endpoints with multi-level structure. This broke in 0.16.0

0.16.2 (2026-01-14)

• @matter/protocol
  • Fix: Improve handling of errors when peers are closed or when removing not-connected nodes

0.16.1 (2026-01-13)

• @matter/protocol
  • Fix: Prevents an unhandled promise rejection when reconnections are in progress when peers are closed

0.16.0 (2026-01-12)

• Breaking: matter.js now requires node.js 20.19+ or 22.13+ or 24.0+ (LTS versions). Node.js 18.x is no longer supported.

• Breaking: Because of the upgrade to TypeScript 5.9, all usages of Uint8Array were changed to use a more convenient own type alias Bytes

• Breaking: Matter 1.4.2 no longer specifies reasonable defaults for many fields, so you may find new places where you need to manually supply an attribute value

• Breaking: The default Node.js storage manager (StorageBackendDisk) was optimized for performance which requires not opening multiple storages for the same ID at the same time. So check your usage of StorageService, if you use it directly too.

• @matter/*:

  • Upgraded to Matter specification version 1.4.2

• @matter/examples

  • Breaking: This package is no longer published. The examples are moved in the repository into the examples/ directory. Simply use the project creator npm init @matter to create a new project based on one of the examples.

• @matter/general

  • Breaking: Our time API is upgraded, most notably with proper typing for time intervals. This makes time handling more consistent and safer, but it does change how you convey intervals to matter.js. For example: delay: Seconds(1) rather than delayMs: 1000.
  • Breaking: There are other small time changes such as converting nowMs() (a function) to nowMs (a property).
  • Breaking: SyncStorage interface got removed
  • Breaking: MaybeAsyncStorage got renamed to Storage because it is the only interface from now on
  • Breaking: Some central services, especially MdnsService, are now tracked automatically by usages and will close correctly when no longer needed. Closing MdnsService manually is not needed anymore.
  • Breaking: The types for observables with synchronous emitters no longer accept async observers. Most observables are async but if you encounter a type error you need to track your promise outside the observable
  • Feature: Adds Blob support to the Storage interface
  • Feature: Add BDX (Bulk Data eXchange) protocol support according to Matter specification
  • Feature: Added support for multiple hash algorithms (SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256, SHA3-256) via HashAlgorithm enum with IANA identifiers
  • Enhancement: Enhanced Crypto.computeHash() to support streaming data via ReadableStreamDefaultReader and AsyncIterator in addition to Bytes and Bytes[] for memory-efficient hash computation
  • Enhancement: Added platform abstractions for of HTTP, WebSockets, and MQTT
  • Enhancement: Added polyfills and additional types for decorators
  • Enhancement: Split out access to random values from the Crypto interface to an Entropy interface
  • Enhancement: Added support for shared Environment services by tracking usages and closing when the last user is gone
  • Enhancement: Specializes camelize() to stop processing when $ is reached to better handle special names for custom clusters
  • Enhancement: Convert PromiseQueue to Semaphore with the obtain / release approach
  • Enhancement: Update Session timing parameters during CASE/PASE as delivered by the peer already during session establishments
  • Fix: Ensures that StandaloneAck messages are always considering the corresponding Secure channel protocol ID

• @matter/model

  • Feature: You can now use Ecma TC39 stage 3 decorators to associate assign Matter semantics to JavaScript classes
  • Feature: You can now reference subproperties in constraints as required by Matter 1.4.2
  • Feature: Constraints now support Matter 1.4.2 functions minOf and maxOf
  • Enhancement: Model API is improved to simplify element filtering based on conformance

• @matter/node

  • Breaking: Endpoint and Node initialization values now require the correct type for some time values and IDs. So for example, VendorId(1234) instead of just 1234
  • Breaking: SubscriptionBehavior is renamed to SubscriptionsServer with corresponding ID change to "subscriptions". This means in part that matter.js will ignore saved subscriptions, but devices will recreate them automatically
  • Breaking: The agentFor method of ActionContext has moved to Endpoint. You likely do not use this directly but if you do you must change context.agentFor(endpoint) to endpoint.agentFor(context)
  • Breaking: We have refactored the ActionContext class to better delineate fields that apply to operations triggered locally vs those triggered by authenticated peers. ActionContext may be a RemoteActorContext or LocalActorContext. You can determine the actor type and access relevant fields using new type guards hasRemoteActor or hasLocalActor and new type assertion assertRemoteActor. These replace the former offline field of ActionContext
  • Breaking: The FabricAction enum emitted by CommissioningServer is replaced with a simple string type
  • Feature: matter.js now natively supports remote access to Matter nodes via non-Matter protocols. You can add HttpServer, WebSocketServer and/or MqttServer to your ServerNode to enable HTTP, WebSocket, and MQTT access respectively
  • Feature: You can now use Ecma TC39 stage 3 decorators to customize the schema associated with a Behavior implementation
  • Feature: New StateStream component offers a high-level API for monitoring changes across multiple nodes
  • Feature: Add default implementation for the Thermostat cluster according to Matter 1.4.2 specification. All features except MSCH and SB (which is considered provisional) are implemented. See the ThermostatServer class for details.
  • Feature: Added feature complete default implementation for the Scenes Management cluster according to Matter 1.4.2 specification.
  • Feature: Added the VendorIdVerification algorithm on device side according to Matter 1.4.2 specification. Controller side is only partially implemented yet.
  • Feature: Added default implementations for OtaSoftwareUpdateRequestor/Provider clusters according to Matter specification.
  • Feature: Added OTA management support component (SoftwareUpdateManager)
  • Enhancement: Adds "maybeReactTo" which only registers the listener when the event exists.
  • Enhancement: Enhances Endpoint#eventsOf and Endpoint#setStateOf with overrides so you can use the ID to obtain variants with generic typing
  • Enhancement: We now enforce bounds for integer types even if not specified explicitly by constraint
  • Enhancement: Also allow to use the Endpoint#set() method with attribute ids instead of attributeNames
  • Fix: Ensures that the InLevel does not interfere with *WithOnOff commands in the Level Control cluster
  • Fix: Ensures correct behavior for announcements and fabric table updates in case of updating fabrics

• @matter/nodejs

  • Breaking: The default storage manager (StorageBackendDisk) was optimized for performance which requires not opening multiple storages for the same ID at the same time. So check your usage of StorageService, if you use it directly too.
  • Enhancement: Uses "stat" to determine storage file existence instead of reading all content
  • Enhancement: Exposes Node's native HTTP server via new abstractions in @matter/general
  • Fix: Corrects network interface selection logic for windows

• @matter/nodejs-ble

  • Fix: Updating Noble and Bleno to enhance compatibility on macOS and Windows

• @matter/nodejs-shell

  • Feature: Added cert command for DCL certificate management with subcommands: list, details, as-pem, delete, and update
  • Feature: Added ota command for OTA update management with subcommands: info, extract, verify, list, add, delete, and copy for managing OTA image files in storage
  • Feature: Added new commands to the node commands to check, download and apply OTA updates for nodes

• @matter/protocol

  • Breaking: The platform-specific BLE abstraction has changed so that higher-level logic may be shared across platforms
  • Breaking: Low-level advertising APIs have changed significantly; in particular, MdnsBroadcaster, MdnsInstanceBroadcaster and MdnsScanner are replaced by MdnsServer, MdnsAdvertisement and MdnsClient
  • Breaking: The Ble.get() singleton is removed; components now instead retrieve the Ble service from the environment
  • Breaking: Moved some controller API classes (Attribute/Event/Command/InteractionClient) into @project-chip/matter.js/cluster package and adjusted to use Node Interactable as backing
  • Breaking: Reading multiple/all attributes via InteractionClient is always reading the data from the device and no longer enrich the result with already known data (option enrichCachedAttributeData is no longer supported). Ideally, use ClusterClient or new Node-based APIs to access the already stored data.
  • Feature: Adds support for advertising of TCP and ICD services (but matter.js does not yet implement those features otherwise)
  • Feature: Adds support for extended advertisement
  • Feature: Added support for Case Authenticated Tags (CATs) in operational CASE sessions for enhanced access control
  • Feature: Added support to read and parse ASN.1 formatted certificates
  • Feature: Added DclCertificateService for managing Product Attestation Authority (PAA) certificates from the Distributed Compliance Ledger (DCL) with automatic updates from production DCL, test DCL, and GitHub development repositories
  • Feature: Added DclOtaUpdateService for checking and downloading Over-The-Air (OTA) software updates from DCL with full validation and checksum verification
  • Feature: Added DclVendorInfoService for retrieving vendor information from DCL
  • Feature: Added OTA image processing utilities (OtaImageReader, OtaImageWriter) for reading, validating, extracting, and creating Matter OTA update files
  • Feature: (@ArtemisMucaj) Added support to pass / generate an intermediate CA in the CertificateAuthority class, when used the NOCs are signed with the ICAC cert
  • Enhancement: (@bhargavnagotha9) Allows the Root keypair to be optional when ICAC is provided
  • Enhancement: MDNS broadcasts more aggressively until a connection is established
  • Enhancement: MDNS and BLE advertising schedules are now configurable and conform to Matter and DNS-SD specifications
  • Enhancement: MDNS client and server efficiency is improved with a shared socket and message parser
  • Enhancement: MDNS Truncated Queries are now handled correctly
  • Enhancement: matter.js no longer uses SO_REUSEADDR on the Matter port, so you can no longer accidentally start two nodes at the same address simultaneously
  • Enhancement: Increases the limitation of parallel exchanges when sending messages to 30 (was 5 before)
  • Enhancement: Migrate Commissioning Flow to ClientInteraction as bases
  • Enhancement: FabricAuthority automatically rotates the operational Fabric NOC key pair on start once (for Controller cases)
  • Adjustment: Subscription data are no longer being flushed when a subscription is replaced by a new one with keepSubscriptions=false
  • Adjustment: When setting certificates and a ICAC is provided but equals the root CA, the ICAC is ignored (workaround of issues with one ecosystem)
  • Fix: Controller networking was previously throwing the incorrect error after a communication timeout
  • Fix: Ensures to only include the MaxTcpMessageSize in Session parameters when TCP is enabled
  • Fix: Fixes the used ACL level for wildcard writes
  • Fix: (@ArtemisMucaj) Fixes noc trust chain verification; verify against both RCAC and ICAC if present

• @matter/react-native

  • Fix: (@Luxni) Update UDP, BLE, and Crypto usage to work with React Native

• @matter/types

  • Breaking: All "epoch-s" and "epoch-us" values are now converted automatically to the correct matter epoch, so that your own code can just use normal 1970-based epochS/US values. If you converted yourself to the Matter 2000-based values before, please remove this conversion.
  • Enhancement: The duplicate event priority definition EventPriority is deprecated; use the generated Priority enum instead
  • Fix: Ensures correct Number ranges for nullable and non-nullable numbers on TLV level

• @project-chip/matter.js

  • Breaking: PairedNode.state renamed to PairedNode.connectionState!
  • Breaking: PairedNode attribute change callbacks and events does not contain the changed and oldValue properties anymore
  • Breaking: Some PairedNode API methods got slightly reduced in functionality, but that should not affect most users
  • Breaking: The Storage location of the controller base data has moved. The data will be migrated automatically on the first start of the new version (be aware, this can take some seconds!)
    • Cached node attribute data (formerly node-<ID>.* in the main storage) are now located in nodes.peerX.endpoints.* because they are now managed
    • The fabric (formerly "credentials.fabric") is now located at "fabrics.*"
    • The certificates (formerly other credentials.*) are now located in certificates.*
    • The list of commissioned nodes (formerly "nodes.commissionedNodes") is now integrated in the node peer data (nodes.peerX)
  • Feature: Added new option enableOtaProvider to CommissioningControllerOptions to enable OTA Provider functionality
  • Enhancement: The PairedNode is data wise now backend by a ServerNode instance which acts as controller and provides all data management and peer access. This API can alredy be moved directly by using PairedNode.node - some convenience methods are also dorectly mapped on the PairedNode itself (see below). initial connection and reconnection management is still handled by PairedNode and will move later.
  • Enhancement: Added more convenient accessors for endpoint cached read-only state: Endpoint.state property for attributes for all clusters in generic way and Endpoint.stateOf() for typed access for a defined Client behavior
  • Enhancement: Added more convenient accessors for endpoint commands: Endpoint.commands property for commands for all clusters in generic way and Endpoint.commandsOf() for a types access for a defined Client behavior
  • Enhancement: Added PairedNode.parts and Endpoint.parts as Map property to access all endpoints of a node
  • Enhancement: Added PairedNode.state, PairedNode.stateOf(), PairedNode.commands and PairedNode.commandsOf() to access all endpoints of te root endpoint in a more convenient way

• @matter/mqtt

  • Feature: New package implementing @matter/main MQTT abstraction using MQTT.js

• @matter/nodejs-shell

  • Fix: Changed the shell CLI option to enable ble to "--ble-enable" to not conflict with internal variables
  • Adjustment: Adjusted to build ESM package by default

• @matter/nodejs-ws

  • Feature: New package implementing @matter/main WebSocket abstraction using ws package and Node.js HTTP server

• Example Applications

  • (markus-becker-tridonic-com) Added an Electron-based example application implementing a Matter controller with BLE commissioning support for Thread networks to demonstrate the use of Matter.js in a desktop environment

• Other

  • Feature: For developers working with the matter.js repository on Macs and Windows, we now offer a devcontainer to facilitate native Linux development

0.15.6 (2025-10-16)

• @matter/general

  • Fix: Ensures services are not removed from parents when they are removed locally

• @matter/node

  • Fix: Ensures OccurrenceManager is closed on node shutdown

• @matter/protocol

  • Enhancement: Removes exchanges earlier when closing to prevent double session closures
  • Enhancement: Ignores invoke responses that should be suppressed but delivered
  • Fix: Fixes Fabric scoped event reads to ensure the filtering is applied correctly

• @project-chip/matter.js

  • Fix: Initializes controller into an own environment instead of using the provided environment
  • Fix: Ensure that the PairedNode meta-data are updated and stored when changed

0.15.5 (2025-10-07)

• @matter/general

  • Enhancement: Accept all variants of MDNS responses, also non-authoritative ones
  • Fix: Adds safeguard check to prevent a crash seen when handling DNS messages
  • Fix: (TheNetStriker) Ensure all log destinations get all logs

• @matter/nodejs

  • Fix: Corrects network interface selection logic for windows

• @matter/protocol

  • Fix: Ignoring existing Pase sessions in the closing state when establishing a new PASE session
  • Fix: Includes FabricIndex when storing resumption records to prevent issues with NodeId collisions

• @project-chip/matter.js

  • Enhancement: Adds events "nodeEndpointAdded/Removed/Changed" (in addition to structureChanged) to PairedNode to allow more detailed tracking of changes
  • Enhancement: Update cached attribute details while reading them from the device to improve connection performance when multiple reads are needed (e.g. for bad reachable devices) to optimize reconnection performance
  • Enhancement: Randomizes FabricId when creating a new controller to prevent Fabric ID collisions
  • Fix: Fixes safeguards in CommissioningController when resetting storage
  • Fix: Fixes detection of endpoint removals and cluster topology changes in PairedNode

0.15.4 (2025-09-20)

• @matter/protocol

  • Fix: Fixes an issue that prevented cached attribute data from being updated correctly
  • Fix: Allow also triggering attribute updates when initially read before the subscription had updated attributes

• @matter/node

  • Fix: (rsulzenbacher) Adjusted OnOffServer default implementation for offWaitTime to be fully compliant to 1.4.1 spec

0.15.3 (2025-08-01)

• @matter/protocol

  • Fix: Update data versions in the attribute data cache also when data are all the same to make sure data version filters work correctly

• @project-chip/matter.js

  • Fix: Makes sure to set the initialized states before emitting the Connected event to prevent edge cases
  • Fix: Fixes an issue that prevented cached attribute data from being used for node connections

0.15.2 (2025-07-27)

• @matter/examples

  • Fix: Initializes default attributes for ElectricalEnergyMeasurement cluster to enable them in the MeasuredSocketDevice example

• @matter/general

  • Fix: Fixes regression for transactions with async post-commit

• @matter/model

  • Enhancement: Convert the Namespace type into an Enum for more convenient usage and fill with all values from Specification. Also adjusted all relevant usages
  • Fix: Optimizes Model object freeze order
  • Fix: Fix attribute generation for [Field] conformance

• @matter/node

  • Fix: Fixes validation of ServiceArea cluster SupportedAreas attribute

• @matter/nodejs-shell

  • Enhancement: Always query the node when reading attributes from remote, ignores internal checks for attribute existence
  • Enhancement: Allows ignoring internal checks for attribute existence on write interactions using the new -- force parameter

• @matter/types

  • Fix: (ArtemisMucaj) Fixes StringSchema validation to allow longer content than 1024 octets

• @project-chip/matter.js

  • Fix: (ArtemisMucaj) Correctly pass a custom "rootCertificateAuthority" and "rootFabric" from CommissioningController options internally

0.15.1 (2025-07-01)

• @matter/general
  • Fix: Do not install standard crypto implementation if the global crypto.subtle is unavailable

0.15.0 (2025-06-27)

• @matter/*

  • Feature: Implement Matter Groups support in protocol, node, and (partly) controller packages

• @matter/general

  • Breaking: The Network.get() singleton is removed
  • Breaking: The Crypto interface has changed; Crypto.get() singleton is removed, the API is modernized, methods are renamed for clarity, and the ecdh* methods are replaced with generateDhSecret
  • Feature: Adds a crypto implementation that should function in any modern JS VM
  • Enhancement: Adjust Dynamic class building approach to not use eval anymore to enable running in more environments
  • Fix: Fixes encoding of special IPv6 addresses in DNS-SD records

• @matter/model

  • (@FlyingNebulae) Fix: Allow aspectCache to also work when a source got transpiled without keeping variable names

• @matter/node

  • Enhancement: Ensures behavior event interactionBegin to fire at the begin of an interaction as soon as the datasource is about to be changed on a behavior
  • Enhancement: Ensures behavior event interactionEnd to fire at the end of an interaction when all logic is done and executed
  • Enhancement: Ensures behavior event stateChanged to fire when an interaction changed the state of the behavior. It fires at the end after all concrete $Changed events are sent out
  • Fix: Ensures to remove all Fabric scoped data when a fabric is being removed
  • Fix: Streamline value conformance checks to cause a ConstraintError instead of an InvalidAction error in all cases

• @matter/protocol

  • Enhancement: Exposed reading cached ClusterClient attributes via get*AttributeFromCache() method
  • Enhancement: Enhances CSR content validation
  • Fix: Correctly handles Non-Concurrent Commissioning flows by skipping scanning for networks and use proper wait times for scan and connect calls for networks

• @matter/nodejs

  • Enhancement: New variables nodejs.crypto, nodejs.network and nodejs.storage allow users to enable/disable the implementation of these features that use Node.js APIs

• @matter/nodejs-ble

  • Fix: Removes Windows-specific workaround needed in older versions of Noble
  • Fix: Adjusts BLEScanner to allow cancellation of discovery processes when BLE is included

0.14.0 (2025-06-04)

• NOTE: This version is compatible with Node.js 20.x, 22.x, and 24.x. Node.js 18.x is also supported with the following exceptions:

  • The matter.js tools for building and running tests and applications (matter-*) which are mainly used by the npm scripts which use the "commander" dependency.

• @matter/*

  • Upgraded to Matter specification version 1.4.1

• @matter/general

  • Feature: Logger allows using a function as a log value which is only executed when the log level matches
  • Enhancement: Enhanced error classes and handling

• @matter/node

  • Enhancement: Exposes endpointProtocol property on Endpoint
  • Enhancement: Refactors InteractionServer to cut out legacy interaction logic and move to Behavior logic
  • Enhancement: Refactors OnlineContext and Transaction handling
  • Fix: Fixes special-case in Wildcard Filtering where not all fixed attributes were filtered out
  • Fix: Fixes ACL check logic order on attribute reads
  • Fix: Consider the potential async nature of Transitions.applyUpdates() correctly in all cases to prevent dangling promises
  • Fix: Correctly handles undefined for optional nullable attributes
  • Fix: Prevents primitive lists in a fabric scoped struct to be handled as fabric scoped when reading or writing

• @matter/nodejs-ble

  • (@spudwebb) Fix: Increase BLE connect timeout fo 120seconds to optimize pairing

• @matter/nodejs-shell

  • (@JimBuzbee) Feature: Adds a websocket mode including an example webpage to control the shell

• @matter/protocol

  • Breaking: logEndpoint() and also EndpointServer class was removed. The Endpoints support logging directly via Diagnostics
  • Breaking: The legacy used classes AttributeServer, EventServer, CommandServer were moved to the matter.js legacy package
  • Breaking: Removed many internally used legacy classes and datastructures
  • Feature: Added getLocal() to AttributeClient to retrieve the currently stored/cached value
  • Enhancement: Optimized the usage of the MDNSScanner to prevent holding data in memory that are not needed (e.g. from other fabrics or such)
  • Enhancement: Introduced multiple subclasses for CommissioningError to allow distinguishing between different error cases more easily:
    • MaximumCommissionedFabricsReachedError
    • CommissioningTimeoutError
    • DeviceAlreadyCommissionedToThisFabricError
    • FabricLabelConflictError
    • WifiOrThreadNetworkCredentialsNotConfiguredError
    • WifiNetworkSetupFailedError
    • ThreadNetworkSetupFailedError
    • NodeIdConflictError
    • CommissionableDeviceDiscoveryFailedError
    • OperativeConnectionFailedError
  • Enhancement: The default CommissioningFlow now validates if there is still a fabric entry left on the device to commission a node to.
  • Enhancement: Retries to re-establish a CASE session when connection fails because of invalid resumption data
  • Adjustment: ACL writes are not sent chunked by default from now on like also in chip SDK
  • Fix: Handles messages only that are secured as required for the relevant protocol
  • Fix: Correctly responds with a CASE Status response in case of commissioning errors for a client CASE establishment

• @matter/general

  • Enhancement: Allows async implementation of crypto methods

• @matter/model

  • Feature: We no longer load data model fields that are not required for operational purposes by default. You can load @matter/model/resources to populate the model with these fields. This saves a significant amount of memory for nodes
  • Enhancement: Model elements now instantiate with a reduced number of fields and object shapes to reduce memory usage and decrease the likelihood of megamorphic function deoptimization in runtimes with a JIT
  • Enhancement: We have optimized the resolution of global datatypes in the Matter model. This reduces startup for large nodes such as bridges with many devices
  • Enhancement: The serialized model now stores cross-references as strings and parses as necessary
  • Enhancement: FieldModel now contains a dedicated title field to capture the full name of features

• @project-chip/matter.js

  • Breaking: Added logging for PairedNode and legacy Endpoint classes via Diagnostics instead of the removed logEndpoint method

0.13.0 (2025-04-28)

• NOTE: This version is compatible with Node.js 20.x, 22.x, and 24.x. Node.js 18.x might be unsupported for BLE if installed before 20.05.2025 because the BLE libraries we use (noble/bleno) were temporarily only compatible with Node.js 20+. This is fixed for bleno >= 0.11.4 and noble >= 2.3.1.

• IMPORTANT: This release upgrades Matter support from Matter 1.3 to the latest release, Matter 1.4.0. This includes BREAKING CHANGES in a number of areas due to specification changes. 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 or when Datatypes or elements got renamed.

  • Especially please note that colorTempPhysicalMinMireds and colorTempPhysicalMaxMireds now need to be set when using ColorControl because the former unrealistic default values were removed from the specification. Please set proper values for your device Hint: realistic color temperature Mireds values are usually roughly between 150 (6500K) and 500 (2000K).
  • Also note the new cluster revision 5 for the OccupancySensing cluster which requires you to use feature flags, and also some attributes have changed behavior or got deprecated. We added logic that automatically fills the attributes occupancySensorTypeBitmap and occupancySensorType with the values according to the enabled features if needed.

• chip-testing

  • Feature: Added Chip-Tool compatible WebSocket Controller implementation to also run interop tests with matter.js controller
  • Feature: Added Docker based own Test Runner and execute all tests there too with chip-tool against matter.js test device

• @matter/examples

  • Enhancement: Added Robotic Vacuum Cleaner example to show the cluster dependencies and basic logic requirements
  • Enhancement: Added Air Quality Sensor example

• @matter/general

  • Breaking: Logger.logger is replaced with Logger.destinations. Properties of individual destinations are slightly different. A deprecated compatibility API should make this largely transparent
  • Feature: Logging destinations may process Diagnostic.Message directly and bypass matter.js formatting
  • Feature: Log formatting is now extensible with custom formats
  • Feature: QuietObservable is an extended event source that emits events at reduced frequency based on configuration
  • Enhancement: Formalized concept of a logging "destination" and converted API for managing destinations to a simple object interface
  • Enhancement: Modifying log levels and format using the Logger static interface now updates defaults and applies changes to all destinations
  • Enhancement: Transaction participants no longer need to implement commit-related methods if they do not participate in persistence
  • Enhancement: Missing IPv4 addresses on network interfaces are now ignored even if IPv4 is not disabled via configuration
  • Fix: Correctly handle MDNS records without QNames

• @matter/main

  • Feature: Automatically handle basicInformation uniqueId Property as defined by specification if not set by the developer

• @matter/node

  • Breaking: The Default OnOffServer implementation no longer has the "Lighting" feature enabled by default! Please enable manually when the relevant device type where the cluster is used in requires it or use the Requirement-classes like OnOffLightRequirements.OnOffServer to get the correct features enabled automatically.
  • Breaking: The Default LevelControlServer implementation no longer has the "OnOff" feature enabled by default! Please enable manually when the relevant device type where the cluster is used in requires it or use the Requirement-classes like DimmedLightRequirements.LevelControlServer to get the correct features enabled automatically.
  • Breaking: LevelControlServer API has a few small changes that may affect device implementors. Most notably the setLevel method is replaced with transition which handles both immediate and gradual level shifts
  • Breaking: Removed Implementation Logic for the "AbsolutePosition" Feature in WindowCovering default implementation because this is a forbidden (Zigbee) Feature anyway that no-one should use!
  • Breaking: The DoorLock cluster attribute supportedOperatingModes bitmap requires clearing bits for supported modes. To allow to set this bitmap correctly we added a helper bit-range alwaysSet (with value 2047) to set the unused bits. Please make sure to set the correct bits for your device according to the specification meaning.
  • Breaking: All default implementations now are async (as before if needed) or expose as MaybePromise to allow async or sync overriding. Ideally this does not change anything for custom implementations but checks for returned promises when calling "super" methods.
  • Feature: Transitions utility class offers a flexible API for implementing Matter attributes that change gradually at a constant rate
  • Feature: Attributes marked as Q (quieter) quality now support an extended quiet property that controls how often and when they emit. By default Q attributes emit once per second
  • Feature: LevelControlServer and ColorControlServer performs smoother transitions with configurable transition step sizes and Matter 1.4-compliant event emitting. It offers several new extension points for integrating with hardware and bridged devices
  • Feature: Added support for the ActionSwitch feature for the SwitchServer default implementation
  • Feature: Added basic validation for all ModeBase derived *Mode clusters
  • Feature: Added basic validation for OperationalState and derived *OperationalState clusters
  • Feature: Added basic validation and logic for the ServiceArea cluster
  • Enhancement: OccupancySensingServer is automatically filling some legacy attributes when features are correctly set as required by new revision 5 of the cluster
  • Enhancement: Event handling has received additional formality. The node now ensures that async handlers register as tasks with the node. Error logging contains more detail on the source of errors
  • Enhancement: $Changed events now run in a separate context from the emitter and errors will not interfere with the emitter
  • Fix: Switched "boot time" to be the time the node comes online instead of the time the OS started
  • Fix: Fixed patching of arrays to correctly allow setting arrays with fewer elements than the original array using set()

• @matter/nodejs

  • Breaking: The StorageBackendDisk class got removed, including the "node-localstorage" dependency, but the name got reused and so the "StorageBackendDiskAsync" is now "StorageBackendDisk".
  • Enhancement: Added a UDP send guard to reject hanging send calls after maximum 1-2s
  • Fix: Improves async storage reliability and error handling to prevent empty storage files in crashing edge cases. With this change write actions need longer a bit but are more reliable, which mainly affects controller use cases when persisting the device attribute data on the first subscription
  • Fix: Also accept incoming UDP traffic from unknown network interfaces for Matter messages

• @matter/nodejs-ble

  • Enhancement: Upgraded Noble and Bleno and optimized stability with BLE device and controller operations

• @matter/nodejs-shell

  • Feature: Added parameters --qrCode and --qrCodeIndex to the commission pair command to also use QR Code strings for pairing
  • Fix: Prevents crash on startup when having set a Fabric label in config

• @matter/protocol

  • Breaking: updateReceived() callback on subscriptions is triggered after all updated data events are sent out.
  • Feature: Enhanced getMultipleAttributesAndEvents() to also return attributeStatus and eventStatus properties with errors returned from the read interaction
  • Feature: Added getMultipleAttributesAndStatus() and getMultipleEventsAndStatus() to InteractionClient to allow also returning attribute and event errors from the read interaction
  • Enhancement: Allows accessing attributes, events, and commands in CLusterClient instances also by their ID.
  • Enhancement: Makes sure that the Node ID for commissioning of a new node is not already commissioned.
  • Enhancement: Returns the maximum interval in seconds when InteractionClient is used to establish a subscription
  • Fix: Makes sure to not Forward StatusResponseError cases that we generate locally to the device when not wanted
  • Fix: Enhances checks for Wi-Fi/Thread credentials in config for CommissioningFlow
  • Fix: Ensures that PASE establishments are guarded as defined by specification to prevent passcode brute force attacks
  • Fix: Informs the device when Controller cancels pairing because of a wrong passcode to allow direct retries

• @project-chip/matter.js

  • Breaking: Reduced exports to the relevant one for Controller usage. Please use @matter/main for the rest.
  • Breaking: Remove the Legacy Device building API. Please use the new SeverNode-based API, which is more flexible and powerful.
  • Breaking: Changed signatures of commissionNode() and createInteractionClient() to provide options as object and not plain parameters
  • Breaking: The handling of the requestFromRemote parameter (first parameter) in get*Attribute methods in ClusterClients changed behavior! providing "false" will now never try to read from remote, "true" will always try to read from remote and "undefined" will use the default behavior (read from remote if not available locally or fabric scoped read). Only relevant if you used this parameter with the value "false". Other use cases stay unchanged.
  • Feature: Allows using a custom Root-NodeId, CertificateAuthority, or CommissioningFlow implementation in the Controller
  • Feature: Allows establishing a secure PASE session to a device and use this to interact with the device in special pre-commissioning cases.
  • Enhancement: Exposing the current Subscription Interval on `PairedNode::currentSubscriptionIntervalSeconds()
  • Enhancement: Adjusted the initial Device connection to Read-All before subscribing to also have initial values for not-changed attributes
  • Enhancement: Added new PairedNode event connectionAlive to expose the subscription-alive triggers (on changes or after max interval)
  • Fix: Fixes an edge case in reconnection handling

• @project-chip/* packages (beside above)

  • Breaking: Packages are removed! Please use the new packages under @matter/* if needed

0.12.6 (2025-03-20)

• @matter/protocol
  • Fix: Fixes BLE commissioning for Controller

0.12.5 (2025-03-02)

• @matter/node
  • Fix: Fixed edge cases where subscriptions were not persisted correctly

0.12.4 (2025-02-26)

• @matter/general

  • Adjustment: Do not accept listeners on read-only transactions
  • Enhancement: Only report locks for slow async transactions in logs
  • Enhancement: Do not report Read transactions anymore in logs

• @matter/node

  • Feature: Added Persisted Subscriptions to try to reestablish subscriptions after a restart, enabled by default
  • Enhancement: Added caching for generated ClusterType and ClusterBehavior classes
  • Enhancement: Added preparations for optimized node read handling

• @matter/protocol

  • Feature: Allows re-establishing subscriptions after a restart
  • Enhancement: Optimized Report Data message chunking
  • Fix: Handles errors when setting fabric label during commissioning as non-critical for the commissioning flow
  • Fix: Ensure to use persisted CaseAdminTags when re-establishing a CASE session from the device side
  • Fix: Fixed another place with a Noc/ICA Fabric-ID validation issue
  • Fix: Fixes Session and Channel deletion in some cases
  • Fix: Properly handle read requests with no attributes and events and return an empty result

• @project-chip/matter.js

  • Cleanup: Deprecated some methods fof the CommissioningController and pairedNode to better define the best practice interfaces to use

0.12.3 (2025-02-05)

• @matter/protocol
  • Fix: Reduced some over-exact certificate validation to unblock Aqara commissioning
  • Fix: Prevented issues where closing subscriptions could block the session closing or establishing new subscriptions
  • Fix: Prevented establishing new exchanges while shutting down Exchange Manager

0.12.2 (2025-02-01)

• @matter/node

  • Enhancement: Added support to check all device types of an endpoint against ACL definition and not only primary one
  • Enhancement: Optimized data handling for subscriptions by reading them endpoint wise to optimize memory usage and to reuse the used context
  • Adjustment: Refactored ACL logic to just get relevant endpoint information instead of a whole EndpointInterface

• @matter/nodejs

  • Fix: Added Workaround for IP family confusion in Node.js 18.0.0 till 18.3.0

• @matter/protocol

  • Enhancement: Optimized sending of DataReports to stream the read data to the encoder when needed to reduce memory usage
  • Adjustment: Moved the handling to set the fabric label during commissioning to after commissioningComplete to work around a Tasmota-Matter bug

0.12.1 (2025-01-25)

• @matter/protocol

  • Adjustment: For subscriptions we now trigger event listeners before attribute listeners
  • Fix: Added force closing of exchanges on shutdown of the node

• @project-chip/matter.js

  • Fix: Allows more cases when checking if a device is battery powered to address real world devices

0.12.0 (2025-01-23)

• @matter/general

  • Enhancement: Limits MDNS expires just to the relevant operational records when removing fabric

• @matter/model

  • Feature: The constraint evaluator now supports simple mathematical expressions
  • Feature: The constraint evaluator now supports limits on the number of Unicode codepoints in a string
  • Feature: Default values may now be a reference to another field

• @matter/node

  • Feature: Constraint and conformance expressions may now reference values by name in any owner of a constrained value
  • Enhancement: Each new PASE session now automatically arms the failsafe timer for 60s as required by specs
  • Enhancement: Optimizes Node shutdown logic to close sessions and subscriptions before shutting down the network
  • Fix: Fixes withBehaviors() method on endpoints

• @matter/nodejs

  • Breaking: The Sync Storage classes mainly used in legacy API now have an async close method!
  • Fix: Converts commissioning.fabrics into dynamically generated property to ensure it is up to date when accessed

• @matter/nodejs-ble

  • Enhancement: Restructures BLE connection handling to improve reliability and eliminate hanging commissioning processes
  • Fix: Adds support for advanced manufacturer data on Windows (Noble update)
  • Fix: Added workaround for Noble on Windows to prevent discovery issues
  • Fix: Considers formerly discovered devices as outdated when new discovery is started

• @matter/protocol

  • Feature: Reworks Event server handling and optionally allows Non-Volatile event storage (currently mainly used in tests)
  • Enhancement: Adds a too-fast-resubmission guard for Unicast MDNS messages
  • Enhancement: Optimized Logging for messages in various places
  • Enhancement: Added support for concurrent and non-concurrent commissioning flows
  • Enhancement: Re-arms the failsafe timer in commissioning flows before steps that could take longer and during operative reconnection
  • Enhancement: Stores Matter relevant MDNS host information to faster reuse when new SRV announcements come in
  • Fix: Corrects some Batch invoke checks and logic
  • Fix: Fixes MDNS discovery duration for retransmission cases to be 5s
  • Fix: Processes all TXT/SRV records in MDNS messages and optimized the processing
  • Fix: Prevents multi-message interactions from trying to continue on a new exchange
  • Fix: Fixes the timed node polling during discovery
  • Fix: Fixes commissionable devices discovery with timeout
  • Fix: Restores the possibility to cancel a (continuous) discovery for commissionable devices
  • Fix: Fixes enablement of MDNS broadcasts when BLE commissioning is used

• @project-chip/matter.js

  • Feature: (Breaking) Added Fabric Label for Controller as a required property to initialize the Controller, including setting the Fabric Label when commissioning and validating and updating the Fabric Label on connection
  • Feature: Added autoConnect property to node connection options to allow not automatically connecting to a node when the PairedNode instance is created. Also introduces a non-blocking PairedNode.connect() method to connect to a node
  • Feature: Added CommissioningController.getNode() method to get a PairedNode instance for a node by its node ID without a direct connection
  • Feature: Allows updating the Fabric Label during controller runtime using updateFabricLabel() on CommissioningController
  • Enhancement: Improves Reconnection Handling for devices that use persisted subscriptions
  • Enhancement: Use data type definitions from Model for Controller Device type definitions
  • Enhancement: Added remove*Listener() to ClusterClient objects to remove listeners added with add*Listener() or subscribe*() (The subscription is not cleared!)
  • Fix: When a paired node gets disconnected (or decommissioned) invalidate subscription handlers to prevent reconnection tries

0.11.9 (2024-12-11)

• @matter/node

  • BREAKING: WindowCovering: supportsCalibration is moved from state property to an internal property
  • 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
  • Enhancement: EventsBehavior allows for configuration of event buffering
  • Enhancement: Matter protocol initialization now runs independently of and after behavior initialization, giving behaviors more flexibility in participating in protocol setup
  • Fix: ColorControl: Do not try to convert color mode details if they are not defined
  • Fix: ColorControl: colorMode attribute needs to be defined if the HS feature is not used because default value 0 is else invalid

• @matter/protocol

  • Fix: Also retry the 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 the default value from the attribute ColorMode of ColorControl cluster because feature specific enum value was used

• @project-chip/matter.js

  • BREAKING: In ContentLauncher cluster ParameterEnum is renamed to Parameter and Parameter is renamed to ParameterStruct
  • Feature: Introduces PairedNode#triggerReconnect() method to trigger a reconnection
  • Enhancement: Considers a node in the 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

• @matter/model

  • BREAKING: ClusterModel and ValueModel properties members, activeMembers and conformantMembers are removed; use Scope#membersOf instead
  • 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

• @matter/protocol

  • Feature: The algorithm that chooses event occurrences to discard when the buffer overflows is now smarter and configurable
  • Feature: Event occurrence buffering now offers optional persistence

• @matter/testing

  • Feature: New test harness supports simplified management of Matter certification tests
  • Feature: Build system for lightweight (relatively speaking) Docker image with chip-tool and CHIP certification tests available at https://github.com/matter-js/matter.js-chip

0.11.8 (2024-11-29)

• @matter/protocol

  • Fix: Correctly parse DataReports with duplicate non-Array data entries

• @matter/node

  • Fix: Ensures to completely remove all stored endpoint data when the endpoint is deleted

• Matter cluster definitions and implementations

  • Fix: Fixes LevelControl cluster extension point definitions and adds a missing parameter

0.11.7 (2024-11-28)

• @matter/node
  • Fix: Fixes race condition that can partially destroy ACL entries when concurrent writes happen in parallel to ACL writes

0.11.6 (2024-11-27)

• @matter/general

  • Fix: Fixes a potential recursion in parsing DnsQNames

• @matter/nodejs

  • Fix: Fixes a typo and crash case on network closing when ending the matter.js process

• @matter/protocol

  • Fix: Adds missing subscription update when the endpoint structure changes

• @matter/types

  • Fix: Do not use revisions of 0 for Unknown fallbacks

0.11.5 (2024-11-25)

• @matter/create

  • Feature: Added a command line option "--verbose" to enable informational NPM messages during initialization
  • Feature: Added template "contributor" to bootstrap dev environment for working on matter.js itself

• @matter/node

  • Enhancement: The with functions on endpoint and cluster behavior types now alias to withBehaviors and withFeatures respectively to make their function more explicit
  • Enhancement: Endpoints now ignore persisted values for clusters when features change across restarts. This allows for startup when persisted values become invalid due to conformance rules
  • Fix: Triggers CommissioningServer#initiateCommissioning when the server restarts outside of factory reset
  • Fix: Ensures to initialize all known endpoint numbers to prevent duplicate number assignment edge cases

• @matter/nodejs

  • Feature: New export @matter/nodejs/config allows for fine-grained configuration of Node.js bootstrap logic
  • Fix: Restores backward compatibility to sync storages from matter.js <0.11 in case ideas used special characters (uncommon)

• @matter/protocol

  • Fix: Corrects the DataVersion Filter shortening logic to ensure the maximum message size is not exceeded

• @matter/tools

  • Multi-project test runs now use a single process to improve performance

• Matter cluster definitions and implementations

  • Enhancement: Removes default value from the attribute ControlSequenceOfOperation of Thermostat cluster because a feature-specific enum value was used
  • Fix: Reverts MoveToLevel workaround from 0.11.4
  • Fix: ColorControl: Round calculated Kelvin values when calculated from Mireds
  • Fix: GeneralDiagnostics: Network interface names are now correctly shortened to 32 characters

• matter.js git repository

  • Feature: We've added project configuration for VS code including recommended extensions, code snippets, and launch configurations

0.11.4 (2024-11-07)

• Matter cluster definitions and implementations
  • Fix: Adjusted levelControl cluster command MoveToLevel implementation to temporarily declare optionsMask/optionsOverride fields optional

0.11.3 (2024-11-06)

• @matter/nodejs

  • Fix: The MaybeAsyncStorage class close method is not async
  • Fix: Makes sure that the Async storage waits that all writes are finished in some cases

• @matter/nodejs-ble

  • Fix: When BLE scanning was not started, we also did not need to stop it (and risk blocking issues)

• @project-chip/matter-node.js

  • Fix invalid import for compat package

0.11.2 (2024-11-02)

• @matter/node

  • Feature: Automatically lock behavior state on invoke
  • Fix: Ensures to fully load the Descriptor cluster before adding additional device types

• @project-chip/matter.js

  • Fix: Fixes some compatibility re-exports that got screwed up since 0.11.0

0.11.1 (2024-10-31)

• @matter/create
  • Fix: Project generator includes all required dependencies for controller and complex devices
  • Feature: Project generator now includes .gitignore and VS Code launch configuration

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 a 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 an 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 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 discovering VendorId + ProductId together optionally

• matter.js clusters:

  • Adds convenience helper method for ElectricalEnergyMeasurement cluster (for usage, see new example MeasuredSocketDevice) to set measurements and also trigger the necessary 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 a 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 reconnections by using dataVersionFilters on read and subscribes to reduce bandwidth on reconnections. The data are not (yet) persisted, so after Controller restarts, the data is collected anew.
  • Feature: Low-level InteractionClient API allows enriching 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 use persisted subscriptions on the device side
  • Enhancement: Only recreate PairedNode internal objects when the structure really changed also on reconnections.
  • Enhancement: Utilize more information (beside partList changes now also feature, serverList, attributeList, generatedCommandLists) as the structure changes to reinitialize objects.
  • Enhancement: Huge refactoring in internal logic, optimized reconnection, and rediscovery

0.10.7 (2024-11-07)

• Matter cluster definitions and implementations
  • Fix: (Backport from 0.11.4) Adjusted levelControl cluster command MoveToLevel implementation to temporarily declare optionsMask/optionsOverride fields optional

0.10.6 (2024-09-21)

• Matter-Core functionality:
  • Fix: Excludes subscription based attribute change reads from acl check in all cases

0.10.5 (2024-09-20)

• Matter-Core functionality:
  • Enhancement: Added some more logging for sessions and ACL failures

0.10.4 (2024-09-16)

• matter.js API:
  • Fix: Prevent trying to access PowerTopology attribute which is not always present
  • Fix: Always add the endpoint device types first to the device type list

0.10.3 (2024-09-15)

• Matter-Core functionality:
  • Fix: Fixes channel cleanup
  • Fix: Fixes Subscription error handling

0.10.1 (2024-09-08)

• Matter-Core functionality:
  • Enhancement: Added an "expected processing time" for interactions to be executed by the peer
  • Enhancement: Added additional wait time after last resubmission was done to allow a full resubmission cycle from the peer
  • Enhancement: Optimized PASE/CASE message timing comparable to chip sdk (expects e.g. 30s processing time for crypto related calls)
  • Fix: Optimized exchange handling for cases where retransmissions were all sent but no ack was received
  • Fix: Makes sure that Retransmissions happen in all error cases
• matter.js New API:
  • Fix: Optimized some special cases in the ColorControl cluster default implementation
• matter.js Controller API:
  • Breaking: Adjusted some method signatures slightly (e.g. connect()) to summarize singe parameters into an options object
  • Enhancement: Restructured Paired Node connection handling to make sure NodeStatus is correct and commands return in case of error. Reconnections are handled in the background.
  • Enhancement: Takes over new connection options when a node is connected again after disconnect with different options

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

0.9.4 (2024-07-19)

• Matter-Core functionality:
  • Feature: Allows to generate Certification declarations flagged as provisional for certification purposes
  • Feature: Allows to disable mandatory field checks on TLV encoding when handling fabric sensitive structs
  • Fix: Makes sure to remove fabric sensitive fields and events when they are not allowed to be read or subscribed
  • Fix: Makes sure to handle commissioning related cases with PASE sessions correctly regarding temporarily added fabrics and certificates
  • Fix: Verifies provided trusted root certificates completely

0.9.3 (2024-06-26)

• Matter-Core functionality:
  • Fix: Makes sure to clear all subscriptions from the subscriber noe and not only the current session when not keeping subscriptions

0.9.2 (2026-06-20)

• Matter-Core functionality:
  • Enhancement: Added some more certification relevant checks in Interaction server

0.9.1 (2024-06-01)

• IMPORTANT: This version adds Access Control functionality and also tries to set missing ACL entries on startup on a best effort basis. If you encounter issues and have Access/Permission denied errors ain the logs then please delete and recommission the device to make sure all ACLs are set correctly. If this is not possible open GitHub issue or contact us in Discord to get help.
• Matter-Core functionality:
  • Feature: Implemented Access Control List (ACL) as required by Matter specification
  • Enhancement: Enhanced several internal structures needed to support ACL properly
  • Enhancement: Enhanced all datatypes that are MEIs to allow validation of the MEI and the allowed scopes and value ranges
  • Enhancement: Remembers CATs from Sessions and uses them for CASE session resumptions
  • Enhancement: Allows decoding of TlvLists with protocol specific tags
  • Enhancement: Refactored channel management to match specification and allow several channels per fabric and node
  • Enhancement: Closing message exchanges already when last message got acknowledged and prevent up to 9s waiting time for closures
  • Enhancement: Prevents to announce a new commissionable device just before doing a factory reset
  • Enhancement: Expires announcements for last removed fabric directly
  • Fix: Fixes deepCopy to really doing a deep copy and not just copying the first level
• matter.js Legacy API:
  • Feature: Added Access Control cluster implementation
  • Feature: Added minimal Group key management cluster implementation which supports no additional groups (so only IPK allowed)
  • Enhancement: Enhanced Operational Credentials cluster to add needed ACLs on commissioning including backward compatibility
• matter.js New API:
  • Feature: Added Access Control cluster implementation
  • Feature: Added minimal Group key management cluster implementation which supports no additional groups (so only IPK allowed)
  • Enhancement: Enhanced Operational Credentials cluster to add needed ACLs on commissioning including backward
  • Enhancement: Optimized Factory reset logic when last Fabric is removed
  • Fix: Persist also writable and fabric scoped data in new API
  • Fix: Releases locks also in Precommit errors
• Chip testing:
  • Added automatic testing of chip tests suites for ACE, ACL, and partly IDM

0.9.0 (2024-05-14)

• Matter-Core functionality:
  • Feature: cluster default implementations for the following clusters were added/updated:
    • BooleanState: Automatically emit the StateChange event when enabled for the cluster and the stateValue changes
    • ColorControl: Implemented all features and commands as defined by specification with an optional transition logic managed by matter.js
    • LevelControl: Implemented all non-Frequency command handlers as defined by specification with an optional transition logic managed by matter.js
    • LocalizationConfiguration: Implemented activeLocale validation
    • LowPower: Implemented event enterLowPowerMode to be emitted when the sleep command gets called
    • ModeSelect: Implemented all features and commands as defined by specification
    • Switch: Implement all features and events including debouncing (optional), switch-release, long- and multi-press detections
    • TimeFormatLocalization: Implemented activeTimeFormat validation
    • WindowCovering: Implemented all features and commands as defined by specification
  • Enhancement: Adjusted handling of TlvList order to match better with matter specification and ensure field orders are preserved
  • Enhancement: Adds Certificate validation and cryptographic verification during commissioning and CASE session establishment
  • Enhancement: Adds additional logging information for PASE and CASE to better understand errors without debug logging
  • Enhancement: Adds several Optimizations and adjustments for Obervers (e.g. Observable.isObserved)
  • Fix: Corrects returned errors for two commands on OperationalCredentials cluster
• matter.js Legacy API:
  • Breaking: The object type for providing custom production certificates has changed to be now in sync with the DeviceCertification class (just the property names changed)
  • Feature: Added on demand certification determination via an async certificate provider method (alternative to provideing certs directly) to determine certificates on first commissioning request
• matter.js New API:
  • Breaking: The name of the _$Change Events for attributes and such are changed to _$Changed . Please adjust your code!
  • Breaking: Introduced ExtensionInterface to define extensible/custom methods for behavior/Cluster-Server implementation to be available when extending this class (needed because of a TS bug 27965)
  • Feature: Added on demand certification determination via an async certificate provider method (alternative to provideing certs directly) to determine certificates on first commissioning request
  • Enhancement: Optimized constraint validations and conformance error messages
  • Enhancement: Conditionally enables the ReachableChanged event on the Root Endpoint BasicInformation cluster if the reachable attribute is defined in the defaults
  • Enhancement: Allow to register events directly when initializing endpoints like in legacy API
  • Enhancement: Allows for cluster implementations to dynamically add/enable state attributes and events
  • Enhancement: Added "fieldName$Changing" event handlers that emit in transaction pre-commit and allow for state mutation and will cycle for a limited number of times until state is stable
  • Enhancement: Allows "fieldName$Changed" and "fieldName$Changing" event handlers to be async
  • Enhancement: Adds Conformance validation for enums, fieldname references, and some more cases
  • Enhancement: Makes various config variables apply dynamically
  • Enhancement: Added environment variable `network.interfaceNameTypeMap' to allow mapping of network interface names to types (Wifi, Thread, Ethernet)
  • Fix: Fixes some issues around event handling in the new API and makes sure events are not de-registered on factory resets
  • Fix: Corrects the returned status error code when an Enum value is set to an invalid value
  • Fix: Fixes a floating promise in FailsafeTimer; it tended to kill a test run without an easy way to identify the cause
  • Fix: Fixes bounds check with references to null fields
  • Fix: Addresses rejections that were erroniously being treated as uncaught when multiple reactions were queued
• Chip testing:
  • Enhancement: Adds automatic CI testing for all clusters listed in matter.js Readme
• matter.js tooling:
  • Enhancement: Migrates cluster identification to the pattern used in the newer device code. It now scans the entire document rather than attempting to navigate via the index. This is simpler and more resilient
  • Enhancement: Various other small changes improve resiliency
  • Enhancement: Removes the "main" closure from codegen scripts that added a bit of friction to debugging
  • Enhancement: Adds proper CLI support to codegen scripts to override various behaviors and provide information on the script
  • Enhancement: We now version the intermediate models. In the future we can use this to add informational revision information to model elements and make the API adaptive based on the targeted Matter version
  • Fix: Fixes a bug that was causing field-level prose to be incorrectly associated with the containing element in malformed portions of the core spec

0.8.1 (2024-04-15)

• Matter-Core functionality:
  • Cluster default implementations for the following clusters were added/updated:
    • (GreydonDesu) Feature: DoorLock: Implemented bare minimal commands to lock/unlock the door
    • Enhancement: Enhanced Identify cluster default implementation by additional state isIdentifying and events startIdentifying and stopIdentifying
  • Enhancement: Diagnostic and logging information, also on SIGUSR2 signal for node.js
  • Fix: Updates subscribed events on structure updates to make sure also new events are reported correctly
  • Fix: Removed invalid length assumption in Sigma2
• matter.js New API code flows:
  • Enhancement: Optimizes Node activity tracking and shutdown/startup handling

0.8.0 (2024-03-29)

• Packages
  • IMPORTANT: We switch away from re-exporting all matter.js functionality in matter-node.js, so please adjust your imports and make sure that you include matter.js together with matter-node.js in your dependencies in the exact same version!
  • Changed BLE library (Bleno/Noble) to another fork with better support for Windows and UART devices
• Matter-Core functionality:
  • Breaking: Storage implementations got added new methods "contexts", "values" and a multi-set valiant that need to be implemented if you have own Storage implementations. Also, storages now derive from a SyncStorage or MaybeAsyncStorage class weather they are sync or async
  • Adjustment: Cluster versions do not need to be persisted, so remove in legacy and new API
  • Fix: Decode Empty nullable data types as null when they have constrains that would require a minimum length
  • Fix: Convert Error type of Network errors and handle in case of subscription failures
  • Fix: Fixes a cryptographic issue that failed PASE establishment in 1/255 times, Replace BN/elliptic by @noble/curves library
  • Fix: Fixed ClusterClient methods set and subscribe to really return the Promise of the action
• matter.js API:
  • IMPORTANT: Introduction of new High level API with complete Device type support for Matter 1.1 types, see migration guide. For now the known API that we had up top 0.7 is still included and fully working and compatible when old imports are used, but called "Legacy" for now. It will be removed in a later version not yet decided.
  • Feature: Introduced Environment concept to centralize MDNS, storage and configuration and platform specific central functionalities (Replaces MatterServer from Legacy API).
  • Feature: Enhanced Matter protocol and interaction abstractions and introduced transactional handling of actions which are rolled back completely in case onf errors.
• matter-node.js
  • Enhancement: Makes sure console.log on node.js correctly log Proxy objects with their data and not the Proxy object itself
  • Enhancement: Allows to send SIGHUP2 signal to the node.js process to print out information on running timers and promises of the process to console
• matter-node.js Examples
  • IMPORTANT: All existing example scripts got renamed to *Legacy.ts when the use the "old/until now"-API and can be used directly after changing the name (exception: DeviceNode.ts became DeviceNodeFullLegacy.ts!). They are 100% compatible to the ones before.
  • Feature: Added all examples again converted to use the new devices API and we also added some more new device types to show the new API better
  • Feature: Enhanced DeviceNodeFull example to show several more way on how to use the new API and special cases.
  • Feature: Enhanced DeviceNodeFull example to simulate a Thread Networking device to check BLE commissioning flows
• matter.js Tooling
  • Enhanced Code generation to also generate classes for Cluster implementations and device types with full Feature configurability and TypeScript typing support for this

0.7.5 (2024-02-23)

• Matter-Core functionality:
  • Feature: Allowed multiple Loggers and log targets to be registered. Logging to console is still default
  • Enhancement: Implemented handling for session interval parameters as defined by Matter 1.2 specification
  • Enhancement: Improved discovery data handling and use MDNS data for Pase/Case connections session interval parameters
  • Enhancement: Storing session parameter with session resumption details to reuse on session restores
  • Enhancement: Enhanced encoding of fabricIndex field in write interactions and optimized validation for such cases
  • Enhancement: Prevented resending the same MDNS scanner queries
  • Enhancement: Optimized MDNS Scanner queries to prevent resending of queries that are already in progress
  • Enhancement: Optimized Commissioning error handling for Controller
  • Enhancement: Enhanced ValidationError to provide the affected structure-aware fieldname in case of an error
  • Fix: Improved Standalone Ack handling for messages to match Matter 1.2 specification
  • Fix: Adjusted commands GoToLiftPercentage and GoToTiltPercentage to match with Matter SDK and work around specification issue
  • Fix: Fixed BLE commissioning for Controller
  • Fix: Makes sure to validate the data when invoking a command from a cluster client
  • Fix: Only set session active timestamp if we create a session based on an incoming message and not when we are the creator of the session to prevent too fast resubmissions
  • Fix: Correctly handle CASE Resumptions without known resumption records and fallback to a full CASE session establishment
  • Fix: Enhanced commissioning flow based on latest Matter SDK test cases and match with specification
  • Fix: Enhanced handling for fabric scoped command invokes to match with specification
  • Fix: Enhanced handling for fabric sensitive attribute reads to match with specification
• matter.js API:
  • Fix (potentially Breaking): Remove NetworkCommissioningCluster (Ethernet) from default added clusters in CommissioningServer because we formally have an out-of-band network connection, re-add manually if needed!
  • Enhancement: Allowed to pass connect options when connecting a node for Controller
  • Enhancement: Stored Discovery and Basic information data for commissioned nodes and allow API access for easy determination of devices without need to connect to them
  • Enhancement: Improved OnOff/Dimmable Lighting devices and add Startup handling to match specification
  • Enhancement: Remove Scenes cluster for now from all device types because provisional and changes upcoming with Matter 1.3
  • Enhancement: Optimized Commissioning error handling
  • Enhancement: Added connection options to Controller connect methods
  • Enhancement: Enhanced CLI arguments parser to allow "--name" additionally to "-name"
  • Fix: Adjusted the Group limits in GroupKeyManagement cluster to 1 because we do not support groups yet
  • Fix: (Luligu) Corrected the Device type for bridged nodes with Power source information
  • Fix: Adjusted Commissioning logic for Controller to accept devices without network commissioning cluster by assuming out-of-band IP connection
• matter.js shell:
  • Feature: Added support for Debug logging into a Logfile additionally to e.g. Info logging in console
  • Enhancement: Adjusted logic to output detailed node information on nodes command
  • Enhancement: Do not subscribe all attributes when connecting a node for administrative actions (unpair, open commissioning windows)
  • Enhancement: Allowed to specify the BLE HCI id as shell start parameter and store in settings
  • Enhancement: Added attribute, event, and command actions in the shell based on the Cluster model (all known Matter 1.1 clusters are supported)
  • Enhancement: Enhanced the Shell Readme with many information and examples
  • Fix: Correctly quote when showing configuration values for wifi- and thread-credentials
  • Fix: Fixed issues when using quoted strings as CLI parameters (e.g. for wifi/thread credentials or JSON structs for commands/attribute writes)

0.7.4 (2023-12-31)

• Matter-Core functionality:
  • Enhancement: Refactor Core Session management to match specification
  • Enhancement: Refactor message duplication detection and handling to match specification
  • Feature: Upgrade Interaction protocol revision to 11 (Matter 1.2) and adjust event error handling in DataReports

0.7.3 (2023-12-18)

• Matter-Core functionality:
  • Feature: Added CASE Authenticated Tags support (initialization from NOC and validation only)
  • Enhancement: Added validation handling to Invoke processing
  • Fix: Fixed message size check to allow processing of two big non matter UDP messages
• matter.js API:
  • Feature: Added NodeStateInfo state "Decommissioned" to inform from about a successful decommissioning of a device
  • Feature: Added check that provided unique storageKeys are really unique
  • Fix: Makes sure to initialize all nodes in the MatterServer on startup also if errors occur on single ones
  • Fix: Only try to connect to a commissioned device in controller if it has at least one
  • Fix: Makes sure to call commissioningChanged callback when device is factory reset
  • Fix: Really remove all data in factory reset of a device

0.7.2 (2023-12-04)

• Matter-Core functionality:
  • Corrected default values for TemperatureMeasurement Cluster
  • Handled Message extensions and Secured extensions in matter messages correctly (means they are ignored for now but read from the data stream)
  • Handles too huge UDP messages correctly by dropping such messages

0.7.1 (2023-11-24)

• Matter-Core functionality:
  • Optimized Exchange deletion and change a throw to log when a already deleted Exchange should be deleted again
• matter.js API:
  • Added some convenient methods on PairedNode instance to access Clusters on Devices and also the RootEndpoint (if needed)
  • Added method to cancel a running discovery process for commissionable devices

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

0.6.0 (2023-10-08)

• Matter-Core functionality:
  • Fix: Adjusted Event Priority definition to match to specs
  • Fix: Adjusted Bleno and Noble to be optional Dependencies to allow building the Monorepo also when these are failing (e.g. on Windows)
  • Fix: Added missing MDNS announcement expiry and allowed to announce fabrics and an open commissioning window in parallel
  • Fix: Prevented crash when logging undefined/null values
  • Feature: Implemented TimedInteractions for Write/Invoke request s as required by specs
  • Feature: Added support for generic Response suppression if requested or needed for group communication
  • Feature (orlenkoo) Implemented first OnOff Cluster Lighting feature command handlers (WIP)
  • Feature: Also publishes matter-node.js packages as ESM in parallel to CJS
  • Feature: Added clear method to the storage classes to allow factory reset of the storage
  • Feature: Added ICAC (Intermediate CA Certificate) decoding
  • Feature: Implemented Array chunking for DataReport messages to allow also bigger array structures to be sent
  • Feature: Implemented Tag compression for DataReport messages (but disabled it because standard do not support it officially yet)
  • Feature: Refactor complete commissioning logic (AdministratorCommissioning, GeneralCommissioning, OperationalCredentials clusters) to match to specs and implement main logics as defined
  • Enhance: Memory footprint optimizations
  • Enhance: Introduced building and building, running, and test executions scripts to not use ts-node anymore and many more optimizations to test and build processes
  • Enhance: ClusterFactory internally uses a simplified method of CLuster types that are compatible to the current ones but soon might replace them
  • Enhance: Using longer response timeouts when Failsafe timer is active during commissioning (Controller)
  • Enhance: Optimized Commissioning logic of Controller implementation regarding failsafe timers and network commissioning
  • Enhance: Added timeout handing to the Message queue to prevent reading DataReports get stuck if device do not send anymore
  • Enhance: Added support in StatusResponseError to also handle a cluster specific status code (for write and invoke)
  • Enhance: Added init and destroy methods to the Cluster-handlers to allow to build proper cluster logics and also to free resources (e.g. stop timers on cluster destroy)
  • Enhance: Re-Announce the device when a subscription was cancelled by a peer in order to have a fast reconnect of the peer
  • Enhance: Adjusted MDNS implementation to be more near to MDNS specifications and also added performance optimizations
• matter-node.js:
  • Fix: (vilic) Enhancements for windows networking and tooling
• matter.js API:
  • Breaking: Move "disableIpv4" from CommissioningController/Server options to MatterServer to also consider it for MDNS scanning and broadcasting
  • Breaking: Change MatterServer constructor second parameter to be an options object
  • Breaking: Streamline Device API and rename onOff/isOnOff -> get/setOnOff
  • Breaking: EndpointStructureLogger (method logEndpointStructure) was moved from util to device export!

0.5.0 (2023-08-22)

• Matter-Core functionality:
  • Breaking: Added support to allow to clearly model some more attribute types with internally different behaviour:
    • Added types for WritableFabricScopedAttribute and OptionalWritableFabricScopedAttribute
    • Added types for FixedAttribute and OptionalFixedAttribute
    • Added FixedAttributeServer which only allows to "get" the value but not to set it
    • Added FabricScopedAttributeServer which gets and sets the value based on the provided fabric
    • Updated ClusterServerObj and ClusterClientObj typings to respect these Attribute types
    • Updated all Cluster definitions that use such attribute types
  • Breaking: Add Interface for Events which requires to define the supported events when creating a ClusterServer
  • Breaking: Include Event support in InteractionClient which changes several Read/Subscribe method signatures or adds new methods
  • Breaking: GeneralCommissioningServerHandler is now a function that takes configuration for setRegulatoryConfig handling
  • Breaking: Types of specific clusters are no longer exported flat on main level. Cluster exports are now namespaces that include their types.
  • Breaking: All collection files meant to be used for exports only are renamed to export.ts and should not be used for internal imports
  • Breaking: Attribute listener methods renamed: addListener -> addValueSetListener, addMatterListener -> addValueChangeListener (also remove methods) to make it more clear what they do
  • Breaking: Change from object style to Branded types for special Datatype objects (e.g. "new VendorId(0xFFF1)" -> "VendorId(0xFFF1)")
  • Breaking: ClusterClient and ClusterServer classes were moved from "interaction" export to "cluster" export
  • Breaking: Refactor the (low level) ClusterClient API to be more convenient to use with many optional fields for read/write/subscribe
  • Breaking: Cluster*Obj and the internal representation for more correct typings
  • Breaking: The InteractionClient is no longer exchangeable in ClusterClient cases (because makes no sense and was never working)
  • Feature: Enhance CommissioningServer options to also specify GeneralCommissioningServer details and settings
  • Feature: Adjust RegulatoryConfig Handling in Device and Controller to match with specifications
  • Feature: Endpoint Structures use custom-unique-id (from EndpointOptions)/uniqueStorageKey (from BasicInformationCluster)/serialNumber (from BasicInformationCluster)/ Index (in this order) to store and restore the endpoint ID in structures
  • Feature: (@mahimamandhanaa) Add BTP (Bluetooth Transport Protocol) codec class for encoding and decoding of BTP messages
  • Feature: Enhanced BitMap typing and Schemas to allow "Partially" provided Bitmaps by suppressing the "unset" bits
  • Feature: Allow to define discoveryCapabilities structure when getting pairing code in CommissioningServer
  • Feature: Added Bluetooth package (matter-node-ble.js) to allow to use Bluetooth as transport layer for initial commissioning. Implemented device side for now
  • Feature: Global Attributes are also accessible in ClusterClient instances (e.g. to get the list of features of the cluster)
  • Feature: Refactor Controller Commissioning process and add network commissioning support
  • Feature: Correctly Handle FabricIndex fields for Read and Write requests
  • Feature: Handle subscription errors and destroy session if failing more than 3 times
  • Feature: Add full event support (Device and Controller) including triggering some default events automatically (startup, shutdown, reachabilityChanged, bootReason)
  • Feature: Added support for dataVersionFiltering and eventFilters for read and subscribe requests for Device and Controllers
  • Feature: Added more parameters to several InteractionClient methods to allow to configure more parameters of the requests
  • Feature: Allows subscripts to be updated dynamically when the endpoint structure for bridges changes by adding or removing a device
  • Feature: When used as Controller also "unknown" CLusters, Attributes, Events, and DeviceTypes are generically parsed and supported and can be detected as unknown in code
  • Feature: When used as controller the read data about supported attributes, events are considered when create Attribute/EventClient objects and can be differentiated by PresentAttributeClient/UnknownPresentAttributeClient class types
  • Enhance: Device port in MDNSBroadcaster is now dynamically set and add UDC (User directed Commissioning) Announcements
  • Enhance: Enhanced MessageCodec and check some more fields
  • Enhance: Added possibility to define conditional cluster attribute/Command/event definitions and introduce runtime checking for these. Part of Cluster Structure rework still WIP
  • Enhance: (@vves) Add Window Covering Cluster definition
  • Enhance: Split up and corrected PowerSource and PressureMeasurement Cluster based on Matter 1.1 Specs
  • Enhance: Detailed cluster data model and related logic
  • Enhance: Generates all cluster definitions from Matter 1.1 specification and CHIP v1.1-branch automatically. This brings basic definition support for all clusters!
  • Enhance: Makes sure Fabric-Scoped requests are handled correctly for read and subscriptions
  • Enhance: All Errors thrown by the library are now derived from the MatterError class and split up into several subclasses
  • Fix: Added missing PulseWidthModulationLevelControlCluster to AllCLusters
  • Fix Typing of Commands in ClusterClient if no commands were present
  • Fix: Fixes equality checks in Attribute servers to check deeper than just === (and introduce new util method isDeepEqual)
  • Fix: Makes sure an error received from sending subscription seed data reports is not bubbling up and activate subscription after successful seeding
  • Fix: Allows Node.js Buffer objects to be persisted to storage as a Uint8Arrays that they subclass
  • Fix: Fixes a Subscription timer duplication issue and collect attribute changes within a 50ms window to reduce the number of subscription messages
  • Fix: Returns correct Error-Status for Read-/Write-/Subscribe- and Invoke-Requests
  • Fix: Fixes TLV Encoding for strings with UTF8 relevant characters
  • Fix: Adjusted DataVersion handling to track version on ClusterInstance level as required by Specs. Stored values that might got invalid by this change are deleted and recreated on next change.
  • Refactor: Refactor Endpoint structuring and determination to allow dynamic and updating structures
• matter.js API:
  • Breaking:
    • Adjusted some constructors of the new API and remove the option to pass an array of clusters to be added initially because this was no longer compatible to the strong typing in some places. Use addClusterServer and addClusterClient methods
    • Endpoint ID parameter got replaced by an EndpointOptions structure that also allows to define a custom unique ID for endpoint structuring
    • Composed devices objects should only be used on an Aggregator
  • Deprecation: The classes MatterDevice and MatterController are deprecated to be used externally to the library and will be removed in later versions.
  • Feature: Enhance Storage system to allow to create subcontext stores to allow better separation of data
  • Feature: Allow to also remove devices from Aggregators
  • Feature: Optionally allow to define discovery capabilities when generating Pairing code
  • Feature: Add methods to CommissioningServer/Controller class to get information on active sessions and commissioned fabrics
  • Feature: Enhance CommissioningController to allow subscribing to all attributes and events directly on startup
• Reference implementation/Examples:
  • Breaking: The storage key structure got changed to allow multi node operations within one process. This requires to change the storage key structure and to migrate or reset the storage.
    • Migration: prepend any storage key except Device._ and Controller._ with "0." in the filename
  • Deprecation: The CLI Examples LegacyDeviceNode and LegacyControllerNode is removed in this version! Use the new variants please.
  • Change: The default storage names now start with a "." at the beginning to allow to hide them in some file explorers and git.
  • Change: Example script are moved to package matter-node.js-examples
  • Feature: The Device example script got a new parameter -ble to also initialize the Bluetooth transport layer
  • Feature: The Controller example script got a new parameter -ble to also initialize the Bluetooth transport layer
  • Feature: The Controller example script got a new parameters -ble-* to provide Wi-Fi/Thread network credentials to use for device commissioning
  • Feature: Add stopping of the example scripts to allow clean shutdown and sending shutdown Event
  • Feature: Add CLI parameter to define the loglevel and log format; default log format changed to ANSI when executed in a shell/tty
  • Feature: Log the endpoint structure of the device/commissioned device on start
• Misc:
  • Added Specification links for Matter Specifications 1.1
  • Optimize typing exports for node10 TS settings
  • Add optional parameter to define a uniqueID used in serial number of examples
  • Add WIP package matter-node-shell.js with the goal to offer a node.js based shell-based controller implementation
  • Add new util class EndpointStructureLogger which logs all endpoint details

0.4.0 (2023-05-16)

• Matter-Core functionality:
  • Deprecation: The classes MatterDevice and MatterController are deprecated to be used externally to the library and will be removed in later versions.
  • Deprecation: The CLI Examples LegacyDeviceNode and LegacyControllerNode will be removed in next version! Use the new variants please.
  • Feature: Generate global Attributes attributeList, acceptedCommandList, and generatedCommandList when generating cluster servers (when used with New API!)
  • Feature: (@digitaldan) Added decoding of Pairingcodes to determine discriminator and pin for Controller usage
  • Feature: Provide the Endpoint as data field for command Handlers to allow to access the endpoint data and other clusters on that endpoint if needed
  • Feature: Add Implementations of Scenes and Groups-Clusters (still to be tested with Controllers in depth!)
  • Feature: Add ClusterExtend to allow building Feature-based conditional cluster definitions (and do that for OnOff/Network-Commissioning)
  • Feature: Refactored Endpoint/Fabric aware Attributes with Getter functions to use Endpoint instance
  • Feature: Added automatic API documentation generation (not included in npm package but can be build locally using npm run build-doc)
  • Feature: Improved Command Invoke Logging
  • Adjustment: Do not send empty arrays for empty subscription messages to further shorten the payload
  • Fix: Respond with Unsupported Command when a unknown command is received and log the error
  • Fix: Increase the array maximum size according to specs
  • Fix: Fixed internal TlvTag representation to allow also decoding of the internal object format of a Tlv stream
  • Fix: Adjust internal tag encoding to not use {} when empty
• matter.js API:
  • Feature: Introduce new High level API, see API.md for details!
  • Breaking: Move DeviceTypes.ts from common to device directory and rename DEVICE to "DeviceTypes"
  • Breaking: ClusterClient interface names changed to get/set/subscribeNAMEAttribute to prevent overlapping with commands
  • Breaking: Revamp internal APIs and convert ClusterServer into an object approach to allow dynamic methods to be defined for get/set/subscribe and streamline the API between ClusterClient and ClusterServer
  • Feature: Introduce NamedHandler util class for an event style typed and named handler/callback approach
  • Feature: Use NamedHandler as commandHandler to forward command calls like identify to the Device classes and testEvenTriggered for commissionable node class
  • Feature: Add constructor value to hand over initial values of the onoff Cluster when initialing the default cluster
  • Feature: make sure BridgedBasicInformation cluster is always set when adding a bridged device and no data parameters were provided
  • Feature: (@lauckhart) Enhance Logging framework to also allow ANSI and HTML colored output and added some features, details see #129
• matter-node.js:
  • Breaking: Remove the exposed legacy API classes (MatterDevice/MatterController) and legacy examples from the exported lists
  • Feature: Autoregister Crypto, Time, and Network in their Node.js variants when including packages from @project-chip/matter-node.js root package but only if not yet registered (so can be overridden by the developer)
  • Examples/Reference implementations:
    • The reference implementations are moved to the example directory and details moved into an own README.md file
    • the "npm run matter" command got renamed to "npm run matter-device" (same for binary usage
    • Add hints for all imports in the examples to show what the corresponding "matter-node.js" import would be (because they cannot be used directly for build reasons)
    • Added the "npm run matter-*" commands also to the base package.json
    • Added parameter -clearstorage to start with an empty storage

0.3.0 (2023-05-03)

• Initial release of matter.js and matter-node.js packages after the code merge
• From now on we will add a changelog for each release

< 0.3.0

• Releases of matter.js with initial Logic