Skip to content

Commit

Permalink
Pull request #12: Matter documentation
Browse files Browse the repository at this point in the history
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
Shayna Kaushal authored and jmartinez-silabs committed Oct 7, 2022
1 parent 4cf2b76 commit 886dbdf
Showing 37 changed files with 1,591 additions and 1 deletion.
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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)

15 changes: 15 additions & 0 deletions docs/silabs/OVERVIEW.md
Original file line number Diff line number Diff line change
@@ -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)
56 changes: 56 additions & 0 deletions docs/silabs/README.md
Original file line number Diff line number Diff line change
@@ -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
-->
1 change: 1 addition & 0 deletions docs/silabs/dev/DEV.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[<< Back to TOC](../README.md)
3 changes: 3 additions & 0 deletions docs/silabs/dev/setup/VSCODE_SETUP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[<< Back to TOC](../../README.md)

todo: [link](https://github.com/project-chip/connectedhomeip/blob/master/docs/VSCODE_DEVELOPMENT.md)
40 changes: 40 additions & 0 deletions docs/silabs/general/ARTIFACTS.md
Original file line number Diff line number Diff line change
@@ -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
30 changes: 30 additions & 0 deletions docs/silabs/general/COMMIT_HASHES.md
Original file line number Diff line number Diff line change
@@ -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\> |
23 changes: 23 additions & 0 deletions docs/silabs/general/FIND_RASPI.md
Original file line number Diff line number Diff line change
@@ -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*** |
16 changes: 16 additions & 0 deletions docs/silabs/general/FLASH_SILABS_DEVICE.md
Original file line number Diff line number Diff line change
@@ -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)
161 changes: 161 additions & 0 deletions docs/silabs/general/ZAP.md
Original file line number Diff line number Diff line change
@@ -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 .
Binary file added docs/silabs/general/images/zap_attributes.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/general/images/zap_commands.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/general/images/zap_endpoint.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/general/images/zap_endpoint_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/general/images/zap_intro.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
70 changes: 70 additions & 0 deletions docs/silabs/thread/BUILD_FLASH_MAD.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
[<< Back to TOC](../README.md)

# How to Build and Flash the Matter Accessory Device (MAD)

The Matter Accessory Device, such as the lighting-app, is the actual Matter
device that you will commission onto the Matter network and control using the
Chip-Tool.

## Step 1: Get the Image File to Flash the MAD

We have provided two ways to get the required image to flash the MAD. You can
use one of the following options:

1. Using the pre-built image file
2. Building the image file from the '`connectedhomeip`' repository

<br>

### **Using the Pre-Built Image File**

All of the Matter Accessory Device image files are accessible through the
[Matter Artifacts Page](../general/ARTIFACTS.md). If you are using the pre-built
image file, you can skip forward to Step #2: Flashing the MAD.

<br>

### **Building the Matter Image File from the Repository**

**1. Clone the Silicon Labs Matter repository**

Since you are reading this documentation it is assumed that you have already cloned the Silicon Labs Matter GitHub repository and have the right branch. If you have not you can follow the directions below.

The Silicon Labs Matter repo is located in Github here:
https://github.com/SiliconLabs/matter.

In order to clone the Matter repo you'll need to have Git installed on your
local machine. Once you have Git installed you can use the following command:

> `$ git clone https://github.com/SiliconLabs/matter.git`
Once you have cloned the repo, enter the repo and sync all the submodules with
the following command:

> `$ cd matter` <br> `$ git submodule update --init --recursive`
<br>

**2. Build the Matter Accessory Device**

The Matter Accessory Device (lighting-app) can be built out of this repo. Documentation on how to build and use the lighting-app Matter Accessory Device is provided in this [README.md](../../../examples/lighting-app/efr32/README.md)

Please note that you only need to build a single device for
the demo such as the lighting-app. If you wish to build other examples such as
the sleepy end device you are welcome to it is just not necessary for the demo.

The build process puts all image files in the following location:

> \<git location>/matter/out/\<app name>/\<board name>
<br>

## Step 2: Flash the Matter Accessory Device

For more information on how to flash your Silabs development platform consider
the following instructions:
[How to Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md)

Once your Matter Accessory Device has been flashed it should show a QR code on
the LCD. If no QR Code is present it may be that you need to add a bootloader to
your device.
180 changes: 180 additions & 0 deletions docs/silabs/thread/CHIP_TOOL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
[<< Back to TOC](../README.md)

# Using the ChipTool

The following commands show how to start a new Thread network from the local
OTBR, commission an EFR32 Matter End Device (Matter Accessory Device), and then
send the on/off commands with the `mattertool` automated script.

| **Command** | **Usage** |
| ------------------------ | ------------------------------------------------------------------------- |
| `mattertool startThread` | Starts the thread network on the OTBR |
| `mattertool bleThread` | Starts commissioning of a Matter Accessory Device using the ChipTool |
| `mattertool on` | Sends the _on_ command to the Matter Accessory Device using the ChipTool |
| `mattertool off` | Sends the _off_ command to the Matter Accessory Device using the ChipTool |

You can also use the full ChipTool command as usual (still using mattertool)

> `$ mattertool levelcontrol read current-level 106 1`
<br><br>

## Informational Section [Optional]

### Image tree

- home
- ubuntu (you are here)
- connectedhomeip (git repo:
https://github.com/project-chip/connectedhomeip.git)
- .
- ot-br-posix (git repo:
https://github.com/openthread/ot-br-posix.git)
- .
- scripts (in-house scripts)
- configurations.sh
- matterTool.sh
- setupOTBR.sh

<br>

### Open Thread Border Router (OTBR)

For information on what commits to use for the OTBR and RCP, please consult the
[Matter Repositories and Commit Hashes page](../general/COMMIT_HASHES.md)

The pre-installed OTBR is configured for the infrastructure interface eth0.

Bash script to modify, reinstall or update the OTBR:

> `otbrsetup`
This bash script centralizes and simplifies the local OTBR installation.

Available commands:

| **Command** | **Description** |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| -h, --help | Prints help options |
| -if, --interface <eth0\|wlan0> | Select infrastructure interface. Default eth0 |
| -i, --install | Bootstrap, set up and install the OTBR. Usually for a new installation |
| -s, --setup | Runs the OTBR setup only, use this to change the configured infrastructure interface (use in combination with -if wlan0 for wifi) |
| -u, --update | Update the OTBR installation after the repo is updated |

<br>

#### Usage:

<br>

Change infrastructure to wlan0: `$ otbrsetup -if wlan0 -s` <br> Rerun full
install for eth0 interface: `$ otbrsetup -i`

Change OTBR commit reference/version

> `$ cd /home/ubuntu/ot-br-posix` <br>
> `$ git fetch` <br>
> `$ git checkout <SHA>` <br>
> `$ otbrsetup -u`
<br>

### Matter - ChipTool

For more information on the commit hashes used for this demo please consult the
following page:
[Matter Repositories and Commit Hashes](../general/COMMIT_HASHES.md)

To change the ChipTool commit reference/version, follow these steps:

> `$ cd /home/ubuntu/connectedhomeip` <br>
> `$ git fetch` <br>
> `$ git checkout <SHA>` <br>
> `$ mattertool buildCT`
The mattertool script centralizes and simplifies the use of ChipTool and
starting a clean thread network.

<br>

Available commands:

| **Command** | **Description** |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| help | Prints help options |
| startThread | Start a new thread network and store the operational thread dataset for the commissioning purpose (bleThread) |
| bleThread | For Matter Ble thread commissioning with an EFR32 device |
| bleWifi | For Matter Ble WiFI commissioning with an EFR32 device |
| buildCT | Clean build of the chip-tool |
| cleanVars | Erase every Set variable used in the script. They will be set back to default or randomized value |
| off | Turn off the Light on the already commissioned EFR32 device |
| on | Turn on the Light on the already commissioned EFR32 device |
| toggle | Toggle the Light on the already commissioned EFR32 device |
| parsePayload | Parse the given Payload (QrCode string) |
| rebuildCT | Rebuild the chip-tool |
| vars | Print the Variables in use by the script |

<br>

Some options/arguments can be added to the command to update the values of the
variables used by the script.

<br>

Available commands:

| **Command** | **Description** |
| ------------------------ | ---------------------------------------------------- |
| -h, --help | Prints help options |
| -n, --nodeId DIGIT | Specify the Nodeid you are trying to reach |
| -e, --endpoint DIGIT | Specify an endpoint for the desired cluster |
| -d, --dataset HEX_STRING | Thread Operation Dataset to be provisioned |
| -s, --ssid STRING | WiFi AP SSID that the end devices need to connect to |
| -p, --password STRING | WiFi AP password |

> These configurations are held until overwritten, cleared with cleanVars or
> when Raspberry Pi reboots.
<br>

Active variables used by mattertool:

| **Variable** | **Value** |
| --------------- | ----------------------------------------------------- |
| MATTER_ROOT | /home/ubuntu/connectedhomeip |
| CHIPTOOL_PATH | /home/ubuntu/connectedhomeip/out/standalone/chip-tool |
| NODE_ID | 31354 |
| THREAD_DATA_SET | \<the_value_you_get> |
| PINCODE | 20202021 |
| DISCRIMINATOR | 3840 |
| SSID | \<your_SSID> |
| lastNodeId | 0 |

You can preset them with export X=Y before running the script or use some
available options to change some of them.

> In most cases, MATTER_ROOT, CHIPTOOL_PATH, PINCODE, and DISCRIMINATOR should
> remain at the default set value.
> For commissioning commands (bleThread, bleWifi) NODE_ID will be randomized if
> it is the same as the last paring
> When the startThread command is used, THREAD_DATA_SET will be assigned with
> the right operation dataset for the created Thread Network.
<br>

### Scripts Alias

The commands presented above are linked to scripts. You can edit **_.bashrc_**
and rename the following alias to your liking.

> `$ alias mattertool=‘source $HOME/scripts/matterTool.sh’` <br>
> `$ alias otbrsetup=‘source $HOME/scripts/setupOTBR.sh’`
71 changes: 71 additions & 0 deletions docs/silabs/thread/DEMO_OVERVIEW.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
[<< Back to TOC](../README.md)

# Matter Demo over Thread Overview

This guide goes through the steps for running an example lighting-app for Matter
over Thread. Please look at [this](THREAD.md) file for an introduction to the
Matter over Thread setup.

At a high level, we will walk through starting a thread network, commissioning a
new device to the thread network using BLE, and finally sending a basic OnOff
command to the end device.

<br>

## Step 0: Prerequisites

Before beginning your Matter project, consider the
[Matter Hardware and Software Prerequisites](./THREAD_PREREQS.md). Here you will find all the information you need on Silicon Labs hardware supported for Matter development.

<br>

## Step 1: Setting up the Matter Hub (Raspberry Pi)

The Matter Hub consists of the OTBR and the ChipTool running on a Raspberry Pi.
Silicon Labs has developed a Raspberry Pi image which can be downloaded and
flashed onto an SD Card that is then to be inserted into the Raspberry Pi.

The Matter Controller sends IPv6 packets to the OTBR, which converts the IPv6
packets into Thread packets. The Thread packets are then routed to the Silicon
Labs end device.

Please refer to this guide for the setup:
[How to use Matter Hub \(Raspberry Pi\) Image](./RASPI_IMG.md)

<br>

## Step 2: Build and Flash the RCP

The Radio Co-Processor (RCP) is a thread device that connects to the Raspberry
Pi via USB. First, to flash the RCP, it should be connected to your laptop via
USB. Thereafter, it should be connected to the Raspberry Pi via USB as well.

Information on building and flashing the RCP is located here:
[How To Build and Flash the RCP](RCP.md)

<br>

## Step 3: Build and Flash the MAD

The Matter Accessory Device (MAD) is the actual Matter device that will be
commissioned onto the Matter network and control using the ChipTool.

Information on how to build and flash the Matter Accessory device is located
here: [How To Build and Flash the Matter Accessory Device](./MATTER_DEVICE.md)

<br>

## Step 4: Commission and Control the MAD

Once the Matter Accessory device has been flashed onto your hardware you can
commission it from the Matter Hub using the commands provided in the Raspberry
Pi image:

| Command | Usage |
| ---------------------- | -------------------------------------------------- |
| mattertool startThread | Starts the thread network on the OTBR |
| mattertool bleThread | Starts commissioning of a MAD using ChipTool |
| mattertool on | Sends an **on** command to the MAD using ChipTool |
| mattertool off | Sends an **off** command to the MAD using ChipTool |

<br>
33 changes: 33 additions & 0 deletions docs/silabs/thread/FAQ.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[<< Back to TOC](../README.md)

<!-- - connecting raspi to netwrok
- why is mattertool not working:
- bad image
- image not flashed correctly -->

# Frequently Asked Questions for Matter over Thread

## Demo

- Why are the `mattertool` commands not working after all the steps?

- You should check if the Radio Co-Processor (RCP) image was build and/or
flashed correctly to the device
- Make sure you see a QR code on the display of the Matter Accessory
Device (MAD)
- Make sure the images being used to flash the Raspberry Pi, RCP and MAD
are correct

<br>

- How can I find the IP address of my Raspberry Pi?

- First, make sure the Raspberry Pi is connected to a network (ethernet or
wifi). This page has more information on the same:
[Setting up the Matter Hub (Raspberry Pi)](RASPI_IMG.md)
- Refer to this page for general questions on finding the Raspberry Pi on
your network: [Finding your Raspberry Pi](../general/FIND_RASPI.md)
- For more detailed information, please refer to this page:
[Raspberry Pi Remote Access](https://www.raspberrypi.com/documentation/computers/remote-access.html)

<br>
72 changes: 72 additions & 0 deletions docs/silabs/thread/RASPI_IMG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
[<< Back to TOC](../README.md)

# Setting up the Matter Hub (Raspberry Pi)

The Matter Hub consists of the Open Thread Border Router and the ChipTool
running on a Raspberry Pi. Silicon Labs has developed a Raspberry Pi image which
can be downloaded and flashed onto an SD Card for the Raspberry Pi.

In short, the Matter Controller sends IPv6 packets to the OTBR, which converts
the IPv6 packets into Thread packets. The Thread packets are then routed to the
Silicon Labs end device.

<br>

## How to use the Silicon Labs Matter Raspberry Pi Image (Matter Hub)

<br>

The Raspberry Pi should be connected to a network - this could be ethernet or a
Wifi network.

Please refer to this page on how to connect your Raspberry Pi to a wifi network:
[Connecting Raspberry Pi to Wifi](https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-networking)

<br>

### Step 1. Raspberry Pi Image Download

The provided Raspberry Pi image is used as a Matter Controller with the OTBR.

The image can be downloaded from the
[Matter Artifacts page](../general/ARTIFACTS.md)

<br>

### Step 2. Flashing your Raspberry Pi

[Raspberry Pi Disk Imager](https://www.raspberrypi.com/software/) can be used to
flash the SD Card which contains the operating system for the Raspberry Pi.

Alternatively, a tool like [balenaEtcher](https://www.balena.io/etcher/) can be
used to flash the image to a micro SD card.

> After flashing the SD card, insert it into the Raspberry Pi and reset the
> Raspberry Pi. Then, wait at least 10 seconds for it to come up and start the
> SSH server.
<br>

### Step 3. Finding your Raspberry Pi on the Network

Please see the [Finding Your Raspberry Pi page](../general/FIND_RASPI.md) for
more information on finding the Raspberry Pi on the local network.

##### Raspberry Pi Login Credentials

- user: **ubuntu**
- password: **raspberrypi**

> When you log into the Raspberry Pi for the first time over SSH you may receive
> a warning regarding a 'key fingerprint' - this is normal and expected. You can
> get past this by just typing '_yes_' at the prompt.
<br>

### Step 4: Using the Matter Hub

The ChipTool, also referred to as the `mattertool`, is provided as a pre-built
application inside the Raspberry Pi image.

Please refer to the ChipTool page for information on using the Matter Hub with
`mattertool` commands: [ChipTool page](./CHIP_TOOL.md)
91 changes: 91 additions & 0 deletions docs/silabs/thread/RCP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
[<< Back to TOC](../README.md)

# How to Build and Flash the Radio Co-Processor (RCP)

The Radio Co-Processor is a 15.4 stack image flashed onto a Silicon Labs
development kit or Thunderboard Sense 2. The 15.4 stack on the development kit
communicates with the higher layers of the Thread stack running on the Raspberry
Pi over a USB connection.

First, in order to flash the RCP, it should be connected to your laptop directly
over USB.

<!-- In order to for the OTBR to work, both the RCP and
the OTBR need to be built off a commit that allows them to communicate properly. -->

<br>

## Step 1: Get or Build the Image File to Flash the RCP

We have provided two ways to get the required image to flash the RCP. You can
use one of the following options:

1. Using the pre-built image `ot-rcp` image file
2. Building the image file from the '`ot-efr32`' repository which is listed on
the [Matter Repositories and Commit Hashes page](../general/COMMIT_HASHES.md)

<br>

### **Using the Pre-built Image File**

All of the RCP image files are accessible through the
[Matter Artifacts Page](../general/ARTIFACTS.md). If you are using the pre-built
image file, you can skip forward to Step #2: Flashing the RCP.

<br>

### **Building the Image File from the Repository**

**1. Clone the ot-efr32 repository**

The ot-efr32 repo is located in Github here:
https://github.com/SiliconLabs/ot-efr32.

In order to clone the ot-efr32 repo, you'll need to have Git installed on your
local machine. Once you have Git installed you can use the following command:

> `$ git clone https://github.com/SiliconLabs/ot-efr32.git`
Once you have cloned the repo, enter the repo and sync all the submodules with
the following command:

> `$ cd ot-efr32` <br> > `$ git submodule update --init --recursive`
After updating the submodules you can checkout the correct branch or commit hash
for the system. Check the current branch and commit hash used here:
[Matter Branches and Commit Hashes](../general/COMMIT_HASHES.md)

> `$ git checkout <commit hash>`
<br>

**2. Build the RCP**

Once you have checked out the correct hash, follow the instructions here:
https://github.com/SiliconLabs/ot-efr32/blob/main/src/README.md to build the RCP
image for your EFR platform.

This process will build several images for your board. The filename of the image
to be flashed onto the board to create an RCP is '`ot-rcp.s37`'.

The output of the build process puts all the image files in the following
location: `<git>/ot-efr32/build/<efr32xgxx>`

<br>

## Step 2: Flash the RCP

Once you get the RCP image '`ot-rcp.s37`' after either downloading it from the
link provided above, or building the image file from the repo as documented
above, you can flash it onto your device which will become the RCP attached to
your Raspberry Pi. Flashing of the device is done directly from your laptop and
not through the Raspberry Pi, so make sure that the device is connected directly
over USB to your laptop. Further information on flashing a Silicon Labs device
is located here:
[How to Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md)

Once you have flashed your RCP device you can disconnect it from you laptop and
connect it via USB to the Raspberry Pi.

The Raspberry Pi's Open Thread Border Router can then use the RCP to communicate
with the Thread network.
40 changes: 40 additions & 0 deletions docs/silabs/thread/THREAD.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
[<< Back to TOC](../README.md)

# Introduction

**Matter 15.4 Setup** ![Overview](./images/thread_overview.png)

A typical simple Matter 15.4 (Thread) network is setup as shown in the image
above. It consists of the following 4 elements:

1. A **Controller** such as an app running on a phone or the ChipTool running
on a Linux box or Raspberry PI
2. An Open Thread Border Router (**OTBR**) running on a Linux box or Raspberry
Pi
3. A Radio Co-Processor (**RCP**) which the OTBR uses to communicate with
Thread network
4. An End Device such as a light or switch, which is the Matter Accessory
Device (**MAD**)

The flow of the setup described above is as follows:

1. The controller commissions the End Device directly over Bluetooth – this
makes the End Device join the Thread network and the CHIP fabric.
2. After commissioning, the Bluetooth connection is terminated and all further
communication is done over Matter.
3. The controller sends ZCL commands, such as the OnOff Toggle, and the End
Device performs the corresponding action; in the case of the OnOff Toggle,
this would turn the LED of the End Device on or off

<br>

There are a few different ways that a Matter network can be built using a
combination of Silicon Labs hardware, a Raspberry Pi, and any external
controller(Macbook, Ubuntu, Android, etc.)

The suggested method involves using a Raspberry Pi to function as both, the
controller, and the OTBR, with a Silicon Labs device as the MAD.

An alternate configuration would be using a Macbook as the controller, a
Raspberry Pi as the OTBR, with a Silicon Labs Device as the MAD. This requires
additional routing between the controller and OTBR.
95 changes: 95 additions & 0 deletions docs/silabs/thread/THREAD_PREREQS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
[<< Back to TOC](../README.md)

# Matter 15.4 Hardware and Software Prerequisites

## Software Requirements

### System Agnostic Software Requirements (Mac/ Linux/ Windows):

1. SSH Client ([Putty](https://www.putty.org/) or similar):
> SSH client is used to communicate with the Raspberry Pi over a secure
> shell
1. [Raspberry Pi Disk Imager](https://www.raspberrypi.com/software/)
> Raspberry Pi Disk Imager is used to flash the SD Card which contains the
> operating system for the Raspberry Pi
1. [Flash tool](../general/FLASH_SILABS_DEVICE.md)
> Simplicity Commander standalone or Simplicity Studio is used to flash
> Silicon Labs hardware with firmware images for the RCP and the Matter
> Accessory Device
1. Git [Required for building images and development]
> Make sure Git is installed on the local machine that will be used to flash
> the devices to that the necessary repositories can be cloned locally and
> used as needed.
<br>

### Windows-Specific Software Requirements

&emsp; These are requirements in addition to those mentioned above, if using a
Windows machine. <br>

&emsp; A Unix-like command line:

- [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about)
**OR**
- [VirtualBox](https://www.virtualbox.org/) with
[Ubuntu 20.04.x LTS](https://ubuntu.com/download/desktop)

> WSL or Virtual Box are used to emulate a virtual Linux machine, which is
> useful for accessing the Linux command line tools
<br><br>

## Hardware Requirements

1. Matter Hub (OTBR + ChipTool)

&emsp;Raspberry Pi 4 with an SD card with storage $\geq$ 64 GB

> The Raspberry Pi 4 is used to run the Open Thread Border Router and the
> Chip Tool. In this documentation the combination of this software on the
> Raspberry Pi is also called the 'Matter Hub'
<br>

2. Radio Co-Processor (RCP)

The RCP is a Silicon Labs development board or ThunderBoard Sense 2 running
the Radio Co-Processor firmware for Thread. The following Silicon Labs
devices are supported:

- EFR32MG based on EFR32 Mighty Gecko Wireless Starter Kit
- [EFR32MG12 Development Kit](https://www.silabs.com/development-tools/wireless/zigbee/efr32mg12-dual-band-starter-kit)

**or**

- Silicon Labs Thunderboard Sense 2
- [Thunderboard Sense 2](https://www.silabs.com/development-tools/thunderboard/thunderboard-sense-two-kit)

<br>

3. Matter Accessory Device (MAD)

The following Silicon Labs devices are supported to function as a MAD:

- **MG12 boards:**

- [EFR32MG12 Development Kit](https://www.silabs.com/development-tools/wireless/zigbee/efr32mg12-dual-band-starter-kit)
- BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm
- [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board)
- BRD4163A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm
- [SLWRB4163A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4163a-efr32mg12-radio-board)
- BRD4164A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm
- [SLWRB4164A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4164a-efr32mg12-radio-board)
- BRD4166A / SLTB004A / Thunderboard Sense 2 / 2.4GHz@10dBm
- [Thunderboard Sense 2](https://www.silabs.com/development-tools/thunderboard/thunderboard-sense-two-kit)
- BRD4170A / SLWSTK6000B / Multiband Wireless Starter Kit /
2.4GHz@19dBm, 915MHz@19dBm
- [SLWRB4170A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4170a-efr32mg12-radio-board)
<br><br>

- **MG24 boards:**
- BRD4186C / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@10dBm
- [XG24-RB4186C](https://www.silabs.com/development-tools/wireless/xg24-rb4186c-efr32xg24-wireless-gecko-radio-board)
- BRD4187C / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm
- [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board)
Binary file added docs/silabs/thread/images/thread_overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
116 changes: 116 additions & 0 deletions docs/silabs/wifi/BUILD_CHIP_ENV.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
[<< Back to TOC](../README.md)

# Build Environment using Linux

This section will go through the steps required to build the demo using Linux.

> **Do not execute any commands on this page as ROOT (no _su_ required), unless
> specified**
<br>

## Prepare Linux Packages

Update the latest packages by typing following commands in terminal:

> `$ sudo apt update`
> `$ sudo apt install`
<br>

## Prerequisites for CHIP project on Linux

### 1. Installing packages on Ubuntu Laptop/PC

- Open the Linux terminal from Start menu
- Install required packages on Ubuntu Laptop/PC using the following commands:

> `$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev` <br>


<br>

### 2. Matter codebase

- Check out Matter codebase from GitHub:

- Create a working directory - we will name it `matter` as part of this
example:

> `$ mkdir matter`
> `$ cd matter`
> `$ MATTER_WORKDIR=pwd`
--> We will use $MATTER_WORKDIR later

- Download the
[Matter codebase](https://github.com/project-chip/connectedhomeip.git)
from here as follows:
> `$ git clone https://github.com/project-chip/connectedhomeip.git`
- Sync submodules by running the following commands:

> `$ cd connectedhomeip`
> `$ git submodule update --init --recursive`
- Environment Builds

- Activate environment builds:
> `$ . scripts/bootstrap.sh`
- Create a directory where binaries will be updated:
> `$ mkdir out`
- **[Optional:** Increasing stack size **]** <br> &emsp; Navigate to
`matter/connectedhomeip` and open the file in the path
`examples/lighting-app/efr32/include/FreeRTOSConfig.h`. Find the macro:
\``configMINIMAL_STACK_SIZE`\`, and change the macro value from `140` to
**`320`**.

<br>

### 3. Compiling the Lighting-app

The following commands are for building the example. Depending on which device
you are using, select the appropriate build command to run.

Build command for RS911x:
`$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/rs911x_lighting BRD4161A --wifi rs911x |& tee out/rs911x_lighting.out`

Build command for WF200:
`$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/wf200_lighting BRD4161A is_debug=false --wifi wf200 |& tee out/rs911x_lighting.out`

Run the following:

> `$ cd connectedhomeip`
> `$ <appropriate_build_command_from_above>`
<br>

> Look for build problems in `out/*.out`, which is the log file that was
> generated by the above command
The generated software can be found in `out/rs911x_xxx/BRD4161A/*.out`.

This is what you will burn into the EFR32.

<br>

## Compiling ChipTool

- Build the ChipTool on a laptop which has Wifi and BLE
- Run the following commands:

> `$ cd $MATTER_WORKDIR/connectedhomeip` <br>
> `$ ./scripts/examples/gn_build_example.sh examples/chip-tool out/standalone`
This will build chiptool in `out/standalone`

Now, you will have all the binaries to flash onto MG12 platform.
74 changes: 74 additions & 0 deletions docs/silabs/wifi/BUILD_PI_ENV.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
[<< Back to TOC](../README.md)

# Building Environment using Raspberry Pi 4

1. Flash the Ubuntu OS onto the SD card
2. Insert the flashed SD card (directly or using a card reader) into the
laptop/PC that will run the Raspberry Pi Imager tool
3. Launch Raspberry Pi 4 Imager
4. Click on 'Choose OS' --> 'Other General-purpose OS' --> 'Ubuntu' --> 'Ubuntu 22.04 64-bit server OS'
5. Click 'Storage' and select the 'SD card detect'
6. This Raspberry Pi 4's console can be accessed in multiple ways, refer to:
https://www.raspberrypi.com/documentation/computers/remote-access.html
7. In this guide, Raspberru Pi 4 is being accessed using Putty. Enter the
details like User name, Password, SSID and it's password to connect to
network. Then, click 'Save'
8. Click 'Write' and then 'Yes' when you are asked for permission to erase data
on the SD card. It will then start flashing the OS onto the SD card
9. When it is done, click 'Continue'
10. Remove the SD card from the reader and insert it into the Raspberry Pi as
shown below:

<!-- ![Inserting SD into Pi](images/sd_into_pi.png) -->
<img src="images/sd_into_pi.png" alt="Inserting SD into Pi" width="550"/>

11. On powering up the board, the red and green lights should start blinking
12. Use this reference to find the IP address of your Raspberry Pi: [Finding Your Raspberry Pi](../general/FIND_RASPI.md)
13. Once you find the IP address, launch Putty, select 'Session', enter the IP
address of the Raspberry Pi, and click 'Open'
14. Enter the username and password given at the time of flashing and click
'Enter'
If you don't give username and password default is user account "ubuntu" and password "ubuntu",

15. Update the latest packages by running following commands in the terminal:

> `$ sudo apt update`
> `$ sudo apt install`
16. Install required packages using the following commands:

> `$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev'

<br>
> If you see any popups between installs, you can select 'Ok' or 'Continue'
## Installing prerequisites on Raspberry Pi 4
Finally, install some Raspberry Pi specific dependencies

refer this link : https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md
In above link follow section "Installing prerequisites on Raspberry Pi 4".

## Bluetooth setup
Make sure BLE is up and running on Raspberry-Pi.
Raspberry pi internally has some issue in BLE and sometimes it crash in middle, BLE is used for
commissioning purpose on Matter So make sure BLE is running.

Use below commands to turn on or restart bluetooth on Raspberry - Pi.

To stop BLE if it is already running.
`$ sudo systemctl stop bluetooth.service`

To restart the Bluetooth service, we need to enable it first as we did before. Hence, we have been using the same systemctl command with a one word change e.g. enable.
`$ sudo systemctl enable bluetooth.service`

When you check the status of a Bluetooth service, you will find it inactive because we haven’t restarted the service yet.
`$ sudo systemctl status bluetooth.service`

So, one needs to restart the Bluetooth service to make it active and running. So we have executed the query below.
`$ sudo systemctl restart bluetooth.service`

After this command, when we have checked the status of the Bluetooth service, we found it active and running.
`$ sudo systemctl status bluetooth.service`
60 changes: 60 additions & 0 deletions docs/silabs/wifi/DEMO_OVERVIEW.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
[<< Back to TOC](../README.md)

# Matter over Wifi Demo Overview

This document walks through the steps to build Matter Lighting-app project using
EFR32 BRD4161A + RS911X and EFR32 BRD4161A + WF200. Silicon Labs has two
families of WiFi adatpers (1. RS911X 2. WF200). Both are supported in this WiFi
port of Matter.

<br>

## Setup Overview

![Overview](./images/wifi_setup.png)

## EFR32MG12 + WF200 Connection

![EFR32MG12 + WF200 connection ](./images/MG12_WF200.jpg)

<br>

<!-- ## Overview -->

This document walks through the steps to build the Matter Lighting-app project
using EFR32 BRD4161A + RS911X and EFR32 BRD4161A + WF200.

Follow this sequence if you are setting up for the first time:

1. [Matter Wifi Prerequisites](WIFI_PREREQS.md)

This page goes through the hardware and software (host side) required for
the demo - make sure you have all the necessary hardware available before
continuing.

2. [Build Linux Environment](BUILD_CHIP_ENV.md)

This part gives you steps to setup the build environment on a Linux machine.
The instructions gives you build steps for the application and the ChipTool.

3. [Build Raspberry-Pi Environment](BUILD_PI_ENV.md)

This section documents steps to setup the build environment on the Raspberry
Pi.

4. [Software Setup](SW_SETUP.md)

This part gives you steps to build the Lighting-app over Wifi. Two separate
build commands are mentioned for RS911x and WF200 adapters to use
accordingly.

5. [Running Matter Demo over Wifi using Linux](RUN_DEMO.md)

This part give you steps to run the Matter Wifi demo using ChipTool running
on a Linux Machine (either Laptop or Raspberry Pi) - follow this after
successfully executing the above steps.

6. [optional] [Running Matter Demo over Wifi using Android](WIFI_ANDROID.md)

This part give you steps to run the Matter Wifi demo using ChipTool running
on an Android phone (either Laptop or Raspberry Pi).
3 changes: 3 additions & 0 deletions docs/silabs/wifi/FAQ.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[<< Back to TOC](../README.md)

# Frequently Asked Questions for Matter over Wifi
115 changes: 115 additions & 0 deletions docs/silabs/wifi/RUN_DEMO.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
[<< Back to TOC](../README.md)

# Runing the Matter Demo over Wifi

## Flashing images/binaries on MG12 platform using Ozone

1. Plug in the WSTK and EFR into the laptop

2. Launch Ozone - this will display a GUI

3. In 'New Project Wizard':

1. Click the three-dots on the 'Device' tab and select 'Manufacturer' as
'`Silicon Labs`'
2. Select 'Device' as '`EFR32MG12PXXF1024`'
3. Click 'OK'
4. The 'Register set' tab will get filled automatically
5. 'Peripherals' tab need not be changed as it is optional

4. Click 'Next' - the window that is displayed will contain:

- Serial Number: Read from device
- Target Interface: JTAG
- Speed: 4MHz
- Host Interface: USB
- There will be one product in the 'Emulators connected via USB' tab -
select this and click 'Next'

5. Click on the 'Silicon Labs device' detected, and then click 'Next'

6. You will be asked to select the image/binary to be loaded: click on the
three-dots on that tab and navigate to '`out/rs911x_lighting/BRD4161A`'
through 'Browse', select the file named `chip-efr32-lighting-example.out` and
click 'Next', this is the same image which we built in previous step.

7. Make sure the next screen has 'Initial PC' selected as 'ELF Entry Point' -
click 'Finish'

> Ignore Diagnostics warning about 'FreeRTOS' detected - click 'Continue'
8. Select 'Download and Reset Program' in the dropdown next to the Power button
on the top left of the page

> The EFR32MG12 will be erased and programmed
9. Run the image by clicking the 'Play' button on the top left (or press the F5
key)

> The output of the EFR32 can be viewed on the console of the Ozone GUI
10. **[Optional]** This step is for when the device has already been flashed and
is being used for testing/debug purposes:

> If you are restarting the device and do not need to re-flash the EFR
> firmware then you can use these commands (JLinkExe & JLinRTTClient). The
> following commands will provide you with a serial cossole of the EFR32
> <br>
> `$ konsole -e JLinkExe -device EFR32MG12PXXXF1024 -if JTAG -speed 4000 -autoconnect 1 &`
> (Put it in the background)
> `$ sleep 3`
> `$ konsole -e JLinkRTTClient &`
> You may need to press <ENTER> in the JLinkExe console first
<br>

## Demo Execution - Commissioning a Wifi Device using ChipTool for Linux

> Commissioning can also be done using ChipTool running either on
> Linux/Raspberry Pi
1. Get the SSID and PSK of the Wifi network (WPA2 - Security) you are connected
to
2. Position the hardware near the laptop as the BLE antenna on the BRD4161A is
slightly weak
3. Run the following:

> `$ cd $MATTER_WORKDIR/connectedhomeip`
### Commissioning Command:

> `$ out/standalone/chip-tool pairing ble-wifi 1122 $SSID $PSK 20202021 3840`
> The node ID used here is 1122. This will be used in future comands.
> '\$SSID' is a placeholder for your Wifi SSID and '\$PSK' is a placeholder
> for the password of your Wifi network.
4. Turning **on** the LED on the EFR32MG12: <br> &emsp;
`$ out/standalone/chip-tool onoff on 1122 1`
5. Turning **off** the LED on the EFR32MG12: <br> &emsp;
`$ out/standalone/chip-tool onoff off 1122 1`

> If there are any failures, run the following command and then re-run the
> ChipTool command: `$ rm -rf /tmp/chip_*`
> As the device remembers the Access Point credentials given for commissioning,
> if you want to run the demo multiple times, do a factory reset by pressing the
> BTN0 on EFR32 MG12 for about 6-7seconds, you will observe the LED0 and LED1
> flashes 3 times and QR code appears again on the LCD screen.
<br>

The commissioning command mentioned above does the following:

- ChipTool scans BLE and located the SiLabs device that uses the specified
discriminator
- Sends the Wifi SSID and Passkey
- The SiLabs device will join the Wifi network and get an IPv4 address. It
then starts providing mDNS records on IPv4 and IPv6
- ChipTool then locates the SiLabs device over Wifi and establishes
operational certificates
- Future communications (tests) will then happen over Wifi
92 changes: 92 additions & 0 deletions docs/silabs/wifi/SW_SETUP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
[<< Back to TOC](../README.md)

# Software Setup and Preliminaries

## Software Setup

Run below commands on a Linux terminal running on either Linux machine, WSL or
Virtual Machine.

1. To download the
[Matter codebase](https://github.com/project-chip/connectedhomeip.git) run
the following commands. Create a working directory - we will name it `matter`
as part of this example flow:

> `$ mkdir matter`
> `$ cd matter`
> `$ MATTER_WORKDIR=pwd` &emsp;&emsp; --> We will use $MATTER_WORKDIR later
> `$ git clone https://github.com/project-chip/connectedhomeip.git`
2. Bootstrapping:

> `$ cd connectedhomeip`
> `$ git submodule update --init --recursive`
> `$ . scripts/bootstrap.sh`
Create a directory where binaries will be updated/compiled. We will call it
`out` in this example:

> `$ mkdir out`
<br>

## Building Software

The following commands are for building the example. Depending on which device
you are using, select the appropriate build command to run.

Build command for RS911x:
`$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/rs911x_lighting BRD4161A --wifi rs911x |& tee out/rs911x_lighting.out`

Build command for WF200:
`$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/wf200_lighting BRD4161A is_debug=false --wifi wf200 |& tee out/rs911x_lighting.out`

Run the following:

> `$ cd connectedhomeip`
> `$ <appropriate_build_command_from_above>`
The generated software can be found in `out/rs911x_xxx/BRD4161A/*.out` for the
RS9116 and in `out/wf200_xxx/BRD4161A/*.out` for the WF200.

This is what you will burn onto the EFR32.

## Compiling the ChipTool

- Build the chiptool on a laptop or Raspberry-pi ( If you are not using Linux
Laptop ) which has Wifi and BLE
- Run the following commands on a terminal where you will run chip-tool:

> `$ mkdir matter`
> `$ cd matter`
> `$ MATTER_WORKDIR=pwd` &emsp;&emsp; --> We will use $MATTER_WORKDIR later
> `$ git clone https://github.com/project-chip/connectedhomeip.git`
2. Bootstrapping:

> `$ cd connectedhomeip`
> `$ git submodule update --init --recursive`
> `$ . scripts/bootstrap.sh`
Create a directory where chip-tool binary will be updated/compiled:

> `$ mkdir out`
> `$ ./scripts/examples/gn_build_example.sh examples/chip-tool out/standalone`
This will build chiptool in `out/standalone`.

After this, follow the steps on the page
'[Runing the Matter Demo over Wifi](RUN_DEMO.md)' to flash the binaries and
execute the demo.
20 changes: 20 additions & 0 deletions docs/silabs/wifi/WIFI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
[<< Back to TOC](../README.md)

# Introduction

[TODO: general matter over wifi writeup]

<!-- ![Overview](./images/wifi_setup.png)
<br>
This document walks through the steps to build Matter Lighting-app project using EFR32 BRD4161A + RS911X and EFR32 BRD4161A + WF200.
[TODO: revamp following flow]
The first part gives instructions on how to setup the build environment using a Linux system (Ubuntu 20.04 LTS).
The second part shows steps to create Lighting-app example and flash on BRD4161A.
The final part introduces how the commissioning takes place using Chip-tool (command line) over the BLE and than control the device using Wi-Fi. -->
40 changes: 40 additions & 0 deletions docs/silabs/wifi/WIFI_ANDROID.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
[<< Back to TOC](../README.md)

# Commissioning Wifi Device using Android

Commissioning can be done using an Android Phone through the following steps.

Download pre-build application from the
[Matter Artifacts page](../general/ARTIFACTS.md).

1. Open the .apk that is installed in the Android mobile
2. Connect the Android phone to the Wi-Fi Access Point that is going to be used
3. Run the installed CHIP app
4. Click 'Provision Chip device with Wi-Fi'
5. The app will bring up the camera:
- Hold the camera to the LCD on the WSTK board
- Scan the QR Code displayed on LCD screen of EFR32 MG12 Platform
6. Input the SSID/Passphrase of the Wi-Fi Access Point on the next screen
7. Hold the phone very close (a few centimeters) from the EFR32 platform (as the
Bluetooth Antenna is slightly weak)
8. You will see messages (Toasts) pop up - saying that the App is 'Scanning',
then 'Pairing', followed by 'Commissioning Done'
9. Once commissioning is completed, the app will go back to the original/home
screen
10. Click on 'Light ON/OFF & Level Cluster'
11. You can then bring up the On/Off Cluster and send On/Off Commands (Toggle
does not work as required currently) - this will cause LED 1 on the WSTK to
change states

> If the Commissioning is not successful, try to re-boot your mobile and try
> again.
> Once commissioning is completed, if you want to repeat the test, follow these
> steps:
>
> - Remove power to the system (EFR32MG12 + RS9116)
> - Power up the system again - this should cause the LCD to turn on and the
> QR code to show up
> - Press the BTN0 button and keep it pressed for about 1 min - this should
> cause LED0 and LED1 to turns ON and OFF for 3 times. You can then leave
> the button
68 changes: 68 additions & 0 deletions docs/silabs/wifi/WIFI_PREREQS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
[<< Back to TOC](../README.md)

# Matter Wifi Prerequisites

Silicon Labs Matter Wifi is supported on two different platforms, the
[WF200](https://www.silabs.com/wireless/wi-fi/wf200-series-2-transceiver-ics)
and the
[RS9116](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit).
In both cases the Wifi part is attached to an EFR32MG12 development board via a
daughter card. The EFR32MG12 is used as a host processor for the application and
for it's Bluetooth capability which is necessary for Matter commissioning.

In addition to the EFR32MG12 and Wifi boards, you will need to run the Matter
ChipTool on some device. This can be build and run on a Linux or Mac laptop or
on a Raspberry Pi.

The hardware that you will need for Silicon Labs Matter Wifi development is as
follows:

## Hardware

- Linux PC/Laptop **or** Raspberry Pi 4 (This is for running the ChipTool to
commission and control the device)
- Kits/Boards:
- SLWSTK6000B Wireless Starter Kit main board
- BRD4161A/BRD4186C daughter boards are supported
- [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board)
- [XG24-RB4186C](https://www.silabs.com/development-tools/wireless/xg24-rb4186c-efr32xg24-wireless-gecko-radio-board)
> BLE and Matter code runs here
- Wifi Dev Kit, either
[RS9116X-SB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit)
**or**
[WF200](https://www.silabs.com/wireless/wi-fi/wf200-series-2-transceiver-ics)
- Interconnect board (included in the wifi kits)
- SPI Cable (included in the RS9116 kit)
- Jumper Cables (included in the RS9116 kit)
- Access point with Internet access
- microSD card (32GB) (If using Raspberry Pi)
- **[Optional]** Android Mobile phone (If using the ChipTool on Android)

<br>

## Software

- Ozone to flash the images generated
- Windows: [Download Ozone](https://www.segger.com/downloads/jlink/)
> Search for "Ozone - The J-Link Debugger" and download the latest
> Windows installer depending on 32/64bit and install it.
- Linux:
[Download Ozone](https://www.segger.com/downloads/jlink/Ozone_Linux_x86_64.deb)
and install it
- [otional] ChipTool Android mobile application:
[Download](https://confluence.silabs.com/download/attachments/240625466/chip-app.zip?version=1&modificationDate=1647837891300&api=v2),
extract, and install to the Android mobile; [TODO: the link is a confluence
link!]
- Raspberry Pi imager tool: [Download](https://www.raspberrypi.com/software/)
- Upgrade firmware on RS9116 EVK:
[Reference](http://draft-docs.suds.silabs.net/rs9116-wiseconnect/2.5/wifibt-wc-getting-started-with-pc/update-evk-firmware)

<br>

## RS9116: Steps to Update Firmware

Pre-Built Rs9116 firmware is available on the
[Matter Artifacts page](../general/ARTIFACTS.md)

1. [Setting up TeraTerm](https://docs.silabs.com/rs9116/wiseconnect/2.0/tera-term-setup)
2. [Updating the RS9116 Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/update-evk-firmware)
Binary file added docs/silabs/wifi/images/MG12_WF200.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/wifi/images/sd_into_pi.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/wifi/images/wifi_code_edit.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/silabs/wifi/images/wifi_setup.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 886dbdf

Please sign in to comment.