/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import { Resource } from "#models/Resource.js";
Resource.add(
  {
    tag: "cluster",
    name: "Actions",
    pics: "ACT",
    xref: "core\xA79.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.\nSpecifically this cluster provides:\n  \u2022 Information about logical grouping of endpoints on the Node (example: lights in a room)\n  \u2022 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  \u2022 Commands to trigger such actions\n  \u2022 Events to receive feedback on the state of such actions.\nThe 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.\nUsing this cluster, a Node can learn about such logical grouping, provided actions, and trigger such actions.\nWhile 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.\nAfter 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.\nActions 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.\nThis 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.\nThe 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\xA79.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\xA79.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\xA79.14.5.3",
        details: 'The SetupURL attribute (when provided) shall indicate a URL; its syntax shall follow the syntax as specified in RFC 1738, 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  \u2022 When used without suffix, it shall provide information about the various actions which the     cluster provides.\n    \u25E6 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  \u2022 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    \u25E6 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\xA79.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.\nIt provides feedback to the client about the progress of the action.\nExample: When InstantActionWithTransition is invoked (with an InvokeID data field), two StateChanged events will be generated:\n  \u2022 one when the transition starts (NewState=Active)\n  \u2022 one when the transition completed (NewState=Inactive)",
        children: [
          {
            tag: "field",
            name: "ActionId",
            xref: "core\xA79.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\xA79.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\xA79.14.7.1.3",
            details: "This field shall be set to state that the action has changed to."
          }
        ]
      },
      {
        tag: "event",
        name: "ActionFailed",
        xref: "core\xA79.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.\nIt provides feedback to the client about the non-successful progress of the action.\nExample: 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  \u2022 StateChanged when the transition starts (NewState=Active)\n  \u2022 ActionFailed when the interrupting command occurs (NewState=Inactive, Error=interrupted)\nExample: 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  \u2022 StateChanged (InvokeID=1, NewState=Active) when the transition starts\n  \u2022 ActionFailed (InvokeID=2, NewState=Inactive, Error=interrupted) when the second command     interrupts the transition\n  \u2022 StateChanged (InvokeID=2, NewState=Inactive) upon the execution of the action for the second     command",
        children: [
          {
            tag: "field",
            name: "ActionId",
            xref: "core\xA79.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\xA79.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\xA79.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\xA79.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\xA79.14.6.1",
        details: 'This command is used to trigger an instantaneous action.\nThis command triggers an action (state change) on the involved endpoints, in a "fire and forget" manner. Afterwards, the action\u2019s state shall be Inactive.\nExample: recall a scene on a number of lights.'
      },
      {
        tag: "command",
        name: "InstantActionWithTransition",
        xref: "core\xA79.14.6.2",
        details: "This command is used to trigger an instantaneous action with a transition over a given time.\nIt 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.\nThis 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\u2019s state shall be Active. Afterwards, the action\u2019s state shall be Inactive.\nExample: recall a scene on a number of lights, with a specified transition time.",
        children: [{
          tag: "field",
          name: "TransitionTime",
          xref: "core\xA79.14.6.2.1",
          details: "This field shall indicate the transition time in 1/10th of seconds."
        }]
      },
      {
        tag: "command",
        name: "StartAction",
        xref: "core\xA79.14.6.3",
        details: "This command is used to trigger the commencement of an action.\nThis command triggers the commencement of an action on the involved endpoints. Afterwards, the action\u2019s state shall be Active.\nExample: start a dynamic lighting pattern (such as gradually rotating the colors around the setpoints of the scene) on a set of lights.\nExample: 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\xA79.14.6.4",
        details: "This command is used to trigger the commencement of an action with a duration.\nThis command triggers the commencement of an action on the involved endpoints, and shall change the action\u2019s state to Active. After the specified Duration, the action will stop, and the action\u2019s state shall change to Inactive.\nExample: 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\xA79.14.6.4.1",
          details: "This field shall indicate the requested duration in seconds."
        }]
      },
      {
        tag: "command",
        name: "StopAction",
        xref: "core\xA79.14.6.5",
        details: "This command is used to stop an action.\nThis command stops the ongoing action on the involved endpoints. Afterwards, the action\u2019s state shall be Inactive.\nExample: stop a dynamic lighting pattern which was previously started with StartAction."
      },
      {
        tag: "command",
        name: "PauseAction",
        xref: "core\xA79.14.6.6",
        details: "This command is used to pause an action.\nThis command pauses an ongoing action, and shall change the action\u2019s state to Paused.\nExample: pause a dynamic lighting effect (the lights stay at their current color) which was previously started with StartAction."
      },
      {
        tag: "command",
        name: "PauseActionWithDuration",
        xref: "core\xA79.14.6.7",
        details: "This command is used to pause an action with a duration.\nThis command pauses an ongoing action, and shall change the action\u2019s state to Paused. After the specified Duration, the ongoing action will be automatically resumed. which shall change the action\u2019s state to Active.\nExample: pause a dynamic lighting effect (the lights stay at their current color) for 10 minutes (Duration=600).\nThe 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\xA79.14.6.7.1",
          details: "This field shall indicate the requested duration in seconds."
        }]
      },
      {
        tag: "command",
        name: "ResumeAction",
        xref: "core\xA79.14.6.8",
        details: "This command is used to resume an action.\nThis command resumes a previously paused action, and shall change the action\u2019s state to Active.\nThe 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.\nExample: resume a dynamic lighting effect (the lights' colors will change gradually, continuing from the point they were paused)."
      },
      {
        tag: "command",
        name: "EnableAction",
        xref: "core\xA79.14.6.9",
        details: "This command is used to enable an action.\nThis command enables a certain action or automation. Afterwards, the action\u2019s state shall be Active.\nExample: enable a motion sensor to control the lights in an area."
      },
      {
        tag: "command",
        name: "EnableActionWithDuration",
        xref: "core\xA79.14.6.10",
        details: 'This command is used to enable an action with a duration.\nThis command enables a certain action or automation, and shall change the action\u2019s state to be Active. After the specified Duration, the action or automation will stop, and the action\u2019s state shall change to Disabled.\nExample: 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\xA79.14.6.10.1",
          details: "This field shall indicate the requested duration in seconds."
        }]
      },
      {
        tag: "command",
        name: "DisableAction",
        xref: "core\xA79.14.6.11",
        details: "This command is used to disable an action.\nThis command disables a certain action or automation, and shall change the action\u2019s state to Inactive.\nExample: disable a motion sensor to no longer control the lights in an area."
      },
      {
        tag: "command",
        name: "DisableActionWithDuration",
        xref: "core\xA79.14.6.12",
        details: 'This command is used to disable an action with a duration.\nThis command disables a certain action or automation, and shall change the action\u2019s state to Disabled. After the specified Duration, the action or automation will re-start, and the action\u2019s state shall change to either Inactive or Active, depending on the actions (see Section 9.14.8.4, \u201CExample 4: Wake-up routine\u201D and Section 9.14.8.6, \u201CExample 6: Alarm system\u201D).\nExample: 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\u2019re not at home). After this period, the wakeup experience will control the lights as before.',
        children: [{
          tag: "field",
          name: "Duration",
          xref: "core\xA79.14.6.12.1",
          details: "This field shall indicate the requested duration in seconds."
        }]
      },
      {
        tag: "datatype",
        name: "CommandBits",
        xref: "core\xA79.14.4.1",
        details: "Note - The bit allocation of this bitmap shall follow the ID\u2019s 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\xA79.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\xA79.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.\nExample: see Section 9.14.8.1, \u201CExample 1: Scene recall\u201D and Section 9.14.8.2, \u201CExample 2: Set dynamic light effect\u201D.'
          },
          {
            tag: "field",
            name: "Sequence",
            description: "A sequence of states with a certain time pattern",
            xref: "core\xA79.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.\nExample: see Section 9.14.8.4, \u201CExample 4: Wake-up routine\u201D."
          },
          {
            tag: "field",
            name: "Automation",
            description: "Control an automation (e.g. motion sensor controlling lights)",
            xref: "core\xA79.14.4.2.3",
            details: "Indications an automation (e.g. a motion sensor controlling lights, an alarm system) which can bee.g. started, stopped, paused, resumed.\nExample: see Section 9.14.8.3, \u201CExample 3: Pause sensor automation\u201D."
          },
          {
            tag: "field",
            name: "Exception",
            description: "Sequence that will run when something doesn\u2019t happen",
            xref: "core\xA79.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.\nExample: lock the doors when the server\u2019s 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\xA79.14.4.2.5",
            details: "Indicates an action that can be triggered (e.g. by InstantAction) to notify the user.\nExample: 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\xA79.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).\nExample: flash all lights in the house when CO sensor triggers."
          }
        ]
      },
      {
        tag: "datatype",
        name: "ActionStateEnum",
        xref: "core\xA79.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\xA79.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\xA79.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\xA79.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\xA79.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\xA79.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\xA79.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\xA79.14.4.6.1",
            details: "This field shall provide an unique identifier used to identify an action."
          },
          {
            tag: "field",
            name: "Name",
            xref: "core\xA79.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\xA79.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\xA79.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\xA79.14.4.6.5",
            details: "This field is a bitmap which shall be used to indicate which of the cluster\u2019s 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\xA79.14.4.6.6",
            details: "This field shall indicate the current state of this action."
          }
        ]
      },
      {
        tag: "datatype",
        name: "EndpointListStruct",
        xref: "core\xA79.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\xA79.14.4.7.1",
            details: "This field shall provide an unique identifier used to identify the endpoint list."
          },
          {
            tag: "field",
            name: "Name",
            xref: "core\xA79.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\xA79.14.4.7.3",
            details: "This field shall indicate the type of endpoint list, see EndpointListTypeEnum."
          },
          {
            tag: "field",
            name: "Endpoints",
            xref: "core\xA79.14.4.7.4",
            details: "This field shall provide a list of endpoint numbers."
          }
        ]
      }
    ]
  }
);
//# sourceMappingURL=actions.resource.js.map
