This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.
Important
This adapter can only be installed from npm. A GitHub install is not possible! For more important information please read the Important Information section!
TODO
- Not installable via GitHub: This adapter can only be installed via npm.
- Never delete partial matter instance objects or object trees! The configuration for this adapter is not contained in just one central object like in other ore simple adapters. This means that deleting instance objects or object trees can lead to a broken configuration, and you might need to reconfigure the adapter from scratch.
- Never reinstall the adapter by deleting the instance if you want to keep paired devices (e.g. on Controller) or paired Controllers (e.g. on Bridges). If you delete the instance all paired devices will be deleted, and you need to pair them again.
- Use an ioBroker Backup to back up the configuration and restore the backup to restore it. If really needed without backup then export the whole object tree of the adapter instance (e.g. matter.0) and import it back if needed. These can be a high number of objects depending on the number of devices and controllers you have paired.
- Some objects are not shown by default because they are irrelevant for normal operation. If you need to see them you can enable the "Expert Mode" in the adapter settings. This mainly is about the "storage" objects. Please do not change them unless you really, really know what you are doing!
- One instance of the adapter is bound to one host (aka IP). Multiple instances require a multi-host setup.
- Make sure IPv6 is enabled in your network and the host you use this adapter on has an IPv6 address
- If you use LXC containers in Proxmox this is like not given because Proxmox hosts are normally not configured for IPv6!
- Make sure that UDP packages can flow between the devices, your mobile app, the hubs and the host you use this adapter on!
- Mainly make sure to not use VLANs, because UDP is usually not routed between VLANs! Or find out how to configure your router to allow this (Fritzbox does not work with this!)
- If you use Docker containers make sure to use Host Mode to allow UDP packages to flow between the containers and the host. Bridged network mode does not work with UDP packages!
Important: In order to expose more than 5 Bridged devices or to expose additional separate Devices or Bridges you need to have a Matter Pro Account with an active Assistant or Remote Control License and entering this into the adapter configuration! Please support our team with the efforts we invest in Matter with this. Controller usage is not limited by this.
- The Bridges and devices that the ioBroker Adapter exposes are not officially certified by the Matter organization. This means they only work in Ecosystems that allow this.
- For Google additional steps might be needed - see https://github.com/project-chip/matter.js/blob/main/docs/ECOSYSTEMS.md#google-home-ecosystem
- Aqara Hub M3 and Yandex are currently (as of November 2024) not allow "uncertified devices" to be paired!
- Each Ecosystem has different limits about devices per Bridge and such. So if a high number of devices (there are test results up to 64 which should work at least in Apple, Google and - a bit wonky - Amazon) one bridge makes issues. please try splitting it up to multiple bridges. I would also be happy to find out the practical limits so please report your experiences.
- For Alexa currently only the "Default Bridge" can be used on a host. Multiple Bridges to use with Alexa are only possible on different hosts.
- If you plan to use Thread based devices (check the package for information) you need to have a Thread Border Router (TBR) in your network. Check https://github.com/project-chip/matter.js/blob/main/docs/ECOSYSTEMS.md for more information about the ecosystems and their Thread support. More information on Thread and also on how to add an own TBR can be found at https://github.com/project-chip/matter.js/blob/main/docs/USAGE_THREAD.md
- If you run on Linux and plan to use Thread based devices and have issues connecting to them please refer to https://github.com/project-chip/matter.js/blob/main/docs/TROUBLESHOOTING.md#ipv6-linux-system-details for instructions how to tweak the IPv6 configuration on your Linux system.
- Initial commissioning of devices is possible with the "ioBroker Visu App" which uses the BLE of your mobile device and is the most convenient way. You can also use the BLE of your ioBroker host but then the device also needs to be in BLE range of your host. When using the App you need an ioBroker Pro Account with an active Assistant or Remote Control License.
| ioBroker Device Type | Mapped to Matter Device Type | Comments |
|---|---|---|
| Button | GenericSwitch | Reports multi-presses when the time between single presses is maximum 300ms. |
| ButtonSensor | GenericSwitch | Reports multi-presses when the time between single presses is maximum 300ms. Reports Long-presses when the PRESS_LONG state is used |
| Ct | Color Temperature Light | |
| Dimmer | Dimmable Light | |
| Door | Contact Sensor | |
| Flood Alarm | Water Leak Detector | |
| Humidity | Humidity Sensor | |
| Illumunance | Illuminance Sensor | |
| Light | OnOff Light | |
| Lock | Door Lock | |
| Motion | Occupancy Sensor | |
| Socket | OnOff PlugIn | |
| Temperature | Temperature Sensor | |
| Window | Contact Sensor |
... more to come
| Matter Device Type | Mapped to ioBroker Device Type |
|---|---|
| Color Temperature Light | Ct |
| Dimmable Light | Dimmer |
| Dimmable PlugIn Unit | Dimmer |
| Contact Sensor | Window |
| Energy Sensor | Light with only energy states |
| Generic Switch (as Latching Switch) | Socket (state ACTUAL only) |
| Generic Switch (as Momentary Switch) | ButtonSensor |
| Humidity Sensor | Humidity |
| Illuminance Sensor | Illuminance |
| OnOff Light | Light |
| Door Lock | Lock |
| Occupancy Sensor | Motion |
| OnOff PlugIn Unit | Socket |
| Temperature Sensor | Temperature |
| Water Leak Detector | Flood Alarm |
... more to come
TBD
TBD
TBD
TBD
TBD
TBD
This is the default mode for all supported device types where ioBroker has a matching own device type. In this case the functionality is conveniently abstracted as defined in ioBroker and how it is mapped for many other adapter states. The exposed functionality is limited to what ioBroker defines for the device type and should allow all normal operations.
If you need more granularity and access to device specific functionality or settings you can enable the "Application Cluster states" for this node or device to gain access (see below).
Note: This is considered Advanced Usage!
Sometimes it might be handy to also see more internal details of the device or to access more specific functionality of the device. In this case you can enable the "Application Cluster states" for the node or device. This e.g. allows to set the sensitivity for a motion sensor. When enabled for a node (valid then for all devices exposed by the node) or a device you will see a lot of additional states in an objects folder "data".
The details are structured by the application cluster and separated in attributes (data states) and commands. The exact meaning, units and allowed values and ranges for the data can be taken from the Matter Application Specification document. When commands are exposed as a "button" then the action can be triggered by just setting a boolean value to the state. But most commands require more data (these are "json" strings) and require that a json string with all command fields are provided. The exact definition of the command fields can be taken from the Matter Application Specification document.
Note: This is considered Professional Usage!
In all normal end user cases you should not need to use the System Cluster states. They are only needed for special cases and for debugging or to deeply explore the Matter cluster data. If you enable them you will see a lot of additional states that are not needed for normal operation. Any changes to the writable states can break the functionality of the devices. So please only use them if you know what you are doing!
- Not all ecosystems support all device types and sometimes ecosystems react strange when you add a device type they do not support. So please check the ecosystem documentation for the supported device types, if available or try it out. We try to collect the details in the Supported ioBroker devices section. Please report any new information as an issue or PR.
- If you plan to use bridges with many devices so please consider commissioning the bridge initially with just some added devices and then add more overtime. This can help to avoid issues with the ecosystems and also could be a better experience for you.
TBD
- On Linux especially see https://github.com/project-chip/matter.js/blob/main/docs/TROUBLESHOOTING.md
- With Alexa only the Default bridge can be used on a host. Multiple Bridges to use with Alexa are only possible on different hosts.
- When an Ecosystem shows the device as disconnected, especially after an adapter restart, then this usually means that the controller has not yet reconnected to the device. This can take some time. If it does not reconnect after a few minutes then please check the connection information in the UI. If an ecosystem is not connecting at all please check logs and potentially debug logs and open an issue.
- Please check Prerequisites to use this adapter and Troubleshooting first
- Check that you are using the latest version available - or if not, if the changelog for the versions since your version contain information about your issue. Then try updating first please.
- Check existing open GitHub issues. If yours is also listed there vote for it by adding a thumbs up on first comment. This helps to prioritize the issues. "Me Too" posts are not needed.
- Create a GitHub issue if your issue is not existing
- Turn on Debug logs fpr the matter instance, and additionally "Matter Debug" logs on the main page of the adapter settings. Include the logs (as Text file please, Logfile location usually /opt/iobroker/logs/...) as text file attachment in your issue report. Please do not cut only the error but also add some minutes of log before and after the error to get some more context. Please also include information on what exactly is seen there, what was done and such. The more context you can provide the better.
- Texts are partially in english
- Sync min/max from Matter into ioBroker objects
- Cleanup objects when devices/states are removed
- ioBroker device types
- (9) Lights:
- rgb
- rgbwSingle
- rgbSingle
- cie
- hue
- (8) blinds + blindButtons
- (-8) thermostat
- (3+) vacuumCleaner
- (3) volume, volumeGroup
- (-3) airCondition
- (2+) fireAlarm
- (-2) mediaPlayer
- warning - how?
- gate - aka blinds?
- windowTilt - how?
- levelSlider - how?
- (9) Lights:
- Matter device types
- (9) Enhanced Color Light -> rgb/rgbw/cie/hue/...
- (8) Thermostat -> thermostat
- (8) Window Covering -> blinds / blindButtons
- (7) Fan -> thermostat?
- (4+) Air Quality Sensor -> ???
- (4+) Air Purifier -> ???
- (4) Pump -> ???
- (4) Pressure Sensor -> ??? DEF
- (3+) Robot Vacuum cleaner -> vacuumCleaner
- (3) Flow Sensor -> ??? DEF
- (3) Room Air Conditioner -> airCondition
- (2+) Smoke & CO Alarm -> fireAlarm? warning?
- (2+) Speaker -> volume, volumeGroup
- (2+) Dishwasher-> ???
- (2) Basic Video Player -> mediaPlayer
- (2) Laundry Washer -> ???
- (2) Refrigerator -> ???
- (2) Temperature Controlled Cabinet -> ???
- (2) Water Freeze Detector -> warning?
- (2) Rain Sensor -> warning?
- (2) Water Valve -> ???
- (2) Laundry Dryer -> ???
- (2) Oven -> ???
- (2) Cooktop -> ???
- (2) Cook Surface -> ???
- (2) Extractor Hood -> ???
- (2) Microwave Oven -> ???
- (1+) Electrical Vehicle Supply Equipment -> ???
- (0) Water Heater -> ???
- (0) Solar Power -> ???
- (0) Battery Storage -> ???
- (0) Heat Pump -> ???
- (@Apollon77) Fixes several discovery issues
- (@Apollon77) Fixes bridge/device icon display in UI
- (@Apollon77) Prevents displaying warning dialogs when nothing is wrong
- (@Apollon77) Adjusts some logs
- BREAKING: Please re-enter your ioBroker Pro Cloud Password!
- (@Apollon77) Makes sure the adapter is stopped before being updated
- (@Apollon77) Optimizes device discovery and allows to stop it again
- (@bluefox) Makes the Adapter UI also available as standalone tab
- (@bluefox) Added error details when adding the same state twice to a bridge or device
- (@Apollon77) Fixes discovery start in UI
- (@Apollon77) When Get and set states are separated then also update set state with new values
- (@Apollon77) Node details dialog in controller now exposes some more Battery information
- (@Apollon77) Also exposes the battery states when features are set wrong on the device
- (@Apollon77) Fixes LightSensor state mapping
- (@Apollon77) Prevents errors when only some energy states exist
- (@Apollon77) Uses the IP provided by Android when commissioning devices if possible
- (@Apollon77) Restructure discovery to run in background and not block the UI
- (@Apollon77) Exposes States for Enums for Matter nodes
- (@Apollon77) Prevent storage to delete wrong data when a node gets removed
- (@bluefox) Fixes progress dialog for DM - used when deleting a node
- (@bluefox) Synchronizes the "do not ask again on delete" time with admin and set to 5 minutes
- (@bluefox) Optimizes bridges display for different color schemes
- (@bluefox) Allows to collapse the information blocks at the top of the pages
- (@bluefox) Adds an ioBroker Logo when display commissioned controllers
- (@bluefox/@apollon77) Adds additional details and error state also for devices and bridged devices
- (@bluefox/@apollon77) Always display QR code to allow additional pairing for device and bridges from adapter UI
- (@bluefox) Optimizes several messages nd approval dialogs
- (@bluefox) Adds a welcome dialog for new users
- (@bluefox) Adds user guidance for big unpaired bridges
- (@Apollon77) Adds Illuminance and Button/ButtonSensor (Switch) device type
- (@Apollon77) Changes/Optimizes naming structure for paired devices and sub-endpoints
- (@Apollon77) Adds information when Matter device types are not yet supported to look into objects for details
- (@Apollon77) Resets connection status when a controller node is disconnected, also on adapter stop
- (@Apollon77) Cleans up internal data structures when a node gets deleted for controller
- (@Apollon77) Uses the configured device type when finding multiple types in the backend
- (@Apollon77) Adjusts UI device type detection to differentiate between supported and other types
- (@Apollon77) Makes sure that controller configuration changes are executed sequentially
- (@Apollon77) Added Transition Time handling for Dimmer and Ct device types in both directions
- (@Apollon77) Added Low-Battery and Battery-percent for all device types in both directions
- (@Apollon77) Added Ethernet Network Commissioning Cluster to prevent issues with Tuya
- (@Apollon77) Cleans up objects when a controller node is deleted
- (@Apollon77) Prevents controller configuration changes to be executed in parallel
- (@Apollon77) Fixes ColorTemperature light initialization because of matter.js update
- (@Apollon77) Sets the "no-compose" flag correctly to normally use composed if needed and adds it to a missing dialog
- (@Apollon77) Allows to use null values if needed
- (@Apollon77) Fixes UNREACH handling for devices
- (@Apollon77) Fixes object change handling for controller
- (@Apollon77) Allows Bridges to expose its name as a device name
- (@Apollon77) Allows to rename controller nodes and devices
- (@Apollon77) Shows a progress indicator when deleting controller nodes
- (@Apollon77) Cuts names and labels to 32 or 64 characters as needed by Matter
- (@Apollon77) Improves error handling on devices and bridges
- (@Apollon77) Clear storage when removing a bridged device
- (@Apollon77) Processes changed objects with a 5s delay to prevent too many changes at once
- (@Apollon77) Fixes version determination
- (@Apollon77) Initializes Device objects more lazily
- (@Apollon77) Makes sure to delete all objects and stop device when a device is deleted in UI
- (@Apollon77) When a devices/bridge object is deleted and adapter runs we try to detect this and stop the device/bridge
- (@Apollon77) Optimizes close handling of adapter
- (@Apollon77) Uses adapter version as Software and Hardware versions in the exposed Matter devices
- (@Apollon77) Fixes "auto" flags in backend when make no sense in objects
- (@Apollon77) Fixes "auto" flag in UI
- (@Apollon77) Prevents cyclic state updates when a state is updated by the adapter to matter
- (@Apollon77) Log warnings when device optional device states are not mapped
- (@Apollon77) Hides Product-ID and VendorId fields in UI when adding devices into a bridge
- (@Apollon77) Uses plain matter.js logs for better readability
- (@Apollon77) Prevents ghost connection entries in the UI
- (@Apollon77) Adds some missing implementations for Controller of Door, Window, FloodAlarm and Motion
- (@Apollon77) Adds Color Temperature conversion if unit is "mireds"
- (@Apollon77) Fixes Color Temperature cluster initialization
- (@Apollon77) Fixes Min/Max calculation when unit conversion is used
- IMPORTANT: Breaking change!! Please decommission ALL devices and do a full factory reset of the adapter Matter storage before installing this version. Pair the devices new afterward.
- (@Apollon77) Finalizes Devices, Bridges and Controller functionality with a first set of 11 device types
- (@Apollon77) Upgrades to new Matter.js version and API (breaks storage structure)
- (@GermanBluefox) Moved build process of GUI to vite
- (@GermanBluefox) Added possibility to group devices in the GUI
- (@GermanBluefox) Working on the controller
- (@GermanBluefox) Implemented the factory reset and re-announcing
- (@GermanBluefox) Devices were implemented
- (@GermanBluefox) Fixed names under linux
- (@GermanBluefox) used library
@iobroker/type-detector
- (@GermanBluefox) Initial commit
Apache-2.0
Copyright (c) 2023-2024 Denis Haev [email protected]