@matter/types 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/clusters/operational-state.ts

@@ -0,0 +1,488 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE IS GENERATED, DO NOT EDIT ***/
+
+import { MutableCluster } from "../cluster/mutation/MutableCluster.js";
+import {
+    Attribute,
+    OptionalAttribute,
+    OptionalCommand,
+    Event,
+    EventPriority,
+    OptionalEvent
+} from "../cluster/Cluster.js";
+import { TlvArray } from "../tlv/TlvArray.js";
+import { TlvString } from "../tlv/TlvString.js";
+import { TlvNullable } from "../tlv/TlvNullable.js";
+import { TlvUInt8, TlvUInt32 } from "../tlv/TlvNumber.js";
+import { TlvField, TlvOptionalField, TlvObject } from "../tlv/TlvObject.js";
+import { TypeFromSchema } from "../tlv/TlvSchema.js";
+import { TlvNoArguments } from "../tlv/TlvNoArguments.js";
+import { Identity } from "#general";
+import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
+
+export namespace OperationalState {
+    /**
+     * The OperationalStateStruct is used to indicate a possible state of the device.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.2
+     */
+    export const TlvOperationalStateStruct = TlvObject({
+        /**
+         * This shall be populated with a value from the OperationalStateEnum.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.2.1
+         */
+        operationalStateId: TlvField(0, TlvUInt8),
+
+        /**
+         * This field shall be present if the OperationalStateID is from the set reserved for Manufacturer Specific
+         * States, otherwise it shall NOT be present. If present, this shall contain a human-readable description of
+         * the operational state.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.2.2
+         */
+        operationalStateLabel: TlvOptionalField(1, TlvString.bound({ maxLength: 64 }))
+    });
+
+    /**
+     * The OperationalStateStruct is used to indicate a possible state of the device.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.2
+     */
+    export interface OperationalStateStruct extends TypeFromSchema<typeof TlvOperationalStateStruct> {}
+
+    /**
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4
+     */
+    export const TlvErrorState = TlvObject({
+        /**
+         * This shall be populated with a value from the ErrorStateEnum.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4.1
+         */
+        errorStateId: TlvField(0, TlvUInt8),
+
+        /**
+         * This field shall be present if the ErrorStateID is from the set reserved for Manufacturer Specific Errors,
+         * otherwise it shall NOT be present. If present, this shall contain a human-readable description of the
+         * ErrorStateID; e.g. for a manufacturer specific ErrorStateID of "0x80" the ErrorStateLabel may contain "My
+         * special error".
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4.2
+         */
+        errorStateLabel: TlvOptionalField(1, TlvString.bound({ maxLength: 64 })),
+
+        /**
+         * This shall be a human-readable string that provides details about the error condition. As an example, if the
+         * ErrorStateID indicates that the device is a Robotic Vacuum that is stuck, the ErrorStateDetails contains
+         * "left wheel blocked".
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4.3
+         */
+        errorStateDetails: TlvOptionalField(2, TlvString.bound({ maxLength: 64 }))
+    });
+
+    /**
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.4
+     */
+    export interface ErrorState extends TypeFromSchema<typeof TlvErrorState> {}
+
+    /**
+     * This command shall be supported by an implementation if any of the other commands defined by this cluster are
+     * supported (i.e. listed in the AcceptedCommandList global attribute). This command shall also be supported by an
+     * implementation of a derived cluster as a response to any commands that may be additionally defined therein.
+     *
+     * This command shall be generated in response to any of the Start, Stop, Pause, or Resume commands.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.5
+     */
+    export const TlvOperationalCommandResponse = TlvObject({
+        /**
+         * This shall indicate the success or otherwise of the attempted command invocation. On a successful invocation
+         * of the attempted command, the ErrorStateID shall be populated with NoError. Please see the individual
+         * command sections for additional specific requirements on population.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.5.1
+         */
+        commandResponseState: TlvField(0, TlvErrorState)
+    });
+
+    /**
+     * This command shall be supported by an implementation if any of the other commands defined by this cluster are
+     * supported (i.e. listed in the AcceptedCommandList global attribute). This command shall also be supported by an
+     * implementation of a derived cluster as a response to any commands that may be additionally defined therein.
+     *
+     * This command shall be generated in response to any of the Start, Stop, Pause, or Resume commands.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.5
+     */
+    export interface OperationalCommandResponse extends TypeFromSchema<typeof TlvOperationalCommandResponse> {}
+
+    /**
+     * Body of the OperationalState operationalError event
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.1
+     */
+    export const TlvOperationalErrorEvent = TlvObject({ errorState: TlvField(0, TlvErrorState) });
+
+    /**
+     * Body of the OperationalState operationalError event
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.1
+     */
+    export interface OperationalErrorEvent extends TypeFromSchema<typeof TlvOperationalErrorEvent> {}
+
+    /**
+     * Body of the OperationalState operationCompletion event
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2
+     */
+    export const TlvOperationCompletionEvent = TlvObject({
+        /**
+         * This field provides an indication of the state at the end of the operation. This field shall have a value
+         * from the ErrorStateEnum set. A value of NoError indicates success, that is, no error has been detected.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2.1
+         */
+        completionErrorCode: TlvField(0, TlvUInt8),
+
+        /**
+         * The total operational time, in seconds, from when the operation was started via an initial Start command or
+         * manual action, until the operation completed. This includes any time spent while paused. There may be cases
+         * whereby the total operational time exceeds the maximum value that can be conveyed by this attribute, in such
+         * instances, this attribute shall be populated with null.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2.2
+         */
+        totalOperationalTime: TlvOptionalField(1, TlvNullable(TlvUInt32)),
+
+        /**
+         * The total time spent in the paused state, in seconds. There may be cases whereby the total paused time
+         * exceeds the maximum value that can be conveyed by this attribute, in such instances, this attribute shall be
+         * populated with null.
+         *
+         * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2.3
+         */
+        pausedTime: TlvOptionalField(2, TlvNullable(TlvUInt32))
+    });
+
+    /**
+     * Body of the OperationalState operationCompletion event
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2
+     */
+    export interface OperationCompletionEvent extends TypeFromSchema<typeof TlvOperationCompletionEvent> {}
+
+    /**
+     * The following table defines the generally applicable ErrorState values.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14.4.3.1
+     */
+    export enum GeneralErrorState {
+        /**
+         * 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
+    }
+
+    /**
+     * @see {@link Cluster}
+     */
+    export const ClusterInstance = MutableCluster({
+        id: 0x60,
+        name: "OperationalState",
+        revision: 2,
+
+        attributes: {
+            /**
+             * Indicates a list of names of different phases that the device can go through for the selected function
+             * or mode. The list may not be in sequence order. For example in a washing machine this could include
+             * items such as "pre-soak", "rinse", and "spin". These phases are manufacturer specific and may change
+             * when a different function or mode is selected.
+             *
+             * A null value indicates that the device does not present phases during its operation. When this
+             * attribute’s value is null, the CurrentPhase attribute shall also be set to null.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.1
+             */
+            phaseList: Attribute(0x0, TlvNullable(TlvArray(TlvString, { maxLength: 32 }))),
+
+            /**
+             * 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".
+             *
+             * Null if the PhaseList attribute is null or if the PhaseList attribute is an empty list.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.2
+             */
+            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.
+             *
+             * A value of 0 means that the operation has completed.
+             *
+             * 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.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.3
+             */
+            countdownTime: OptionalAttribute(
+                0x2,
+                TlvNullable(TlvUInt32.bound({ max: 259200 })),
+                { omitChanges: true, default: null }
+            ),
+
+            /**
+             * This attribute describes the set of possible operational states that the device exposes. An operational
+             * state is a fundamental device state such as Running or Error. Details of the phase of a device when, for
+             * example, in a state of Running are provided by the CurrentPhase attribute.
+             *
+             * All devices shall, at a minimum, expose the set of states matching the commands that are also supported
+             * by the cluster instance, in addition to Error. The set of possible device states are defined in the
+             * OperationalStateEnum. A device type requiring implementation of this cluster shall define the set of
+             * states that are applicable to that specific device type.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.4
+             */
+            operationalStateList: Attribute(0x3, TlvArray(TlvOperationalStateStruct), { default: [] }),
+
+            /**
+             * This attribute specifies the current operational state of a device. This shall be populated with a valid
+             * OperationalStateID from the set of values in the OperationalStateList Attribute.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.5
+             */
+            operationalState: Attribute(0x4, TlvUInt8),
+
+            /**
+             * This attribute shall specify the details of any current error condition being experienced on the device
+             * when the OperationalState attribute is populated with Error. Please see ErrorStateStruct for general
+             * requirements on the population of this attribute.
+             *
+             * When there is no error detected, this shall have an ErrorStateID of NoError.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.5.6
+             */
+            operationalError: Attribute(0x5, TlvErrorState)
+        },
+
+        commands: {
+            /**
+             * This command shall be supported if the device supports remotely pausing the operation. If this command
+             * is supported, the Resume command shall also be supported.
+             *
+             * On receipt of this command, the device shall pause its operation if it is possible based on the current
+             * function of the server. For example, if it is at a point where it is safe to do so and/or permitted, but
+             * can be restarted from the point at which pause occurred.
+             *
+             * If this command is received when already in the Paused state the device shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.
+             *
+             * A device that receives this command in any state which is not Pause-compatible shall respond
+             *
+             * with an OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState and shall take
+             * no further action.
+             *
+             * States are defined as Pause-compatible as follows:
+             *
+             *   • For states defined in this cluster specification, in Table 3, “Pause Compatibility”.
+             *
+             *   • For states defined by derived cluster specifications, in the corresponding specifications.
+             *
+             *   • For manufacturer-specific states, by the manufacturer.
+             *
+             * A device that is unable to honor the Pause command for whatever reason shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState but take no further
+             * action.
+             *
+             * Otherwise, on success:
+             *
+             *   • The OperationalState attribute shall be set to Paused.
+             *
+             *   • The device shall respond with an OperationalCommandResponse command with an ErrorStateID of NoError.
+             *
+             * The following table defines the compatibility of this cluster’s states with the Pause command.
+             *
+             * ### Table 3. Pause Compatibility
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.1
+             */
+            pause: OptionalCommand(0x0, TlvNoArguments, 0x4, TlvOperationalCommandResponse),
+
+            /**
+             * This command shall be supported if the device supports remotely stopping the operation.
+             *
+             * On receipt of this command, the device shall stop its operation if it is at a position where it is safe
+             * to do so and/or permitted. Restart of the device following the receipt of the Stop command shall require
+             * attended operation unless remote start is allowed by the device type and any jurisdiction governing
+             * remote operation of the device.
+             *
+             * If this command is received when already in the Stopped state the device shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.
+             *
+             * A device that is unable to honor the Stop command for whatever reason shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState but take no further
+             * action.
+             *
+             * Otherwise, on success:
+             *
+             *   • The OperationalState attribute shall be set to Stopped.
+             *
+             *   • The device shall respond with an OperationalCommandResponse command with an ErrorStateID of NoError.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.2
+             */
+            stop: OptionalCommand(0x1, TlvNoArguments, 0x4, TlvOperationalCommandResponse),
+
+            /**
+             * This command shall be supported if the device supports remotely starting the operation. If this command
+             * is supported, the 'Stop command shall also be supported.
+             *
+             * On receipt of this command, the device shall start its operation if it is safe to do so and the device
+             * is in an operational state from which it can be started. There may be either regulatory or
+             * manufacturer-imposed safety and security requirements that first necessitate some specific action at the
+             * device before a Start command can be honored. In such instances, a device shall respond with a status
+             * code of CommandInvalidInState if a Start command is received prior to the required on- device action.
+             *
+             * If this command is received when already in the Running state the device shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.
+             *
+             * A device that is unable to honor the Start command for whatever reason shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of UnableToStartOrResume but take no further
+             * action.
+             *
+             * Otherwise, on success:
+             *
+             *   • The OperationalState attribute shall be set to Running.
+             *
+             *   • The device shall respond with an OperationalCommandResponse command with an ErrorStateID of NoError.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.3
+             */
+            start: OptionalCommand(0x2, TlvNoArguments, 0x4, TlvOperationalCommandResponse),
+
+            /**
+             * This command shall be supported if the device supports remotely resuming the operation. If this command
+             * is supported, the Pause command shall also be supported.
+             *
+             * On receipt of this command, the device shall resume its operation from the point it was at when it
+             * received the Pause command, or from the point when it was paused by means outside of this cluster (for
+             * example by manual button press).
+             *
+             * If this command is received when already in the Running state the device shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.
+             *
+             * A device that receives this command in any state which is not Resume-compatible shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState and shall take no
+             * further action.
+             *
+             * States are defined as Resume-compatible as follows:
+             *
+             *   • For states defined in this cluster specification, in Table 4, “Resume Compatibility”.
+             *
+             *   • For states defined by derived cluster specifications, in the corresponding specifications.
+             *
+             *   • For manufacturer-specific states, by the manufacturer.
+             *
+             * The following table defines the compatibility of this cluster’s states with the Resume command.
+             *
+             * ### Table 4. Resume Compatibility
+             *
+             * A device that is unable to honor the Resume command for any other reason shall respond with an
+             * OperationalCommandResponse command with an ErrorStateID of UnableToStartOrResume but take no further
+             * action.
+             *
+             * Otherwise, on success:
+             *
+             *   • The OperationalState attribute shall be set to the most recent non-Error operational state prior to
+             *     entering the Paused state.
+             *
+             *   • The device shall respond with an OperationalCommandResponse command with an ErrorStateID of NoError.
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.6.4
+             */
+            resume: OptionalCommand(0x3, TlvNoArguments, 0x4, TlvOperationalCommandResponse)
+        },
+
+        events: {
+            /**
+             * This event is generated when a reportable error condition is detected. A device that generates this
+             * event shall also set the OperationalState attribute to Error, indicating an error condition.
+             *
+             * This event shall contain the following fields:
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.1
+             */
+            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
+             * Washing Machine.
+             *
+             * This event shall contain the following fields:
+             *
+             * @see {@link MatterSpecification.v13.Cluster} § 1.14.7.2
+             */
+            operationCompletion: OptionalEvent(0x1, EventPriority.Info, TlvOperationCompletionEvent)
+        }
+    });
+
+    /**
+     * This cluster supports remotely monitoring and, where supported, changing the operational state of any device
+     * where a state machine is a part of the operation.
+     *
+     * This cluster defines common states, scoped to this cluster (e.g. Stopped, Running, Paused, Error). A derived
+     * cluster specification may define more states scoped to the derivation. Manufacturer specific states are
+     * supported in this cluster and any derived clusters thereof. When defined in a derived instance, such states are
+     * scoped to the derivation.
+     *
+     * Actual state transitions are dependent on both the implementation, and the requirements that may additionally be
+     * imposed by a derived cluster.
+     *
+     * An implementation that supports remotely starting its operation can make use of this cluster’s Start command to
+     * do so. A device that supports remote pause or stop of its currently selected operation can similarly make use of
+     * this cluster’s Pause and Stop commands to do so. The ability to remotely pause or stop is independent of how the
+     * operation was started (for example, an operation started by using a manual button press can be stopped by using
+     * a Stop command if the device supports remotely stopping the operation).
+     *
+     * Additionally, this cluster provides events for monitoring the operational state of the device.
+     *
+     * @see {@link MatterSpecification.v13.Cluster} § 1.14
+     */
+    export interface Cluster extends Identity<typeof ClusterInstance> {}
+
+    export const Cluster: Cluster = ClusterInstance;
+    export const Complete = Cluster;
+}
+
+export type OperationalStateCluster = OperationalState.Cluster;
+export const OperationalStateCluster = OperationalState.Cluster;
+ClusterRegistry.register(OperationalState.Complete);