/** * @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: "Switch", pics: "SWTCH", xref: "cluster§1.13", details: "This cluster exposes interactions with a switch device, for the purpose of using those interactions " + "by other devices. Two types of switch devices are supported: latching switch (e.g. rocker switch) " + "and momentary switch (e.g. push button), distinguished with their feature flags. Interactions with " + "the switch device are exposed as attributes (for the latching switch) and as events (for both types " + "of switches). An interested client may subscribe to these attributes/events and thus be informed of " + "the interactions, and can perform actions based on this, for example by sending commands to perform " + "an action such as controlling a light or a window shade.", children: [ { tag: "attribute", name: "FeatureMap", xref: "cluster§1.13.4", children: [ { tag: "field", name: "LS", xref: "cluster§1.13.4.1", details: "This feature flag is for a switch that maintains its position after being pressed (or turned)." }, { tag: "field", name: "MS", xref: "cluster§1.13.4.2", details: "This feature flag is for a switch that does not maintain its position after being pressed (or " + "turned). After releasing, it goes back to its idle position." }, { tag: "field", name: "MSR", xref: "cluster§1.13.4.3", details: "This feature flag is for a momentary switch that can distinguish and report release events." }, { tag: "field", name: "MSL", xref: "cluster§1.13.4.4", details: "This feature flag is for a momentary switch that can distinguish and report long presses from short " + "presses." }, { tag: "field", name: "MSM", xref: "cluster§1.13.4.5", details: "This feature flag is for a momentary switch that can distinguish and report double press and " + "potentially multiple presses with more events, such as triple press, etc." }, { tag: "field", name: "AS", xref: "cluster§1.13.4.6", details: "This feature flag indicates simplified handling of events for multi-press-capable switches. See " + "Section 1.13.8, \"Sequence of events for MultiPress\"." } ] }, { tag: "attribute", name: "NumberOfPositions", xref: "cluster§1.13.5.1", details: "Indicates the maximum number of positions the switch has. Any kind of switch has a minimum of 2 " + "positions. Also see Section 1.13.10, \"Multi Position Details\" for the case NumberOfPositions>2." }, { tag: "attribute", name: "CurrentPosition", xref: "cluster§1.13.5.2", details: "Indicates the position of the switch." + "\n" + "The valid range is zero to NumberOfPositions - 1." + "\n" + "CurrentPosition value 0 shall be assigned to the default position of the switch: for example the " + "\"open\" state of a rocker switch, or the \"idle\" state of a push button switch." }, { tag: "attribute", name: "MultiPressMax", xref: "cluster§1.13.5.3", details: "Indicates how many consecutive presses can be detected and reported by a momentary switch which " + "supports multi-press (MSM feature flag set)." + "\n" + "For example, a momentary switch supporting single press, double press and triple press, but not quad " + "press and beyond, would return the value 3." + "\n" + "When more than MultiPressMax presses are detected within a multi-press sequence:" + "\n" + " - The server for cluster revision $<$ 2 SHOULD generate a MultiPressComplete event with the " + "TotalNumberOfPressesCounted field set to the value of the MultiPressMax attribute, and avoid " + "generating any further InitialPress and MultiPressOngoing events until the switch has become " + "fully idle (i.e. no longer in the process of counting presses within the multipress)." + "\n" + " - The server for cluster revision $>=$ 2 shall generate a MultiPressComplete event with the " + "TotalNumberOfPressesCounted field set to zero (indicating an aborted sequence), and shall NOT " + "generate any further InitialPress and MultiPressOngoing events until the switch has become fully " + "idle (i.e. no longer in the process of counting presses within the multipress)." + "\n" + "This approach avoids unintentionally causing intermediate actions where there is a very long " + "sequence of presses beyond MultiPressMax that may be taken in account specially by switches (e.g. to " + "trigger special behavior such as factory reset for which generating events towards the client is not " + "appropriate)." }, { tag: "event", name: "SwitchLatched", xref: "cluster§1.13.6.1", details: "This event shall be generated, when the latching switch is moved to a new position. It may have been " + "delayed by debouncing within the switch.", children: [{ tag: "field", name: "NewPosition", xref: "cluster§1.13.6.1.1", details: "This field shall indicate the new value of the CurrentPosition attribute, i.e. after the move." }] }, { tag: "event", name: "InitialPress", xref: "cluster§1.13.6.2", details: "This event shall be generated, when the momentary switch starts to be pressed (after debouncing).", children: [{ tag: "field", name: "NewPosition", xref: "cluster§1.13.6.2.1", details: "This field shall indicate the new value of the CurrentPosition attribute, i.e. while pressed." }] }, { tag: "event", name: "LongPress", xref: "cluster§1.13.6.3", details: "This event shall be generated when the momentary switch has been pressed for a \"long\" time. The time " + "interval constituting a \"long\" time is manufacturer-determined, since it depends on the switch " + "physics." + "\n" + " - When the AS feature flag is set, this event:" + "\n" + " - shall NOT be generated during a multi-press sequence (since a long press is a separate cycle " + "from any multi-press cycles);" + "\n" + " - shall only be generated after the first InitialPress following a MultiPressComplete when a " + "long press is detected after the idle time." + "\n" + " - Else, when the MSM feature flag is set, this event:" + "\n" + " - shall NOT be generated during a multi-press sequence (since a long press is a separate cycle " + "from any multi-press cycles);" + "\n" + " - shall only be generated after the first InitialPress following a MultiPressComplete when a " + "long press is detected after the idle time;" + "\n" + " - shall NOT be generated after a MultiPressOngoing event without an intervening " + "MultiPressComplete event." + "\n" + "The above constraints imply that for a given activity detection cycle of a switch having MSM and/or " + "MSL feature flags set, the entire activity is either a single long press detection cycle of " + "(InitialPress, LongPress, LongRelease), or a single multi-press detection cycle (ending in " + "MultiPressComplete), where presses that would otherwise be reported as long presses are instead " + "reported as a counted press in the MultiPressComplete event, and as InitialPress/ShortRelease pairs " + "otherwise (where applicable)." + "\n" + "The rationale for this constraint is the ambiguity of interpretation of events when mixing long " + "presses and multi-press events.", children: [{ tag: "field", name: "NewPosition", xref: "cluster§1.13.6.3.1", details: "This field shall indicate the new value of the CurrentPosition attribute, i.e. while pressed." }] }, { tag: "event", name: "ShortRelease", xref: "cluster§1.13.6.4", details: "If the server has the Action Switch (AS) feature flag set, this event shall NOT be generated at all, " + "since setting the Action Switch feature flag forbids the Momentary Switch ShortRelease (MSR) feature " + "flag from being set. Otherwise, the following paragraphs describe the situations where this event is " + "generated." + "\n" + "This event shall be generated, when the momentary switch has been released (after debouncing)." + "\n" + " - If the server has the Momentary Switch LongPress (MSL) feature flag set, then this event shall " + "be generated when the switch is released if no LongPress event had been generated since the " + "previous InitialPress event." + "\n" + " - If the server does not have the Momentary Switch LongPress (MSL) feature flag set, this event " + "shall be generated when the switch is released - even when the switch was pressed for a long " + "time." + "\n" + " - Also see Section 1.13.7, \"Sequence of generated events\".", children: [{ tag: "field", name: "PreviousPosition", xref: "cluster§1.13.6.4.1", details: "This field shall indicate the previous value of the CurrentPosition attribute, i.e. just prior to " + "release." }] }, { tag: "event", name: "LongRelease", xref: "cluster§1.13.6.5", details: "This event shall be generated, when the momentary switch has been released (after debouncing) and " + "after having been pressed for a long time, i.e. this event shall be generated when the switch is " + "released if a LongPress event has been generated since the previous InitialPress event. Also see " + "Section 1.13.7, \"Sequence of generated events\".", children: [{ tag: "field", name: "PreviousPosition", xref: "cluster§1.13.6.5.1", details: "This field shall indicate the previous value of the CurrentPosition attribute, i.e. just prior to " + "release." }] }, { tag: "event", name: "MultiPressOngoing", xref: "cluster§1.13.6.6", details: "If the server has the Action Switch (AS) feature flag set, this event shall NOT be generated at all. " + "Otherwise, the following paragraphs describe the situations where this event is generated." + "\n" + "This event shall be generated to indicate how many times the momentary switch has been pressed in a " + "multi-press sequence, during that sequence. See Section 1.13.8, \"Sequence of events for MultiPress\".", children: [ { tag: "field", name: "NewPosition", xref: "cluster§1.13.6.6.1", details: "This field shall indicate the new value of the CurrentPosition attribute, i.e. while pressed." }, { tag: "field", name: "CurrentNumberOfPressesCounted", xref: "cluster§1.13.6.6.2", details: "This field shall contain:" + "\n" + " - a value of 2 when the second press of a multi-press sequence has been detected," + "\n" + " - a value of 3 when the third press of a multi-press sequence has been detected," + "\n" + " - a value of N when the N^th press of a multi-press sequence has been detected." } ] }, { tag: "event", name: "MultiPressComplete", xref: "cluster§1.13.6.7", details: "This event shall be generated to indicate how many times the momentary switch has been pressed in a " + "multi-press sequence, after it has been detected that the sequence has ended. See Section 1.13.8, " + "\"Sequence of events for MultiPress\"." + "\n" + "The PreviousPosition field shall indicate the previous value of the CurrentPosition attribute, i.e. " + "just prior to release." + "\n" + "The TotalNumberOfPressesCounted field shall contain:" + "\n" + " - a value of 0 when there was an aborted multi-press sequence, where the number of presses goes " + "beyond MultiPressMax presses," + "\n" + " - a value of 1 when there was exactly one press in a multi-press sequence (and the sequence has " + "ended), i.e. there was no double press (or more)," + "\n" + " - a value of 2 when there were exactly two presses in a multi-press sequence (and the sequence has " + "ended)," + "\n" + " - a value of 3 when there were exactly three presses in a multi-press sequence (and the sequence " + "has ended)," + "\n" + " - a value of N when there were exactly N presses in a multi-press sequence (and the sequence has " + "ended)." + "\n" + " > [!NOTE]" + "\n" + " > NOTE: The introduction of TotalNumberOfPressesCounted supporting the value 0 may impact " + "clients of switches using cluster revision 1 since such servers would not use this value of " + "TotalNumberOfPressesCounted to indicate an aborted sequence. Clients SHOULD always act using " + "the TotalNumberOfPressesCounted field taken into account since for values from 1 to " + "MultiPressMax, the user action that led to the event was different depending on the count." } ] });