[matter] Initial contribution #18486

digitaldan · 2025-04-04T22:37:30Z

The Matter Binding for openHAB allows seamless integration with Matter-compatible devices.

This binding supports 2 different types of matter functionality which operate independently of each other.

Matter Client
- This allows openHAB to discover and control other Matter devices like lights, thermostats, window coverings, locks, etc...
Matter Bridge
- This allows openHAB to expose items as Matter devices to other Matter clients. This allows local control of openHAB devices from other ecosystems like Apple Home, Amazon Alexa, and Google Home.

This has been published on the market place as a 4.x binding for almost 6 months and has seen quite a bit of usage on a variety of networks, platforms and matter devices. So its relatively tested and performing well. I am personally running my home system with 20+ real matter devices (and growing), and using the matter bridge to expose around 100 devices/items to Alexa, Google and Apple for local voice control.

Other openHAB projects that will need enhancements (volunteers wanted !)

Main UI
- Add matter tags along with existing Alexa, GA and Homekit tags for items for voice control
  - See Add Matter metadata openhab-webui#3129
- Allow interaction with Mobile clients for adding new devices via bluetooth, wifi or thread (similar to menu callbacks). Not required for release (nice to have)
Mobile Clients (not required for release)
- Add iOS Functionality to add new devices via iOS Matter SDK (prototype started)
- Add Android Functionality to add new devices via Android Matter SDK
openHABIan
- Ensure updated NodeJS binaries are installed (this might be done?)
openhab-docker
- Alpine linux needs to be able to install NodeJS
  - Alpine image: Install NodeJS for Matter binding openhab-docker#454
  - Matter Binding Requirements openhab-docker#461

There are a lot of moving pieces in this binding, i have started some documentation to help explain this, as well as quite a bit of docs in the README.

A Big thank you to the matter.js team, especially Apollon77 for both developing the matter.js SDK and helping troubleshoot many, many early issues with the binding.

I realize this is going to be a pain to review, so i apologize in advance to our maintainers ;-) The goal is to have this in for the 5.0 release! So hopefully we have enough time.

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

lsiepel · 2025-04-07T18:56:59Z

I can look at the readme, thing structure and java code etc. But i'm no good at the typescript / nodejs / json stuff. Hope others are available to jointly review this.

lolodomo · 2025-04-07T19:07:43Z

Same thing for me.
@lsiepel : we can start by distributing java code ?
I let you take a look to README, I already read it in the past and it was very good in my opinion.
And I can check thing structure if you are ok.

florian-h05 · 2025-04-07T19:18:57Z

I can jump in to take a look at the TypeScript/JavaScript code 👍

digitaldan · 2025-04-07T19:42:16Z

Thanks everyone !

Couple things:

@florian-h05 , I kept the Typescript code at a minimum, as my goal was to keep as much logic as possible in Java land. The matter websocket server is basically a glorified RPC service for the controller side, using the JS equivalent of reflection to execute cluster commands dynamically. The bridge side of the websocket server is a little more complicated, but again i kept the logic there at a minimum, just thin wrappers around device types. Would appreciate your review of all of this. I know there's some cleanup i should probably be doing.

I would not spend to much time (or any) in the code-gen part, fortunately it only needs to be run if there are matter specification changes to generate new Java cluster classes. As you can imagine, creating Java classes from handlebar templates was difficult (but works shockingly well). One thing might be tweaking the templates to produce better formatted code, but the maven build runs spotless against the generated classes as part of the code-gen build task, so maybe not so important.

So the bulk of the logic is in the Java code, hopefully that makes it a bit easier. The DEVELOPMENT.md readme has some info on the structure (client, controller, bridge) , hopefully that helps too.

lsiepel · 2025-04-07T19:55:45Z

Maybe it has been asked before. Is there a specific reason that the client and bridge part are combined into one binding?
Wouldn't it make sense to move the client part to another binding similar to hueemulation, homekit etc?

jlaur

Thank you @digitaldan for this amazing binding! I will try to help out with the review as well, although with limited capacity and sadly currently no ability to try it out.

I had a very quick look at some of the code, and it already looks quite solid.

I have added a few very minor comments from first iteration through the README.

bundles/org.openhab.binding.matter/README.md

...ter/src/main/java/org/openhab/binding/matter/internal/controller/MatterControllerClient.java

...matter/src/main/java/org/openhab/binding/matter/internal/handler/MatterBaseThingHandler.java

bundles/org.openhab.binding.matter/README.md

bundles/org.openhab.binding.matter/src/main/resources/OH-INF/addon/addon.xml

digitaldan · 2025-04-07T20:49:35Z

Maybe it has been asked before. Is there a specific reason that the client and bridge part are combined into one binding?

I was thinking about this quite a bit actually. And the code is partitioned that way actually. But ultimately my reasoning was this.

The two share a lot of common code , so there would have to be 3 bindings, common, client, and bridge (hence the naming in the source directory structure)
The bridge and client need to run in the same node.js process and do share a global network service in node for shared services like MDNS (this is deep in the matter.js code). This could still be done with a shared 3rd addon (common) as the web socket server/runner is a OSGI singleton service, but now it gets more complicated.
Maybe the most persuasive argument was i wanted users to just be able to install the "Matter" binding and have all functionality available, and not have to install 2 different bindings.

Obviously i was on the fence on this one, but ultimately decided on wanting this easy for users. If there are strong feelings about this, i'm open for further discussion.

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

… upgrades matter sdk Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan · 2025-04-16T19:38:54Z

FYI, i forgot that the ConsoleCommandExtension.java file is not complete, i'm hoping to work on it a bit this weekend, but if i don't find time, i just may remove it for now.

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

jlaur

I'm flushing a few fragmented comments, sorry for that. As I'm trying to acquiant myself with the binding I'm going back and forth through different bits and adding comments along the way. I could hold them back and publish all at once, but the PR would probably be merged by then. 😄

bundles/org.openhab.binding.matter/src/main/resources/OH-INF/thing/channels.xml

.../openhab/binding/matter/internal/controller/devices/converter/ColorControlConverterTest.java

bundles/org.openhab.binding.matter/code-gen/src/app.ts

...ing.matter/src/main/java/org/openhab/binding/matter/internal/bridge/devices/ColorDevice.java

bundles/org.openhab.binding.matter/src/main/resources/OH-INF/thing/channels.xml

Refs openhab/openhab-addons#18486 --------- Also-by: Florian Hotze <dev@florianhotze.com> Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan · 2025-05-28T15:40:30Z

Thanks everyone, i think i have addressed all outstanding comments with my last PR. I would be good merging as is right now, i think its in good shape thanks to the thoughtful reviews. I will follow up this weekend with a few more PRs around TS formatting, more docs, as well as some new devices i have been holding off on adding until this is merged.

florian-h05 · 2025-05-28T15:49:16Z

Let me check the changes this evening 👍

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

florian-h05

Typescript code LGTM now, apart from the license header in the utils, I don’t know if it should be there.

bundles/org.openhab.binding.matter/matter-server/src/util/error.ts

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan · 2025-05-28T23:08:11Z

Just pushed an update to address the last comment, thanks!

lolodomo · 2025-05-29T09:12:39Z

In case an urgent merge is required, I can already confirm that all my existing comments were properly handled, thank you Dan.

lolodomo

Few questions mainly about ColorControlConverter

...va/org/openhab/binding/matter/internal/controller/devices/converter/ThermostatConverter.java

.../org/openhab/binding/matter/internal/controller/devices/converter/ColorControlConverter.java

lolodomo

Review of class MatterControllerClient

...ter/src/main/java/org/openhab/binding/matter/internal/controller/MatterControllerClient.java

lolodomo · 2025-05-29T11:34:08Z

...ter/src/main/java/org/openhab/binding/matter/internal/controller/MatterControllerClient.java

+     * @param nodeId the node ID to get the pairing codes for
+     * @return a future that completes when the pairing codes are retrieved
+     */
+    public CompletableFuture<PairingCodes> enhancedCommissioningWindow(BigInteger nodeId) {


Shouldn't you add JsonParseException as possible thrown exception ?

My idea was to add it not only in javadoc but also in method declaration.

...ter/src/main/java/org/openhab/binding/matter/internal/controller/MatterControllerClient.java

digitaldan · 2025-05-30T02:45:07Z

Thanks @lolodomo , i'll have time tomorrow afternoon PDT to address and get a commit posted asap.

lolodomo

Few minor remarks when reviewing partially the handler package

...ab.binding.matter/src/main/java/org/openhab/binding/matter/internal/handler/NodeHandler.java

...matter/src/main/java/org/openhab/binding/matter/internal/handler/MatterBaseThingHandler.java

...ab.binding.matter/src/main/java/org/openhab/binding/matter/internal/handler/NodeHandler.java

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan · 2025-05-31T19:11:44Z

Latest commit should address the latest comments, thanks!

lolodomo · 2025-06-01T07:35:21Z

.../org/openhab/binding/matter/internal/controller/devices/converter/ColorControlConverter.java

+        if (lastOnOff)
+            updateState(CHANNEL_ID_COLOR_TEMPERATURE, miredsToPercentType(lastColorTemperatureMireds));


Please add {} in a next change.

lolodomo · 2025-06-01T07:37:07Z

@jlaur : I let you the privilege to push the merge button as you are the only one to have done a full review ;)

jlaur

Thanks for this important binding and all the effort invested in this, @digitaldan. Awesome work! 👍 Let's get this merged for the next milestone, and also so the related work in other repos can progress.

lolodomo · 2025-06-01T11:07:08Z

I plan to run new tests with the official version in the coming days.

lolodomo · 2025-06-01T11:09:43Z

Dan, I was asking myself if you could list what is not yet supported by the binding? Type of devices, certain features, ...

digitaldan · 2025-06-01T15:50:36Z

Yeah, i think putting together a supported matter Device Type list would be good, i'll look into it.

lolodomo · 2025-06-01T18:58:21Z

Dan, I just checked the JSON I sent to you in the past for my Matter lightbulb and colorTempPhysicalMinMireds is 153.
The binding will finally consider 154 as minimum.
Does it mean Tapo is not respecting the Matter standard or does it mean that your minimum value at 154 should be rather 153 ?

I plan to run new tests with the official version in the coming days.

As we have difficulties to build a new snapshot, I compiled the binding form code and installed it in a previous snapshot.

digitaldan · 2025-06-01T21:11:19Z

Sorry, that was my mistake, i meant to test if its == "0" not less then the default min, i'll post a fix right now for that.

digitaldan · 2025-06-01T21:31:10Z

~~Actually, i think i did get it right, if its less then or equal to MIN_MIREDS then we default to a sane value. MIN_MIREDS is 1 (1 is the matter 1.4 default, it was 0 in 1.3 and earlier)~~

No, your right, i'm doing an unnecessary Math.max on that, i'll fix that and put a test in for it

lolodomo · 2025-06-08T08:39:31Z

Dan, now, you could add the binding's logo to the openHAB website. See https://www.openhab.org/docs/developer/addons/#add-your-add-on-s-logo-to-the-openhab-website

digitaldan · 2025-06-08T16:50:49Z

Done!
openhab/openhab-docs#2505

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

[matter] Initial Commit

85e191d

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan added the new binding If someone has started to work on a binding. For a new binding PR. label Apr 4, 2025

digitaldan added this to the 5.0 milestone Apr 4, 2025

digitaldan requested a review from a team as a code owner April 4, 2025 22:37

remove local npm cache from deps

cab34ce

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan added the work in progress A PR that is not yet ready to be merged label Apr 5, 2025

digitaldan changed the title ~~[matter] Initial Commit~~ [matter] Initial Contribution Apr 5, 2025

digitaldan added 2 commits April 5, 2025 09:41

Adds gitignore for generated node related output dirs

c28c6da

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Make code-gen an optional maven profile, spotless gen files

da4b48c

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

digitaldan removed the work in progress A PR that is not yet ready to be merged label Apr 5, 2025

digitaldan mentioned this pull request Apr 5, 2025

Add Matter metadata openhab/openhab-webui#3129

Merged

Dimmable brdiged light fix

42b82b6

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

lsiepel added the cre Coordinated Review Effort label Apr 7, 2025

jlaur reviewed Apr 7, 2025

View reviewed changes

bundles/org.openhab.binding.matter/src/main/resources/OH-INF/addon/addon.xml Show resolved Hide resolved

digitaldan added 6 commits April 12, 2025 14:01

Support for Thread Boarder Router Devices.

a3ba9c6

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

PR review comments, adds polling for diag clusters, TBR improvements,…

0e534ae

… upgrades matter sdk Signed-off-by: Dan Cunningham <dan@digitaldan.com>

README updates

d53035a

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

README updates

57667cf

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Remove logo

aa0925f

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

newline

9a32094

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Make polling configurable, remove dead code, fix readme

d5f3d71

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

jlaur reviewed Apr 18, 2025

View reviewed changes

florian-h05 pushed a commit to openhab/openhab-webui that referenced this pull request May 28, 2025

Add Matter metadata (#3129)

6c66733

Refs openhab/openhab-addons#18486 --------- Also-by: Florian Hotze <dev@florianhotze.com> Signed-off-by: Dan Cunningham <dan@digitaldan.com>

PR rewiew feedback

4b57513

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Bump matter.js

91497aa

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

florian-h05 approved these changes May 28, 2025

View reviewed changes

bundles/org.openhab.binding.matter/matter-server/src/util/error.ts Show resolved Hide resolved

remove apache headers

6495525

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

lolodomo reviewed May 29, 2025

View reviewed changes

lolodomo requested changes May 29, 2025

View reviewed changes

lolodomo requested changes May 30, 2025

View reviewed changes

digitaldan added 2 commits May 31, 2025 10:59

PR review feedback

25f8b80

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

bump matter sdk, ensure color device is on when sending temp commands

5fd73d2

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

lolodomo reviewed Jun 1, 2025

View reviewed changes

jlaur approved these changes Jun 1, 2025

View reviewed changes

jlaur merged commit f88de93 into openhab:main Jun 1, 2025
2 checks passed

jlaur changed the title ~~[matter] Initial Contribution~~ [matter] Initial contribution Jun 1, 2025

phenix1990 pushed a commit to phenix1990/openhab-addons that referenced this pull request Jul 31, 2025

[matter] Initial contribution (openhab#18486)

d3114ac

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

		if (lastOnOff)
		updateState(CHANNEL_ID_COLOR_TEMPERATURE, miredsToPercentType(lastColorTemperatureMireds));

Uh oh!

[matter] Initial contribution #18486

[matter] Initial contribution #18486

Uh oh!

Conversation

digitaldan commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lsiepel commented Apr 7, 2025

Uh oh!

lolodomo commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

florian-h05 commented Apr 7, 2025

Uh oh!

digitaldan commented Apr 7, 2025

Uh oh!

lsiepel commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jlaur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

digitaldan commented Apr 7, 2025

Uh oh!

digitaldan commented Apr 16, 2025

Uh oh!

jlaur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

digitaldan commented May 28, 2025

Uh oh!

florian-h05 commented May 28, 2025

Uh oh!

florian-h05 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

digitaldan commented May 28, 2025

Uh oh!

lolodomo commented May 29, 2025

Uh oh!

lolodomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lolodomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lolodomo May 29, 2025

Choose a reason for hiding this comment

Uh oh!

digitaldan commented Apr 4, 2025 •

edited

Loading

lolodomo commented Apr 7, 2025 •

edited

Loading

lsiepel commented Apr 7, 2025 •

edited

Loading

lolodomo Jun 1, 2025 •

edited

Loading

lolodomo commented Jun 1, 2025 •

edited

Loading

digitaldan commented Jun 1, 2025 •

edited

Loading

digitaldan commented Jun 8, 2025 •

edited

Loading