Current Smart Homes are full of bridges that are the central component to talk to your proprietary devices via more or less open wireless protocols (Zigbee, DuoFern, Bluetooth, Wifi, etc.). So, should you just throw all your old systems away to make room for new matter devices? No, Matter has also a solution for this scenario and we will take a closer look at what a Matter Bridge is and how it will convert all your proprietary bridges into compatible matter devices.
Hands-on Matter - The Matter Bridge (Part 4)
Tim Conrad – Senior Security Consultant
Note:
This blog post is written for developers and other people with a technical background and interest in a security focused overview of Matter.
This blog post is written for developers and other people with a technical background and interest in a security focused overview of Matter.
Attention:
Please note that the Matter code open source, so a lot and examples and tools might change through out the process. We will do everything on Ubuntu 20.04. For other systems we will provide the link to the original document in the Matter repository.
Please note that the Matter code open source, so a lot and examples and tools might change through out the process. We will do everything on Ubuntu 20.04. For other systems we will provide the link to the original document in the Matter repository.
The Matter Standard has a special feature set to allow old Bridges and Smart Home Controllers to adapt Matter to become compatible.
The following picture shows a typical smart home setup, The Bridge in the middle could be a ZigBee Bridge or a Platform like Home Assistant (which already announced to support Matter and you can find a workshop here).
The Concept
The following figure will show you a brief overview of the Matter Bridge Concept. If you want to know more about the topics Nodes, Endpoints and Clusters please refer to Part 2.
The Matter Bridge exposes Non-Matter devices as Endpoints on its Matter interface. The Matter Bridge will consist of two parts a Matter stack and a Vendor specific OS connecting to the previously installed Smart Home devices. Often with some kind of vendor app or interface to on-board new devices or configure them remotely.
The following flow would be possible to connect the Matter Fabric with the current Smart Home installation:
1.) To allow easy integration the Commissioner will onboard the Bridge as he would with every other Matter device.
2.) Endpoint 0 (Bridge):
a.) The Bridge Node will expose the Descriptor Cluster on Endpoint 0. As part of its attributes it will have the DeviceType Root Node, Bridge which will indicate that this device has bridging capabilities. The PartsList attributes contains a list of all Endpoints that symbolizes a bridged device. Here we have Endpoint 10 for the Light, Endpoint 11 for the Laundry Machine and Endpoint 12 for the Hygrometer.
b.) The Cluster Bridged Action will provide information about the logical grouping such as which Endpoint belongs to which room. These are all information that are likely to be configured by the user in the initial setup of the Non-Matter Smart Home. Here we can see that Endpoint the is in the Bathroom and Endpoint 11 and 12 are in the Guest Bathroom. The Cluster has further functions such as, named actions, commands to trigger actions or receive feedback of actions.
3.) Endpoint 1-9:
a.) These endpoints are not of interest of this scenario as they will implement Bridge specific Matter capability.
b.) Bridged devices will be on the first free Endpoint and increment from there. (Max. 65536 Endpoints per device)
c.) Endpoint 1-9 are arbitrarily chosen as the number of endpoints would be Bridge implementation specific.
4.) Endpoint 10 (Light):
a.) Has the same Descriptor Cluster as the Bridge and will expose its DeviceTypes as Light, Bridged Device to directly indicate the user what kind of devices are bridged.
b.) The Bridged Device Basic Cluster is used to give other Matter devices information about the functionality or used technology (vendor name, model, or user assigned name) in this case the NodeLable attribute will show the light as “Mirror Light” a name given by the user.
c.) The remaining Cluster will implement the features of the device like OnOff-Cluster for turning the device on and off.
5.) Endpoint 11 (Laundry Machine):
a.) Descriptor Cluster will show device as Laundry Machine, Bridged Device.
b.) Bridged Device Basic Cluster will show the device with a Label: “Vendor X Machine”.
c.) The remaining Cluster will implement the features of the device like OnOff-Cluster for turning the device on and off.
6.) Endpoint 12 (Hygrometer):
a.) Descriptor Cluster will show the device as Hygrometer, Bridged Device.
b.) Bridged Device Basic Cluster will show the label: “Entrance Hygrometer“.
c.) Special about this device is that it is battery powered and such devices will need to implement two more clusters to inform the user about the current energy situation:
i.) Power Source Configuration Cluster will inform about on which Endpoint the power source can be found.
ii.) Power Source Cluster will tell the energy level, which kind of power source is its (e.g. replaceable battery), etc.
d.) The remaining Cluster will implement the features of the device like OnOff-Cluster for turning the device on and off.
7.) After the Matter Commissioner has learned about all the exposed devices they should be easy identify and to integrate in the current Matter Fabric.
In summary the Bridge should make it easy for the user to use existing devices within the Matter ecosystem.
Hands-on: ESP32 Matter Bridge
Now we leave our concept example and head over to our hands-on example. We will use the ESP32 hardware and a bridge example from the Matter repository. To setup the example follow these steps:
# Only perform this if you do not have the esp idf tool setup already.
mkdir ${HOME}/tools
cd ${HOME}/tools
git clone https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout v4.4
git submodule update --init
./install.sh
. ./export.sh
# Move to your matter repo
cd ~/connectedhomeip
git pull
# This will remove your enviromental settings just in case you have errors during the activate.
rm -r .environment
# Bootstrap and activate Matter repo
source ./scripts/bootstrap.sh
source ./scripts/activate.sh
# Move to example
cd examples/bridge-app/esp32
idf.py set-target esp32
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
Now we have the Matter Bridge flashed with the firmware, to continue we need to add the device as an existing node to our fabric like we done in Part 2 with the chip-tool.
./chip-tool pairing ble-wifi 12344323 "IoT Testing" NotTheRealPassword 20202021 3840
Now the Bridge is associated with our chip-tool and we can inspect the different clusters we already talked about.
We know from the README that the following (virtual) devices are available:
- Light1 at endpoint 3
- Light2 at endpoint 7
- Light3 at endpoint 5
- Light4 at endpoint 6
Lets take a look at the Bridges (Node: 12344323) Descriptor Cluster on Endpoint 0:
./chip-tool descriptor read device-list 12344323 0
The truncated output of the chip-tool:
[...]
[1657290058.991092][57239:57244] CHIP:TOO: Endpoint: 0 Cluster: 0x0000_001D Attribute 0x0000_0000 DataVersion: 3416323786
[1657290058.991108][57239:57244] CHIP:TOO: device list: 2 entries
[1657290058.991114][57239:57244] CHIP:TOO: [1]: {
[1657290058.991117][57239:57244] CHIP:TOO: Type: 22
[1657290058.991121][57239:57244] CHIP:TOO: Revision: 1
[1657290058.991125][57239:57244] CHIP:TOO: }
[1657290058.991129][57239:57244] CHIP:TOO: [2]: {
[1657290058.991132][57239:57244] CHIP:TOO: Type: 14
[1657290058.991134][57239:57244] CHIP:TOO: Revision: 1
[1657290058.991137][57239:57244] CHIP:TOO: }
[...]
If we take a look at the matter-device.xml we can see that:
- Type 22 (0x0016) is a “Matter Root Node”
- Type 14 (0x000e) is a “Matter Bridge”
Let’s take a look at the configured endpoints in parts-list:
./chip-tool descriptor read parts-list 12344323 0
The truncated output of the chip-tool:
[...]
[1657700077.871107][84013:84021] CHIP:TOO: Endpoint: 0 Cluster: 0x0000_001D Attribute 0x0000_0003 DataVersion: 3229110934
[1657700077.871128][84013:84021] CHIP:TOO: parts list: 5 entries
[1657700077.871134][84013:84021] CHIP:TOO: [1]: 1
[1657700077.871138][84013:84021] CHIP:TOO: [2]: 3
[1657700077.871142][84013:84021] CHIP:TOO: [3]: 6
[1657700077.871146][84013:84021] CHIP:TOO: [4]: 5
[1657700077.871150][84013:84021] CHIP:TOO: [5]: 7
[...]
Know we know we would need to query Endpoints 1,3,6,5,7.
Note about Endpoint order:
You might have noticed that the endpoints are in a weird order for the lights. The reason is that there are lights deleted and added dynamically in the source code to mimic a more realistic state on the bridge with old devices removed and new ones added.
Please refer to the source code in the main.cpp line 337 following.
Lets query the endpoint 1 for the device-list:
./chip-tool descriptor read device-list 12344323 1
The truncated output of the chip-tool:
[1657700147.909334][86373:86378] CHIP:TOO: Endpoint: 1 Cluster: 0x0000_001D Attribute 0x0000_0000 DataVersion: 176756417
[1657700147.909354][86373:86378] CHIP:TOO: device list: 1 entries
[1657700147.909370][86373:86378] CHIP:TOO: [1]: {
[1657700147.909377][86373:86378] CHIP:TOO: Type: 14
[1657700147.909381][86373:86378] CHIP:TOO: Revision: 1
[1657700147.909385][86373:86378] CHIP:TOO: }
Type 14 (0x000e) is a “Matter Bridge”. Endpoint 1 holds the application clusters for the Matter Bridge it self. This could range from OnOff Cluster to various other functionality implemented for the Bridge.
Lets check the other endpoints which are the bridged devices:
./chip-tool descriptor read device-list 12344323 3
[...]
[1657700367.445234][91280:91289] CHIP:TOO: Endpoint: 3 Cluster: 0x0000_001D Attribute 0x0000_0000 DataVersion: 553770957
[1657700367.445252][91280:91289] CHIP:TOO: device list: 1 entries
[1657700367.445267][91280:91289] CHIP:TOO: [1]: {
[1657700367.445276][91280:91289] CHIP:TOO: Type: 257
[1657700367.445282][91280:91289] CHIP:TOO: Revision: 1
[1657700367.445287][91280:91289] CHIP:TOO: }
[...]
Type 257 (0x0101) is a “Matter Dimmable Light“.
Endpoints 5,6,7 will return the same types:
./chip-tool descriptor read device-list 12344323 5
[...]
[1657700785.126684][99635:99640] CHIP:TOO: Endpoint: 5 Cluster: 0x0000_001D Attribute 0x0000_0000 DataVersion: 3152016014
[1657700785.126706][99635:99640] CHIP:TOO: device list: 2 entries
[1657700785.126717][99635:99640] CHIP:TOO: [1]: {
[1657700785.126724][99635:99640] CHIP:TOO: Type: 256
[1657700785.126728][99635:99640] CHIP:TOO: Revision: 1
[1657700785.126732][99635:99640] CHIP:TOO: }
[1657700785.126738][99635:99640] CHIP:TOO: [2]: {
[1657700785.126741][99635:99640] CHIP:TOO: Type: 19
[1657700785.126745][99635:99640] CHIP:TOO: Revision: 1
[1657700785.126748][99635:99640] CHIP:TOO: }
[...]
Type 257 (0x0100) is a “Matter On/Off Light“ and type 19 (0x0013) is a “Matter Bridged Device“.
Lets check the other clusters to see what more info we can get from the bridge.
Use node-lable to look up names of the lights:
./chip-tool bridgeddevicebasic read node-label 12344323 5
[...]
[1657702930.584221][153146:153151] CHIP:TOO: Endpoint: 5 Cluster: 0x0000_0039 Attribute 0x0000_0005 DataVersion: 2347267613
[1657702930.584234][153146:153151] CHIP:TOO: NodeLabel: Light 3
[...]
./chip-tool bridgeddevicebasic read node-label 12344323 6
[...]
[1657703305.955855][160146:160151] CHIP:TOO: Endpoint: 6 Cluster: 0x0000_0039 Attribute 0x0000_0005 DataVersion: 1372647712
[1657703305.955867][160146:160151] CHIP:TOO: NodeLabel: Light 4
[...]
./chip-tool bridgeddevicebasic read node-label 12344323 7
[...]
[1657703331.673510][161432:161437] CHIP:TOO: Endpoint: 7 Cluster: 0x0000_0039 Attribute 0x0000_0005 DataVersion: 2733600498
[1657703331.673521][161432:161437] CHIP:TOO: NodeLabel: Light 2
[...]
./chip-tool bridgeddevicebasic read node-label 12344323 2
[...]
[1657703349.844390][162619:162624] CHIP:TOO: Response Failure: IM Error 0x000005C3: General error: 0xc3 (UNSUPPORTED_CLUSTER)
[...]
./chip-tool bridgeddevicebasic read reachable 12344323 5
[...]
[1657703677.946278][173494:173499] CHIP:TOO: Endpoint: 5 Cluster: 0x0000_0039 Attribute 0x0000_0011 DataVersion: 2347267613
[1657703677.946363][173494:173499] CHIP:TOO: Reachable: TRUE
[...]
Unfortunately the logical information are not available as the Bridged Action cluster is not implemented for the ESP32 example.
Use the OnOff cluster in the same way as described in Part 2 of our series to turn the (virtual) lights on and off.
# ./chip-tool onoff toggle destination-id endpoint-id
./chip-tool onoff toggle 12344323 3
This concludes our Matter series, we worked from the concepts, over hands-on with Matter device (lights and switch) to a Bridge to use legacy device in our Matter Fabric.
Do you have any questions or would you like to realise a Matter project?
Patrick Sernetz – Head of Solution Architecture
Hi, I'm Patrick. Do you have any questions about Matter? Feel free to contact me by e-mail.