Matter integration

[harrykausl]

I don't know, but I prefer to use the basic protocol and this is matter for tadoX. My only question was, if it could be possible to integrate the home assistant matter solution in domoticz? Somebody did this also some times ago for the mqtt auto-explore I think.

Another advantage of matter is, that it works in homekit and you don't have to use homebridge for this devices. It's not sure, that homebridge-edomatics plugin will work with the next homebridge 2.0 version.

[gizmocuz]

Maybe write a plugin for matterbridge:

https://github.com/Luligu/matterbridge

[solarboy]

Just a heads up, the Ikea Zigbee bulbs are on offer and vanishing quickly to be replaced by a Matter only eco-system. Already at my local branch there are only basic WW bulbs available (2 types). A real shame as Ikea was a great source of Zigbee stuff. Would love to see some kind of USB border router and matter2mqtt docker become established.

[Varazir]

Just a heads up, the Ikea Zigbee bulbs are on offer and vanishing quickly to be replaced by a Matter only eco-system. Already at my local branch there are only basic WW bulbs available (2 types). A real shame as Ikea was a great source of Zigbee stuff. Would love to see some kind of USB border router and matter2mqtt docker become established.

I read some posts that you can switch between matter and Zigbee on the new bulbs.
But there are no oblivious documentation on IKEAs web page.

[solarboy]

Just a heads up, the Ikea Zigbee bulbs are on offer and vanishing quickly to be replaced by a Matter only eco-system. Already at my local branch there are only basic WW bulbs available (2 types). A real shame as Ikea was a great source of Zigbee stuff. Would love to see some kind of USB border router and matter2mqtt docker become established.

I read some posts that you can switch between matter and Zigbee on the new bulbs.
But there are no oblivious documentation on IKEAs web page.

I've also read this, From what I can gather, you double the amount of switch on/switch off sequences to pair via zigbee.

[peterchef]

This article about new ikea devices may be of interest ...

https://matter-smarthome.de/en/products ... nd-zigbee/

[Thorgal789]

“It allows us and other manufacturers to support Zigbee, Thread, and Bluetooth – all at the same time, on one chip, with one antenna.”

Lol, and they are thinking with that users will forget their zigbee stuff to go to Matter one ?
I call that a "step backwards".

[fleinze]

I made a simple proof of concept plugin for matter integration:
https://github.com/fleinze/Mattericz

The plugin requires a running python-matter-server (https://github.com/matter-js/python-matter-server). The same server is used by Home Assistant.

It's quite simple and only supports switches, temperature and humidity at the moment. Commissioning of new nodes is also not supported, this needs to be done in Home Assistant or via the matter server website.

I would love to hear some feedback from you and would like to encourage forking and expanding the plugin.

[waltervl]

I made a simple proof of concept plugin for matter integration:
https://github.com/fleinze/Mattericz

The plugin requires a running python-matter-server (https://github.com/matter-js/python-matter-server). The same server is used by Home Assistant.

It's quite simple and only supports switches, temperature and humidity at the moment. Commissioning of new nodes is also not supported, this needs to be done in Home Assistant or via the matter server website.

I would love to hear some feedback from you and would like to encourage forking and expanding the plugin.

Interesting! When that matter server already has some kind of web UI for commisioning and control etc you can simply embed it into Domoticz with a custom menu: https://wiki.domoticz.com/Custom_menu

[fleinze]

Interesting! When that matter server already has some kind of web UI for commisioning and control etc you can simply embed it into Domoticz with a custom menu: https://wiki.domoticz.com/Custom_menu

The matter-server actually has a WebUI. Thanks for the tip, I think I will do this instead of building a whole webinterface for commissioning.

[Fogelholk]

I made a simple proof of concept plugin for matter integration:
https://github.com/fleinze/Mattericz

The plugin requires a running python-matter-server (https://github.com/matter-js/python-matter-server). The same server is used by Home Assistant.

It's quite simple and only supports switches, temperature and humidity at the moment. Commissioning of new nodes is also not supported, this needs to be done in Home Assistant or via the matter server website.

I would love to hear some feedback from you and would like to encourage forking and expanding the plugin.

Hi, I recently got some Matter/Thread devices and I really like Domoticz and would like to keep using it for my automation needs.

Saw this plugin and tried to connect it to a running instance of Home Assistants Matter Server just to see what would happen, looks like it is not working and I fully get that it's in very early stage and possibly even an unsupported setup.

Anyways, this is the output I got in the Domoticz logs (totalling 2600 lines, so just adding a snippet of them):

Code: Select all

2026-04-10 20:10:42.145  Matter: TCP connected to hass:5580 - sending WS upgrade ...
2026-04-10 20:10:42.145  Matter: Disconnected from Matter server.
2026-04-10 20:10:42.195  Matter: WebSocket handshake complete.
2026-04-10 20:10:42.195  Matter: [Matter] Connected – sending start_listening
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) 64 bit WebSocket messages lengths not supported.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (11) encountered.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (15) encountered.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (3) encountered.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (4) encountered.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (12) encountered.
2026-04-10 20:10:42.246  Error: (ProcessWholeMessage) Unknown Operation Code (0) encountered.
.....
2026-04-10 20:10:42.257  Error: (ProcessWholeMessage) Unknown Operation Code (0) encountered.
2026-04-10 20:10:42.257  Error: (ProcessWholeMessage) Unknown Operation Code (0) encountered.
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b'  "message'
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b'd": "start_listening",\n  "result": [\n   '
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b':43.790822",\n      "last_interview": "20'
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b'.790826",\n      "interview_version": 6,\n'
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b'ble": true,\n      "is_bridge": true,\n   '
2026-04-10 20:10:42.257  Error: Matter: [Matter] Binary/compressed payload received - the server is still using permessage-deflate. First bytes: b'    "0": 22,\n            "1": 1\n'
...

Don't know if anything helps with developing the plugin. So far I have the following Matter/Thread devices:
Aqara H200 hub
Aqara U200 lock
Aqara Door/Window Sensor P2

[fleinze]

I started to get the same errors as soon as I joined a third device to my matter fabric.

The problem is:
As soon as there is more data to be transmitted the python-matter-server starts to fragment messages. There is nothing on the client side to prevent this. The fragmented messages have the operation code 0.
Domoticz does not support fragmented WebSocket messages. This can not be fixed within the plugin.
I tried a variant with "protocol=None", but this crashed the whole plugin-system.

I am afraid there is currently nothing more that I can do.

[fleinze]

Ok, I think I found a solution. I have pushed a working plugin to the github repository right now. It now works with Protocol="None" instead of Protocol="WS", this means that the WebSockets-protocol is now implemented in python.
It's still a messy prototype, use with caution.

[gizmocuz]

Domoticz does not support fragmented WebSocket messages

That is not entirely true, the libwebem (backend c++) does support fragmented messages, but the Python WS implementation does/did currently not.

The root cause was exactly as you described: CPluginProtocolWS (the Protocol="WS" handler in the plugin system) did
not reassemble fragmented WebSocket messages. Continuation frames (opcode 0x00) were treated as an unknown opcode and
silently dropped, so any message the server split across multiple frames was lost.

The fix implements RFC 6455 section 5.4 fragment reassembly: the plugin system now accumulates continuation frames and
only delivers the message to the plugin once the final fragment (FIN=1) arrives, using the opcode from the first
frame. Interleaved control frames (Ping/Pong) during a fragmented sequence are handled correctly too.

A few additional issues found during review were also fixed: bounds checks on 16-bit payload length fields and masking
key parsing, a Python refcount leak on Ping/Pong frames, and stale fragment state being carried over after a
reconnect.

The fix is in hardware/plugins/PluginProtocols.cpp and is included in development builds from now on (17720). You should be
able to keep Protocol="WS" in your plugin without any workaround needed.

A test plugin has been included in the folder plugins/examples/TestWebsocketFragmentation

[fleinze]

The fix is in hardware/plugins/PluginProtocols.cpp and is included in development builds from now on (17720). You should be
able to keep Protocol="WS" in your plugin without any workaround needed.

Thanks for the fix. It works with some errors:

Code: Select all

2026-04-12 21:52:49.639  Error: mattertest: Call to function 'ProcessInbound' failed, exception details:
2026-04-12 21:52:49.639  Error: mattertest: Exception: 'UnicodeDecodeError: 'utf-8' codec can't decode byte 0xca in position 3: invalid continuation byte'.  No traceback available.

Some messages (not all!) fail because they are compressed and in line 2367 of PluginProtocols.cpp the payload is forced to be returned as unicode. The messages are later decompressed in the python plugin.
If I request uncompressed messages from python-matter-server I run into another problem: 64 bit Websocket message length, which is currently unsupported in Domoticz.

I made a small workaround that allows my plugin to run without constant errors:
https://github.com/fleinze/domoticz/com ... 03dd7761be

I think the best way forward would be for PluginProtocols.cpp to support 64 bit message length and perhaps permessage-deflate.

What do you think, gizmocuz?

[gizmocuz]

I made a small workaround that allows my plugin to run without constant errors:
https://github.com/fleinze/domoticz/com ... 03dd7761be

I think the best way forward would be for PluginProtocols.cpp to support 64 bit message length and perhaps permessage-deflate.

What do you think, gizmocuz?

Thanks for the report and the workaround. I've committed a more complete fix to the development branch (17725).

Three things were addressed:

1. 64-bit WebSocket frame lengths
The 127-length case now properly decodes the 8-byte big-endian payload length. A SIZE_MAX guard is included so it also
works correctly on 32-bit platforms.

2. RSV1 (compressed) tracking across fragmented messages
The workaround read RSV1 from each individual frame. That works for single-frame messages, but for fragmented
compressed messages only the first frame has RSV1=1 — continuation and final frames have RSV1=0, so the flag was
always false at reassembly time. The fix saves RSV1 from the first frame of a fragment sequence (mirroring how the
opcode is already saved) and restores it after the final fragment is reassembled.

3. Text frame UTF-8 decode guard
When the payload is compressed (bCompressed is true), the opcode 0x01 handler no longer attempts to force-decode the
raw bytes as a UTF-8 Unicode string. The Python plugin receives the raw bytes and can decompress them itself,
preventing the UnicodeDecodeError.

[fleinze]

Thanks for the report and the workaround. I've committed a more complete fix to the development branch (17725).

Thank you very much for the complete fix. It now works great with python-matter-server and I updated my plugin to use it.

[BartSr]

I am not a programmer so I don't understand a word of Gizmocus post but does this mean we can use matter devices in a way? If so how to manage such? Zigbee and Zwave are working fine but matter.... just a wish.

[waltervl]

I am not a programmer so I don't understand a word of Gizmocus post but does this mean we can use matter devices in a way? If so how to manage such? Zigbee and Zwave are working fine but matter.... just a wish.

That part is in fact off topic as it has to do how a python plugin communicaties with Domoticz.

You can use the plugin

https://github.com/fleinze/Mattericz

As mentioned to connect matter devices to Domoticz. See the instructions on the plugin github repository for more info.

[gizmocuz]

But in the end it would be great is it was a stand-alone application like zigbee2mqtt / zwavejs-ui that works with MQTT Auto Discovery, with it's web interface to include/exclude nodes, etc.
That way it could work with other home automation systems as well.

@fleinze
Great that communication part is working!
Do you also combine temp+hum / temp+hum+baro sensors? Energy+Power (kWh) sensors?

I hope you are using Claude code to assist you. If yes, maybe you could include the project folder/CLAUDE.md file
If not, consider moving to Clause code (not the web page) asap and follow some youtube guides about coding and review agents

Maybe also consider using type names, also easier for non developers

Domoticz.Device(Name="My Counter", Unit=1, TypeName="Counter Incremental")
Domoticz.Device(Name="MykWh", Unit=2, TypeName="kWh")

See 'Available Device Types'

https://wiki.domoticz.com/Developing_a_Python_plugin

And if possible also a docker compose setup on your main readme as it is more easier (and practical) to use docker compose
(with a local data folder instead of the home directory)

How are you c++ skills? As it might be useful to have this natively in Domoticz (also for QR code related stuff), I know someone is already looking into this (and supporting MQTT-AD), but I think it can be easily done natively as well
I will create a C++ websocket client that Domoticz hardware can easily use (currently it is only build into libwebem and python)