Skip to content

Commit 3d356e9

Browse files
s-hadingers-hadinger
authored
Update Matter doc
1 parent ce188d1 commit 3d356e9

2 files changed

Lines changed: 168 additions & 76 deletions

File tree

‎docs/Matter-Internals.md‎

Lines changed: 124 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -18,35 +18,55 @@ The plugin system is designed to have different implementations for different ty
1818

1919
Endpoint `root` (0) is managed by the `matter.Plugin_Root` class because of its specific behavior.
2020

21-
We provide currently the following classes:
22-
23-
| Plug-in class | Description | Bridge | Virtual |
24-
| ----------------------- | ------------------------------------------------- |--------|---------|
25-
| Plugin_Device | Generic device (abstract) | | |
26-
| Plugin_Root | Root node (type 0x0016) | | |
27-
| Plugin_Aggregator | Aggregator for Bridge mode (type 0x000E) | | |
28-
| Plugin_OnOff | Simple On/Off Plug (type 0x010A) | x | x |
29-
| Plugin_Light0 | Light with 0 channel (OnOff) (type 0x0100) | x | x |
30-
| Plugin_Light1 | Light with 1 channels (Dimmer) (type 0x0101) | x | x |
31-
| Plugin_Light2 | Light with 2 channels (CT) (type 0x010C) | x | x |
32-
| Plugin_Light3 | Light with 3 channels (RGB) (type 0x010D) | x | x |
33-
| Plugin_Fan | Fan (type 0x002B) Virtual only | | x |
34-
| Plugin_Sensor | Generic Sensor class (abstract) | | |
35-
| Plugin_Sensor_Temp | Temperature Sensor (type 0x0302) | x | x |
36-
| Plugin_Sensor_Pressure | Pressure Sensor (type 0x0305) | x | x |
37-
| Plugin_Sensor_Illuminance | Light/Illuminance Sensor (type 0x0106) | x | x |
38-
| Plugin_Sensor_Humidity | Humidity Sensor (type 0x0307) | x | x |
39-
| Plugin_Sensor_Flow | Flow Sensor (type 0x0306) | x | x |
40-
| Plugin_Sensor_Boolean | Generic Booleand Sensor class (abstract) | | |
41-
| Plugin_Sensor_Occupancy | Occupancy Sensor linked to a swithch (type 0x0107)| x | x |
42-
| Plugin_Sensor_Contact | Contact Sensor (type 0x0015) | x | x |
43-
| Plugin_Sensor_OnOff | OnOff Sensor (type 0x0850) | | |
44-
| Plugin_Sensor_Rain | Rain Sensor (type 0x0044) | x | x |
45-
| Plugin_Sensor_Waterleak | Water Leak Sensor (type 0x0043) | x | x |
46-
| Plugin_Sensor_Air_Quality | Air Quality Sensor (co2, pm...) (type 0x002C) | x | x |
47-
| Plugin_Sensor_GenericSwitch_Btn | Generic switch for Buttons (type 0x000F) | | |
48-
| Plugin_Shutter | Shutter (type 0x0202) | | |
49-
| Plugin_Shutter_Tilt | Shutter with Tilt control (type 0x0202) | | |
21+
The registered plug-in types below are current for the Matter 1.6.1 implementation. The `TYPE` value is the value saved in an endpoint configuration. `Matter_Plugin_Device`, `Matter_Plugin_Sensor`, and `Matter_Plugin_Sensor_Boolean` are base classes, not selectable endpoint types.
22+
23+
| Plug-in class | `TYPE` | Description / Matter device type |
24+
| --- | --- | --- |
25+
| `Matter_Plugin_Root` | `root` | Root node (`0x0016`, rev. 5) |
26+
| `Matter_Plugin_Aggregator` | `aggregator` | Aggregator (`0x000E`, rev. 1), used by a bridge |
27+
| `Matter_Plugin_Light0` | `light0` | On/Off Light (`0x0100`) |
28+
| `Matter_Plugin_Light1` | `light1` | Dimmable Light (`0x0101`) |
29+
| `Matter_Plugin_Light2` | `light2` | Color Temperature Light (`0x010C`) |
30+
| `Matter_Plugin_Light3` | `light3` | Extended Color Light (`0x010D`) |
31+
| `Matter_Plugin_OnOff` | `relay` | On/Off Plug-in Unit (`0x010A`) |
32+
| `Matter_Plugin_OnOff_Power` | `relay_power` | On/Off Plug-in Unit plus Electrical Sensor (`0x010A` + `0x0510`) |
33+
| `Matter_Plugin_Fan` | `fan` | Fan (`0x002B`) |
34+
| `Matter_Plugin_GarageDoor` | `garage` | Closure / garage door (`0x0230`, rev. 1) |
35+
| `Matter_Plugin_Shutter` | `shutter` | Window Covering (`0x0202`) |
36+
| `Matter_Plugin_ShutterTilt` | `shutter+tilt` | Window Covering with tilt (`0x0202`) |
37+
| `Matter_Plugin_Thermostat` | `thermostat` | Generic thermostat model (`0x0301`); `v_hvac` provides the current usable integration |
38+
| `Matter_Plugin_Sensor_Temp` | `temperature` | Temperature Sensor (`0x0302`) |
39+
| `Matter_Plugin_Sensor_Pressure` | `pressure` | Pressure Sensor (`0x0305`) |
40+
| `Matter_Plugin_Sensor_Illuminance` | `illuminance` | Light Sensor (`0x0106`) |
41+
| `Matter_Plugin_Sensor_Humidity` | `humidity` | Humidity Sensor (`0x0307`) |
42+
| `Matter_Plugin_Sensor_Flow` | `flow` | Flow Sensor (`0x0306`) |
43+
| `Matter_Plugin_Sensor_Soil` | `soil` | Soil Sensor (`0x0045`, rev. 1) |
44+
| `Matter_Plugin_Sensor_Contact` | `contact` | Contact Sensor (`0x0015`) |
45+
| `Matter_Plugin_Sensor_Occupancy` | `occupancy` | Occupancy Sensor (`0x0107`) |
46+
| `Matter_Plugin_Sensor_OnOff` | `onoff` | On/Off Sensor (`0x0850`) |
47+
| `Matter_Plugin_Sensor_Rain` | `rain` | Rain Sensor (`0x0044`) |
48+
| `Matter_Plugin_Sensor_Waterleak` | `waterleak` | Water Leak Detector (`0x0043`) |
49+
| `Matter_Plugin_Sensor_Air_Quality` | `airquality` | Air Quality Sensor (`0x002C`), with optional CO₂, NO₂, PM, and TVOC measurements |
50+
| `Matter_Plugin_Sensor_GenericSwitch_Btn` | `gensw_btn` | Generic Switch (`0x000F`) |
51+
52+
HTTP bridge plug-ins have `http_` types and extend the corresponding local implementation:
53+
54+
| Classes | `TYPE` values |
55+
| --- | --- |
56+
| Lights and relays | `http_light0`, `http_light1`, `http_light2`, `http_light3`, `http_relay`, `http_relay_power` |
57+
| Sensors | `http_temperature`, `http_pressure`, `http_illuminance`, `http_humidity`, `http_flow`, `http_soil`, `http_contact`, `http_occupancy`, `http_rain`, `http_waterleak`, `http_airquality` |
58+
59+
Each HTTP bridge type also has a dynamically registered MQTT alias: replace `http_` with `mqtt_` (for example, `http_light1` → `mqtt_light1`). MQTT bridge plug-ins reuse the HTTP bridge class; they receive commands and state updates through MQTT rather than HTTP polling.
60+
61+
Virtual plug-ins have `v_` types and can be updated with [`MtrUpdate`](Matter.md#mtrupdate-command):
62+
63+
| Classes | `TYPE` values |
64+
| --- | --- |
65+
| Lights and relays | `v_light0`, `v_light1`, `v_light2`, `v_light3`, `v_relay`, `v_relay_power` |
66+
| Appliances | `v_fan`, `v_garage`, `v_hvac`, `v_hvac_option` |
67+
| Sensors | `v_temperature`, `v_pressure`, `v_illuminance`, `v_humidity`, `v_flow`, `v_soil`, `v_contact`, `v_occupancy`, `v_rain`, `v_waterleak`, `v_airquality` |
68+
69+
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`.
5070

5171
**Bridge**: Tasmota is able to act as a Bridge to other Tasmota devices (ESP8266 or ESP32) and drive them via the HTTP API.
5272

@@ -55,37 +75,83 @@ We provide currently the following classes:
5575
Plugins Hierarchy:
5676
```
5777
Matter_Plugin
58-
+--- Matter_Plugin_Root
59-
+--- Matter_Plugin_Aggregator
60-
+--+ Matter_Plugin_Device
61-
|--+ Matter_Plugin_Light0
62-
| +--+ Matter_Plugin_Light1
63-
| | +--- Matter_Plugin_Light2
64-
| | +--- Matter_Plugin_Light3
65-
| +--- Matter_Plugin_OnOff
66-
+--+ Matter_Plugin_Fan
67-
+--+ Matter_Plugin_Shutter
68-
| +--- Matter_Plugin_ShutterTilt
69-
+--+ Matter_Plugin_Sensor
70-
| +--+ Matter_Plugin_Sensor_Humidity
71-
| +--- Matter_Plugin_Zigbee_Humidity
72-
| +--+ Matter_Plugin_Sensor_Temperature
73-
| +--- Matter_Plugin_Zigbee_Temperature
74-
| +--+ Matter_Plugin_Sensor_Pressure
75-
| +--- Matter_Plugin_Zigbee_Pressure
76-
| +--- Matter_Plugin_Sensor_Illuminance
77-
| +--- Matter_Plugin_Sensor_Flow
78-
+--+ Matter_Plugin_Sensor_Boolean
79-
| +--- Matter_Plugin_Sensor_Contact
80-
| +--- Matter_Plugin_Sensor_Occupancy
81-
| +--- Matter_Plugin_Sensor_OnOff
82-
| +--- Matter_Plugin_Sensor_Rain
83-
| +--- Matter_Plugin_Sensor_WaterLeak
84-
+--- Matter_Plugin_Sensor_AirQuality
85-
+--- Matter_Plugin_Sensor_GenericSwitch_Btn
78+
├── Matter_Plugin_Root
79+
├── Matter_Plugin_Aggregator
80+
└── Matter_Plugin_Device
81+
├── Matter_Plugin_Light0
82+
│ ├── Matter_Plugin_Light1
83+
│ │ ├── Matter_Plugin_Light2
84+
│ │ │ ├── Matter_Plugin_Bridge_Light2
85+
│ │ │ ├── Matter_Plugin_Virt_Light2
86+
│ │ │ └── Matter_Plugin_Zigbee_Light2
87+
│ │ ├── Matter_Plugin_Light3
88+
│ │ │ ├── Matter_Plugin_Bridge_Light3
89+
│ │ │ └── Matter_Plugin_Virt_Light3
90+
│ │ ├── Matter_Plugin_Bridge_Light1
91+
│ │ └── Matter_Plugin_Virt_Light1
92+
│ ├── Matter_Plugin_OnOff
93+
│ │ ├── Matter_Plugin_OnOff_Power
94+
│ │ │ ├── Matter_Plugin_Bridge_OnOff_Power
95+
│ │ │ └── Matter_Plugin_Virt_OnOff_Power
96+
│ │ └── Matter_Plugin_Virt_OnOff
97+
│ ├── Matter_Plugin_Bridge_Light0
98+
│ │ └── Matter_Plugin_Bridge_OnOff
99+
│ ├── Matter_Plugin_Virt_Light0
100+
│ └── Matter_Plugin_Zigbee_Light0
101+
├── Matter_Plugin_Fan
102+
│ └── Matter_Plugin_Virt_Fan
103+
├── Matter_Plugin_GarageDoor
104+
│ └── Matter_Plugin_Virt_GarageDoor
105+
├── Matter_Plugin_Shutter
106+
│ └── Matter_Plugin_ShutterTilt
107+
├── Matter_Plugin_Thermostat
108+
│ └── Matter_Plugin_Virt_HVAC
109+
├── Matter_Plugin_Sensor
110+
│ ├── Matter_Plugin_Sensor_Temp
111+
│ │ ├── Matter_Plugin_Bridge_Sensor_Temp
112+
│ │ ├── Matter_Plugin_Virt_Sensor_Temp
113+
│ │ └── Matter_Plugin_Zigbee_Temperature
114+
│ ├── Matter_Plugin_Sensor_Humidity
115+
│ │ ├── Matter_Plugin_Bridge_Sensor_Humidity
116+
│ │ ├── Matter_Plugin_Virt_Sensor_Humidity
117+
│ │ └── Matter_Plugin_Zigbee_Humidity
118+
│ ├── Matter_Plugin_Sensor_Pressure
119+
│ │ ├── Matter_Plugin_Bridge_Sensor_Pressure
120+
│ │ ├── Matter_Plugin_Virt_Sensor_Pressure
121+
│ │ └── Matter_Plugin_Zigbee_Pressure
122+
│ ├── Matter_Plugin_Sensor_Illuminance
123+
│ │ ├── Matter_Plugin_Bridge_Sensor_Illuminance
124+
│ │ └── Matter_Plugin_Virt_Sensor_Illuminance
125+
│ ├── Matter_Plugin_Sensor_Flow
126+
│ │ ├── Matter_Plugin_Bridge_Sensor_Flow
127+
│ │ └── Matter_Plugin_Virt_Sensor_Flow
128+
│ └── Matter_Plugin_Sensor_Soil
129+
│ ├── Matter_Plugin_Bridge_Sensor_Soil
130+
│ └── Matter_Plugin_Virt_Sensor_Soil
131+
├── Matter_Plugin_Sensor_Boolean
132+
│ ├── Matter_Plugin_Sensor_Contact
133+
│ │ ├── Matter_Plugin_Bridge_Sensor_Contact
134+
│ │ └── Matter_Plugin_Virt_Sensor_Contact
135+
│ ├── Matter_Plugin_Sensor_Occupancy
136+
│ │ ├── Matter_Plugin_Bridge_Sensor_Occupancy
137+
│ │ ├── Matter_Plugin_Virt_Sensor_Occupancy
138+
│ │ └── Matter_Plugin_Zigbee_Occupancy
139+
│ ├── Matter_Plugin_Sensor_OnOff
140+
│ ├── Matter_Plugin_Sensor_Rain
141+
│ │ ├── Matter_Plugin_Bridge_Sensor_Rain
142+
│ │ └── Matter_Plugin_Virt_Sensor_Rain
143+
│ └── Matter_Plugin_Sensor_Waterleak
144+
│ ├── Matter_Plugin_Bridge_Sensor_Waterleak
145+
│ └── Matter_Plugin_Virt_Sensor_Waterleak
146+
├── Matter_Plugin_Sensor_Air_Quality
147+
│ ├── Matter_Plugin_Bridge_Sensor_Air_Quality
148+
│ └── Matter_Plugin_Virt_Sensor_Air_Quality
149+
└── Matter_Plugin_Sensor_GenericSwitch_Btn
150+
151+
Matter_Plugin_Virt_HVAC_Option : Matter_Plugin_OnOff
86152
```
87153

88-
All endpoints that support `Bridge`, `Virtual` and `Zigbee` have `Matter_Plugin_Bridge_<name>`, `Matter_Plugin_Virt_<name>` and `Matter_Plugin_Zigbee_<name>` subclasses.
154+
Only the variants shown in the tree exist. In particular, there are no HTTP/MQTT or Zigbee bridge variants for fans, shutters, garage doors, or thermostats.
89155

90156

91157
## Plugin superclass

‎docs/Matter.md‎

Lines changed: 44 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -318,26 +318,52 @@ MtrUpdate {"Name":"Light0", "Power":1}
318318

319319
If the endpoint is valid, the returned payload contains the entire state of the endpoint, similar to `MtrInfo` command.
320320

321-
List of attributes supported by endpoints:
321+
List of attributes supported by virtual endpoints:
322322

323-
Attribute|Type of endpoint|Description
323+
`MtrUpdate` only updates an endpoint whose type is virtual (`v_*`). Attribute names are case-insensitive, but the names below are returned in their canonical form by `MtrInfo` and `MtrUpdate`. A virtual endpoint accepts the attributes inherited from its base plug-in; for example, `v_light3` accepts `Power`, `Bri`, `Hue`, and `Sat`.
324+
325+
Attribute|Virtual endpoint type|Description
324326
:---|:---|:---
325-
Power|Relay, all Lights|`0`/`1` report Power change
326-
Bri|Lights|`0..254` report Brightness change
327-
CT|Light 2|`153..500` White Temperature in mireds
328-
Hue|Ligth 3|`0..254` Hue converted from 0..360 to 0..254
329-
Sat|Light 3|`0..254` Saturation
330-
Contact|Contact|`0`/`1` state of the Contact sensor
331-
Occupancy|Occupancy|`0`/`1` state of the Occupancy sensor
332-
Humidity|Humidity|`0..10000` Humidity in 1/100th of percentage
333-
Illuminance|Illuminance|`0..65534` Illuminance with formula `log10(val + 1) * 10000`
334-
Pressure|Pressure|Pressure in `hPa`
335-
Temperature|Temperature|`-32767..32767` Temperature in 1/100th of °C
336-
Rain|Rain|`0`/`1` change rain sensor state°C
337-
Waterleak|Waterleak|`0`/`1` change rain sensor state
338-
FanMode|Fan|`0`: Off<br>`1`: Low (33%)<br>`2`: Med (66%)<br>`3`: High (100%)
339-
FanSpeed|Fan|`0..100` Fan speed in percentage
340-
FanSpeed255|Fan|`0..255` Fan speed in a range more suitable for Rules and PWM
327+
Power|`v_relay`, `v_relay_power`, `v_light0`, `v_light1`, `v_light2`, `v_light3`, `v_hvac_option`|`0`/`1` On/Off state
328+
Bri|`v_light1`, `v_light2`, `v_light3`|`0..254` brightness
329+
CT|`v_light2`|`153..500` colour temperature in mireds (or `200..380` when Alexa emulation is enabled)
330+
Hue|`v_light3`|`0..254` hue, mapped to Tasmota's `0..360` range
331+
Sat|`v_light3`|`0..254` saturation
332+
Voltage|`v_relay_power`|RMS voltage in volts
333+
Current|`v_relay_power`|RMS current in amperes
334+
ActivePower|`v_relay_power`|Active power in watts; this name avoids ambiguity with the `Power` On/Off state
335+
ApparentPower|`v_relay_power`|Apparent power in VA
336+
ReactivePower|`v_relay_power`|Reactive power in var
337+
Factor|`v_relay_power`|Power factor, normally `0..1`
338+
Frequency|`v_relay_power`|Frequency in Hz
339+
FanMode|`v_fan`|`0`: Off; `1`: Low; `2`: Medium; `3`: High
340+
FanSpeed|`v_fan`|`0..100` fan speed in percent
341+
FanSpeed255|`v_fan`|`0..255` fan speed, convenient for Rules and PWM
342+
ShutterPos|`v_garage`|Current position: `0` closed to `100` open
343+
ShutterTarget|`v_garage`|Target position: `0` closed to `100` open
344+
ShutterDirection|`v_garage`|`-1` closing, `0` stopped, `1` opening
345+
SystemMode|`v_hvac`|Thermostat mode: `0` Off, `1` Auto, `3` Cool, `4` Heat, `7` Fan only, `8` Dry
346+
Temp|`v_hvac`|Set both cooling and heating setpoints, in hundredths of °C
347+
CoolSetpoint|`v_hvac`|Cooling setpoint, in hundredths of °C
348+
HeatSetpoint|`v_hvac`|Heating setpoint, in hundredths of °C
349+
LocalTemperature|`v_hvac`|Measured local temperature, in hundredths of °C
350+
Temperature|`v_temperature`|Temperature in Tasmota's configured unit; Matter reports hundredths of °C
351+
Humidity|`v_humidity`|Relative humidity in hundredths of percent (`0..10000`)
352+
Pressure|`v_pressure`|Pressure in hPa
353+
Illuminance|`v_illuminance`|Raw illuminance in lux; Matter reports `log10(value + 1) * 10000`
354+
Flow|`v_flow`|Flow in m³/h; Matter reports the value ×10
355+
Moisture|`v_soil`|Soil moisture in percent (`0..100`)
356+
Contact|`v_contact`|`0`/`1` contact state
357+
Occupancy|`v_occupancy`|`0`/`1` occupancy state
358+
Rain|`v_rain`|`0`/`1` rain state
359+
Waterleak|`v_waterleak`|`0`/`1` water-leak state
360+
AirQuality|`v_airquality`|Air-quality enum: `0` Unknown, `1` Good, `4` Poor
361+
CO2|`v_airquality`|Carbon-dioxide concentration
362+
NO2|`v_airquality`|Nitrogen-dioxide concentration
363+
PM1|`v_airquality`|PM1 concentration
364+
PM2.5|`v_airquality`|PM2.5 concentration
365+
PM10|`v_airquality`|PM10 concentration
366+
TVOC|`v_airquality`|Total volatile organic compounds concentration
341367

342368

343369
Keep in mind that many values are in the range `0..254` because `255` is an invalid value (this comes from Zigbee).

0 commit comments

Comments
 (0)