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

package/src/clusters/rvc-run-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,124 +23,101 @@ export namespace RvcRunMode {
     /**
      * These are optional features supported by RvcRunModeCluster.
      *
-     * @see {@link MatterSpecification.v13.Cluster} § 1.10.4
+     * @see {@link MatterSpecification.v13.Cluster} § 7.2.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"
     }
 
     export enum ModeTag {
         /**
-         * The device is not performing any of the main operations of the other modes. However, auxiliary actions, such
-         * as seeking the charger or charging, may occur.
-         *
-         * For example, the device has completed cleaning, successfully or not, on its own or due to a command, or has
-         * not been asked to clean after a restart.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.1
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2
          */
-        Idle = 16384,
+        Auto = 0,
 
         /**
-         * The device was asked to clean so it may be actively running, or paused due to an error, due to a pause
-         * command, or for recharging etc. If currently paused and the device can resume it will continue to clean.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.2
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2
          */
-        Cleaning = 16385,
+        Quick = 1,
 
         /**
-         * The device was asked to create a map of the space it is located in, so it may be actively running, or paused
-         * due to an error, due to a pause command, or for recharging etc. If currently paused and the device can
-         * resume, it will continue to map.
-         *
-         * NOTE
-         *
-         * this mode is intended to be used so the current space can be mapped by the device if the robot has not
-         * previously done that, or if the layout has substantially changed, for an optimal subsequent cleaning
-         * experience.
-         *
-         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.3
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2
          */
-        Mapping = 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.2.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.2.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.2.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.2.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.2.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.2.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.2.7.2
          */
-        Min = 6,
+        Day = 9,
 
         /**
-         * The mode uses the highest available setting value.
+         * The device is not performing any of the main operations of the other modes. However, auxiliary actions, such
+         * as seeking the charger or charging, may occur.
          *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * For example, the device has completed cleaning, successfully or not, on its own or due to a command, or has
+         * not been asked to clean after a restart.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.1
          */
-        Max = 7,
+        Idle = 16384,
 
         /**
-         * The mode is recommended or suitable for use during night time.
+         * The device was asked to clean so it may be actively running, or paused due to an error, due to a pause
+         * command, or for recharging etc. If currently paused and the device can resume it will continue to clean.
          *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.2
          */
-        Night = 8,
+        Cleaning = 16385,
 
         /**
-         * The mode is recommended or suitable for use during day time.
+         * The device was asked to create a map of the space it is located in, so it may be actively running, or paused
+         * due to an error, due to a pause command, or for recharging etc. If currently paused and the device can
+         * resume, it will continue to map.
+         *
+         * NOTE
+         *
+         * this mode is intended to be used so the current space can be mapped by the device if the robot has not
+         * previously done that, or if the layout has substantially changed, for an optimal subsequent cleaning
+         * experience.
          *
-         * @see {@link MatterSpecification.v13.Cluster} § 1.10.8
+         * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.2.3
          */
-        Day = 9
+        Mapping = 16386
     }
 
     /**
@@ -170,7 +147,7 @@ export namespace RvcRunMode {
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.10.5.1.2
          */
-        value: TlvField(1, TlvEnum<ModeTag>())
+        value: TlvField(1, TlvEnum<ModeTag | ModeBase.ModeTag>())
     });
 
     /**
@@ -184,14 +161,6 @@ export namespace RvcRunMode {
      * 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 Idle mode tag in the ModeTags field.
-     *
-     * At least one entry in the SupportedModes attribute (different from the one above) shall include the Cleaning
-     * mode tag in the ModeTags field.
-     *
-     * The Mapping, Cleaning, and Idle mode tags are mutually exclusive and shall NOT be used together in a mode’s
-     * ModeTags.
-     *
      * @see {@link MatterSpecification.v13.Cluster} § 7.2.5.1
      */
     export const TlvModeOption = TlvObject({
@@ -254,14 +223,6 @@ export namespace RvcRunMode {
      * 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 Idle mode tag in the ModeTags field.
-     *
-     * At least one entry in the SupportedModes attribute (different from the one above) shall include the Cleaning
-     * mode tag in the ModeTags field.
-     *
-     * The Mapping, Cleaning, and Idle mode tags are mutually exclusive and shall NOT be used together in a mode’s
-     * ModeTags.
-     *
      * @see {@link MatterSpecification.v13.Cluster} § 7.2.5.1
      */
     export interface ModeOption extends TypeFromSchema<typeof TlvModeOption> {}
@@ -305,37 +266,7 @@ export namespace RvcRunMode {
         /**
          * @see {@link MatterSpecification.v13.Cluster} § 7.2.7.1
          */
-        BatteryLow = 72,
-
-        /**
-         * 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
+        BatteryLow = 72
     }
 
     /**
@@ -344,23 +275,28 @@ export namespace RvcRunMode {
     export const Base = MutableCluster.Component({
         id: 0x54,
         name: "RvcRunMode",
-        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.2.6
+             * At least one entry in the SupportedModes attribute shall include the Idle mode tag in the ModeTags field.
+             *
+             * At least one entry in the SupportedModes attribute (different from the one above) shall include the
+             * Cleaning mode tag in the ModeTags field.
+             *
+             * The Mapping, Cleaning, and Idle mode tags are mutually exclusive and shall NOT be used together in a
+             * mode’s ModeTags.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 7.2.6.1
              */
             supportedModes: FixedAttribute(
                 0x0,
@@ -371,7 +307,7 @@ export namespace RvcRunMode {
             /**
              * @see {@link MatterSpecification.v13.Cluster} § 7.2.6
              */
-            currentMode: Attribute(0x1, TlvUInt8, { scene: true, persistent: true })
+            currentMode: Attribute(0x1, TlvUInt8, { persistent: true })
         },
 
         commands: {
@@ -389,7 +325,7 @@ export namespace RvcRunMode {
          * This metadata controls which RvcRunModeCluster elements matter.js activates for specific feature
          * combinations.
          */
-        extensions: MutableCluster.Extensions()
+        extensions: MutableCluster.Extensions({ flags: { onOff: true }, component: false })
     });
 
     /**
@@ -398,8 +334,8 @@ export namespace RvcRunMode {
     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 running modes of these devices.
+     * This cluster is derived from the Mode Base cluster and defines additional mode tags and namespaced enumerated
+     * values for the running modes of robotic vacuum cleaner devices.
      *
      * RvcRunModeCluster supports optional features that you can enable with the RvcRunModeCluster.with() factory
      * method.

package/src/clusters/scenes-management.ts

@@ -136,17 +136,19 @@ export namespace ScenesManagement {
         /**
          * This field shall be present for all instances in a given ExtensionFieldSetStruct.
          *
-         * The data type of AttributeValue shall be the data type of the attribute indicated by AttributeID.
+         * Which Value* field is used shall be determined based on the data type of the attribute indicated by
+         * AttributeID, as described in the Value* Fields subsection.
          *
          * The AttributeID field shall NOT refer to an attribute without the Scenes ("S") designation in the Quality
          * column of the cluster specification.
          *
-         *   1.4.7.3.2. ValueUnsigned8, ValueSigned8, ValueUnsigned16, ValueSigned16, ValueUnsigned32, ValueSigned32,
-         *              ValueUnsigned64, ValueSigned64 Fields
+         * ### 1.4.7.3.2. ValueUnsigned8, ValueSigned8, ValueUnsigned16, ValueSigned16, ValueUnsigned32, ValueSigned32,
+         * ValueUnsigned64, ValueSigned64 Fields
          *
          * These fields shall indicate the attribute value as part of an extension field set, associated with a given
-         * AttributeID under an ExtensionFieldSetStruct’s ClusterID. The proper field shall be present that maps to the
-         * data type of the attribute indicated.
+         * AttributeID under an ExtensionFieldSetStruct’s ClusterID. Which of the fields is used shall
+         *
+         * be determined by the type of the attribute indicated by AttributeID as follows:
          *
          *   • Data types bool, map8, and uint8 shall map to ValueUnsigned8.
          *
@@ -160,33 +162,48 @@ export namespace ScenesManagement {
          *
          *   • Data types int24 and int32 shall map to ValueSigned32.
          *
-         *   • Data types map64, uint48, uint56 and uint64 shall map to ValueUnsigned64.
+         *   • Data types map64, uint40, uint48, uint56 and uint64 shall map to ValueUnsigned64.
+         *
+         *   • Data types int40, int48, int56 and int64 shall map to ValueSigned64.
+         *
+         *   • For derived types, the mapping shall be based on the base type. For example, an attribute of type
+         *     percent shall be treated as if it were of type uint8, whereas an attribute of type percent100ths shall
+         *     be treated as if it were of type uint16.
+         *
+         *   • For boolean nullable attributes, any value that is not 0 or 1 shall be considered to have the null value.
          *
-         *   • Data types int48, int56 and int64 shall map to ValueSigned64.
+         *   • For boolean non-nullable attributes, any value that is not 0 or 1 shall be considered to have the value
+         *     FALSE.
          *
-         *   • For nullable attributes, any value that is not a valid numeric value for the attribute’s type after
-         *     accounting for range reductions due to being nullable and constraints shall be considered to have the
-         *     null value for the type.
+         *   • For non-boolean nullable attributes, any value that is not a valid numeric value for the attribute’s
+         *     type after accounting for range reductions due to being nullable and constraints shall be considered to
+         *     have the null value for the type.
          *
-         *   • For non-nullable attributes, any value that is not a valid numeric value for the attribute’s type after
-         *     accounting for constraints shall be considered to have the maximum legal value in the attribute’s
-         *     constrained range.
+         *   • For non-boolean non-nullable attributes, any value that is not a valid numeric value for the attribute’s
+         *     type after accounting for constraints shall be considered to be the valid attribute value that is
+         *     closest to the provided value.
+         *
+         *     ◦ In the event that an invalid provided value is of equal numerical distance to the two closest valid
+         *       values, the lowest of those values shall be considered the closest valid attribute value.
+         *
+         * If the used field does not match the data type of the attribute indicated by AttributeID, the
+         * AttributeValuePairStruct shall be considered invalid.
          *
          * Examples of processing are:
          *
          *   • ColorControl cluster CurrentX (AttributeID 0x0003) has a type of uint16 and is not nullable.
          *
-         *     ◦ AttributeValue of 0xAB12 would be used as-is, as it is in range.
+         *     ◦ ValueUnsigned16 of 0xAB12 would be used as-is, as it is in range.
          *
-         *     ◦ AttributeValue of 0xAA0011 is outside of the range of uint16, and would be saturated to the maximum of
-         *       the attribute’s constraint range: 0xFEFF.
+         *     ◦ ValueUnsigned16 of 0xFF80 is outside of the range allowed for attribute CurrentX, and would be
+         *       saturated to the closest valid value, which is the maximum of the attribute’s constraint range: 0xFEFF.
          *
          *   • LevelControl cluster CurrentLevel (AttributeID 0x0000) has a type of uint8 and is nullable.
          *
-         *     ◦ AttributeValue of 0xA1 would be used as-is, as it is in range.
+         *     ◦ ValueUnsigned8 of 0xA1 would be used as-is, as it is in range.
          *
-         *     ◦ AttributeValue of 0xBB12 is outside the range of nullable uint8, and would be considered as the null
-         *       value.
+         *     ◦ ValueUnsigned8 of 0xFF is outside the range allowed for nullable attribute CurrentLevel, and would be
+         *       considered as the null value.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.4.7.3.1
          */
@@ -756,9 +773,7 @@ export namespace ScenesManagement {
         groupIdentifierFrom: TlvField(1, TlvGroupId),
 
         /**
-         * This field shall be set to the same values as in the corresponding fields of the received CopyScene
-         *
-         * command.
+         * This field shall be set to the same values as in the corresponding fields of the received CopyScene command.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 1.4.9.16.3
          */
@@ -991,7 +1006,7 @@ export namespace ScenesManagement {
      * In most cases scenes are associated with a particular group identifier. Scenes may also exist without a group,
      * in which case the value 0 replaces the group identifier. Note that extra care is required in these cases to
      * avoid a scene identifier collision, and that commands related to scenes without a group may only be unicast,
-     * i.e., they may not be multicast or broadcast.
+     * i.e., they shall NOT be multicast or broadcast.
      *
      * NOTE Support for Scenes Management cluster is provisional.
      *