/** * @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: "Actions", pics: "ACT", xref: "core§9.14", details: "This cluster provides a standardized way for a Node (typically a Bridge, but could be any Node) to " + "expose logical grouping and actions." + "\n" + "Specifically this cluster provides:" + "\n" + " - Information about logical grouping of endpoints on the Node (example: lights in a room)" + "\n" + " - Information about named actions that can be performed on such a group of endpoints (example: " + "recall a scene for a group of lights by its name)" + "\n" + " - Commands to trigger such actions" + "\n" + " - Events to receive feedback on the state of such actions." + "\n" + "The information on grouping and available actions is typically provided by the user or Bridge " + "manufacturer via some means not defined in Matter, and therefore provided as read-only to Nodes. For " + "example: a manufacturer-provided app allows a user to set up logical grouping and create/assign " + "scene for such groups." + "\n" + "Using this cluster, a Node can learn about such logical grouping, provided actions, and trigger such " + "actions." + "\n" + "While the origin of this cluster stems from use cases with a Bridge, its server side may also be " + "implemented on any Node which can expose certain grouping, actions or automations to other users." + "\n" + "After defining the attributes, commands and events for this cluster, and the associated data types, " + "several examples are provided to illustrate the capabilities of this cluster." + "\n" + "Actions can be defined in a flexible manner to suit the needs of the various nodes implementing this " + "cluster. For each action, the commands available for that particular action are defined." + "\n" + "This cluster can be used to expose only the grouping of endpoints without any actions defined by " + "populating the EndpointList attribute accordingly and providing an empty list for ActionList." + "\n" + "The term 'action' in the description of this cluster should not be confused with the term 'action' " + "as used in the Interaction Model.", children: [ { tag: "attribute", name: "ActionList", xref: "core§9.14.5.1", details: "The ActionList attribute holds the list of actions. Each entry shall have an unique ActionID, and " + "its EndpointListID shall exist in the EndpointLists attribute." }, { tag: "attribute", name: "EndpointLists", xref: "core§9.14.5.2", details: "The EndpointLists attribute holds the list of endpoint lists. Each entry shall have an unique " + "EndpointListID." }, { tag: "attribute", name: "SetupUrl", xref: "core§9.14.5.3", details: "The SetupURL attribute (when provided) shall indicate a URL; its syntax shall follow the syntax as " + "specified in RFC1738, max. 512 ASCII characters and shall use the https scheme. The location " + "referenced by this URL shall provide additional information for the actions provided:" + "\n" + " - When used without suffix, it shall provide information about the various actions which the " + "cluster provides." + "\n" + " - Example: SetupURL could take the value of example://Actions or " + "https://domain.example/Matter/bridgev1/Actions for this generic case (access generic info how " + "to use actions provided by this cluster)." + "\n" + " - When used with a suffix of \"/?a=\" and the decimal value of ActionID for one of the actions, it " + "may provide information about that particular action. This could be a deeplink to " + "manufacturer-app/website (associated somehow to the server node) with the " + "information/edit-screen for this action so that the user can view and update details of the " + "action, e.g. edit the scene, or change the wake-up experience time period." + "\n" + " - Example of SetupURL with suffix added: example://Actions/?a=12345 or " + "https://domain.example/Matter/bridgev1/Actions/?a=12345 for linking to specific info/editing " + "of the action with ActionID 0x3039." }, { tag: "event", name: "StateChanged", xref: "core§9.14.7.1", details: "This event shall be generated when there is a change in the State of an ActionID during the " + "execution of an action and the most recent command using that ActionID used an InvokeID data field." + "\n" + "It provides feedback to the client about the progress of the action." + "\n" + "Example: When InstantActionWithTransition is invoked (with an InvokeID data field), two StateChanged " + "events will be generated:" + "\n" + " - one when the transition starts (NewState=Active)" + "\n" + " - one when the transition completed (NewState=Inactive)", children: [ { tag: "field", name: "ActionId", xref: "core§9.14.7.1.1", details: "This field shall be set to the ActionID of the action which has changed state." }, { tag: "field", name: "InvokeId", xref: "core§9.14.7.1.2", details: "This field shall be set to the InvokeID which was provided to the most recent command referencing " + "this ActionID." }, { tag: "field", name: "NewState", xref: "core§9.14.7.1.3", details: "This field shall be set to state that the action has changed to." } ] }, { tag: "event", name: "ActionFailed", xref: "core§9.14.7.2", details: "This event shall be generated when there is some error which prevents the action from its normal " + "planned execution and the most recent command using that ActionID used an InvokeID data field." + "\n" + "It provides feedback to the client about the non-successful progress of the action." + "\n" + "Example: When InstantActionWithTransition is invoked (with an InvokeID data field), and another " + "controller changes the state of one or more of the involved endpoints during the transition, thus " + "interrupting the transition triggered by the action, two events would be generated:" + "\n" + " - StateChanged when the transition starts (NewState=Active)" + "\n" + " - ActionFailed when the interrupting command occurs (NewState=Inactive, Error=interrupted)" + "\n" + "Example: When InstantActionWithTransition is invoked (with an InvokeID data field = 1), and the same " + "client invokes an InstantAction with (the same or another ActionId and) InvokeID = 2, and this " + "second command interrupts the transition triggered by the first command, these events would be " + "generated:" + "\n" + " - StateChanged (InvokeID=1, NewState=Active) when the transition starts" + "\n" + " - ActionFailed (InvokeID=2, NewState=Inactive, Error=interrupted) when the second command " + "interrupts the transition" + "\n" + " - StateChanged (InvokeID=2, NewState=Inactive) upon the execution of the action for the second " + "command", children: [ { tag: "field", name: "ActionId", xref: "core§9.14.7.2.1", details: "This field shall be set to the ActionID of the action which encountered an error." }, { tag: "field", name: "InvokeId", xref: "core§9.14.7.2.2", details: "This field shall be set to the InvokeID which was provided to the most recent command referencing " + "this ActionID." }, { tag: "field", name: "NewState", xref: "core§9.14.7.2.3", details: "This field shall be set to state that the action is in at the time of generating the event." }, { tag: "field", name: "Error", xref: "core§9.14.7.2.4", details: "This field shall be set to indicate the reason for non-successful progress of the action." } ] }, { tag: "command", name: "InstantAction", xref: "core§9.14.6.1", details: "This command is used to trigger an instantaneous action." + "\n" + "This command triggers an action (state change) on the involved endpoints, in a \"fire and forget\" " + "manner. Afterwards, the action's state shall be Inactive." + "\n" + "Example: recall a scene on a number of lights." }, { tag: "command", name: "InstantActionWithTransition", xref: "core§9.14.6.2", details: "This command is used to trigger an instantaneous action with a transition over a given time." + "\n" + "It is recommended that, where possible (e.g., it is not possible for attributes with Boolean data " + "type), a gradual transition SHOULD take place from the old to the new state over this time period. " + "However, the exact transition is manufacturer dependent." + "\n" + "This command triggers an action (state change) on the involved endpoints, with a specified time to " + "transition from the current state to the new state. During the transition, the action's state shall " + "be Active. Afterwards, the action's state shall be Inactive." + "\n" + "Example: recall a scene on a number of lights, with a specified transition time.", children: [{ tag: "field", name: "TransitionTime", xref: "core§9.14.6.2.1", details: "This field shall indicate the transition time in 1/10th of seconds." }] }, { tag: "command", name: "StartAction", xref: "core§9.14.6.3", details: "This command is used to trigger the commencement of an action." + "\n" + "This command triggers the commencement of an action on the involved endpoints. Afterwards, the " + "action's state shall be Active." + "\n" + "Example: start a dynamic lighting pattern (such as gradually rotating the colors around the " + "setpoints of the scene) on a set of lights." + "\n" + "Example: start a sequence of events such as a wake-up experience involving lights moving through " + "several brightness/color combinations and the window covering gradually opening." }, { tag: "command", name: "StartActionWithDuration", xref: "core§9.14.6.4", details: "This command is used to trigger the commencement of an action with a duration." + "\n" + "This command triggers the commencement of an action on the involved endpoints, and shall change the " + "action's state to Active. After the specified Duration, the action will stop, and the action's state " + "shall change to Inactive." + "\n" + "Example: start a dynamic lighting pattern (such as gradually rotating the colors around the " + "setpoints of the scene) on a set of lights for 1 hour (Duration=3600).", children: [{ tag: "field", name: "Duration", xref: "core§9.14.6.4.1", details: "This field shall indicate the requested duration in seconds." }] }, { tag: "command", name: "StopAction", xref: "core§9.14.6.5", details: "This command is used to stop an action." + "\n" + "This command stops the ongoing action on the involved endpoints. Afterwards, the action's state " + "shall be Inactive." + "\n" + "Example: stop a dynamic lighting pattern which was previously started with StartAction." }, { tag: "command", name: "PauseAction", xref: "core§9.14.6.6", details: "This command is used to pause an action." + "\n" + "This command pauses an ongoing action, and shall change the action's state to Paused." + "\n" + "Example: pause a dynamic lighting effect (the lights stay at their current color) which was " + "previously started with StartAction." }, { tag: "command", name: "PauseActionWithDuration", xref: "core§9.14.6.7", details: "This command is used to pause an action with a duration." + "\n" + "This command pauses an ongoing action, and shall change the action's state to Paused. After the " + "specified Duration, the ongoing action will be automatically resumed. which shall change the " + "action's state to Active." + "\n" + "Example: pause a dynamic lighting effect (the lights stay at their current color) for 10 minutes " + "(Duration=600)." + "\n" + "The difference between Pause/Resume and Disable/Enable is on the one hand semantic (the former is " + "more of a transitionary nature while the latter is more permanent) and on the other hand these can " + "be implemented slightly differently in the implementation of the action (e.g. a Pause would be " + "automatically resumed after some hours or during a nightly reset, while an Disable would remain in " + "effect until explicitly enabled again).", children: [{ tag: "field", name: "Duration", xref: "core§9.14.6.7.1", details: "This field shall indicate the requested duration in seconds." }] }, { tag: "command", name: "ResumeAction", xref: "core§9.14.6.8", details: "This command is used to resume an action." + "\n" + "This command resumes a previously paused action, and shall change the action's state to Active." + "\n" + "The difference between ResumeAction and StartAction is that ResumeAction will continue the action " + "from the state where it was paused, while StartAction will start the action from the beginning." + "\n" + "Example: resume a dynamic lighting effect (the lights' colors will change gradually, continuing from " + "the point they were paused)." }, { tag: "command", name: "EnableAction", xref: "core§9.14.6.9", details: "This command is used to enable an action." + "\n" + "This command enables a certain action or automation. Afterwards, the action's state shall be Active." + "\n" + "Example: enable a motion sensor to control the lights in an area." }, { tag: "command", name: "EnableActionWithDuration", xref: "core§9.14.6.10", details: "This command is used to enable an action with a duration." + "\n" + "This command enables a certain action or automation, and shall change the action's state to be " + "Active. After the specified Duration, the action or automation will stop, and the action's state " + "shall change to Disabled." + "\n" + "Example: enable a \"presence mimicking\" behavior for the lights in your home during a vacation; the " + "Duration field is used to indicated the length of your absence from home. After that period, the " + "presence mimicking behavior will no longer control these lights.", children: [{ tag: "field", name: "Duration", xref: "core§9.14.6.10.1", details: "This field shall indicate the requested duration in seconds." }] }, { tag: "command", name: "DisableAction", xref: "core§9.14.6.11", details: "This command is used to disable an action." + "\n" + "This command disables a certain action or automation, and shall change the action's state to " + "Inactive." + "\n" + "Example: disable a motion sensor to no longer control the lights in an area." }, { tag: "command", name: "DisableActionWithDuration", xref: "core§9.14.6.12", details: "This command is used to disable an action with a duration." + "\n" + "This command disables a certain action or automation, and shall change the action's state to " + "Disabled. After the specified Duration, the action or automation will re-start, and the action's " + "state shall change to either Inactive or Active, depending on the actions (see Section 9.14.8.4, " + "\"Example 4: Wake-up routine\" and Section 9.14.8.6, \"Example 6: Alarm system\")." + "\n" + "Example: disable a \"wakeup\" experience for a period of 1 week when going on holiday (to prevent them " + "from turning on in the morning while you're not at home). After this period, the wakeup experience " + "will control the lights as before.", children: [{ tag: "field", name: "Duration", xref: "core§9.14.6.12.1", details: "This field shall indicate the requested duration in seconds." }] }, { tag: "datatype", name: "CommandBits", xref: "core§9.14.4.1", details: "Note - The bit allocation of this bitmap shall follow the ID's of the Commands of this cluster.", children: [ { tag: "field", name: "InstantAction", description: "Indicate support for InstantAction command" }, { tag: "field", name: "InstantActionWithTransition", description: "Indicate support for InstantActionWithTransition command" }, { tag: "field", name: "StartAction", description: "Indicate support for StartAction command" }, { tag: "field", name: "StartActionWithDuration", description: "Indicate support for StartActionWithDuration command" }, { tag: "field", name: "StopAction", description: "Indicate support for StopAction command" }, { tag: "field", name: "PauseAction", description: "Indicate support for PauseAction command" }, { tag: "field", name: "PauseActionWithDuration", description: "Indicate support for PauseActionWithDuration command" }, { tag: "field", name: "ResumeAction", description: "Indicate support for ResumeAction command" }, { tag: "field", name: "EnableAction", description: "Indicate support for EnableAction command" }, { tag: "field", name: "EnableActionWithDuration", description: "Indicate support for EnableActionWithDuration command" }, { tag: "field", name: "DisableAction", description: "Indicate support for DisableAction command" }, { tag: "field", name: "DisableActionWithDuration", description: "Indicate support for DisableActionWithDuration command" } ] }, { tag: "datatype", name: "ActionTypeEnum", xref: "core§9.14.4.2", children: [ { tag: "field", name: "Other", description: "Use this only when none of the other values applies" }, { tag: "field", name: "Scene", description: "Bring the endpoints into a certain state", xref: "core§9.14.4.2.1", details: "Can be used to set a static state of the associated endpoints (typically using InstantAction or " + "InstantActionWithTransition), or to bring these endpoints into a more dynamic state (typically using " + "StartAction), where the endpoints would e.g. gradually cycle through certain colors for a pleasing " + "effect. A voice controller could use \"set\" (to map to InstantAction) or \"play\" (to map to " + "StartAction) to trigger such actions. Example: see Section 9.14.8.1, \"Example 1: Scene recall\" and " + "Section 9.14.8.2, \"Example 2: Set dynamic light effect\"." }, { tag: "field", name: "Sequence", description: "A sequence of states with a certain time pattern", xref: "core§9.14.4.2.2", details: "Indicates an action which involves a sequence of events/states of the associated endpoints, such as " + "a wake-up experience. Example: see Section 9.14.8.4, \"Example 4: Wake-up routine\"." }, { tag: "field", name: "Automation", description: "Control an automation (e.g. motion sensor controlling lights)", xref: "core§9.14.4.2.3", details: "Indications an automation (e.g. a motion sensor controlling lights, an alarm system) which can be " + "e.g. started, stopped, paused, resumed. Example: see Section 9.14.8.3, \"Example 3: Pause sensor " + "automation\"." }, { tag: "field", name: "Exception", description: "Sequence that will run when something doesn't happen", xref: "core§9.14.4.2.4", details: "Indicates some action which the server will execute when a certain condition (which normally does " + "not happen) is not met. Example: lock the doors when the server's system has detected no one is at " + "home while the doors are in the 'unlocked' state." }, { tag: "field", name: "Notification", description: "Use the endpoints to send a message to user", xref: "core§9.14.4.2.5", details: "Indicates an action that can be triggered (e.g. by InstantAction) to notify the user. Example: play " + "a pattern on the lights in the living room if there is someone in the garden in the evening." }, { tag: "field", name: "Alarm", description: "Higher priority notification", xref: "core§9.14.4.2.6", details: "Similar to Notification but with a higher priority (and might override other endpoint states which " + "Type=Notification would not override). Example: flash all lights in the house when CO sensor " + "triggers." } ] }, { tag: "datatype", name: "ActionStateEnum", xref: "core§9.14.4.3", details: "Note that some of these states are applicable only for certain actions, as determined by their " + "SupportedCommands.", children: [ { tag: "field", name: "Inactive", description: "The action is not active" }, { tag: "field", name: "Active", description: "The action is active" }, { tag: "field", name: "Paused", description: "The action has been paused" }, { tag: "field", name: "Disabled", description: "The action has been disabled" } ] }, { tag: "datatype", name: "ActionErrorEnum", xref: "core§9.14.4.4", children: [ { tag: "field", name: "Unknown", description: "Other reason not listed in the row(s) below" }, { tag: "field", name: "Interrupted", description: "The action was interrupted by another command or interaction" } ] }, { tag: "datatype", name: "EndpointListTypeEnum", xref: "core§9.14.4.5", details: "The Room and Zone values are provided for the cases where a user (or the system on behalf of the " + "user) has created logical grouping of the endpoints (e.g. bridged devices) based on location.", children: [ { tag: "field", name: "Other", description: "Another group of endpoints", xref: "core§9.14.4.5.1", details: "This value is provided for the case of an endpoint list which is tied specifically to this action " + "i.e. not independently created by the user. For Type=Other the Name may be empty. A Matter " + "controller would typically not use this for anything else than just to know which endpoints would be " + "affected by the action." }, { tag: "field", name: "Room", description: "User-configured group of endpoints where an endpoint can be in only one room", xref: "core§9.14.4.5.2", details: "Is used for the situation where an endpoint can only be part of one such rooms (e.g. physical " + "mapping). Using these exposed logical groups, a Matter controller who has a similar grouping concept " + "can use it to place each endpoint (bridged device) in the right room automatically, without user " + "having to redo that setup for each device in each system - both at first contact and upon later " + "updates to the endpoints (e.g. user adds a bridged device or creates a new room)." }, { tag: "field", name: "Zone", description: "User-configured group of endpoints where an endpoint can be in any number of zones", xref: "core§9.14.4.5.3", details: "Is a more general concept where an endpoint can be part of multiple zones, e.g. a light in the " + "living room can be part of the \"reading corner\" zone (subset of the lights in the living room) but " + "also part of the \"downstairs\" zone which contains all the lights on a floor, e.g. combining living " + "room, kitchen and hallway. This indicates that a user has defined this list of endpoints as " + "something they logically would like to control as a group, so Matter controllers could provide the " + "user with a way to do as such." } ] }, { tag: "datatype", name: "ActionStruct", xref: "core§9.14.4.6", details: "This data type holds the details of a single action, and contains the data fields below.", children: [ { tag: "field", name: "ActionId", xref: "core§9.14.4.6.1", details: "This field shall provide an unique identifier used to identify an action." }, { tag: "field", name: "Name", xref: "core§9.14.4.6.2", details: "This field shall indicate the name (as assigned by the user or automatically by the server) " + "associated with this action. This can be used for identifying the action to the user by the client. " + "Example: \"my colorful scene\"." }, { tag: "field", name: "Type", xref: "core§9.14.4.6.3", details: "This field shall indicate the type of action. The value of Type of an action, along with its " + "SupportedCommands can be used by the client in its UX or logic to determine how to present or use " + "such action. See ActionTypeEnum for details and examples." }, { tag: "field", name: "EndpointListId", xref: "core§9.14.4.6.4", details: "This field shall provide a reference to the associated endpoint list, which specifies the endpoints " + "on this Node which will be impacted by this ActionID." }, { tag: "field", name: "SupportedCommands", xref: "core§9.14.4.6.5", details: "This field is a bitmap which shall be used to indicate which of the cluster's commands are supported " + "for this particular action, with a bit set to 1 for each supported command according to the table " + "below. Other bits shall be set to 0." }, { tag: "field", name: "State", xref: "core§9.14.4.6.6", details: "This field shall indicate the current state of this action." } ] }, { tag: "datatype", name: "EndpointListStruct", xref: "core§9.14.4.7", details: "This data type holds the details of a single endpoint list, which relates to a set of endpoints that " + "have some logical relation, and contains the data fields below.", children: [ { tag: "field", name: "EndpointListId", xref: "core§9.14.4.7.1", details: "This field shall provide an unique identifier used to identify the endpoint list." }, { tag: "field", name: "Name", xref: "core§9.14.4.7.2", details: "This field shall indicate the name (as assigned by the user or automatically by the server) " + "associated with the set of endpoints in this list. This can be used for identifying the action to " + "the user by the client. Example: \"living room\"." }, { tag: "field", name: "Type", xref: "core§9.14.4.7.3", details: "This field shall indicate the type of endpoint list, see EndpointListTypeEnum." }, { tag: "field", name: "Endpoints", xref: "core§9.14.4.7.4", details: "This field shall provide a list of endpoint numbers." } ] } ] } );