Pull request project-chip#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 <thomas.bowley@silabs.com>
Date:   Wed Oct 5 17:29:53 2022 +0200

    UIC-2478+UIC-2479: Refactored documentation for Unify Matter Bridge

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 

docs/silabs/README.md

@@ -22,15 +22,24 @@
     3. [Running Matter Demo over Wi-Fi](wifi/RUN_DEMO.md)
        <br><br>
 
-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)
+<br><br>
+
+6. Development using VS Code
 
     1. [Setting up environment](dev/vscode/SETUP.md)
     2. [Running tasks](dev/vscode/TASKS.md)
         1. [Build](dev/vscode/BUILD.md)
         2. [Flash](dev/vscode/FLASH.md)
         3. [Debug](dev/vscode/DEBUG.md) <br><br>
 
-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)<br><br>
 
-7. Frequently Asked Questions (FAQ) / Troubleshooting
+8. Frequently Asked Questions (FAQ) / Troubleshooting
 
     - [Thread FAQ](thread/FAQ.md)
     - [Wi-Fi FAQ](wifi/FAQ.md)

silabs_examples/unify-matter-bridge/readme_building.md

@@ -1,105 +1,108 @@
-# 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:/<dir>$ 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/<dir>$` 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.
 
 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:
 
 1. If you did not source the `matter/scripts/activate.sh` `gn` and other common
    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

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._...<br>
+...
+_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)