From 7ad317cdac5f3880120cd8fcf2bb79a06d7cdae1 Mon Sep 17 00:00:00 2001 From: Mathieu Kardous Date: Fri, 7 Oct 2022 14:34:20 +0000 Subject: [PATCH] Pull request #160: Cherry-Pick UIC-2478: Refactored documentation Merge in WMN_TOOLS/matter from cherry-pick/uic_documentation to silabs_1.0 Squashed commit of the following: commit a6267069748486e06480bceff0966d9454dde6e8 Author: Thomas Bowley Date: Fri Oct 7 14:06:13 2022 +0000 Pull request #151: UIC-2478: Refactored documentation Merge in WMN_TOOLS/matter from feature/UIC-2478-integrating-the-bridge-documentation-into-the-silabs-github-docs-build-guide to silabs Squashed commit of the following: commit b3b55278b471bb5d9bb7cf1cb0fd1c5d4d7797fd Author: Thomas Bowley Date: Wed Oct 5 17:29:53 2022 +0200 UIC-2478+UIC-2479: Refactored documentation for Unify Matter Bridge --- docs/silabs/OVERVIEW.md | 5 +- docs/silabs/README.md | 15 +- .../unify-matter-bridge/readme_building.md | 95 ++++--- .../unify-matter-bridge/readme_overview.md | 43 +++ .../unify-matter-bridge/readme_user.md | 263 ++++++++++-------- .../unify-matter-bridge/release_notes.md | 6 +- 6 files changed, 257 insertions(+), 170 deletions(-) create mode 100644 silabs_examples/unify-matter-bridge/readme_overview.md diff --git a/docs/silabs/OVERVIEW.md b/docs/silabs/OVERVIEW.md index 7da7b024c39df2..21629f2e91530d 100644 --- a/docs/silabs/OVERVIEW.md +++ b/docs/silabs/OVERVIEW.md @@ -2,13 +2,16 @@ Welcome to the Silicon Labs Matter user documentation set. This provides all of the information required to use the Matter demos or start development with Matter on the Thread and Wi-Fi transport protocols. -The Thread development use cases differs from Wi-Fi because the Thread protocol requires the use of an Open Thread Border Router (OTBR). +> **Note:** The Thread development use cases differs from Wi-Fi because the Thread protocol requires the use of an Open Thread Border Router (OTBR). + +> **Note:** The Matter Bridge development use cases differs from Wi-Fi because it requires the use of the [Unify Host SDK](https://www.silabs.com/developers/unify-sdk). This content covers - Software and Hardware prerequisites for working with Silicon Labs Matter. - [Thread demo and development information](./thread/DEMO_OVERVIEW.md) - [Wi-Fi demo and development information](./wifi/DEMO_OVERVIEW.md) +- [Getting started with Unify Matter Bridge](../../silabs_examples/unify-matter-bridge/readme_user.md#running-the-matter-bridge) - Information on using [VSCode and the provided container environment](./dev/vscode/SETUP.md) - A list of useful reference guides - Frequently asked questions about both Thread and Wi-Fi development diff --git a/docs/silabs/README.md b/docs/silabs/README.md index 865002ee9ddd23..397bb55383911b 100644 --- a/docs/silabs/README.md +++ b/docs/silabs/README.md @@ -22,7 +22,16 @@ 3. [Running Matter Demo over Wi-Fi](wifi/RUN_DEMO.md)

-5. Development using VS Code +5. Matter Bridging to Zigbee/Z-Wave + + 1. [Unify Matter Bridge Overview](../../silabs_examples/unify-matter-bridge/readme_overview.md) + 2. [Building the Matter Bridge](../../silabs_examples/unify-matter-bridge/readme_building.md) + 3. [Getting Started](../../silabs_examples/unify-matter-bridge/readme_user.md#Running-the-Matter-Bridge) + 4. [Control a Z-Wave OnOff device](../../silabs_examples/unify-matter-bridge/readme_user.md#Testing-the-bridge-using-the-chip-tool) + 5. [Toggle a group of OnOff devices](../../silabs_examples/unify-matter-bridge/readme_user.md#toggle-a-group-of-onoff-devices) +

+ +6. Development using VS Code 1. [Setting up environment](dev/vscode/SETUP.md) 2. [Running tasks](dev/vscode/TASKS.md) @@ -30,7 +39,7 @@ 2. [Flash](dev/vscode/FLASH.md) 3. [Debug](dev/vscode/DEBUG.md)

-6. Reference Guides +7. Reference Guides 1. [Matter Hardware Requirements](general/HARDWARE_REQUIREMENTS.md) 2. [Matter Software Requirements](general/SOFTWARE_REQUIREMENTS.md) @@ -47,7 +56,7 @@ 13. [Using Simplicity Studio's Energy Profiler with Matter](./general/EP.md) 14. [Using Wireshark to Capture Network Traffic in Matter](./general/WIRESHARK.md)

-7. Frequently Asked Questions (FAQ) / Troubleshooting +8. Frequently Asked Questions (FAQ) / Troubleshooting - [Thread FAQ](thread/FAQ.md) - [Wi-Fi FAQ](wifi/FAQ.md) diff --git a/silabs_examples/unify-matter-bridge/readme_building.md b/silabs_examples/unify-matter-bridge/readme_building.md index d861b788572e83..0f980d3b75375c 100644 --- a/silabs_examples/unify-matter-bridge/readme_building.md +++ b/silabs_examples/unify-matter-bridge/readme_building.md @@ -1,89 +1,92 @@ -# Unify Matter Bridge +# Building the Unify Matter Bridge -The Unify Matter Bridge bridges the Matter ecosystem with the Unify ecosystem. +This build guide cross compiles for armhf architecture to be run on Unify's reference platform - a RPi4 with the 32-bit version of Debian Buster. -## Building the Unify Matter Bridge +> **Note:** +> In the following subsections the commands should either be run on your local development machine or inside a running Docker container. +> - _some-command_ should be executed on your local machine. +> - _`dev-machine:~$ some-command`_ +> - _some-other-command_ should be executed inside the Docker container. +> - _`root@docker:/$ some-other-command`_ -This building guide cross compiles for armhf architecture. +## Checkout submodules -Pay attention to if the command should be executed on the host machine or inside -of the docker build environment. A `docker/$` means inside the docker and -docker left out means on your host machine. - -### Checkout submodules - -For the Unify bridge we checkout the necessary submodules with the below -command. +For the Unify bridge we checkout the necessary submodules with the below command. ```bash -matter$ ./scripts/checkout_submodules.py --platform linux +dev-machine:~$ ./scripts/checkout_submodules.py --platform linux ``` -### Downloading and staging the uic repo +## Downloading and staging the uic repo ```bash -matter$ git clone --depth 1 --branch ver_1.2.1-103-g34db9516-unify-matter-bridge ssh://git@stash.silabs.com/uic/uic.git --recursive ../uic +dev-machine:~$ git clone --depth 1 --branch external/matter-bridge-unstable https://github.com/SiliconLabs/UnifySDK.git --recursive ../uic-matter ``` -#### Build the docker container (armhf compilation) +### Build the docker container (armhf compilation) ```bash -matter$ docker build -t unify-matter silabs_examples/unify-matter-bridge/docker/ +dev-machine:~$ docker build -t unify-matter silabs_examples/unify-matter-bridge/docker/ ``` Starting the docker: ```bash -matter$ docker run -it -v $PWD:/matter -v $PWD/../uic:/uic unify-matter +dev-machine:~$ docker run -it -v $PWD:/matter -v $PWD/../uic-matter:/uic unify-matter ``` -#### Building libunify +### Building libunify -The Unify Matter Bridge is depending on the libunify library from the Unify -project. +The Unify Matter Bridge is depending on the libunify library from the Unify project. -This library must first be compiled for the target system +This library must first be compiled for the target system, by changing directory to the `/uic` folder and running the following: ```bash -docker/uic$ cmake -DCMAKE_INSTALL_PREFIX=$PWD/stage -GNinja -DCMAKE_TOOLCHAIN_FILE=../cmake/armhf_debian.cmake -B build_unify_armhf/ -S components -docker/uic$ cmake --build build_unify_armhf -docker/uic$ cmake --install build_unify_armhf --prefix $PWD/stage +root@docker:/uic$ cmake -DCMAKE_INSTALL_PREFIX=$PWD/stage -GNinja -DCMAKE_TOOLCHAIN_FILE=../cmake/armhf_debian.cmake -B build_unify_armhf/ -S components +root@docker:/uic$ cmake --build build_unify_armhf +root@docker:/uic$ cmake --install build_unify_armhf --prefix $PWD/stage ``` -After having cross compiled unify library we set two paths in the -PKG_CONFIG_PATH. The first path is for the staged unify library and the second -one is for cross compiling to armhf. +After having cross compiled the Unify library we set two paths in the PKG_CONFIG_PATH. +The first path is for the staged Unify library and the second one is for cross compiling to armhf. ```bash -docker/uic$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$PWD/stage/share/pkgconfig -docker/uic$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/lib/arm-linux-gnueabihf/pkgconfig +root@docker:/uic$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$PWD/stage/share/pkgconfig +root@docker:/uic$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/lib/arm-linux-gnueabihf/pkgconfig ``` -### Setup the matter build environment +### Setup the Matter build environment -Now setup the matter environment. +Now setup the Matter environment. -After having all the necessary submodules source the environment of matter with -the below command. The source command will load a number of build tools, and -will make sure the correct toolchains and compilers are used for compiling the -unify matter bridge. +After having all the necessary submodules source the environment of Matter with the below command. +The source command will load a number of build tools, and will make sure the correct toolchains and compilers are used for compiling the Unify Matter Bridge. ```bash -docker$ source ./scripts/activate.sh +root@docker:/matter$ source ./scripts/activate.sh ``` -Compile the Unify bridge +### Compile the Unify bridge ```bash -docker/matter$ cd silabs_examples/unify-matter-bridge/linux/ -docker/silabs_examples/unify-matter-bridge/linux$ gn gen out/armhf --args='target_cpu="arm"' -docker/silabs_examples/unify-matter-bridge/linux$ ninja -C out/armhf +root@docker:/matter$ cd silabs_examples/unify-matter-bridge/linux/ +root@docker:/matter/silabs_examples/unify-matter-bridge/linux$ gn gen out/armhf --args='target_cpu="arm"' +root@docker:/matter/silabs_examples/unify-matter-bridge/linux$ ninja -C out/armhf ``` -After building the unify-matter-bridge binary is located at -`out/armhf/obj/bin/unify-matter-bridge`. +After building, the `unify-matter-bridge` binary is located at `/matter/silabs_examples/unify-matter-bridge/linux/out/armhf/obj/bin/unify-matter-bridge`. + +### Compile the chip-tool + +The `chip-tool`is a CLI tool that can be used to commission the bridge and to control end devices. +```bash +root@docker:/matter$ cd examples/chip-tool +root@docker:/matter/examples/chip-tool$ gn gen out/armhf --args='target_cpu="arm"' +root@docker:/matter/examples/chip-tool$ ninja -C out/armhf +``` +After building the chip-tool binary is located at `/matter/examples/chip-tool/out/armhf/obj/bin/chip-tool`. -### Unit testing +### Unit Testing It is always preferable to write unit testing for quality software. So we encourage to do this when developing for the Unify Matter Bridge. @@ -91,7 +94,7 @@ encourage to do this when developing for the Unify Matter Bridge. Documentation on unit testing can be found within the [README.md](linux/src/tests/README.md) of the `linux/src/tests` folder. -### Trouble shooting +### Troubleshooting Common errors one might encounter: @@ -99,7 +102,7 @@ Common errors one might encounter: build tools won't be found. 2. If you did not export the `pkgconfig` for the `arm-linux-gnueabihf` toolchain you will get errors such as `G_STATIC_ASSERT(sizeof (unsigned long long) == sizeof (guint64));` -3. If you are compiling unit tests do not try to compile the matter bridge at +3. If you are compiling unit tests do not try to compile the Unify Matter Bridge at the same time. This will not work as when compiling unit tests you are also compiling unit tests for all other sub components. 4. If you are encountering errors linking to `libunify` try to redo the compile diff --git a/silabs_examples/unify-matter-bridge/readme_overview.md b/silabs_examples/unify-matter-bridge/readme_overview.md new file mode 100644 index 00000000000000..a9dc97a0460ca0 --- /dev/null +++ b/silabs_examples/unify-matter-bridge/readme_overview.md @@ -0,0 +1,43 @@ +# Unify Matter Bridge Overview + +_[The Unify Host SDK](https://github.com/SiliconLabs/UnifySDK) provides the fastest path for bridging Matter and other protocols as well as a development environment for connecting to ecosystems such as Google Home._ - [https://www.silabs.com/wireless/matter] + +"_The Unify Framework provides software source code and binary packages for Raspberry Pi 4 to help build an IoT gateway product. +The Unify Framework enables an IoT service to control and manage end nodes in several wireless PHY radios (e.g., Z-Wave, Zigbee, and so on) supported by Silicon Labs. +The Unify Framework uses the Unify Controller Language (UCL) as an internal abstraction layer to seamlessly control various end nodes that are enabled with multiple wireless PHY radios. +The detailed architecture of the Unify Framework is described in the Unify Framework Specification._...
+... +_A Unify gateway consists of a Message Queuing Telemetry Transport (MQTT) broker and a number of MQTT clients. The Unify Framework uses the Mosquitto MQTT broker."_ - [https://siliconlabs.github.io/UnifySDK/doc/UnifySDK.html]. + +## Matter Bridge as an IoT Service + +The Unify Matter Bridge is an Unify IoT Service that allows for control of Unify devices from a Matter fabric. +It translates Matter cluster commands and attributes accesses into the corresponding Unify MQTT publish messages. +Unify node attributes are readable from the Matter Fabric, eg. in your Google Home App, as the Unify Matter Bridge also caches the state of those attributes. + +The Unify data model is largely based on the same data model as Matter, making the job of the Unify Matter Bridge relatively simple. +There is almost a 1-1 relationship between the Matter commands and attributes and the Unify command and attributes. + +> **Note:** Currently there is no control going the other way, that is, the Unify Matter Bridge can not '_see_' what else is on the Matter Fabric, let alone control end devices in the Matter Fabric. + +See the [release notes for the Unify Matter Bridge](release_notes.md) for details on feature additions, bug fixes and known issues. + +## Supported Clusters/Devices + +The Unify Matter bridge currently supports the mapping of the following clusters/device types. + +| Cluster | +|---------------------| +| Bridged Device Info | +| Group | +| Identify | +| Level | +| OnOff | + +## Further Reading + +- [Unify Host SDK Documentation](https://siliconlabs.github.io/UnifySDK/doc/UnifySDK.html) +- [Building the Matter Bridge](./readme_building.md) +- [Getting Started](./readme_user.md#running-the-matter-bridge) +- [Control a Z-Wave OnOff device](./readme_user.md#toggle-an-onoff-device) +- [Toggle a group of OnOff devices](./readme_user.md#toggle-a-group-of-onoff-devices) diff --git a/silabs_examples/unify-matter-bridge/readme_user.md b/silabs_examples/unify-matter-bridge/readme_user.md index 1bed5670ebb199..8d730faac7f968 100644 --- a/silabs_examples/unify-matter-bridge/readme_user.md +++ b/silabs_examples/unify-matter-bridge/readme_user.md @@ -1,140 +1,134 @@ # Matter Bridge User's Guide -This guide describes how to use the unify matter bridge. - -The unify matter bridge is a Unify IoT service that allows control of Unify -devices from a matter fabric. The bridge translates matter cluster commands and -attributes accesses into the corresponding Unify MQTT publish messages. The -bridge also caches the state of Unify node attributes and make those attribute -readable on the matter fabric. - -## Command line arguments - -Using the _--help_ the following help text appear +The Unify Matter Bridge is a Unify IoT Service that allows interaction with Unify devices from a Matter fabric. +For a more thorough description, have a look at the [Unify Matter Bridge Overview](../../silabs_examples/unify-matter-bridge/readme_overview.md). + +As a prerequisite for the Matter Bridge to work, at least one Unify protocol controller should be set up and running. +For now we will assume that you have setup the Z-Wave Protocol Controller (uic-zpc) to run on a Raspberry Pi 4 and connected it to an MQTT broker in your network. +Read the [Unify Host SDK's Getting Started Guide](https://siliconlabs.github.io/UnifySDK/doc/getting_started.html) for information on how to set this up. + +Once a protocol controller is running, the Matter Bridge can be started. + +The following assumes that you have build the Unify Matter Bridge application by following the _[Build Guide](./readme_building.md)_ and have transferred the _`unify-matter-bridge`_ to your RPi4 running the 32-bit version of Debian Buster. + +> **Note:** +> +> The requirements for using the Matter Bridge with the Google Home App (GHA) are: +> +> - Inclusion to the [Matter Early Access Program (EAP)](https://developers.home.google.com/matter/eap/) is required. +> - A project properly configured in the [Google Home Developer Console](https://console.home.google.com/projects). +> - Only a specific version of the Google Home App for Android is supported. +> +> +> This guide will use the CLI tool called _`chip-tool`_ for commissioning and device control. + +
+ +- [Running the Matter Bridge](#running-the-matter-bridge) + - [Important configurations](#important-configurations) +- [Commissioning the bridge to a network](#commissioning-the-bridge-to-a-network) +- [Testing the bridge using the chip tool](#testing-the-bridge-using-the-chip-tool) +- [Sending a group command](#sending-a-group-command) +- [Command line arguments](#command-line-arguments) + +## Running the Matter Bridge + +At start up, the Matter Bridge needs to connect to the Matter Fabric as well as the MQTT Broker. +It is therefore crucial that you have access to port 1883, the default MQTT Broker's port, as well as a network setup that allows mDNS through. + +There are a few important runtime configurations that needs to be considered as well as some other configuration options. +A full list of commandline parameters is listed are the [Command line arguments](#command-line-arguments) section. + +### Important configurations +- #### Network Interface + Choosing the network interface on which the Matter Fabric runs - ie. on a regular RPi4 setup it would be `wlan0` for WiFi and `eth0` for ethernet. + Specify this with the '`--interface`' argument, as such: + ```bash + ./unify-matter-bridge --interface eth0 + ``` + +- #### Key-Value store (KVS) + The Matter Bridge uses a Key-Value store for persisting various run-time configurations. + Make sure to have read/write access to the default path '`/var/chip_unify_bridge.kvs`' or provide the path to where it is allowed to write this data to. + If you delete this file prior to start up, you will reset everything and the bridge will not belong to any Matter Fabric until it has yet again been comissioned. + ```bash + ./unify-matter-bridge --kvs ./matter-bridge.kvs + ``` + +- #### MQTT Host + If you have followed the [Unify Host SDK's Getting Started Guide](https://siliconlabs.github.io/UnifySDK/doc/getting_started.html) to the letter, your MQTT Broker should be running on '`localhost`'. + In the case where you have decided to run the MQTT broker on a different host, you can tell the Unify Matter Bridge to connect to a different host. + ```bash + ./unify-matter-bridge --mqtt.host 10.0.0.42 + ``` + +- #### Vendor and Product ID + If you do have access to the EAP, and you want to use the Google Home App, you need to set a specific VID and PID for the Matter Bridge. + This can be done in the following way: + ```bash + ./unify-matter-bridge --vendor fff1 --product 8001 + ``` + +### Starting the Matter Bridge +Now that you have decided on the configuration parameters it is time to start the bridge application. ```bash -Usage: ./applications/matter_bridge/unify_matter_bridge [Options] - -Options: - --conf arg (=/etc/uic/uic.cfg) Config file in YAML format. UIC_CONF - env variable can be set to override the - default config file path - --help Print this help message and quit - --dump-config Dumps the current configuration on a - YAML config file format that can be - passed to --conf option - --version Print version information and quit - -Following options can also be in a Config file. - Options and values passed on command line here take precedence over the options and values in config file: - --log.level arg (=i) Log Level (d,i,w,e,c) - --log.tag_level arg Tag based log level - Format: :, - :, ... - --interface arg (=en0) Ethernet interface to use - --kvs arg (=/tmp/chip_unify_bridge.kvs) - Matter key value store path - --vendor arg (=65521) Vendor ID - --product arg (=32769) Product ID - --mqtt.host arg (=localhost) MQTT broker hostname or IP - --mqtt.port arg (=1883) MQTT broker port - --mqtt.cafile arg Path to file containing the PEM encoded - CA certificate to connect to Mosquitto - MQTT broker for TLS encryption - --mqtt.certfile arg Path to file containing the PEM encoded - client certificate to connect to - Mosquitto MQTT broker for TLS - encryption - --mqtt.keyfile arg Path to a file containing the PEM - encoded unencrypted private key for - this client - --mqtt.client_id arg (=unify_matter_bridge_71460) - Set the MQTT client ID of the - application. +./unify-matter-bridge --interface eth0 --kvs ./matter-bridge.kvs --mqtt.host localhost --mqtt.port 1337 ``` -## How it works +## Commissioning the bridge to a network -The Unify Matter Bridge acts as a Unify IoT service. The Unify data model -is largely based on the same data model as Matter, making the job of the Unify -Matter Bridge relatively simple. There is almost a 1-1 correspondence between -the Matter commands and attributes and the Unify command and attributes. +For the bridge to be included into the Matter network, it needs to be commissioned. +The first time the bridge starts it will automatically go into commissioning mode, after 10 minutes the bridge will exit commissioning mode again. +If the bridge has not been commissioned within this window, the application must be restarted to open the commissioning window again or you can +write `commission` in the CLI when running the bridge. -## Using the matter bridge +The Unify Matter Bridge uses the "On Network" commissioning method - for now there is no Bluetooth commissioning support. -As a prerequisite for the matter bridge to work at least one Unify protocol -controller should be set up and running. Read the [Unify User Guide](../../doc/user_guide.md) -for information on how to set this up. - -Once a protocol controller is running on the system the matter bridge can be -started, by executing the following command +The commisioning procedure requires a pairing code to be used. +This pairing code is written to the console when running the Matter Bridge. +Look for something similar to the following example with a pairing code of '`MT:-24J029Q00KA0648G00`': +This code can be used when commissioning with the CLI commissioning tool `chip-tool`. ```bash -sudo systemctl start uic-matter-bridge -```` - -To monitor the log output of the bridge use this command: - -```bash -journalctl -f -u uic-matter-bridge +[1659615301.367669][1967:1967] CHIP:SVR: SetupQRCode: [MT:-24J029Q00KA0648G00] ``` -### Commissioning the bridge to a network - -The first time the bridge starts it will automatically go into commissioning mode, after -10 minutes the bridge will exit commissioning mode again. If the bridge has not been -commissioned within this window the application must be restarted to open the commissioning window again. - -The Unify Matter Bridge uses the "On Network" commissioning method, ie there is no -Bluetooth or WiFI involved. - -To obtain the QR commissioning code run the following command: +For a simpler, more userfriendly way of commmissioning, one could use the Google Home App with a QR code containing the pairing code. +The QR code can be obtained by following the link seen in the console, similar to the line below: ```bash -journalctl -u uic-matter-bridge | grep qrcode | tail -1 -Aug 04 14:15:01 raspberrypi unify_matter_bridge[1967]: [1659615301.367723][1967:1967] CHIP:SVR: https://dhrishi.github.io/connectedhomeip/qrcode.html?data=MT%3A-24J029Q00KA0648G00 +[1659615301.367723][1967:1967] CHIP:SVR: https://dhrishi.github.io/connectedhomeip/qrcode.html?data=MT%3A-24J029Q00KA0648G00 ``` -Open the printed link in a browser to get the QR code. It should be noted that the commissioner -must be on the same network as the raspberry pi. Also, note that by default the bridge binds -to the eth0 interface. If another interface is to be used this must be set using the -`--interface` command argument. - -In case of commission with the matter chip tool, the raw QR code string should be obtained: - -```bash -journalctl -u uic-matter-bridge | grep QRCode | tail -1 -Aug 04 14:15:01 raspberrypi unify_matter_bridge[1967]: [1659615301.367669][1967:1967] CHIP:SVR: SetupQRCode: [MT:-24J029Q00KA0648G00] -``` +It should be noted that the commissioner **must** be on the same network as the Raspberry Pi. +Please note that by default the bridge binds to the eth0 interface. +If another interface is to be used have a look at the description of the commandline arguments for setting [Network Interface](#network-interface). -### Testing the bridge using the chip tool +### Using the chip-tool to commission -To commission the matter bridge with the `chip-tool` and assign the bridge node id 1 -run the following command: +In the following make sure to use the pairing code taken from the console output, as described above. +To commission the Matter Bridge with the `chip-tool` and assign the bridge the Node ID 1: ```bash -chip-tool pairing qrcode 1 MT:-24J0AFN00KA0648G00 +chip-tool pairing code 1 MT:-24J0AFN00KA0648G00 ``` -To send a command OnOff cluster Toggle command to an endpoint on the bridge +### Toggle an OnOff device +To send a command OnOff cluster Toggle command to a bridged endpoint with id 2, via Matter Fabric Node ID 1: ```bash chip-tool onoff toggle 1 2 ``` -Here the bridge is node matter fabric node id 1 and the bridged endpoint is 2 +For further information on how to use the `chip-tool` see the [chip-tool manual](../../docs/guides/chip_tool_guide.md) on the Matter website. -For further information on how to use the `chip-tool` see the [chip-tool manual](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/chip_tool_guide.md) -on the Matter website. +## Toggle a group of OnOff devices -### Sending a group command +The Matter Bridge has support for forwarding group messages from the Matter Fabric to Unify Nodes. +The protocol controllers will send the group messages as actual group cast messages on the destination network(Z-Wave/ZigBee). -The matter bridge has support for forwarding group messages from the matter fabric to Unify -Nodes. The protocol controllers will send the group messages as actual group cast messages -on the destination network(Z-Wave/ZigBee). - -To send a group command, the group keys must first be set up in the bridge, again here -the bridge is assumed to be node id 1, we add the keyset id 42 to group id 1: +To send a group command, the group keys must first be set up in the bridge, again here the bridge is assumed to be Node ID 1, we add the GroupKeySetID 42 to Group ID 1: ```bash chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null },{"fabricIndex": 1, "privilege": 4, "authMode": 3, "subjects": [1], "targets": null }]' 1 0 @@ -142,13 +136,13 @@ chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 42, "groupKeySecur chip-tool groupkeymanagement write group-key-map '[{"groupId": 1, "groupKeySetID": 42, "fabricIndex": 1}]' 1 0 ``` -Now we can add bridge endpoint 2 to group id 0x0001 +Now we can add bridge endpoint 2 to Group ID 0x0001 ```bash chip-tool groups add-group 0x0001 grp1 1 2 ``` -Now we need to program the chip tool: +Now we need to program the chip-tool: ```bash chip-tool groupsettings add-group grp1 0x0002 @@ -171,14 +165,49 @@ Finally, a multicast command may be sent using the chip-tool ./chip-tool onoff toggle 0xffffffffffff0001 1 ``` -## Supported Clusters +## Command line arguments + +The Unify Matter Bridge provides the following command line arguments: + +Using the _--help_ the following help text appear. -The Unify Matter bridge currently supports the mapping of the following clusters +```bash +Usage: ./unify_matter_bridge [Options] -| Cluster | -|---------------------| -| Bridged Device Info | -| Group | -| Identify | -| Level | -| OnOff | +Options: + --conf arg (=/etc/uic/uic.cfg) Config file in YAML format. UIC_CONF + env variable can be set to override the + default config file path + --help Print this help message and quit + --dump-config Dumps the current configuration on a + YAML config file format that can be + passed to --conf option + --version Print version information and quit + +Following options can also be in a Config file. + Options and values passed on command line here take precedence over the options and values in config file: + --log.level arg (=i) Log Level (d,i,w,e,c) + --log.tag_level arg Tag based log level + Format: :, + :, ... + --interface arg (=en0) Ethernet interface to use + --kvs arg (=/var/chip_unify_bridge.kvs) + Matter key value store path + --vendor arg (=65521) Vendor ID + --product arg (=32769) Product ID + --mqtt.host arg (=localhost) MQTT broker hostname or IP + --mqtt.port arg (=1883) MQTT broker port + --mqtt.cafile arg Path to file containing the PEM encoded + CA certificate to connect to Mosquitto + MQTT broker for TLS encryption + --mqtt.certfile arg Path to file containing the PEM encoded + client certificate to connect to + Mosquitto MQTT broker for TLS + encryption + --mqtt.keyfile arg Path to a file containing the PEM + encoded unencrypted private key for + this client + --mqtt.client_id arg (=unify_matter_bridge_71460) + Set the MQTT client ID of the + application. +``` diff --git a/silabs_examples/unify-matter-bridge/release_notes.md b/silabs_examples/unify-matter-bridge/release_notes.md index 3714878f111f1b..b331e8c9eb56d3 100644 --- a/silabs_examples/unify-matter-bridge/release_notes.md +++ b/silabs_examples/unify-matter-bridge/release_notes.md @@ -5,11 +5,11 @@ ### Fixed - Fixed the issue of the bridge service does not persists mapping between endpoint numbers and - unify UNIDs. As a consequence the endpoints may swap ids on each program + Unify UNIDs. As a consequence the endpoints may swap ids on each program startup. -- Fixed the issue of group mapping does not check for existing unify groups. As a consequence the - matter bridge may use an already assigned unify group. +- Fixed the issue of group mapping does not check for existing Unify groups. As a consequence the + Matter Bridge may use an already assigned Unify group. ### Added