Matter Binding

[digitaldan (Dan Cunningham)]

The Matter Binding for openHAB allows seamless integration with Matter-compatible devices as well as exposing openHAB as a Matter Bridge.

Please note this binding requires openHAB 4.3 builds or later that support discovery codes when searching for devices.

The Matter binding currently supports many types of devices including lighting, sensors, thermostats, fans, locks, buttons and more. Additional devices will be added as they become available for testing.

If you are having issues, please ALWAYS include the following information before posting:

1. Hardware and Virtualization info (NUC, Pi, Docker, Proxmox, VMWare, etc…)
2. Operating System and Versions
3. Network configurations (Vlans, wifi, ethernet, multiple interfaces, etc…)
4. openHAB version
5. Logs using TRACE logging
6. Confirm you have read the Matter README thoroughly
7. Is this an issue with the controller or bridge feature?

Supported modes

This binding supports 2 different types of Matter functionality.

• A Matter controller

  • This allows openHAB to discover and control other Matter devices like lights, thermostats, window coverings, locks, etc…

• A Matter Bridge

  • This allows openHAB to expose items as Matter devices to other Matter clients. This allows local control of openHAB devices from 3rd party ecosystems like Apple Home, Amazon Alexa, and Google Home.

These are 2 separate features, with different configurations and do not interact with each other.

Quick Start

To add a Matter device to openHAB:

1. Ensure you have manually added a Controller thing from the Main UI. This will create a local Matter Fabric for devices.
2. Get a pairing code from either the device manufacturer if new, or from another matter system if the device is already connected (like Amazon Alexa, Apple Home, or Google Home). (if this is a Thread Device, see the README for additional instructions)
3. Scan for a device in the Main UI using the Matter binding. Enter the code (with or without dashes) then hit “scan”
4. Add the device if found

To Expose openHAB Items to Matter clients like Amazon Alexa, Apple Home, and Google Home

1. Add matter metadata to the item you wish to expose, ie: matter="DimmableLight" . See the README for a list of tags and examples.
2. Pair a matter controller (Amazon Alexa, Apple Home, Google Home, etc…) using the pairing code found in the Main UI → Settings → Add-on Settings → Matter Binding. Make sure “Allow Commissioning” is enabled (click save if needed)

README and Detailed Information on Matter

Please refer to the Matter README for detailed information on the Matter protocol, IPV6 requirements, Thread support, device type support and more.

If you are having issues, PLEASE read the Matter README carefully before asking for help. Its a bit long, but contains important information.

Matter and IPv6 (IMPORTANT!!!)

Matter requires IPv6 to be enabled and be routable between openHAB and the Matter device. This means IPv6 needs to be enabled on the host openHAB is running, and the network must be able route IPv6 unicast and multicast messages. Docker, VLANs, subnets and other configurations can prohibit Matter from working if not configured correctly. See the IPv6 Requirements section of the readme for more information. This is probably the #1 reason for support issues.

Help Wanted

Please don’t be afraid to create PRs, refactor code, add documentation, etc… I would love to have others collaborate on and enhance our Matter support. Its a very feature rich ecosystem that would benefit from other’s support and points of view.

Resources

Jar file (OH4.3+)

Source code and documentation

Last published Date

Jan 16 2025 - 09:45 PDT

[Pedro_Liberal]

Excellent contribution!
Just recently I’ve added a govee t3 lite with matter and it’s working great

[Lolodomo]

Hi Dan,
The binding does not appear as available because the tag “published” is missing.

[digitaldan (Dan Cunningham)]

@Lolodomo

the tag “published” is missing.

Thanks! I just added it.

[mjcumming (Michael Cumming)]

@digitaldan thank you for all the great work on this binding - without it OpenHAB would quickly lose its relevance. I have no doubt that going forward the majority of home automation devices will be Matter based.

[tizen (Amin)]

Hi @digitaldan ,

I m able to control Aqara U200 Door lock using this binding. Thanks for all the support. let me know if you need any other info to add more lock features in this binding.

On a seperate note, is there any Item type for Locks in OpenHAB? I feel there should be different action to unlock, like slider or anything similar. I know I can build it using UI controls but having a built-in support will be really helpful.

Having a normal switch for lock seems bit risky. Switch items can be touched accidently which may leave the door open, especially on doors which dont have latch handle from outside. This is very common in India. We just have,generally, dead bolt key hole outside.

I m thinking to put small magnet catcher to avoid situation where door opens itself after it is unlocked.

Anyway thanks for this amazing binding. I think, I m going to only use matter enabled devices going farword for simplier integration.

Thank you for your support!

[hmerk (Hans-Jörg Merk)]

@tizen

Having a normal switch for lock seems bit risky. Switch items can be touched accidently which

There is no slider control for locks,
This is what you might be looking for. You can set this a the default standalone and/or listitem widget for your lock.
[Custom Widget - Confirm Switch - Apps & Services / HABPanel - openHAB Community] Confirm Button - Add-on Marketplace / UI Widgets - openHAB Community

[Pedro_Liberal]

In case anyone else skims the documentation - instead of actually reading it - don’t forgot to link a switch item to your color control matter channel if you need a simple on/off control for it

:oops:

[kjknauss (KJ)]

Any tips or tricks to switching from the jar file to the marketplace version? Or should we just stay on the jar until binding becomes official?

[sihui]

@kjknauss

switching from the jar file to the marketplace version?

Delete the jar file in your addons folder and install the binding through the marketplace.
That’s how I did it, no issues.

[Pedro_Liberal]

No restart no nothing?

[sihui]

Nope, not in my case.

[kjknauss (KJ)]

Just did it. Delete jar, add binding from marketplace, all came back online.

[jswim788 (John Schmitz)]

Tried to enable commissioning and got this warning. I can see that the value ‘240’ is used for the ‘discriminator’ in the settings page - is that related? OH 4.3 release, Matter binding: 4.3.0.202412262040.

Strangely, I cannot change the log level in the Matter binding page. Other bindings show the selection for the log level, but not the Matter binding. (This has worked in the past with earlier versions of the binding - I’ll try a reboot to see if it reappears.)

2024-12-28 15:35:05.003 [WARN ] [penhab.core.config.core.ConfigParser] - Could not set field value for field 'discriminator': For input string: "240.0"
java.lang.NumberFormatException: For input string: "240.0"
        at java.lang.NumberFormatException.forInputString(NumberFormatException.java:67) ~[?:?]
        at java.lang.Integer.parseInt(Integer.java:668) ~[?:?]
        at java.lang.Integer.valueOf(Integer.java:999) ~[?:?]
        at org.openhab.core.config.core.ConfigParser.valueAs(ConfigParser.java:216) ~[bundleFile:?]
        at org.openhab.core.config.core.ConfigParser.configurationAs(ConfigParser.java:128) [bundleFile:?]
        at org.openhab.core.config.core.Configuration.as(Configuration.java:79) [bundleFile:?]
        at org.openhab.binding.matter.internal.bridge.MatterBridge.modified(MatterBridge.java:202) [bundleFile:?]
        at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:?]
        at jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[?:?]
        at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[?:?]
        at java.lang.reflect.Method.invoke(Method.java:569) ~[?:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.invokeMethod(BaseMethod.java:245) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.access$500(BaseMethod.java:41) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod$Resolved.invoke(BaseMethod.java:687) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.invoke(BaseMethod.java:531) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.ActivateMethod.invoke(ActivateMethod.java:317) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.ActivateMethod.invoke(ActivateMethod.java:307) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.invokeModifiedMethod(SingleComponentManager.java:856) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.modify(SingleComponentManager.java:810) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.reconfigure(SingleComponentManager.java:725) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.reconfigure(SingleComponentManager.java:686) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.ConfigurableComponentHolder.configurationUpdated(ConfigurableComponentHolder.java:440) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.RegionConfigurationSupport.configurationEvent(RegionConfigurationSupport.java:347) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.RegionConfigurationSupport$2.configurationEvent(RegionConfigurationSupport.java:115) [bundleFile:?]
        at org.apache.felix.cm.impl.ConfigurationManager$FireConfigurationEvent.sendEvent(ConfigurationManager.java:1723) [bundleFile:?]
        at org.apache.felix.cm.impl.ConfigurationManager$FireConfigurationEvent.run(ConfigurationManager.java:1664) [bundleFile:?]
        at org.apache.felix.cm.impl.UpdateThread.run0(UpdateThread.java:122) [bundleFile:?]
        at org.apache.felix.cm.impl.UpdateThread.run(UpdateThread.java:84) [bundleFile:?]
        at java.lang.Thread.run(Thread.java:840) [?:?]
2024-12-28 15:35:10.386 [WARN ] [penhab.core.config.core.ConfigParser] - Could not set field value for field 'discriminator': For input string: "240.0"
java.lang.NumberFormatException: For input string: "240.0"
        at java.lang.NumberFormatException.forInputString(NumberFormatException.java:67) ~[?:?]
        at java.lang.Integer.parseInt(Integer.java:668) ~[?:?]
        at java.lang.Integer.valueOf(Integer.java:999) ~[?:?]
        at org.openhab.core.config.core.ConfigParser.valueAs(ConfigParser.java:216) ~[bundleFile:?]
        at org.openhab.core.config.core.ConfigParser.configurationAs(ConfigParser.java:128) [bundleFile:?]
        at org.openhab.core.config.core.Configuration.as(Configuration.java:79) [bundleFile:?]
        at org.openhab.binding.matter.internal.bridge.MatterBridge.modified(MatterBridge.java:202) [bundleFile:?]
        at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:?]
        at jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[?:?]
        at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[?:?]
        at java.lang.reflect.Method.invoke(Method.java:569) ~[?:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.invokeMethod(BaseMethod.java:245) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.access$500(BaseMethod.java:41) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod$Resolved.invoke(BaseMethod.java:687) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.BaseMethod.invoke(BaseMethod.java:531) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.ActivateMethod.invoke(ActivateMethod.java:317) [bundleFile:?]
        at org.apache.felix.scr.impl.inject.methods.ActivateMethod.invoke(ActivateMethod.java:307) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.invokeModifiedMethod(SingleComponentManager.java:856) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.modify(SingleComponentManager.java:810) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.reconfigure(SingleComponentManager.java:725) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.SingleComponentManager.reconfigure(SingleComponentManager.java:686) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.ConfigurableComponentHolder.configurationUpdated(ConfigurableComponentHolder.java:440) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.RegionConfigurationSupport.configurationEvent(RegionConfigurationSupport.java:347) [bundleFile:?]
        at org.apache.felix.scr.impl.manager.RegionConfigurationSupport$2.configurationEvent(RegionConfigurationSupport.java:115) [bundleFile:?]
        at org.apache.felix.cm.impl.ConfigurationManager$FireConfigurationEvent.sendEvent(ConfigurationManager.java:1723) [bundleFile:?]
        at org.apache.felix.cm.impl.ConfigurationManager$FireConfigurationEvent.run(ConfigurationManager.java:1664) [bundleFile:?]
        at org.apache.felix.cm.impl.UpdateThread.run0(UpdateThread.java:122) [bundleFile:?]
        at org.apache.felix.cm.impl.UpdateThread.run(UpdateThread.java:84) [bundleFile:?]
        at java.lang.Thread.run(Thread.java:840) [?:?]

[Lolodomo]

@jswim788

Strangely, I cannot change the log level in the Matter binding page. Other bindings show the selection for the log level, but not the Matter binding.

Same for me.
Is it because installed from marketplace?
Is it working for other bindings installed from marketplace?

[sihui]

@Lolodomo

Same for me.

Same here, openHAB 4.3.0 Release

@Lolodomo

Is it working for other bindings installed from marketplace?

I have two bindings installed from Marketplace, Matter and Worxlandroid, with both bindings I cannot change the loglevel from the UI.

It works fine though for all other bindings.

[hmerk (Hans-Jörg Merk)]

@sihui

I have two bindings installed from Marketplace, Matter and Worxlandroid, with both bindings I cannot change the loglevel from the UI.

This is a known issue for bindings installed from Marketplace.

[sihui]

@hmerk

known issue

Ahh, hadn’t heard about that.

[hmerk (Hans-Jörg Merk)]

It has been discussed with @florian-h05 here:

Contribution - LG ThinQ Binding

Thats strange. Tried it yesterday with a different Marketplace Binding and saw the little gear icon. Today, it is gone… Third Party Marketplace Bindings like Smathome/J Tuya Binding still have this icon… We will have to check…… @florian-h05 Do you have an idea what’s wrong here ???

[digitaldan (Dan Cunningham)]

@jswim788

java.lang.NumberFormatException: For input string: "240.0"

Hmm, thats odd, i wonder if somehow the UI is passing a float/double which breaks as we expect a int format ? I’ll take a look today.