@matter/types 0.12.6-alpha.0-20250304-03716637c → 0.13.0-alpha.0-20250307-ebf84a05a

package/src/clusters/rvc-clean-mode.ts

@@ -14,8 +14,8 @@ import { TlvField, TlvOptionalField, TlvObject } from "../tlv/TlvObject.js";
 import { TlvString } from "../tlv/TlvString.js";
 import { TlvUInt8, TlvEnum } from "../tlv/TlvNumber.js";
 import { TlvVendorId } from "../datatype/VendorId.js";
-import { TypeFromSchema } from "../tlv/TlvSchema.js";
 import { ModeBase } from "./mode-base.js";
+import { TypeFromSchema } from "../tlv/TlvSchema.js";
 import { Identity } from "#general";
 import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
 
@@ -23,16 +23,13 @@ export namespace RvcCleanMode {
     /**
      * These are optional features supported by RvcCleanModeCluster.
      *
-     * @see {@link MatterSpecification.v13.Cluster} § 1.10.4
+     * @see {@link MatterSpecification.v13.Cluster} § 7.3.4
      */
     export enum Feature {
         /**
          * OnOff (DEPONOFF)
          *
-         * This feature creates a dependency between an OnOff cluster instance and this cluster instance on the same
-         * endpoint. See OnMode for more information.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.4.1
+         * Dependency with the OnOff cluster
          */
         OnOff = "OnOff"
     }
@@ -41,91 +38,71 @@ export namespace RvcCleanMode {
         /**
          * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        DeepClean = 16384,
+        Auto = 0,
 
         /**
-         * The device’s vacuuming feature is enabled in this mode.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2.2
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Vacuum = 16385,
+        Quick = 1,
 
         /**
-         * The device’s mopping feature is enabled in this mode.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2.3
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Mop = 16386,
+        Quiet = 2,
 
         /**
-         * The device decides which options, features and setting values to use.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Auto = 0,
+        LowNoise = 3,
 
         /**
-         * The mode of the device is optimizing for faster completion.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Quick = 1,
+        LowEnergy = 4,
 
         /**
-         * The device is silent or barely audible while in this mode.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Quiet = 2,
+        Vacation = 5,
 
         /**
-         * Either the mode is inherently low noise or the device optimizes for that.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        LowNoise = 3,
+        Min = 6,
 
         /**
-         * The device is optimizing for lower energy usage in this mode. Sometimes called "Eco mode".
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        LowEnergy = 4,
+        Max = 7,
 
         /**
-         * A mode suitable for use during vacations or other extended absences.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Vacation = 5,
+        Night = 8,
 
         /**
-         * The mode uses the lowest available setting value.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Min = 6,
+        Day = 9,
 
         /**
-         * The mode uses the highest available setting value.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2
          */
-        Max = 7,
+        DeepClean = 16384,
 
         /**
-         * The mode is recommended or suitable for use during night time.
+         * The device’s vacuuming feature is enabled in this mode.
          *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2.2
          */
-        Night = 8,
+        Vacuum = 16385,
 
         /**
-         * The mode is recommended or suitable for use during day time.
+         * The device’s mopping feature is enabled in this mode.
          *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.2.3
          */
-        Day = 9
+        Mop = 16386
     }
 
     /**
@@ -155,7 +132,7 @@ export namespace RvcCleanMode {
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.10.5.1.2
          */
-        value: TlvField(1, TlvEnum<ModeTag>())
+        value: TlvField(1, TlvEnum<ModeTag | ModeBase.ModeTag>())
     });
 
     /**
@@ -169,9 +146,6 @@ export namespace RvcCleanMode {
      * The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOptionStruct type.
      * A blank field indicates no change.
      *
-     * At least one entry in the SupportedModes attribute shall include the Vacuum and/or the Mop mode tag in the
-     * ModeTags field list.
-     *
      * @see {@link MatterSpecification.v13.Cluster} § 7.3.5.1
      */
     export const TlvModeOption = TlvObject({
@@ -234,9 +208,6 @@ export namespace RvcCleanMode {
      * The table below lists the changes relative to the Mode Base cluster for the fields of the ModeOptionStruct type.
      * A blank field indicates no change.
      *
-     * At least one entry in the SupportedModes attribute shall include the Vacuum and/or the Mop mode tag in the
-     * ModeTags field list.
-     *
      * @see {@link MatterSpecification.v13.Cluster} § 7.3.5.1
      */
     export interface ModeOption extends TypeFromSchema<typeof TlvModeOption> {}
@@ -245,37 +216,7 @@ export namespace RvcCleanMode {
         /**
          * @see {@link MatterSpecification.v13.Cluster} § 7.3.7.1
          */
-        CleaningInProgress = 64,
-
-        /**
-         * Switching to the mode indicated by the NewMode field is allowed and possible. The CurrentMode attribute is
-         * set to the value of the NewMode field.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.7.2.1.2
-         */
-        Success = 0,
-
-        /**
-         * The value of the NewMode field doesn’t match any entries in the SupportedMode attribute.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.7.2.1.2
-         */
-        UnsupportedMode = 1,
-
-        /**
-         * Generic failure code, indicating that switching to the mode indicated by the NewMode field is not allowed or
-         * not possible.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.7.2.1.2
-         */
-        GenericFailure = 2,
-
-        /**
-         * The received request cannot be handled due to the current mode of the device
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.7.2.1.2
-         */
-        InvalidInMode = 3
+        CleaningInProgress = 64
     }
 
     /**
@@ -284,23 +225,23 @@ export namespace RvcCleanMode {
     export const Base = MutableCluster.Component({
         id: 0x55,
         name: "RvcCleanMode",
-        revision: 2,
+        revision: 3,
 
         features: {
             /**
              * OnOff
              *
-             * This feature creates a dependency between an OnOff cluster instance and this cluster instance on the
-             * same endpoint. See OnMode for more information.
-             *
-             * @see {@link MatterSpecification.v13.Cluster} § 1.10.4.1
+             * Dependency with the OnOff cluster
              */
             onOff: BitFlag(0)
         },
 
         attributes: {
             /**
-             * @see {@link MatterSpecification.v13.Cluster} § 7.3.6
+             * At least one entry in the SupportedModes attribute shall include the Vacuum and/or the Mop mode tag in
+             * the ModeTags field list.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 7.3.6.1
              */
             supportedModes: FixedAttribute(
                 0x0,
@@ -311,7 +252,7 @@ export namespace RvcCleanMode {
             /**
              * @see {@link MatterSpecification.v13.Cluster} § 7.3.6
              */
-            currentMode: Attribute(0x1, TlvUInt8, { scene: true, persistent: true })
+            currentMode: Attribute(0x1, TlvUInt8, { persistent: true })
         },
 
         commands: {
@@ -329,7 +270,7 @@ export namespace RvcCleanMode {
          * This metadata controls which RvcCleanModeCluster elements matter.js activates for specific feature
          * combinations.
          */
-        extensions: MutableCluster.Extensions()
+        extensions: MutableCluster.Extensions({ flags: { onOff: true }, component: false })
     });
 
     /**
@@ -338,8 +279,8 @@ export namespace RvcCleanMode {
     export const ClusterInstance = MutableCluster(Base);
 
     /**
-     * This cluster is derived from the Mode Base cluster to define specifics for Robotic Vacuum Cleaner devices. It
-     * also defines a namespace for the cleaning type for these devices.
+     * This cluster is derived from the Mode Base cluster and defines additional mode tags and namespaced enumerated
+     * values for the cleaning type of robotic vacuum cleaner devices.
      *
      * RvcCleanModeCluster supports optional features that you can enable with the RvcCleanModeCluster.with() factory
      * method.

package/src/clusters/rvc-operational-state.ts

@@ -20,9 +20,9 @@ import { TlvString } from "../tlv/TlvString.js";
 import { TlvNullable } from "../tlv/TlvNullable.js";
 import { TlvUInt8, TlvUInt32, TlvEnum } from "../tlv/TlvNumber.js";
 import { TlvField, TlvOptionalField, TlvObject } from "../tlv/TlvObject.js";
+import { OperationalState as OperationalStateNamespace } from "./operational-state.js";
 import { TypeFromSchema } from "../tlv/TlvSchema.js";
 import { TlvNoArguments } from "../tlv/TlvNoArguments.js";
-import { OperationalState as OperationalStateNamespace } from "./operational-state.js";
 import { Identity } from "#general";
 import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
 
@@ -33,11 +33,11 @@ export namespace RvcOperationalState {
      *
      * RVC Pause Compatibility defines the compatibility of the states this cluster defines with the Pause command.
      *
-     * ### Table 39. RVC Pause Compatibility
+     * ### Table 13. RVC Pause Compatibility
      *
      * RVC Resume Compatibility defines the compatibility of the states this cluster defines with the Resume command.
      *
-     * ### Table 40. RVC Resume Compatibility
+     * ### Table 14. RVC Resume Compatibility
      *
      * While in the Charging or Docked states, the device shall NOT attempt to resume unless it transitioned to those
      * states while operating and can resume, such as, for example, if it is recharging while in a cleaning cycle.
@@ -48,6 +48,26 @@ export namespace RvcOperationalState {
      * @see {@link MatterSpecification.v13.Cluster} § 7.4.4.1
      */
     export enum OperationalState {
+        /**
+         * The device is stopped
+         */
+        Stopped = 0,
+
+        /**
+         * The device is operating
+         */
+        Running = 1,
+
+        /**
+         * The device is paused during an operation
+         */
+        Paused = 2,
+
+        /**
+         * The device is in an error state
+         */
+        Error = 3,
+
         /**
          * The device is en route to the charging dock
          */
@@ -75,7 +95,7 @@ export namespace RvcOperationalState {
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.2.1
          */
-        operationalStateId: TlvField(0, TlvEnum<OperationalState>()),
+        operationalStateId: TlvField(0, TlvEnum<OperationalState | OperationalStateNamespace.OperationalStateEnum>()),
 
         /**
          * This field shall be present if the OperationalStateID is from the set reserved for Manufacturer Specific
@@ -101,6 +121,26 @@ export namespace RvcOperationalState {
      * @see {@link MatterSpecification.v13.Cluster} § 7.4.4.2
      */
     export enum ErrorState {
+        /**
+         * The device is not in an error state
+         */
+        NoError = 0,
+
+        /**
+         * The device is unable to start or resume operation
+         */
+        UnableToStartOrResume = 1,
+
+        /**
+         * The device was unable to complete the current operation
+         */
+        UnableToCompleteOperation = 2,
+
+        /**
+         * The device cannot process the command in its current state
+         */
+        CommandInvalidInState = 3,
+
         /**
          * The device has failed to find or reach the charging dock
          */
@@ -151,7 +191,7 @@ export namespace RvcOperationalState {
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4.1
          */
-        errorStateId: TlvField(0, TlvEnum<ErrorState>()),
+        errorStateId: TlvField(0, TlvEnum<ErrorState | OperationalStateNamespace.ErrorState>()),
 
         /**
          * This field shall be present if the ErrorStateID is from the set reserved for Manufacturer Specific Errors,
@@ -239,9 +279,10 @@ export namespace RvcOperationalState {
 
             /**
              * This attribute represents the current phase of operation being performed by the server. This shall be
-             * the positional index representing the value from the set provided in the PhaseList Attribute, where the
-             * first item in that list is an index of 0. Thus, this attribute shall have a maximum value that is
-             * "length(PhaseList) - 1".
+             * the positional index representing the value from the set provided in the PhaseList Attribute,
+             *
+             * where the first item in that list is an index of 0. Thus, this attribute shall have a maximum value that
+             * is "length(PhaseList) - 1".
              *
              * Null if the PhaseList attribute is null or if the PhaseList attribute is an empty list.
              *
@@ -250,24 +291,37 @@ export namespace RvcOperationalState {
             currentPhase: Attribute(0x1, TlvNullable(TlvUInt8)),
 
             /**
-             * Indicates the estimated time left before the operation is completed, in seconds. Changes to this value
-             * shall NOT be reported in a subscription (note the C Quality). A Client implementation may periodically
-             * poll this value to ensure alignment of any local rendering of the CountdownTime with the device provided
-             * value.
+             * Indicates the estimated time left before the operation is completed, in seconds.
+             *
+             * A value of 0 (zero) means that the operation has completed.
+             *
+             * A value of null represents that there is no time currently defined until operation completion. This may
+             * happen, for example, because no operation is in progress or because the completion time is unknown.
+             *
+             * Changes to this attribute shall only be marked as reportable in the following cases:
              *
-             * A value of 0 means that the operation has completed.
+             *   • If it has changed due to a change in the CurrentPhase or OperationalState attributes, or
              *
-             * When this attribute is null, that represents that there is no time currently defined until operation
-             * completion. This may happen, for example, because no operation is in progress or because the completion
-             * time is unknown.
+             *   • When it changes from 0 to any other value and vice versa, or
+             *
+             *   • When it changes from null to any other value and vice versa, or
+             *
+             *   • When it increases, or
+             *
+             *   • When there is any increase or decrease in the estimated time remaining that was due to progressing
+             *     insight of the server’s control logic, or
+             *
+             *   • When it changes at a rate significantly different from one unit per second.
+             *
+             * Changes to this attribute merely due to the normal passage of time with no other dynamic change of
+             * device state shall NOT be reported.
+             *
+             * As this attribute is not being reported during a regular countdown, clients SHOULD NOT rely on the
+             * reporting of this attribute in order to keep track of the remaining duration.
              *
              * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.3
              */
-            countdownTime: OptionalAttribute(
-                0x2,
-                TlvNullable(TlvUInt32.bound({ max: 259200 })),
-                { omitChanges: true, default: null }
-            ),
+            countdownTime: OptionalAttribute(0x2, TlvNullable(TlvUInt32.bound({ max: 259200 })), { default: null }),
 
             /**
              * This attribute describes the set of possible operational states that the device exposes. An operational
@@ -289,7 +343,10 @@ export namespace RvcOperationalState {
              *
              * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.5
              */
-            operationalState: Attribute(0x4, TlvEnum<OperationalState>()),
+            operationalState: Attribute(
+                0x4,
+                TlvEnum<OperationalState | OperationalStateNamespace.OperationalStateEnum>()
+            ),
 
             /**
              * This attribute shall specify the details of any current error condition being experienced on the device
@@ -339,10 +396,14 @@ export namespace RvcOperationalState {
             operationalError: Event(0x0, EventPriority.Critical, TlvOperationalErrorEvent),
 
             /**
-             * This event is generated when the overall operation ends, successfully or otherwise. For example, the
-             * completion of a cleaning operation in a Robot Vacuum Cleaner, or the completion of a wash cycle in a
+             * This event SHOULD be generated when the overall operation ends, successfully or otherwise. For example,
+             * the completion of a cleaning operation in a Robot Vacuum Cleaner, or the completion of a wash cycle in a
              * Washing Machine.
              *
+             * It is highly recommended that appliances device types employing the Operational State cluster support
+             * this event, even if it is optional. This assists clients in executing automations or issuing
+             * notifications at critical points in the device operation cycles.
+             *
              * This event shall contain the following fields:
              *
              * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2
@@ -356,7 +417,8 @@ export namespace RvcOperationalState {
     });
 
     /**
-     * This cluster provides an interface for monitoring the operational state of a Robotic Vacuum Cleaner.
+     * This cluster is derived from the Operational State cluster and provides an interface for monitoring the
+     * operational state of a robotic vacuum cleaner.
      *
      * @see {@link MatterSpecification.v13.Cluster} § 7.4
      */