Matter Internals~

#define USE_MATTER_DEVICE

Below are implementation notes to understand and extend Matter.

Plugin System~

The plugin system is designed to have different implementations for different types of devices or sensors. Each Matter endpoint is managed by an instance of a Plugin class.

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

We provide currently the following classes:

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

Virtual: the endpoint is not connected to any device by Tasmota, and can be driven by Berry code to drive any hardware device or simulate a hardware device.

Plugins Hierarchy:

Matter_Plugin
+--- Matter_Plugin_Root
+--- Matter_Plugin_Aggregator
+--+ Matter_Plugin_Device
   |--+ Matter_Plugin_Light0
   |  +--+ Matter_Plugin_Light1
   |  |  +--- Matter_Plugin_Light2
   |  |  +--- Matter_Plugin_Light3
   |  +--- Matter_Plugin_OnOff
   +--+ Matter_Plugin_Fan
   +--+ Matter_Plugin_Shutter
   |  +--- Matter_Plugin_ShutterTilt
   +--+ Matter_Plugin_Sensor
   |  +--+ Matter_Plugin_Sensor_Humidity
   |     +--- Matter_Plugin_Zigbee_Humidity
   |  +--+ Matter_Plugin_Sensor_Temperature
   |     +--- Matter_Plugin_Zigbee_Temperature
   |  +--+ Matter_Plugin_Sensor_Pressure
   |     +--- Matter_Plugin_Zigbee_Pressure
   |  +--- Matter_Plugin_Sensor_Illuminance
   |  +--- Matter_Plugin_Sensor_Flow
   +--+ Matter_Plugin_Sensor_Boolean
   |  +--- Matter_Plugin_Sensor_Contact
   |  +--- Matter_Plugin_Sensor_Occupancy
   |  +--- Matter_Plugin_Sensor_OnOff
   |  +--- Matter_Plugin_Sensor_Rain
   |  +--- Matter_Plugin_Sensor_WaterLeak
   +--- Matter_Plugin_Sensor_AirQuality
   +--- Matter_Plugin_Sensor_GenericSwitch_Btn

All endpoints that support Bridge, Virtual and Zigbee have Matter_Plugin_Bridge_<name>, Matter_Plugin_Virt_<name> and Matter_Plugin_Zigbee_<name> subclasses.

Plugin superclass~

All plugins inherit from the Matter_Plugin superclass.

Note: for solidification to succeed, you need to declare class Matter_Plugin end fake class in the same Berry file. The actual class will be used in solidified code.

Core classes~

class matter.Device used as monad matter_device~

matter_device is a monad of matter.Device automatically created at boot. It checks if Matter si enabled (SetOption151 1) and instantiates all sub-systems.

Device attributes~

The following are saved as Matter device configuration

When commissioning is open, here are the variables used:

For default commissioning, the following values are used (and can be changed via UI):

Device methods~

Incoming messages handing

UDPPacket_sent~

mDNS (DNS-SD)~

Class UDPServer~

This class creates a monad (singleton) in charge of receiving and sending all UDP packets. Packets to sent are generally put in a queue, and are re-sent with exponential backoff until they are acknowledged by the receiver (as part of Matter over UDP) or after the maximum of retries have been made.

MessageHandler~

matter_device.message_handler is a monad of matter.MessageHandler

Dispatches incoming messages and sends outgoing messages

General methods:

TLV~

Implements the TLV encoding and decoding as defined in Appendix A of the Matter specification. TLV stands for Tag-length-value encoding. It is a way to encode tagged values and structures in a binary compact format. Most Matter messages are encoded in TLV.

Parse and print: m = matter.TLV.parse(b) print(m)

TLV Types~

Creating TLV~

Simple value:

matter.TLV.create_TLV(type, value)

Example:

matter.TLV.create_TLV(matter.TLV.UTF1, "Hello world")
matter.TLV.create_TLV(matter.TLV.BOOL, true)
matter.TLV.create_TLV(matter.TLV.NULL, nil)
matter.TLV.create_TLV(matter.TLV.FLOAT, 3.5)
matter.TLV.create_TLV(matter.TLV.I2, -345)
matter.TLV.create_TLV(matter.TLV.U8, bytes("DEADBEEFDEADBEEF"))

Subscriptions~

When a subscription is issued by an initiator, we create an instance of matter.IM_Subscription which holds:

• the CASE session on which the subscription was issued. If the session is closed, the subscription dies. Subscriptions are not persisted and stop if reboot
• subscription_id (int) used to tell the initiator which subscription it was
• path_list list of matter.Path instances recording all the attributes subscribed to. They can include wildcards
• min_interval and max_interval (in seconds): Tasmota waits at least min_interval before sending a new value, and sends a message before max_interval (usually heartbeats to signal that the subscription is still alive). Generally changes to attributes are dispatched immediately.
• fabric_filtered: not used for now

Below are internal arguments:

• not_before: the actual timestamp that we should wait before sending updates, as to respect min_interval
• expiration: the maximum timestamp we can wait before sending a heartbeat. Both are updated after we sent a new value
• wait_status: signals that we sent everything and we wait for the final StatusReport to resume sending further updates
• is_keep_alive (bool) did the last message was a keep-alive, if so we just expect a Ack and no StatusReport
• updates: list of concrete attributes that have values changed since last update. They don't contain the new value, we will actually probe each attribute value when sending the update

IM_Subscription_Shop~

This class (monad) contains the global list of all active subscriptions. Method|Description :----|:--- init(im)|Instantiate the monad with the global IM monad new_subscription(session, req)|Take a session and a SubscribeRequestMessage, parse the message and create a matter.IM_Subscription instance.
Returns the matter.IM_Subscription() instance. Also allocates a new subscription id.

What happens when an attribute is updated~

Subscriptions are triggered by the value of an attribute changing. They can originate from an explicit WRITE Matter command from an initiator or another device, of be the consequence of a Matter command (like switching a light ON). The can also originated from independent source, like an action at Tasmota level (using Tasmota Power command), or Tasmota detecting that a sensor value has changed after periodical polling.

Note: default plugins for Lights actually probe Tasmota light status every second, and report any difference between the last known change (also called shadow value) and the current status. We realized that it was more consistent and reliable than trying to create rules for every event.

When an attribute's value changed, you need to call the plugin's method
self.attribute_updated(<endpoint_id>, <cluster_id>, <attribute_id> [, <fabric_specific>])

<fabric_specific> (bool) is optional and currently ignored and reserved for future use.

The endpoint_id argument is optional. If the endpoint is unknown, the message is broadcast to all endpoints that support reading this attributes:
self.attribute_updated(nil, <cluster_id>, <attribute_id>)

More generally, you can use the global method to signal an attribute change from any code:
matter_device.attribute_updated(nil, <cluster_id>, <attribute_id>)

Note: internally this method creates a matter.Path instance and calls
matter_device.message_handler.im.subs_shop.attribute_updated_ctx(ctx, fabric_specific)
which in turns calls attribute_updated_ctx(ctx, fabric_specific) on every active subscription.

Calls to attribute_updated_ctx() are first check whether the attribute matches the filtering criteria's (that may include wildcards). If they match, the attribute is candidate to be added to the list. We then call _add_attribute_unique_path() to check if the attribute is not already in the list, and if not add it to the list of future updates. It's possible that during the min_interval time, an attribute may change value multiple times; yet we publish a single value (the last one).

Updates~

TheSubscription_Shop monad checks every 250ms if there are updates ready to be sent via every_250ms().

It does a first scan across all active subscriptions if updates can be sent out:

• subscription is not in wait_status (i.e. not waiting for a previous exchange to complete)
• subscription has a non-empty list of updates
• subscription has reached the not_before timestamp (so as to not sent too frequent updates)

If so:

• im.send_subscribe_update(sub) is called
• the subscription list of updates is cleared via sub.clear_before_arm()

Once all updates are sent, the subscription are scanned again to see if any heartbeat needs to be sent:

• subscription is not in wait_status
• subscription has reached expiration timestamp If so:
• im.send_subscribe_update(sub) is called
• the subcription list of updates is cleared via sub.clear_before_arm() XXX TODO

Extending Matter~

All Matter support code is located in berry_matter as a lib, which avoids polluting the main directory of drivers. Berry allows to develop much faster compared to C++, and performance is mostly not an issue with Matter.

The Berry code is located in the embedded directory. Then the code is compiled into bytecode and the bytecode is stored in Flash. This avoids consuming RAM which is a very previous resource on ESP32. To solidify, you just need to run ./solidify_all.be in berry_matter. But before you need to have a local version of Berry: in berry directory, just do make. For windows users, compiling Berry can be challenging so a pre-compiled berry.exe is provided.

Creating a new endpoint type (class)~

Ideally select the best super class and inherit from it. Most new type will derive from Matter_Plugin_Device.

Below are the class attributes that need to be defined or are inherited from their superclass