/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ /*** THIS FILE IS GENERATED, DO NOT EDIT ***/ import { Resource } from "#models/Resource.js"; Resource.add({ tag: "cluster", name: "OperationalState", pics: "OPSTATE", xref: "cluster§1.14", details: "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." + "\n" + "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." + "\n" + "Actual state transitions are dependent on both the implementation, and the requirements that may " + "additionally be imposed by a derived cluster." + "\n" + "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)." + "\n" + "Additionally, this cluster provides events for monitoring the operational state of the device.", children: [ { tag: "attribute", name: "PhaseList", xref: "cluster§1.14.5.1", details: "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." + "\n" + "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." }, { tag: "attribute", name: "CurrentPhase", xref: "cluster§1.14.5.2", details: "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\"." + "\n" + "Null if the PhaseList attribute is null or if the PhaseList attribute is an empty list." }, { tag: "attribute", name: "CountdownTime", xref: "cluster§1.14.5.3", details: "Indicates the estimated time left before the operation is completed, in seconds." + "\n" + "A value of 0 (zero) means that the operation has completed." + "\n" + "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." + "\n" + "Changes to this attribute shall only be marked as reportable in the following cases:" + "\n" + " - If it has changed due to a change in the CurrentPhase or OperationalState attributes, or" + "\n" + " - When it changes from 0 to any other value and vice versa, or" + "\n" + " - When it changes from null to any other value and vice versa, or" + "\n" + " - When it increases, or" + "\n" + " - 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" + "\n" + " - When it changes at a rate significantly different from one unit per second." + "\n" + "Changes to this attribute merely due to the normal passage of time with no other dynamic change of " + "device state shall NOT be reported." + "\n" + "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." }, { tag: "attribute", name: "OperationalStateList", xref: "cluster§1.14.5.4", details: "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." + "\n" + "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." }, { tag: "attribute", name: "OperationalState", xref: "cluster§1.14.5.5", details: "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." }, { tag: "attribute", name: "OperationalError", xref: "cluster§1.14.5.6", details: "This attribute shall specify the details of any current error condition being experienced on the " + "device when the OperationalState attribute is populated with Error. See Section 1.14.4.4, " + "\"ErrorStateStruct Type\" for general requirements on the population of this attribute." + "\n" + "When there is no error detected, this shall have an ErrorStateID of NoError." }, { tag: "event", name: "OperationalError", xref: "cluster§1.14.7.1", details: "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." + "\n" + "This event shall contain the following fields:" }, { tag: "event", name: "OperationCompletion", xref: "cluster§1.14.7.2", details: "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." + "\n" + "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." + "\n" + "This event shall contain the following fields:", children: [ { tag: "field", name: "CompletionErrorCode", xref: "cluster§1.14.7.2.1", details: "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." }, { tag: "field", name: "TotalOperationalTime", xref: "cluster§1.14.7.2.2", details: "The total operational time, in seconds, from when the operation was started via an initial Start " + "command or autonomous/manual starting 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." }, { tag: "field", name: "PausedTime", xref: "cluster§1.14.7.2.3", details: "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." } ] }, { tag: "command", name: "Pause", xref: "cluster§1.14.6.1", details: "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." + "\n" + "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." + "\n" + "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." + "\n" + "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." + "\n" + "States are defined as Pause-compatible as follows:" + "\n" + " - For states defined in this cluster specification, in Table 3, \"Pause Compatibility\"." + "\n" + " - For states defined by derived cluster specifications, in the corresponding specifications." + "\n" + " - For manufacturer-specific states, by the manufacturer." + "\n" + "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." + "\n" + "Otherwise, on success:" + "\n" + " - The OperationalState attribute shall be set to Paused." + "\n" + " - The device shall respond with an OperationalCommandResponse command with an ErrorStateID of " + "NoError." }, { tag: "command", name: "Stop", xref: "cluster§1.14.6.2", details: "This command shall be supported if the device supports remotely stopping the operation." + "\n" + "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." + "\n" + "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." + "\n" + "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." + "\n" + "Otherwise, on success:" + "\n" + " - The OperationalState attribute shall be set to Stopped." + "\n" + " - The device shall respond with an OperationalCommandResponse command with an ErrorStateID of " + "NoError." }, { tag: "command", name: "Start", xref: "cluster§1.14.6.3", details: "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." + "\n" + "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." + "\n" + "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." + "\n" + "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." + "\n" + "Otherwise, on success:" + "\n" + " - The OperationalState attribute shall be set to Running." + "\n" + " - The device shall respond with an OperationalCommandResponse command with an ErrorStateID of " + "NoError." }, { tag: "command", name: "Resume", xref: "cluster§1.14.6.4", details: "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." + "\n" + "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)." + "\n" + "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." + "\n" + "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." + "\n" + "States are defined as Resume-compatible as follows:" + "\n" + " - For states defined in this cluster specification, in Table 4, \"Resume Compatibility\"." + "\n" + " - For states defined by derived cluster specifications, in the corresponding specifications." + "\n" + " - For manufacturer-specific states, by the manufacturer." + "\n" + "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." + "\n" + "Otherwise, on success:" + "\n" + " - The OperationalState attribute shall be set to the most recent non-Error operational state prior " + "to entering the Paused state." + "\n" + " - The device shall respond with an OperationalCommandResponse command with an ErrorStateID of " + "NoError." }, { tag: "command", name: "OperationalCommandResponse", xref: "cluster§1.14.6.5", details: "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." + "\n" + "This command shall be generated in response to any of the Start, Stop, Pause, or Resume commands.", children: [{ tag: "field", name: "CommandResponseState", xref: "cluster§1.14.6.5.1", details: "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. See the " + "individual command sections for additional specific requirements on population." }] }, { tag: "datatype", name: "OperationalStateEnum", xref: "cluster§1.14.4.1", details: "This type defines the set of known operational state values, and is derived from enum8. The " + "following table defines the applicable ranges for values that are defined within this type. All " + "values that are undefined shall be treated as reserved. As shown by the table, states that may be " + "specific to a certain Device Type or other modality shall be defined in a derived cluster of this " + "cluster." + "\n" + "The derived cluster-specific state definitions shall NOT duplicate any general state definitions. " + "That is, a derived cluster specification of this cluster cannot define states with the same " + "semantics as the general states defined below." + "\n" + "A manufacturer-specific state definition shall NOT duplicate the general state definitions or " + "derived cluster state definitions. That is, a manufacturer-defined state defined for this cluster or " + "a derived cluster thereof cannot define a state with the same semantics as the general states " + "defined below or states defined in a derived cluster. Such manufacturer-specific state definitions " + "shall be scoped in the context of the Vendor ID present in the Basic Information cluster.", children: [ { tag: "field", name: "Stopped", description: "The device is stopped" }, { tag: "field", name: "Running", description: "The device is operating" }, { tag: "field", name: "Paused", description: "The device is paused during an operation" }, { tag: "field", name: "Error", description: "The device is in an error state" }, { tag: "field", name: "ManufacturerStates", description: "Vendor specific states" } ] }, { tag: "datatype", name: "OperationalStateStruct", xref: "cluster§1.14.4.2", details: "The OperationalStateStruct is used to indicate a possible state of the device.", children: [ { tag: "field", name: "OperationalStateId", xref: "cluster§1.14.4.2.1", details: "This shall be populated with a value from the OperationalStateEnum." }, { tag: "field", name: "OperationalStateLabel", xref: "cluster§1.14.4.2.2", details: "This field is present when the OperationalStateID is from the set reserved for Manufacturer Specific " + "States. If present, this shall contain a human-readable description of the operational state." } ] }, { tag: "datatype", name: "ErrorStateEnum", xref: "cluster§1.14.4.3", details: "This type defines the set of known operational error values, and is derived from enum8. The " + "following table defines the applicable ranges for values that are defined within this type. All " + "values that are undefined shall be treated as reserved. As shown by the table, errors that may be " + "specific to a certain Device Type or other modality shall be defined in a derived cluster of this " + "cluster." + "\n" + "The derived cluster-specific error definitions shall NOT duplicate the general error definitions. " + "That is, a derived cluster specification of this cluster cannot define errors with the same " + "semantics as the general errors defined below." + "\n" + "The manufacturer-specific error definitions shall NOT duplicate the general error definitions or " + "derived cluster-specific error definitions. That is, a manufacturer-defined error defined for this " + "cluster or a derived cluster thereof cannot define errors with the same semantics as the general " + "errors defined below or errors defined in a derived cluster. Such manufacturer-specific error " + "definitions shall be scoped in the context of the Vendor ID present in the Basic Information " + "cluster." + "\n" + "The set of ErrorStateID field values defined in each of the generic or derived Operational State " + "cluster specifications is called ErrorState.", children: [ { tag: "field", name: "NoError", description: "The device is not in an error state" }, { tag: "field", name: "UnableToStartOrResume", description: "The device is unable to start or resume operation" }, { tag: "field", name: "UnableToCompleteOperation", description: "The device was unable to complete the current operation" }, { tag: "field", name: "CommandInvalidInState", description: "The device cannot process the command in its current state" }, { tag: "field", name: "ManufacturerError", description: "Vendor specific errors" } ] }, { tag: "datatype", name: "ErrorStateStruct", xref: "cluster§1.14.4.4", children: [ { tag: "field", name: "ErrorStateId", xref: "cluster§1.14.4.4.1", details: "This shall be populated with a value from the ErrorStateEnum." }, { tag: "field", name: "ErrorStateLabel", xref: "cluster§1.14.4.4.2", details: "This field is present when the ErrorStateID is from the set reserved for Manufacturer Specific " + "errors. If present, this shall contain a human-readable description of the error state." }, { tag: "field", name: "ErrorStateDetails", xref: "cluster§1.14.4.4.3", details: "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\"." } ] } ] });