Add Matter virtual switch

Author: s-hadinger

docs/Matter-Internals.md

@@ -47,7 +47,8 @@ The registered plug-in types below are current for the Matter 1.6.1 implementati
 | `Matter_Plugin_Sensor_Rain` | `rain` | Rain Sensor (`0x0044`) |
 | `Matter_Plugin_Sensor_Waterleak` | `waterleak` | Water Leak Detector (`0x0043`) |
 | `Matter_Plugin_Sensor_Air_Quality` | `airquality` | Air Quality Sensor (`0x002C`), with optional CO₂, NO₂, PM, and TVOC measurements |
-| `Matter_Plugin_Sensor_GenericSwitch_Btn` | `gensw_btn` | Generic Switch (`0x000F`) |
+| `Matter_Plugin_Sensor_GenericSwitch_Btn` | `gensw_btn` | Generic Switch (`0x000F`), mapped to a Tasmota button |
+| `Matter_Plugin_Virt_Sensor_GenericSwitch_Btn` | `v_gensw` | Virtual Generic Switch (`0x000F`) for remote completed gestures |
 
 HTTP bridge plug-ins have `http_` types and extend the corresponding local implementation:
 
@@ -64,6 +65,7 @@ Virtual plug-ins have `v_` types and can be updated with [`MtrUpdate`](Matter.md
 | --- | --- |
 | Lights and relays | `v_light0`, `v_light1`, `v_light2`, `v_light3`, `v_relay`, `v_relay_power` |
 | Appliances | `v_fan`, `v_garage`, `v_hvac`, `v_hvac_option` |
+| Buttons | `v_gensw` |
 | Sensors | `v_temperature`, `v_pressure`, `v_illuminance`, `v_humidity`, `v_flow`, `v_soil`, `v_contact`, `v_occupancy`, `v_rain`, `v_waterleak`, `v_airquality` |
 
 Zigbee bridge plug-ins are virtual internally and set `ZIGBEE = true`: `z_light0`, `z_light1`, `z_light2`, `z_temp`, `z_humidity`, `z_pressure`, and `z_occupancy`.
@@ -147,6 +149,7 @@ Matter_Plugin
     │   ├── Matter_Plugin_Bridge_Sensor_Air_Quality
     │   └── Matter_Plugin_Virt_Sensor_Air_Quality
     └── Matter_Plugin_Sensor_GenericSwitch_Btn
+        └── Matter_Plugin_Virt_Sensor_GenericSwitch_Btn
 
 Matter_Plugin_Virt_HVAC_Option : Matter_Plugin_OnOff
 ```

docs/Matter.md

@@ -357,6 +357,7 @@ Contact|`v_contact`|`0`/`1` contact state
 Occupancy|`v_occupancy`|`0`/`1` occupancy state
 Rain|`v_rain`|`0`/`1` rain state
 Waterleak|`v_waterleak`|`0`/`1` water-leak state
+Presses|`v_gensw`|Completed Generic Switch gesture: integer `1..5`; each command emits one gesture
 AirQuality|`v_airquality`|Air-quality enum: `0` Unknown, `1` Good, `4` Poor
 CO2|`v_airquality`|Carbon-dioxide concentration
 NO2|`v_airquality`|Nitrogen-dioxide concentration
@@ -368,6 +369,24 @@ TVOC|`v_airquality`|Total volatile organic compounds concentration
 
 Keep in mind that many values are in the range `0..254` because `255` is an invalid value (this comes from Zigbee).
 
+### Virtual Generic Switch/Button
+
+The `v_gensw` endpoint represents a remote button or completed button gesture. Add a virtual **Generic Switch/Button** endpoint in **Configuration → Configure Matter**, assign it a name, and send a gesture with `MtrUpdate`:
+
+```text
+MtrUpdate {"Name":"Wall button 1","Presses":1}
+```
+
+`Presses` must be an integer from `1` through `5`. The value selects the gesture count: `1` is a single press, `2` is a double press, and so on. Repeated commands are separate gestures. The endpoint returns to the released state after each gesture. Omitting `Presses` queries the endpoint state; invalid values return an error and publish no events. Long presses are not supported.
+
+A remote Tasmota device can send the command directly with `WebSend`, without an MQTT broker:
+
+```text
+ON Button1#State=10 DO WebSend [192.0.2.1] MtrUpdate {"Name":"Wall button 1","Presses":1} ENDON
+```
+
+Use the bridge's normal WebSend authentication syntax when a web password is configured. These commands are not idempotent: automatic retries can repeat the button action.
+
 ### Full Example
 
 The example below implements a simple bridge between Matter and IR (Infra Red). This allows to trigger On/Off commands from the Matter controller, that are translated to On/Off infra-red commands (we use the simple NEC protocol in the example, like used in Magic Home LED strips). You can also received On/Off infra-red commands that are reflected in the virtual light. In reality, you will probably use only Matter-to-IR or IR-to-Matter direction, but it doesn't harm to have both directions implemented.