Knowledge Base

Matter is an open, local (no cloud) smart home standard that allows devices from different manufacturers to work together. Matter devices communicate over the local network without a specified protocol, they may use wifi, ethernet, thread... Thread is a separate protocol from Matter entirely.

ComfortClick can act as a Matter controller. Matter devices such as lights, plugs, switches, sensors, thermostats, door locks and blinds can be added to bOS and controlled directly from the configuration. After a device is added, its values and functions can be used in visualization, schedules, scenes, alerts and custom tasks, just like other devices in the project.

A Matter device can be connected to more than one system at the same time through multi-admin. The device can be in Apple Home, Google Home or the manufacturer's app all at once and be controlled from bOS as well, it works either way.

Table of contents

Requirements

Matter requires a very recent 64-bit Debian, including a recent kernel. Controllers with an older operating system are not supported. Matter is available on the following controllers:

• Jigsaw (Serial number JS)

• Jigsaw Pro

• Colibri (Serial number CO)

On other controllers, Matter Server is not available in the list of devices.

The Matter server runs in a container on the controller. The first time the Matter Server node is started, bOS installs the container manager and downloads the Matter server automatically. This can take a few minutes and requires an internet connection. Progress is shown in the device log.

Matter devices are found and controlled over IPv6 multicast, which sets the following requirements for the local network:

• IPv6 must be enabled in the local network.

• The controller, Matter devices, Thread border routers and the phone used for pairing must be in the same LAN/VLAN. Matter communication does not pass between separate LANs or VLANs.

• Multicast filtering on routers and access points (ex. Multicast optimization) must be turned off. IGMP/MLD snooping can either help or cause problems, so test it if devices are not found.

Thread devices require a Thread border router in the same network, for example Apple HomePod mini, Apple TV 4K or Google Nest Hub. bOS reaches Thread devices through the border router.

Matter Server Settings

Matter Server node is added under Devices. Only one Matter Server can be added to a project. All Matter devices added to bOS are listed under the Matter Server node.

• Matter Server Log Level - Level of Matter server messages written to the device log. These are incoming from the actual docker container, logs (debug) are also always written on device itself for more thorough analysis.

• Enable Time Sync - Sends the controller time to devices that support time synchronization. Enable only when the controller time is set correctly.

• Enable Test Net DCL - Allows adding uncertified development and test devices. Useful for testing or in special cases (if you would like to add home made devices etc).

• Fabric Label - Name under which bOS is shown in other apps that are connected to the same device. Default is ComfortClick.

• Fabric id - Unique ID of the bOS Matter network.

• Schema compatible - Shows if the Matter server version is supported by this version of bOS. Controller schema version, Minimum supported controller schema version and BOS schema version show the versions that are compared.

Functions

• Get Nodes - Refreshes the list of added devices from the Matter server.

• Get Info - Refreshes the fabric and version values.

• Discover Commissionable - Searches the network for devices that are in pairing mode and lists them in the device log.

• Get Diagnostics - Writes a summary of the Matter server state to the device log.

• Get Thread Border Routers - Lists the Thread border routers found on the network in the device log.

• Get Thread Diagnostics - Writes the state of the Thread networks to the device log.

• Get Network Topology - Writes a summary of the Matter network, border routers and the links between them to the debug log.

Adding Devices

Matter devices are added to bOS with a pairing code. bOS does not support adding devices over Bluetooth, so the device must already be connected to the network. The easiest way is to first add the device in the app it was designed for (Apple Home, Google Home, SmartThings or the manufacturer's app) and then share it with bOS.

Sharing a Device from Another App

1. Add the device in the other app and make sure it works there.

2. In the other app, open the device settings and turn on pairing mode for another system. In Apple Home this is Turn On Pairing Mode, in Google Home Linked Matter apps & services. The app shows a new pairing code.

3. In bOS Configurator, select the Matter Server node and click Add Commission in the Commission Jobs list.

4. Enter the pairing code and click OK.

The pairing mode in the other app is open only for a limited time, so enter the code in bOS right away.

• Pairing Code - Manual pairing code (11 or 21 digits) or the text of the QR code (starts with MT:).

• Network Only (Wi-Fi) - bOS looks for the device only on the IP network and skips Bluetooth discovery.

A device connected by Ethernet can also be added directly, with the pairing code printed on the device or its packaging.

Commission Jobs

Every pairing attempt is listed in the Commission Jobs list with its Attempt ID, Code and Status.

• InProgress - Pairing is running.

• Success - Device was added and is shown under the Matter Server node.

• Failed - Pairing failed. The reason is written to the device log.

• Stale - No result was received within 3 minutes.

Clear All removes all jobs from the list.

Matter Node

Each added device is shown as a Matter Node under the Matter Server, named by its Node ID, vendor and product (ex. [5] Eve Systems - Eve Energy). Selecting the node shows device information and its connection status.

Info

• Node ID - A unique ID that is assigned to the device when it is added.

• Vendor Name, Product Name, Product Label - Manufacturer and product information.

• Node Label - Name of the device, if it was set during pairing.

• Serial Number, Software Version, Hardware Version - Device information.

• Matter Version - Version of the Matter specification the device was certified for.

• Is a Matter Bridge - True when the device is a bridge that connects other devices to Matter (ex. Philips Hue Bridge, Aqara hub).

• IP Addresses - IP addresses of the device.

• Date Commissioned - Date and time when the device was added.

• Last Interview - Date and time when bOS last read the device structure.

Availability

• Enable Node Pings - Periodically checks if the device is reachable.

• Ping Interval (s) - Time in seconds between two checks.

• Available - Shows if the device is currently reachable.

• Availability percentage - Percentage of time the device was reachable. Availability Tracking Duration shows how long it has been measured.

• Last Communication - Date and time of the last message from the device.

Functions

• Reinterview Node - Reads the full device structure again. Useful when endpoints or clusters are missing, for example after a firmware update.

• Remove Node From Fabric - Removes the device from bOS. The device stays connected to other apps. Deleting the Matter Node in the configuration does the same.

• Get Node IP Addresses - Refreshes the IP Addresses of the device.

• Reset Availability Tracking - Starts measuring the availability percentage again.

Endpoints and Clusters

A Matter device is divided into endpoints. Each endpoint is one part of the device, for example one channel of a double switch. Endpoints are listed under the Matter Node and named by their Endpoint ID and device type (ex. [1] On/Off Light). Endpoint 0 contains general information about the device.

Each endpoint contains clusters. A cluster is a group of values, settings and functions for one feature of the device, for example On/Off, Level Control, Color Control, Temperature Measurement or Door Lock. Cluster values and functions can be dragged into the visualization and used in tasks like the values of any other device.

• Endpoint Id - Number of the endpoint on the device.

• Tags - Labels the device uses to tell similar endpoints apart (ex. Left, Right).

• Identify - Makes the device identify itself, for example by blinking, so it can be found in the room. Identify Type shows how the device identifies itself. Available only on devices that support it.

Clusters that bOS does not support are listed in the device log. Manufacturer specific clusters can usually only be used in the manufacturer's app.

Bridged Devices

When the device is a Matter bridge, each device connected to the bridge is shown as a Bridged Matter Endpoint with its own product information and endpoints. The Reachable value shows if the bridge can currently reach the device. Commands are not sent to a bridged device while it is not reachable.

Battery Devices (ICD)

Battery powered Matter devices (Intermittently Connected Devices, ICD) sleep most of the time and wake up periodically to report to the controller. ICD settings and functions are shown on the Matter Node only for devices that support it.

• ICD Supported - Device is a battery powered device.

• ICD LIT Supported - Device supports Long Idle Time mode, where it sleeps longer to save battery.

• ICD Registered - bOS is registered to receive check-ins from the device.

• ICD Operating Mode - Current mode of the device: SIT (Short Idle Time) or LIT (Long Idle Time).

• ICD Awake - Device is currently awake and reachable.

• ICD Next Expected Check-In - Time of the next expected check-in from the device.

Functions

• Register ICD - Registers bOS for check-ins, so a LIT device can enter its low power mode.

• Unregister ICD - Stops the check-ins. A LIT device goes back to SIT mode.

• Refresh ICD State - Refreshes the ICD values without waking the device.

• Resync ICD - Reconnects a device that stopped responding. This can take as long as the device sleep interval.

Firmware Updates

bOS checks if a newer firmware is published for the device when the device is added.

• Update Available - Shows if a newer firmware is available.

• Available Software Version - Newest firmware version available for the device.

• Last Update Check - Date and time of the last check.

• Check Node Software Update - Checks for a new firmware again.

• Update Node Software - Starts the update to the available version. The update runs in the background and can take several minutes, during which the device may not respond.

Multi Admin

A device added to bOS can also be shared with another app, for example Apple Home or Google Home, so it can be controlled from both.

1. Select the Matter Node and open Multi Admin.

2. Click Open. bOS turns on pairing mode on the device and shows the QR Code and Manual code.

3. In the other app, add a new Matter device and enter the code.

• Multi Admin Timeout (s) - How long the pairing mode stays open, in seconds. Default is 300.

• Multi Admin Active - Shows if the pairing mode is currently open.

Matter Network Map

Matter network map is a visualization control that shows the Matter network: Thread border routers, Thread routers, end devices and the links between them.

Dragging and dropping the Matter Server node into the visualization and selecting Matter network map creates the control.