Pull request project-chip#12: Matter documentation

Merge in WMN_TOOLS/matter from matter-documentation to silabs

Squashed commit of the following:

commit e8146293fbd04a20fc6d6a7997731d714271cceb
Author: Shayna Kaushal <[email protected]>
Date:   Thu Jul 21 12:53:24 2022 -0400

    [wifi] flow

commit df0bfc5d938e139ed8fbcfdd4dbbcb5eb280b43a
Author: Ezra Hale <[email protected]>
Date:   Thu Jul 21 10:37:06 2022 -0400

    updated release version links

commit 1c2445e0d2f7a9fcd467635958d1361c99fb070b
Author: Ezra Hale <[email protected]>
Date:   Thu Jul 21 10:20:06 2022 -0400

    fixed broken link in doc

commit 0353026f6d24a5c03be7ab751232bb1a04b48814
Author: Ezra Hale <[email protected]>
Date:   Thu Jul 21 09:39:59 2022 -0400

    updated

commit 7fff13c2087349701291f7d49132f88e6b1e3c4b
Author: Ezra Hale <[email protected]>
Date:   Thu Jul 21 09:36:23 2022 -0400

    added links

commit 20265a85d2e4ef9951f69e9c6b82c2e673a3c3ff
Author: Ezra Hale <[email protected]>
Date:   Thu Jul 21 08:58:48 2022 -0400

    updated location of pi image

commit 52cd19670d0d5e07ee62b961f142e296b2214703
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 14:44:47 2022 -0400

    updated title

commit 23132dd01ccc4e3bad0196a1de88e123d4ff89e7
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 14:43:33 2022 -0400

    updated some language

commit 3392b1eae54510f0470d656492c4cb1940ec3518
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 14:40:30 2022 -0400

    added header to Matter README.md

commit b1427675245daac4c223ee9bc3284ebddfb022ce
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 13:55:31 2022 -0400

    small edit

commit 16483955fa46c4415275b6e14810f21231acde0f
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 13:53:58 2022 -0400

    update doc in build and flash

commit e34b02701f18ece1a87e03df5164cf142bd9b685
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 13:47:03 2022 -0400

    updated link on build and flash

commit 5fd1f9330a89f8b6b8ac3ba87d0708c8fbe78b12
Author: Ezra Hale <[email protected]>
Date:   Wed Jul 20 09:46:55 2022 -0400

    updated links and supported platforms

commit f83790ae5ad212714f2a3149ca22033125262c50
Author: jepenven-silabs <[email protected]>
Date:   Tue Jul 19 14:31:52 2022 -0400

    cleanup documentation

commit 02221236ea0c17fa9051d115b174763353f49b76
Author: Ezra Hale <[email protected]>
Date:   Tue Jun 28 13:39:23 2022 -0400

    first commit of matter documentation

README.md

@@ -1,4 +1,9 @@
-# Matter
+# Silicon Labs Matter
+
+Welcome to the Silicon Labs Matter Github repo. This is your one stop shop for all things related to Silicon Labs and Matter development. To develop a Matter application with Silicon Labs please start here: [Silicon Labs Matter Table of Contents](./docs/silabs/README.md)
+
+<BR>
+
 
 [![Builds](https://github.com/project-chip/connectedhomeip/workflows/Builds/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/build.yaml)
 

docs/silabs/OVERVIEW.md

@@ -0,0 +1,15 @@
+[<< Back to TOC](./README.md)
+
+# Silicon Labs Matter Repo Overview
+
+Welcome to the Silicon Labs Matter Repo. For more information on Matter in general please checkout the main Matter Overview page located here [Matter Overview](../../README.md)
+
+Silicon Labs supports Matter on both 802.15.4 (Thread) and 802.11 (Wifi) transport protocols. 
+
+This Repo is the starting point for all Silicon Labs related Matter development. In this repo you will find documentation, demos, examples and all the code needed for Matter Accessory Device development on both Thread and Wifi.
+
+The Thread and Wifi development use cases differ because the Thread protocol requires the use of an Open Thread Border Router (OTBR).
+
+The Thread development use case is described in the Thread section of this documentation located here: [Matter Thread](./thread/THREAD.md)
+
+The Wifi development use case is described in the Wifi section of this documentation located here: [Matter Wifi](./wifi/WIFI.md)

docs/silabs/README.md

@@ -0,0 +1,56 @@
+# Silicon Labs Matter Table of Contents
+
+1. [Silicon Labs Matter Overview](OVERVIEW.md) <br>
+
+2. [Matter over Thread \(15.4\)](thread/THREAD.md)
+
+    1. [Matter Thread Demo Overview](thread/DEMO_OVERVIEW.md)
+    2. [Matter Thread Demo Prerequisites](thread/THREAD_PREREQS.md)
+    3. [Loading the Raspberry Pi image onto the Matter Hub](thread/RASPI_IMG.md)
+    4. [Setting up the RCP](thread/RCP.md)
+    5. [Creating your first Matter Device](thread/BUILD_FLASH_MAD.md)
+    6. [Using the Chip-Tool](thread/CHIP_TOOL.md)<BR> <BR>
+
+3. [Matter over Wifi](wifi/WIFI.md)
+
+    1. [Matter Wifi Demo Overview](wifi/DEMO_OVERVIEW.md)
+    2. [Matter Wifi Demo Prerequisites](wifi/WIFI_PREREQS.md)
+    3. [Building Linux Environment](wifi/BUILD_CHIP_ENV.md)
+    4. [Building Raspberry Pi Environment](wifi/BUILD_PI_ENV.md)
+    5. [Software Setup](wifi/SW_SETUP.md)
+    6. [Running Matter Demo over Wifi using Linux](wifi/RUN_DEMO.md)
+    7. [optional]
+       [Running Matter Demo over Wifi using Android](wifi/WIFI_ANDROID.md)
+       <br><br>
+
+4. Reference Guides
+
+    1. [How to Flash a Silicon Labs Device](general/FLASH_SILABS_DEVICE.md)
+    2. [How to Find Your Raspberry Pi](general/FIND_RASPI.md)
+    3. [Silicon Labs Matter Commit Hashes](general/COMMIT_HASHES.md) <br><br>
+
+5. Frequently Asked Questions (FAQ)
+    - [Thread FAQ](thread/FAQ.md)
+    - [Wifi FAQ](wifi/FAQ.md)
+
+<!--
+(WIP)
+Matter Setup for Development
+Download Silicon Labs Matter Repo
+Setup VSCode
+Create a new sample application
+Build ( 1 task)
+Debug (1 task)
+Edit
+ZAP (Standalone) (1 task)
+Pin Tool (Studio) (1 task)
+BLE Configurator (Studio) (1 task)
+Build Arguments (Sleepy End Device) (1 task)
+Monitor Network (Wireshark, Studio) (1 task)
+Bootloader (Studio) (1 task)
+Energy Profiler (Studio) (1 task)
+Studio Integration
+Metadata for Matter SDK
+Misc
+Non Raspi based controllers
+-->

docs/silabs/dev/DEV.md

@@ -0,0 +1 @@
+[<< Back to TOC](../README.md)

docs/silabs/dev/setup/VSCODE_SETUP.md

@@ -0,0 +1,3 @@
+[<< Back to TOC](../../README.md)
+
+todo: [link](https://github.com/project-chip/connectedhomeip/blob/master/docs/VSCODE_DEVELOPMENT.md)

docs/silabs/general/ARTIFACTS.md

@@ -0,0 +1,40 @@
+[<< Back to TOC](../README.md)
+
+# Matter Software Artifacts
+This page provides links to pre-built software image "artifacts" that can be used to set up the Matter Demo for the Thread and Wifi use cases.
+
+<br>
+
+## Matter Hub Raspberry Pi Image
+The Matter Hub image is intended to be flashed onto an SD card for a Raspberry Pi. The Matter Hub Image provides both an Open Thread Border Router and the Matter "ChipTool". Please download the Matter Hub Raspberry Pi image here. Note the image is ~10GB in size so depending on your internet connection this download may take some time. 
+
+https://www.silabs.com/documents/public/software/SilabsMatterPi.zip
+
+<br>
+
+## Radio Co-Processor (RCP) Images 
+The Radio Co-Processor firmware is used to turn an EFR into an RCP that can be used with a Raspberry Pi to allow the Raspberry Pi's Open Thread Border Router to access the Thread network. Radio Co-Processor (RCP) images are available in the Assets section of this page, here: 
+
+https://github.com/SiliconLabs/matter/releases/tag/v0.1.0
+
+<br>
+
+## Matter Accessory Device Images
+The Matter Accessory Device Images are used to turn an EFR into a Matter device. These are pre-built binary images for the Matter Demo. Matter Accessory Device Images are located in the Assets section of this page: 
+
+https://github.com/SiliconLabs/matter/releases/tag/v0.1.0
+
+<br>
+
+<!--
+## Matter Chip Tool Android APK
+Matter Chip Tool .apk file is located here: http://silabs.com
+
+<br>
+-->
+
+## RS9116 Firmware
+The RS9116 firmware is used to update the RS9116. 
+RS9116 Firmware is located in GitHub here: 
+
+https://github.com/SiliconLabs/wiseconnect-wifi-bt-sdk/tree/2.5.0/firmware

docs/silabs/general/COMMIT_HASHES.md

@@ -0,0 +1,30 @@
+[<< Back to TOC](../README.md)
+
+# Matter Repositories and Commit Hashes
+
+The following repositories, branches and commit hashes are to be used together
+in this release of the Silicon Labs Matter Out of Box Experience
+
+## Open Thread Border Router (OTBR)
+
+| Repo                                       | Branch | Commit Hash                              |
+| ------------------------------------------ | ------ | ---------------------------------------- |
+| https://github.com/SiliconLabs/ot-br-posix | main   | 1813352247aa60fb8993773918f1e5b4af6f3b79 |
+
+## Radio Co-Processor (RCP)
+
+| Repo                                    | Branch | Commit Hash                              |
+| --------------------------------------- | ------ | ---------------------------------------- |
+| https://github.com/SiliconLabs/ot-efr32 | main   | 7a567da02a078546eb34136c1c44170c8832dd55 |
+
+## Matter ChipTool
+
+| Repo                                            | Branch | Commit Hash                              |
+| ----------------------------------------------- | ------ | ---------------------------------------- |
+| https://github.com/SiliconLabs/matter | \<this branch\>   | \<this commit\> |
+
+## Matter Accessory Device (MAD)
+
+| Repo                                            | Branch | Commit Hash                              |
+| ----------------------------------------------- | ------ | ---------------------------------------- |
+| https://github.com/SiliconLabs/matter | \<this branch\>   | \<this commit\> |

docs/silabs/general/FIND_RASPI.md

@@ -0,0 +1,23 @@
+[<< Back to TOC](../README.md)
+
+# How to find your Raspberry Pi on the Network
+
+## Finding the IP address of your Raspberry Pi
+
+Sometimes it can be difficult to find your Raspberry Pi on the network. One way of interacting with the Raspberry Pi is connecting a keyboard, mouse and monitor to it. The preferred method, however, is over SSH. For this, you will need to know the IP address of your Raspberry Pi.
+
+[This](https://raspberryexpert.com/find-raspberry-pi-ip-address/) is a good tutorial on how to find the IP address.
+
+
+| Platform | Strategy |
+| -------- | -------- | 
+| Mac / Linux | ***Nmap*** <br> &emsp; The use of nmap on the Mac may require a software download. <br> &emsp; Use nmap with the following command: <br> &emsp;&emsp; `sudo nmap -sn <subnet>.0/24` <br><br> &emsp; Example: `sudo nmap -sn 1-.4.148.0/24` <br><br> &emsp; Among other returned values, you will see: <br> &emsp;&emsp;&emsp; `Nmap scan report for ubuntu.silabs.com (10.4.148.44)` <br> &emsp;&emsp;&emsp; `Host is up (0.00025s latency).` <br> &emsp;&emsp;&emsp; `MAC Address: E4:5F:01:7B:CD:12 (Raspberry Pi Trading)` <br><br> &emsp; And this is the Raspberry Pi at 10.4.148.44 <br><br> ***Arp*** <br> &emsp; Alternatively, use Arp with the following command: <br> &emsp;&emsp; `arp -a \| grep -i "b8:27:eb\|dc:a6:32"` |
+| Windows | In the command prompt, use `nslookup` to fnd your Raspberry Pi. <br> &emsp; Example: `nslookup ubuntu` |
+
+<br>  
+
+## Connecting to your Raspberry Pi over SSH
+
+| Platform | Strategy |
+| -------- | -------- | 
+| Mac / Linux / Windows | Once you have found your Raspberry Pi's IP address, you can use Secure Shell (SSH) to connect to it over the command line with the following command: <br> &emsp; `ssh <raspberry pi's username>@<raspberry pi's IP address>` <br><br> Example: <br> &emsp; `ssh [email protected]` <br> &emsp;`password: raspberrypi` <br><br> When prompted provide the raspberry pi's password, in the case of the Silicon Labs Matter Hub image the username is ***ubuntu*** and the password is ***raspberrypi*** | 

docs/silabs/general/FLASH_SILABS_DEVICE.md

@@ -0,0 +1,16 @@
+[<< Back to TOC](../README.md)
+
+# How to Flash a Silicon Labs Device
+
+Once you have an image built, you can flash it onto your EFR device (either a EFR32 development board or the Thunderboard Sense 2) over USB connected to your development machine. This can be done using either Simplicity Studio or the standalone Simplicity Commander.
+
+<br>
+
+## Simplicity Commander
+A link to download Simplicity Commander's standalone version is located along with documentation in the 
+ - [Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf)
+
+## Simplicity Studio: 
+Simplicity Studio is a complete development environment and tool suite. It has the ability to discover USB connected development boards and flash them.
+- [Download Simplicity Studio](https://www.silabs.com/developers/simplicity-studio)
+- [Simplicity Studio Reference Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-building-and-flashing/flashing)

docs/silabs/general/ZAP.md

@@ -0,0 +1,161 @@
+[<< Back to TOC](../README.md)
+
+# ZCL Advanced Platform (ZAP) Tool for Matter
+
+## Overview
+
+EFR32 example applications provide a baseline demonstration of a lock device,
+built using the Matter SDK and the Silicon Labs GeckoSDK. It can be controlled
+by a CHIP controller over Openthread network.
+
+The EFR32 device can be commissioned over Bluetooth Low Energy (BLE) where the
+device and the CHIP controller will exchange security information with the
+Rendez-vous procedure. Thread Network credentials are provided to the EFR32
+device which will then join the network.
+
+The LCD on the Silicon Labs WSTK shows a QR Code containing the needed
+commissioning information for the BLE connection and starting the Rendez-vous
+procedure.
+
+The lock example is intended to serve both as a means to explore the workings of
+CHIP, and a template for creating real products on the Silicon Labs platform.
+
+Each Matter application consists of the following layers:
+
+-   Matter SDK: Source code necessary to communicate through the Matter network
+    over Thread or Wifi
+-   Data model layer in the form of clusters. There are two types of clusters:
+    -   Utility Clusters:
+        -   They represent common management and diagnostic features of a Matter
+            endpoint
+        -   Identify cluster is an example of a Utility Cluster. Given a Node
+            ID, it can be used to Blink LED0 to the corresponding Silicon Labs
+            WSTK
+    -   Application Clusters:
+        -   These clusters represent functionalities specific to a given
+            application
+        -   Door Lock Cluster is an example of an Application specific cluster.
+            This cluster contains commands to lock and unlock a door(door-lock
+            is represented by an LED), with options to set passwords and lock
+            schedules
+
+<br>
+
+## Clusters
+
+Every Matter Application uses multiple clusters leveraged from the Zigbee
+Cluster Library(ZCL). A cluster can be seen as a building block for the Data
+Model of a Matter application. Clusters contains attributes, commands, and
+events. Attributes are customizable variables specified by the Zigbee Advanced
+Platform(ZAP) tool. Commands are sent to the application, which may respond with
+data, LED flickering, lock actuation, etc. Events are notifications sent out by
+the server.
+
+An application can have multiple Matter endpoints. Application endpoints
+generally refer to one device, and inherits its information from the "cluster"
+it belongs to. Utility clusters are required to be on the endpoint with ID 0.
+Application clusters are assigned to endpoints with IDs 1 and higher.
+
+Some applications have callbacks that are left to be implemented by the device
+manufacturer. For example, the storage and mangement of users and credentials in
+the lock-app is left up to the application developer.
+
+<br>
+
+## ZAP Tool
+
+The ZAP tool is built and maintained by Silicon Labs and developers in the ZAP opensource community. It inherits its name and
+features from the Zigbee Cluster Library, which was the starting point for the Matter data model. ZAP is used
+for generating code for Matter applications based on the Zigbee Cluster
+Library and associated Matter code templates.
+
+The ZAP tool can be cloned using the following git command. This will create a
+root level matter folder in your current directory. All following commands
+should be run from the matter folder.
+
+> `$ git clone https://github.com/SiliconLabs/matter.git`
+
+The `run_zaptool.sh` script can be invoked
+without arguments, or, you can provide the path to a ZAP file to be opened upon
+launch.
+
+In the following examples, the ZAP file for the lock-app has been chosen.
+
+> `$ ./scripts/tools/zap/run_zaptool.sh ($PATH_TO_ZAP_FILE)`
+
+This shows the output of the run_zaptool script with no arguments. To load a new
+zap file, click the application menu for Electron (Upper left corner of the
+screen for macs), then click "Open File". Then navigate to the desired .zap
+file.
+
+![ZAP Introduction Page](./images/zap_intro.png)
+
+This shows the output of the run_zaptool script with a zap file given as an
+argument, or after a .zap file has been opened in the ZAP UI. An Electron
+application will open, pre-loaded with the information from the .zap file
+provided as a command line argument.
+
+![ZAP Endpoint](./images/zap_endpoint.png)
+
+The Out of the box(OOB) example lock application has 2 endpoints. Endpoint 0 is
+called the root node. It contains all Service and Device management clusters. In
+general, any cluster or feature that is not specific to a device type belongs in
+Endpoint 0. Examples of clusters one might find in Endpoint 0: Device Descriptor
+cluster, Network Diagnostics cluster.
+
+Endpoint 1 contains information specific to the device type. Conveniently, the
+ZAP tool offers a Door lock cluster, which contains Commands(lock, unlock, set
+credential, etc..) and Attributes(Lock state, Require PIN) that a standard door
+lock application might use.
+
+More endpoints can be added. Each endpoint acts like a port on a network interface.
+
+Endpoints contain clusters which are bundles of device functionality. Clusters have both a Client and a Server interface. In general the Client interface sends commands and the Server interface receives them. For instance a Light would implement the Server side of the on/off clusters. A Switch would implement the Client side of the same cluster.
+
+Click on Endpoint 1 on the left hand side of the application. The door lock
+cluster should already be enabled as "Server".
+
+![ZAP Endpoint 1](./images/zap_endpoint_1.png)
+
+<br>
+
+## Attributes
+
+Attributes are analogous to member variables of a class. Each attribute is
+provided with generated setter/getter code from the ZAP tool. They can be
+enabled or disabled for each cluster on a Matter endpoint. Some attributes are
+required to be enabled, else the application will not function properly. There
+is an option to add attributes to either the server code or client code. The ZAP
+tool also allows you choose a storage space for attributes. Attributes can be
+stored in standard RAM, Non-volatile memory or external memory. Each attribute
+has a type, some are standard C types and some have specially defined enums.
+Each attribute can be provided with a default starting value value.
+
+Click the settings wheel to enable/disable, choose a storage option, and choose
+a default value for attributes, commands and events for Endpoint 1. 
+
+![ZAP Attributes](./images/zap_attributes.png)
+
+<br>
+
+## Commands
+
+Commands can be enabled/disabled like attributes. Some commands are required for
+an application to function properly. Many of the functions run when a command is
+received are implemented on the server side. But some of these are left up to
+the application to define. In the EFR32 lock example, the set/get user and
+credential functions are customizable as each implementation of a lock might
+store these differently.
+
+![ZAP Commands](./images/zap_commands.png)
+
+<br>
+
+## Generation of Code
+
+Once desirable cluster options are chosen for an application, one must save the
+current zap configuration using the application menu in the upper left corner.
+Then click generate in the top menu bar. The user will be prompted to choose a
+save location for the generated ZAP code. In the Silicon Labs Matter repository,
+the lock-app generated files belong in
+matter/zzz_generated/lock-app/zap-generated .