diff --git a/docs/silabs/README.md b/docs/silabs/README.md index 15b214c22242ef..bbd6a411a38849 100644 --- a/docs/silabs/README.md +++ b/docs/silabs/README.md @@ -2,60 +2,62 @@ 1. [Silicon Labs Matter Overview](OVERVIEW.md)
-2. [Matter over Thread \(15.4\)](thread/THREAD.md) +2. Matter Pre-requisites + + 1. [Matter Hardware Requirements](general/HARDWARE_REQUIREMENTS.md) + 2. [Matter Software Requirements](general/SOFTWARE_REQUIREMENTS.md)

+ +3. [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)

- -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) + 2. [Loading the Raspberry Pi image onto the Matter Hub](thread/RASPI_IMG.md) + 3. [Setting up the RCP](thread/RCP.md) + 4. [Creating a Thread Matter End Device](thread/BUILD_FLASH_MAD.md) + 5. [Using the Chip-Tool](thread/CHIP_TOOL.md)

+ +4. [Matter over Wi-Fi](wifi/WIFI.md) + + 1. [Matter Wi-Fi Demo Overview](wifi/DEMO_OVERVIEW.md) + 2. [Building A Matter Wi-Fi End Device](wifi/BUILD_CHIP_ENV.md) + 3. [Running Matter Demo over Wi-Fi](wifi/RUN_DEMO.md) + 4. [optional] + [Running Matter Demo over Wi-Fi using Android](wifi/WIFI_ANDROID.md)

-4. Development using VS Code +5. 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) -

- -5. 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) - 4. [OTA Software Update](general/OTA_SOFTWARE_UPDATE.md)

- -6. Frequently Asked Questions (FAQ) / Troubleshooting + 3. [Debug](dev/vscode/DEBUG.md)

+ +6. Reference Guides + + 1. [Matter Hardware Requirements](general/HARDWARE_REQUIREMENTS.md) + 2. [Matter Software Requirements](general/SOFTWARE_REQUIREMENTS.md) + 3. [Matter Artifacts Page](general/ARTIFACTS.md) + 4. [Matter Commit Hashes](general/COMMIT_HASHES.md) + 5. [How to Flash a Silicon Labs Device](general/FLASH_SILABS_DEVICE.md) + 6. [How to Find Your Raspberry Pi](general/FIND_RASPI.md) + 7. [Silicon Labs Matter Commit Hashes](general/COMMIT_HASHES.md) + 8. [Building a Custom Matter Device](general/CUSTOM_MATTER_DEVICE.md) + 9. [Matter OTA Software Update](general/OTA_SOFTWARE_UPDATE.md) + 10. [Matter Attestation Credentials for EFR32](../../silabs_examples/credentials/README.md) + 11. [Using Simplicity Studio's Pin Tool and Project Configurator with Matter](./general/PINTOOL.m) + 12. [Using Simplicity Studio's BLE GATT Configurator with Matter](./general/GATT.md) + 13. [Using Simplicity Studio's Energy Profiler with Matter](./general/EP.md) + 14. [Using Wireshark to Capture Network Traffic in Matter](./general/WIRESHARK.md)

+ +7. Frequently Asked Questions (FAQ) / Troubleshooting - [Thread FAQ](thread/FAQ.md) - - [Wifi FAQ](wifi/FAQ.md) + - [Wi-Fi FAQ](wifi/FAQ.md) diff --git a/docs/silabs/dev/vscode/SETUP.md b/docs/silabs/dev/vscode/SETUP.md index 36e2db0582702c..8e9465cf64554a 100644 --- a/docs/silabs/dev/vscode/SETUP.md +++ b/docs/silabs/dev/vscode/SETUP.md @@ -5,17 +5,18 @@ 1. Install Visual Studio Code for your operating system of choice here: https://code.visualstudio.com/Download 2. Install [Git](https://git-scm.com/) if you haven't already -3. *Windows Only* Enable git to use LF instead of CLRF by default: `git config - --global core.autocrlf false` +3. _Windows Only_ Enable git to use LF instead of CLRF by default: + `git config --global core.autocrlf false` 4. Git clone the Silicon Labs Matter repository here: https://github.com/SiliconLabs/matter 5. Launch Visual Studio Code, and open the cloned folder 6. When prompted to "install recommended extensions" please select "Install" - * Recommended Extensions can be found [here](../../../../.vscode/extensions.json) + - Recommended Extensions can be found + [here](../../../../.vscode/extensions.json) 7. Ensure the following extensions are installed: - 1. C/C++ Extension Pack - language support for C/C++ - 2. Python - language support for Python - 3. Cortex-Debug - GDB debugger support + 1. C/C++ Extension Pack - language support for C/C++ + 2. Python - language support for Python + 3. Cortex-Debug - GDB debugger support 8. ARM GCC Toolchain (https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) - required arm-none-eabi tools @@ -23,12 +24,60 @@ (https://www.segger.com/downloads/jlink) 10. Python - (https://www.python.org/downloads/) +### Installing prerequisites on macOS + +On macOS, first install Xcode from the Mac App Store. The remaining dependencies +can be installed and satisfied using [Brew](https://brew.sh/): + +> `$ brew install openssl pkg-config` + +However, that does not expose the package to `pkg-config`. To fix that, one +needs to run something like the following: + +Intel: + +> `$ cd /usr/local/lib/pkgconfig ln -s ../../Cellar/openssl@1.1/1.1.1g/lib/pkgconfig/* .` + +where `openssl@1.1/1.1.1g` may need to be replaced with the actual version of +OpenSSL installed by Brew. + +Apple Silicon: + +> `$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:"/opt/homebrew/opt/openssl@3/lib/pkgconfig"` + +Note: If using MacPorts, `port install openssl` is sufficient to satisfy this +dependency. + +### Mac OS (Apple Silicon) Users + +These requirements are are needed for Mac OS (Apple Silicon) in addition to +those mentioned above.
+ +1. Add ARM GCC toolchain to the search path within `bootstrap.sh` by adding this + line of code: + + > `$ export PATH="/Applications/ARM/bin:$PATH"` + +2. Users may also have to specify which `pkg-config`/`openssl` to use by adding + these lines of code as well: + + > `$ export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"` + + > `$ export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig"` + +### Installing prerequisites on Linux + +On Debian-based Linux distributions such as Ubuntu, these dependencies can be +satisfied with the following: + +> ` $ 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` + ## Bootstrapping your source tree (one time) 1. Under the "Terminal" menu (or using shortcut Ctrl+shift+p), select "Run Task..." 2. Select the "Bootstrap" task ------ +--- [Table of Contents](../../README.md) diff --git a/docs/silabs/general/ARTIFACTS.md b/docs/silabs/general/ARTIFACTS.md index cbaaa636525367..6e57458546d9e4 100644 --- a/docs/silabs/general/ARTIFACTS.md +++ b/docs/silabs/general/ARTIFACTS.md @@ -24,7 +24,7 @@ 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: -https://github.com/SiliconLabs/matter/releases/tag/v0.2.0 +https://github.com/SiliconLabs/matter/releases/tag/v0.3.0
@@ -34,25 +34,26 @@ 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.2.0 +https://github.com/SiliconLabs/matter/releases/tag/v0.3.0
## Matter Bootloader Binaries -If you are using the OTA functionality and especially if you are using an EFR32MG2x device you will need to flash a bootloader binary on your device along with the application image. Bootloader binaries for all of the Matter supported devices are available here: +If you are using the OTA functionality and especially if you are using an +EFR32MG2x device you will need to flash a bootloader binary on your device along +with the application image. Bootloader binaries for all of the Matter supported +devices are available here: -https://github.com/SiliconLabs/matter/releases/tag/v0.2.0 +https://github.com/SiliconLabs/matter/releases/tag/v0.3.0 +
## RS9116 Firmware The RS9116 firmware is used to update the RS9116 - it can be found in the -repository you have cloned, at the following relative path from the -`/matter` directory: - -> $ /third_party/silabs/wiseconnect-wifi-bt-sdk/firmware - +repository you have cloned, at the following relative path from the `/matter` +directory, `./third_party/silabs/wiseconnect-wifi-bt-sdk/firmware`
diff --git a/docs/silabs/general/CUSTOM_MATTER_DEVICE.md b/docs/silabs/general/CUSTOM_MATTER_DEVICE.md new file mode 100644 index 00000000000000..f504dfa57df95d --- /dev/null +++ b/docs/silabs/general/CUSTOM_MATTER_DEVICE.md @@ -0,0 +1,130 @@ +# Custom Matter Device Development + +Build a customizable lighting app using the Matter protocol + +## Overview + +This guide will cover the basics of building a customizable lighting application +using Matter. + +## Using Matter with Clusters + +In Matter, commands can be issued by using a cluster. A cluster is a set of +attributes and commands which are grouped together under a relevant theme. + +Attributes store values (think of them as variables). Commands are used to +modify the value of attributes. + +For example, the "On/Off" cluster has an attribute named "OnOff" of type +boolean. The value of this attribute can be set to "1" by sending an "On" +command or it can be set to "0" by sending an "Off" command. + +The C++ implementation of these clusters is located in the clusters directory. +Note that you can also create your own custom cluster. + +## ZAP configuration + +From the matter repository, run the following command in a terminal to launch +the ZAP UI. This will open up the ZAP configuration for the EFR32 lighting +application example. + +> `$ ./scripts/tools/zap/run_zaptool.sh examples/lighting-app/lighting-common/lighting-app.zap` + +On the left hand side of the application, there is a tab for Endpoint 0 and +Endpoint 1. Endpoint 0 is known as the root node. This endpoint is akin to a +"read me first" endpoint that describes itself and the other endpoints that make +up the node. Endpoint 1 represents a lighting application device type. There are +a number of required ZCL clusters enabled in Endpoint 1. Some clusters are +common across most device types, such as identify and group clusters. Others, +such as the On/Off, Level Control and Color Control clusters are required for a +lighting application device type. + +Clicking on the blue settings icon on the right hand side of the application +will bring you to the zap configuration settings for that cluster. Each cluster +has some required attributes that may cause compile-time errors if they are not +selected in the zap configuration. Other attributes are optional and are allowed +to be disabled. Clusters also have a list of client-side commands, again some +are mandatory and others are optional depending on the cluster. ZCL offers an +extensive list of optional attributes and commands that allow you to customize +your application to the full power of the Matter SDK. + +For example, if one was building a lighting application which only includes +single color LEDs instead of RGB LEDs, it might make sense to disable the Color +Control cluster in the ZAP configuration. Similarly, if one were to build a +lighting application that doesn't take advantage of the Level Control cluster, +which allows you to customize current flow to an LED, it might make sense to +disable the Level Control cluster. + +Each time a modification is made to the ZAP UI, one must save (Electron→Save on +a Mac toolbar) the current ZAP configuration and run the following command to +generate ZAP code. + +> `$ ./scripts/tools/zap/generate.py examples/lighting-app/lighting-common/lighting-app.zap -o zzz_generated/lighting-app/zap-generated/` + +## Receiving Matter commands + +All Matter commands reach the application through the intermediate function +MatterPostAttributeChangeCallback(). When a request is made by a Matter client, +the information contained in the request is forwarded to a Matter application +through this function. The command can then be dissected using conditional logic +to call the proper application functions based on the most recent command +received. + +## Adding a cluster to a ZAP configuration + +In the ZAP UI, navigate to the Level Control cluster. Make sure this cluster is +enabled as a server in the drop down menu in the "Enable" column. Then click on +the blue settings wheel in the "Configure" column. This cluster can be used to +gather power source configuration settings from a Matter device. It contains a +few required attributes, and a number of optional attributes. + +## Adding a new attribute + +In the Level Control cluster configurations, ensure the CurrentLevel attribute +is set to enabled. Set the default value of this attribute as 1. + +## Adding a new command + +Navigate to the commands tab in zap and enable the MoveToLevel command. Now save +the current zap configuration, and run the aforementioned generate.py script. + +## React to Level Control cluster commands in ZclCallbacks + +In the MatterPostAttributeCallback function in ZclCallbacks, add the following +line of code or similar. This will give the application the ability to react to +MoveToLevel commands. The developer can define platform specific behavior for a +MoveToLevel action. + + else if (clusterId == LevelControl::Id) + { + ChipLogProgress(Zcl, "Level Control attribute ID: " ChipLogFormatMEI " Type: %u Value: %u, length %u", + ChipLogValueMEI(attributeId), type, *value, size); + + if (attributeId == LevelControl::Attributes::CurrentLevel::Id) + { + action_type = LightingManager::MOVE_TO_LEVEL; + } + + LightMgr().InitiateActionLight(AppEvent::kEventType_Light, action_type, endpoint, *value); + } + +## Send a MoveToLevel command and read the CurrentLevel attribute + +Rebuild the application and load the new executable on your EFR32 device. Send +the following mattertool commands and verify that the current-level default +attribute was updated as was configured. Replace {desired_level} with 10, and +node_ID with the node ID assigned to the device upon commissioning + +> `$ mattertool levelcontrol read current-level 1 1 // Returns 1` + +> `$ mattertool levelcontrol move-to-level {desired_level} 0 1 1 {node_ID} 1` + +> `$ mattertool levelcontrol read current-level 1 1 // Returns 10` + +More Information Silicon Labs lighting example on a Thunderboard Sense 2 - +[sl-newlight/efr32](../../../silabs_examples/sl-newLight/efr32/README.md) + +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/general/EP.md b/docs/silabs/general/EP.md new file mode 100644 index 00000000000000..6c3d80f74c902e --- /dev/null +++ b/docs/silabs/general/EP.md @@ -0,0 +1,19 @@ +# Using Simplicity Studio's Energy Profiler with Matter + +Simplicity Studio's Energy Profiler allows the developer to see a graphical view +of their devices energy usage over time. This can be very useful when developing +an energy friendly device. + +Using Energy Profiler with Matter is the same as any other protocol except that +you need to start the usage from within Energy Profiler rather than using an +existing Simplicity Studio project since your Matter project will not have been +created inside Simplicity Studio. + +Complete documentation on using the Simplicity Studio Energy Profiler is +provided in the +[Simplicity Studio 5 Energy Profiler User's Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/1.0/using-the-tools/energy-profiler/) + +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/general/FLASH_SILABS_DEVICE.md b/docs/silabs/general/FLASH_SILABS_DEVICE.md index 937a593186f86c..7700030d44b63a 100644 --- a/docs/silabs/general/FLASH_SILABS_DEVICE.md +++ b/docs/silabs/general/FLASH_SILABS_DEVICE.md @@ -13,5 +13,9 @@ Simplicity Studio is a complete development environment and tool suite. It has t - [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) +## (Optional) Ozone J-Link Debugger: +Multi-platform debugger and performance analyzer for J-Link and J-Trace +- Download for: [Windows](https://www.segger.com/downloads/jlink/Ozone_Setup_Windows_x64.exe) | [Mac](https://www.segger.com/downloads/jlink/Ozone_macOS_Universal.pkg) | [Linux](https://www.segger.com/downloads/jlink/Ozone_Linux_x86_64.deb) + ---- [Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file diff --git a/docs/silabs/general/GATT.md b/docs/silabs/general/GATT.md new file mode 100644 index 00000000000000..aff39f1c548cdf --- /dev/null +++ b/docs/silabs/general/GATT.md @@ -0,0 +1,54 @@ +# Using Simplicity Studio's GATT Configurator with Matter + +The Simplicity Studio Bluetooth GATT Configurator is an Advanced Configurator +within the Simplitiy Studio Project Confguration suite. For more information on +using the +[Simplicity Studio Project Configurator in Matter please refer to this guide](./PINTOOL.md). +Use of the BLE GATT Configurator in Matter assumes that you are already familiar +with creating and using an `Empty C++` Project in Simplicity Studio. + +Once you have created your `Empty C++` project, you can add the Bluetooth +component which will give you access to the GATT configurator for your project. +More information on use of the +[BLE GATT Configurator in Simplicity Studio is provided here](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/bluetooth-gatt-configurator). + +The basic steps for using the Simplicity Studio BLE GATT Configurator are as +follows: + +1. Create an `Empty C++` project in Simplicity Studio's Project Creation Wizard + + More information on creating an `Empty C++` project can be found in + [the Project Configurator guide here.](./PINTOOL.md) + +2. Add the BLE component to your project + + Once you have opened your `Empty C++` project, you can add the BLE GATT + configuration by adding the `Bluetooth > GATT > Configuration` component to + your project. This will enable the BLE GATT Configurator under + `Configuration Tools > Bluetooth GATT Configurator` + +3. Open the BLE GATT Advanced Configurator in Simplicity Studio + + In the top menu of your project navigate to + `Configuration Tools > Bluetooth GATT Configurator` + +4. Change your GATT settings as you wish for your project. + + More information on using the + [BLE GATT Configurator is provided here.](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/bluetooth-gatt-configurator) + +5. Save your project which will force the generation of your BLE GATT + Configuration + +6. BLE GATT database is stored in the `autogen` folder in your project directory + +7. Move the BLE GATT db into your Matter project. + + Copy the BLE GATT db header files out of your project and into the Matter + project. BLE GATT db header and `.c` files are located in + `./src/platform/EFR32` in the Silicon Labs Matter GitHub repo. + +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/general/HARDWARE_REQUIREMENTS.md b/docs/silabs/general/HARDWARE_REQUIREMENTS.md new file mode 100644 index 00000000000000..6f96c159e8862d --- /dev/null +++ b/docs/silabs/general/HARDWARE_REQUIREMENTS.md @@ -0,0 +1,142 @@ +# Matter Hardware Requirements + +Whether you are running Matter over Thread or Matter over Wi-Fi you will need +some Silicon Labs hardware in order to run demos and do development. What +follows are the hardware requirements for both Thread and Wi-Fi use cases broken +down by platform and transport protocol. + +## Matter Over Thread "Matter Hub" Requirements + +If you are running Matter over Thread and do not have a platform on which to run +the Open Thread Border Router and Chip-Tool, Silicon Labs recommends that you +run them on a Raspberry Pi. This recommendation leads to the following +requirements: + +- **Raspberry Pi** + + - Raspberry Pi 4 with an SD card with storage >= 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' A software image + > for the Raspberry Pi is provided on the + > [Matter Artifacts page](./ARTIFACTS.md). + +- **Radio Co-Processor (RCP)** + + The Matter Hub needs a 15.4 Radio Co-Processor (RCP) in order to create and + interact with the Thread network. The RCP can be any Silicon Labs + development board that is capable of running the OpenThread RCP firmware. + The RCP radio board is connected to the Raspberry Pi via USB. + + Over 60 Silicon Labs boards support the running of the RCP firmware. For a + complete list of boards supported please download and build your image in + Simplicity Studio. Pre-built OpenThread RCP firmware images are provided for + the following boards on the [Matter Artifacts page](./ARTIFACTS.md): + + - **MG12 boards:** + + - BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm + - [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board) + - BRD4162A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@10dBm + - [SLWRB4162A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4162a-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) +

+ + - **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) + +## Matter Over Thread Accessory Device Requirements + +The Matter Accessory Device (MAD) is the actual device that the Matter +application firmware runs on. This is the Matter Light or the Matter Switch for +instance. Several different platforms for the Matter Accessory Device are +supported. Pre-built binary images for the Matter accessory devices are provided +on the [Matter Artifacts page](./ARTIFACTS.md). Silicon Labs supports +development of Matter Accessory Devices for Matter over Thread on the following +platforms: + +- **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) + - BRD4162A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@10dBm + - [SLWRB4162A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4162a-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) +

+ +- **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) + - BRD2703A / MG24 Explorer Kit + > Note: This board has yet to be released to the public, but it is + > supported in the Silicon Labs build flow. + - BRD2601B / MG24 Explorer Kit + - [XG24-DK2601B](https://www.silabs.com/development-tools/wireless/efr32xg24-dev-kit?tab=overview) + +## Matter over Wi-Fi Accessory Device Requirements + +The Silicon Labs Matter over Wi-Fi demo and development requires two boards, the +Silicon Labs EFR32 Radio board to run the Matter code along with either the +RS9116 or the WF200 to run the Wi-Fi protocol stack. Pre-built images for both +the EFR32 and the RS9116 are provided on the +[Matter Artifacts page](./ARTIFACTS.md). The following boards are supported for +the Matter over Wi-Fi demos and development: + +- **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) + - BRD4162A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@10dBm + - [SLWRB4162A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4162a-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) +

+ +- **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) +

+ +- **Wi-Fi Dev Kit** + + - RS9116 + - [RS9116X-SB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit) + - WF200 + - [WF200](https://www.silabs.com/wireless/wi-fi/wf200-series-2-transceiver-ics) + - Interconnect board (included in the Wi-Fi kits) + - SPI Cable (included in the RS9116 kit) + - Jumper Cables (included in the RS9116 kit) + +## Additional Matter over Wi-Fi Hardware Requirements + +Matter over Wi-Fi has a few additional requirements for the working of the demo +and development. In addition to your Matter over Wi-Fi Accessory Device you will +need the following: + +- Access point with Internet access +- microSD card (32GB) (if using Raspberry Pi) +- **[Optional]** Android Mobile phone (If using the ChipTool on Android) diff --git a/docs/silabs/general/OTA_BOOTLOADER.md b/docs/silabs/general/OTA_BOOTLOADER.md index fd2cbe5382320f..a65fb5a2ef75a0 100644 --- a/docs/silabs/general/OTA_BOOTLOADER.md +++ b/docs/silabs/general/OTA_BOOTLOADER.md @@ -1,89 +1,173 @@ # Creating Gecko Bootloader for Use in Matter OTA Software Update -The Matter OTA Software Update functionality on EFR32 devices requires the use of a Gecko Bootloader built with correct configuration parameters. The key parameters are the storage slot size and (in case of internal storage) storage slot address. The current document lists the steps required to build the Gecko Bootloader for Matter OTA Update and discusses the configuration parameter selection. For a detailed discussion of Gecko Bootloader refer to _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_. - -The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These instructions assume that you have installed Simplicity Studio 5, the Simplicity Commander tool (installed by default with Simplicity Studio), the GSDK and associated utilities, and that you are familiar with generating, compiling, and flashing an example application in the relevant version. +The Matter OTA Software Update functionality on EFR32 devices requires the use +of a Gecko Bootloader built with correct configuration parameters. The key +parameters are the storage slot size and (in case of internal storage) storage +slot address. The current document lists the steps required to build the Gecko +Bootloader for Matter OTA Update and discusses the configuration parameter +selection. For a detailed discussion of Gecko Bootloader refer to _UG489: +Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_. + +The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These +instructions assume that you have installed Simplicity Studio 5, the Simplicity +Commander tool (installed by default with Simplicity Studio), the GSDK and +associated utilities, and that you are familiar with generating, compiling, and +flashing an example application in the relevant version. ## Bootloader Project In Studio + ### Creating the Project -In Simplicity Studio click on Project->New->Silicon Labs Project Wizard to create a new project. Select the correct Target Board, SDK and the Toolchain. For Matter 1.0 it is recommended that the bootloader is built with GSDK 4.1. -In the next screen select the example project the bootloader will be based on. For a bootloader using external storage select "Bootloader SoC SPI Flash Storage (single image with slot size of 1024K)". For a bootloader using internal storage select "Bootloader - SoC Internal Storage (single image on 512kB device)" +In Simplicity Studio click on Project->New->Silicon Labs Project Wizard to +create a new project. Select the correct Target Board, SDK and the Toolchain. +For Matter 1.0 it is recommended that the bootloader is built with GSDK 4.1. -### Configuring Storage Components and Parameters -In the newly created project select the project's .slcp file, click the "Software Components" tab, and select Platform->Bootloader->Storage. In the Bootloader Storage Slot component (it should be already installed) configure Slot 0's Start Address and Slot size. +In the next screen select the example project the bootloader will be based on. +For a bootloader using external storage select "Bootloader SoC SPI Flash Storage +(single image with slot size of 1024K)". For a bootloader using internal storage +select "Bootloader - SoC Internal Storage (single image on 512kB device)" -- For external storage bootloaders the Start Address should be 0 and Slot size should be 1048576 -- both values are set by default -- For internal storage bootloaders see the "Internal Bootloader: Image Size, Selecting Storage Slot Address and Size" section below -In the Common Storage component leave the "Start address of bootload info" at 0. - -### Configuring Other Components -It is recommended to install the "GBL Compression (LZMA)" component under Platform->Bootloader->Core: this allows the bootloader to handle compressed GBL files. This component is required for internal storage bootloaders. +### Configuring Storage Components and Parameters -At this point the project contains all the components necessary to support the Matter OTA Software Update functionality. Other components can now be added to support additional features such as Secure Boot. Refer to _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_ for the description of various Bootloader features and the steps to enable them. +In the newly created project select the project's .slcp file, click the +"Software Components" tab, and select Platform->Bootloader->Storage. In the +Bootloader Storage Slot component (it should be already installed) configure +Slot 0's Start Address and Slot size. -### Building and Flashing the Bootloader -Build the project by clicking on the hammer icon in the Studio toolbar. Flash the bootloader to the board using the "Upload Application" option from the Debug Adapters view. +- For external storage bootloaders the Start Address should be 0 and Slot size + should be 1048576 -- both values are set by default +- For internal storage bootloaders see the "Internal Bootloader: Image Size, + Selecting Storage Slot Address and Size" section below In the Common Storage + component leave the "Start address of bootload info" at 0. -### Combined bootloader for MG12 boards -The MG12 boards (which are Series 1 EFR32 boards) require a combined bootloader image (first stage bootloader + main bootloader) the first time a device is programmed -- whether during development or manufacturing. For subsequent programming, if the combined bootloader had been previously flashed to the device use the regular version. +### Configuring Other Components -To create the combined bootloader follow this additional step (Step 6 in Section 6 of _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_) before clicking the build icon: Right-click the project name in the Project Explorer view and select Properties. In the C/C++ Build group, click Settings. On the Build Steps tab, in the Post Build Steps Command field enter +It is recommended to install the "GBL Compression (LZMA)" component under +Platform->Bootloader->Core: this allows the bootloader to handle compressed GBL +files. This component is required for internal storage bootloaders. - ../postbuild.sh "${ProjDirPath}" "${StudioSdkPath}" "${CommanderAdapterPackPath}" +At this point the project contains all the components necessary to support the +Matter OTA Software Update functionality. Other components can now be added to +support additional features such as Secure Boot. Refer to _UG489: Silicon Labs +Gecko Bootloader User's Guide for GSDK 4.0 and Higher_ for the description of +various Bootloader features and the steps to enable them. -Click Apply and Close. Three bootloader images will be generated into the build directory: a main bootloader, a main bootloader with CRC32 checksum, and a combined first stage and main bootloader with CRC32 checksum. The main bootloader image is called .s37, the main bootloader with CRC32 checksum is called -crc.s37, while the combined first stage image + main bootloader image with a CRC32 checksum is called -combined.s37. +### Building and Flashing the Bootloader +Build the project by clicking on the hammer icon in the Studio toolbar. Flash +the bootloader to the board using the "Upload Application" option from the Debug +Adapters view. -## Internal Bootloader: Image Size, Selecting Storage Slot Address and Size -The internal storage bootloader for Matter OTA software update is supported on MG24 boards only. In this use case both the running image and the downloadable update image must fit on the internal flash at the same time. This in turn requires that both images are built with a reduced feature set such as disabled logging and Matter shell (see [here](./OTA_SOFTWARE_UPDATE.md#Internal-Storage-Bootloader) for the list of features). Using LZMA compression when building the GBL file further reduces the downloaded image size. +### Combined bootloader for MG12 boards -When building an internal storage bootloader the two key configuration parameters are the Slot Start Address and Slot Size in the Bootloader Storage Slot component. The storage slot must not overlap with the running image and the NVM section of the flash. In other words, the slot start address must be greater than the end of the running image address and the sum of the start address and the slot size must be less than the address of the NVM section. +The MG12 boards (which are Series 1 EFR32 boards) require a combined bootloader +image (first stage bootloader + main bootloader) the first time a device is +programmed -- whether during development or manufacturing. For subsequent +programming, if the combined bootloader had been previously flashed to the +device use the regular version. + +To create the combined bootloader follow this additional step (Step 6 in Section +6 of _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and +Higher_) before clicking the build icon: Right-click the project name in the +Project Explorer view and select Properties. In the C/C++ Build group, click +Settings. On the Build Steps tab, in the Post Build Steps Command field enter + +> `$ ../postbuild.sh "${ProjDirPath}" "${StudioSdkPath}" "${CommanderAdapterPackPath}"` + +Click Apply and Close. Three bootloader images will be generated into the build +directory: a main bootloader, a main bootloader with CRC32 checksum, and a +combined first stage and main bootloader with CRC32 checksum. The main +bootloader image is called .s37, the main bootloader with CRC32 +checksum is called -crc.s37, while the combined first stage image + +main bootloader image with a CRC32 checksum is called +-combined.s37. + +## Internal Bootloader: Image Size, Selecting Storage Slot Address and Size + +The internal storage bootloader for Matter OTA software update is supported on +MG24 boards only. In this use case both the running image and the downloadable +update image must fit on the internal flash at the same time. This in turn +requires that both images are built with a reduced feature set such as disabled +logging and Matter shell (see +[here](./OTA_SOFTWARE_UPDATE.md#Internal-Storage-Bootloader) for the list of +features). Using LZMA compression when building the GBL file further reduces the +downloaded image size. + +When building an internal storage bootloader the two key configuration +parameters are the Slot Start Address and Slot Size in the Bootloader Storage +Slot component. The storage slot must not overlap with the running image and the +NVM section of the flash. In other words, the slot start address must be greater +than the end of the running image address and the sum of the start address and +the slot size must be less than the address of the NVM section. ![Internal Flash Layout](./images/InternalFlashLayout.png) -The simplest way to get the relevant addresses for the running image and NVM is by using the Simplicity Commander tool: +The simplest way to get the relevant addresses for the running image and NVM is +by using the Simplicity Commander tool: - Build the running image for the Matter application -- Erase the chip and flash the running image to it (For example: use Simplicity Studio's Debug Adapters view context menu to flash the application image and some bootloader valid for the device board. Make sure to select the "Erase chip before uploading image" option). -- In Simplicity Commander, select Device Info -> Flash Map. The blank area in the middle of the flash (between the running image in the beginning and NVM at the end) is available for the bootloader storage slot. Each block represents a flash page (8K on MG24 boards). Hovering the mouse over a block shows the block's start and end address. -- Set the Slot Start Address to be the address of the first available block. Calculate the Slot Size to be the difference between the end address of the last free block and the Slot Start Address. The Slot Size must be greater that the size of the GBL file for the update image. -- (Optional) It might be advisable to set the Slot Start Address to the beginning of the second or third available block to account for potential growth of the application image -- this way the bootloader won't have to be reconfigured for every increase in the image size. The storage slot must still be able to accommodate the GBL image for the update. -Another way to calculate the Storage Slot parameters is by examining the application's .map file: +- Erase the chip and flash the running image to it (For example: use + Simplicity Studio's Debug Adapters view context menu to flash the + application image and some bootloader valid for the device board. Make sure + to select the "Erase chip before uploading image" option). +- In Simplicity Commander, select Device Info -> Flash Map. The blank area in + the middle of the flash (between the running image in the beginning and NVM + at the end) is available for the bootloader storage slot. Each block + represents a flash page (8K on MG24 boards). Hovering the mouse over a block + shows the block's start and end address. +- Set the Slot Start Address to be the address of the first available block. + Calculate the Slot Size to be the difference between the end address of the + last free block and the Slot Start Address. The Slot Size must be greater + that the size of the GBL file for the update image. +- (Optional) It might be advisable to set the Slot Start Address to the + beginning of the second or third available block to account for potential + growth of the application image -- this way the bootloader won't have to be + reconfigured for every increase in the image size. The storage slot must + still be able to accommodate the GBL image for the update. Another way to + calculate the Storage Slot parameters is by examining the application's .map + file: - Build the running image for the Matter application -- In the application .map file find the highest address preceding the .data section, round it up to align on the 8K page boundary (e.g. 0x00000000080f1704 would round up to 0x00000000080f2000) and then add 0x2000 get the next page block address -- the result would be the Slot Start Address. The address of the .nvm section in the .map file is the end of the space available for the Storage Slot. The Slot Size is the difference of the .nvm address and the Slot Start Address. +- In the application .map file find the highest address preceding the .data + section, round it up to align on the 8K page boundary (e.g. + 0x00000000080f1704 would round up to 0x00000000080f2000) and then add 0x2000 + get the next page block address -- the result would be the Slot Start + Address. The address of the .nvm section in the .map file is the end of the + space available for the Storage Slot. The Slot Size is the difference of the + .nvm address and the Slot Start Address. ## Example -This example is for an internal storage bootloader for the Matter lighting app on BRD4186C. -- Build the application disabling all optional features +This example is for an internal storage bootloader for the Matter lighting app +on BRD4186C. - $ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/lighting-app BRD4186A chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true +- Build the application disabling all optional features + > `$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out lighting-app BRD4186A chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true` -Build the GBL file for the update image and note its size +- Build the GBL file for the update image and note its size - $ commander gbl create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37 + > `$ commander gbl create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37` - $ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl - 451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl + > `$ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl 451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl` - -- Flash the application image, bootloader (pre-built BRD4186C bootloader binary from the [Matter Artifacts page](./ARTIFACTS.md). Erase the flash. +- Flash the application image, bootloader (pre-built BRD4186C bootloader + binary from the [Matter Artifacts page](./ARTIFACTS.md). Erase the flash. ![Erase Flash](./images/ApplicationUploadEraseFlash.png) - - - In Simplicity Commander display the flash map -![Flash Map](./images/CommanderFlashMap.png) - - - -- The address of the first available page is 0x080b8000, the end address of the last available block is 0x08172000. This means you can set the Slot Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file (451176 bytes) -- Create a project base on the "Bootloader - SoC Internal Storage (single image on 512kB device)" example. Configure the Bootloader Storage Slot component and set Slot Address and Slot Size. -![StudioProject](./images/StudioProject.png) + ![Flash Map](./images/CommanderFlashMap.png) + +- The address of the first available page is 0x080b8000, the end address of + the last available block is 0x08172000. This means you can set the Slot + Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = + 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file + (451176 bytes) +- Create a project base on the "Bootloader - SoC Internal Storage (single + image on 512kB device)" example. Configure the Bootloader Storage Slot + component and set Slot Address and Slot Size. + ![StudioProject](./images/StudioProject.png) - Enable the "GBL Compression (LZMA)" component. - Build the project diff --git a/docs/silabs/general/OTA_SOFTWARE_UPDATE.md b/docs/silabs/general/OTA_SOFTWARE_UPDATE.md index e049df26979ec3..ebb4289cde02b9 100644 --- a/docs/silabs/general/OTA_SOFTWARE_UPDATE.md +++ b/docs/silabs/general/OTA_SOFTWARE_UPDATE.md @@ -1,8 +1,8 @@ # Matter Software Update with EFR32 Example Applications -The Over The Air (OTA) Software Update functionality is enabled by default -for all of the EFR32 example applications. Its inclusion in an application -is controlled by the `chip_enable_ota_requestor` compile flag. +The Over The Air (OTA) Software Update functionality is enabled by default for +all of the EFR32 example applications. Its inclusion in an application is +controlled by the `chip_enable_ota_requestor` compile flag. ## Running the OTA Download Scenario @@ -13,66 +13,52 @@ is controlled by the `chip_enable_ota_requestor` compile flag. - On a Linux or Darwin platform build the chip-tool and the ota-provider-app as follows: - - scripts/examples/gn_build_example.sh examples/chip-tool out/ - scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false - + > `$ scripts/examples/gn_build_example.sh examples/chip-tool out/` + + > `$ scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false` - Build or download the Gecko Bootloader binary. Follow the instructions in - [Creating the Bootloader for Use in Matter OTA](OTA_BOOTLOADER.md). For the bootloader - using the external flash select the "external SPI" bootloader type - configured with a single slot of at least 1000 KB. For the bootloader using - the internal flash see the Internal Storage Bootloader section below. - Pre-built binaries for some configurations are available on the [Matter Artifacts page](./ARTIFACTS.md), - see README.md for details. - + [Creating the Bootloader for Use in Matter OTA](OTA_BOOTLOADER.md). For the + bootloader using the external flash select the "external SPI" bootloader + type configured with a single slot of at least 1000 KB. For the bootloader + using the internal flash see the Internal Storage Bootloader section below. + Pre-built binaries for some configurations are available on the + [Matter Artifacts page](./ARTIFACTS.md), see README.md for details. + - Using the commander tool, upload the bootloader to the device running the application. - Create a bootable image file (using the Lighting application image as an example): - - commander gbl create chip-efr32-lighting-example.gbl --app chip-efr32-lighting-example.s37 - + > `$ commander gbl create chip-efr32-lighting-example.gbl --app chip-efr32-lighting-example.s37` - Create the Matter OTA file from the bootable image file: - - ./src/app/ota_image_tool.py create -v 0xFFF1 -p 0x8005 -vn 2 -vs "2.0" -da sha256 chip-efr32-lighting-example.gbl chip-efr32-lighting-example.ota - + > `$ ./src/app/ota_image_tool.py create -v 0xFFF1 -p 0x8005 -vn 2 -vs "2.0" -da sha256 chip-efr32-lighting-example.gbl chip-efr32-lighting-example.ota` - In a terminal start the Provider app and pass to it the path to the Matter OTA file created in the previous step: - - rm -r /tmp/chip_* - ./out/debug/chip-ota-provider-app -f chip-efr32-lighting-example.ota - + > `$ rm -r /tmp/chip_* ./out/debug/chip-ota-provider-app -f chip-efr32-lighting-example.ota` - In a separate terminal run the chip-tool commands to provision the Provider: - - ./out/chip-tool pairing onnetwork 1 20202021 - ./out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 - + > `$ ./out/chip-tool pairing onnetwork 1 20202021` -- If the application device had been previously commissioned, hold Button 0 for - six seconds to factory-reset the device. + > `$ ./out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0` -- In the chip-tool terminal enter: +- If the application device had been previously commissioned, hold Button 0 + for six seconds to factory-reset the device. - - ./out/chip-tool pairing ble-thread 2 hex: 20202021 3840 - +- In the chip-tool terminal enter: + > `$ ./out/chip-tool pairing ble-thread 2 hex: 20202021 3840` where operationalDataset is obtained from the OpenThread Border Router. - Once the commissioning process completes enter: - - ./out/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0 - + > ` $ ./out/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0` - The application device will connect to the Provider and start the image download. Once the image is downloaded the device will reboot into the @@ -87,9 +73,14 @@ that both images are built with a reduced feature set such as disabled logging and Matter shell. The following set of compile flags leaves out all the optional features and results in the minimal image size: - - chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true - + chip_detail_logging=false + chip_automation_logging=false + chip_progress_logging=false + is_debug=false + show_qr_code=false + chip_build_libshell=false + enable_openthread_cli=false + chip_openthread_ftd=true Using LZMA compression when building the .gbl file ( passing `--compress lzma` parameter to the `commander gbl create` command) further reduces the downloaded @@ -101,8 +92,8 @@ Slot component. The storage slot must not overlap with the running image and the NVM section of the flash. In other words, the slot start address must be greater than the end of the running image address and the sum of the start address and the slot size must be less than the address of the NVM section. The simplest way -to get the relevant addresses for the running image and NVM is by using -the Silicon Labs `Simplicity Commander` (Device Info->Main Flash->Flash Map). +to get the relevant addresses for the running image and NVM is by using the +Silicon Labs `Simplicity Commander` (Device Info->Main Flash->Flash Map). The pre-built bootloader binaries are configured with slot start address of 0x080EC000 and slot size of 548864 @@ -135,7 +126,6 @@ Product ID that identify the image served by the Provider, see Example provider configuration file: - { "foo": 1, // ignored by parser "deviceSoftwareVersionModel": [ @@ -143,7 +133,6 @@ Example provider configuration file: ] } - ## Additional Info Developers can find more resources on diff --git a/docs/silabs/general/PINTOOL.md b/docs/silabs/general/PINTOOL.md new file mode 100644 index 00000000000000..29ad5eea7a85bc --- /dev/null +++ b/docs/silabs/general/PINTOOL.md @@ -0,0 +1,58 @@ +# Using Simplicity Studio's Pintool and Project Configuration with Matter + +In the course of developing your product you will likely run into a situation +where you need to move your project over to your custom hardware. In this case, +you will likely need to change the pinout and hardware configuration from what +it is in the example project to reflect your own custom project. You can do this +with Simplicity Studio's Pintool starting from a blank C++ project. + +## 1. Locating the board support files in the Matter repo + +The pin and peripheral configuration for your example application is stored +within the Silicon Labs Matter support directory. For all the examples used in +the matter repository, the peripheral and pin configurations are stored at + +`./third_party/silabs/matter_support/matter/efr32///config` + +When creating a configuration for a custom board you do the following: + +1. Create a Custom C++ project within Simplicity Studio. +2. Include your desired peripherals in the project. +3. Copy the generated output config files into a custom board support directory + within the Matter repository. + +## 2. Create a sample "Empty C++ project" in Simplicity Studio + +1. Create a project Open Simplicity Studio and click on `Create a New Project` + to start the project wizard. Choose your development board type, and the + latest Gecko SDK you'll be working from. Click `Next` + +1. Example C++ Project Choose your example `Empty C++ Project` and click `Next` + +1. Create your project Click on `Finish` to create your project. + +## 3. Customize your Components and Pin configuration in Simplicity Studio + +Once you have your project created you will see your project and project +configuration in Simplicity Studio's Project Configurator. Full documentation on +the use of the Project Configurator and Pin Tool are located here: +[Simplicity Studio 5 User's Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/) + +## 4. Generate your Component and Pin configuration in Simplicity Studio + +When you save your project configuration, you will notice that Simplicity Studio +saves all the generated header files out into a `config` directory in your +project. These are the files that make up the software component and pin tool +configuration for your device. + +## 5. Move your pin configuration over to your Matter project + +All of the header files in your `config` project directory constitute the +hardware configuration for your device. You will want to copy these files over +into your Matter project so that they can be used in place of the ones provided +in the example. + +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/general/SOFTWARE_REQUIREMENTS.md b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md new file mode 100644 index 00000000000000..91a8ab1f5c065d --- /dev/null +++ b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md @@ -0,0 +1,123 @@ +# Matter Software Requirements + +## **System Agnostic Software Requirements (Windows/Mac/Linux):** + +1. SSH Client ([PuTTY](https://www.putty.org/), Terminal, or similar): + > SSH client is used to communicate with the Raspberry Pi over a secure + > shell. +2. [Raspberry Pi Disk Imager](https://www.raspberrypi.com/software/) + > Raspberry Pi Disk Imager is used to flash the SD Card that contains the + > operating system for the Raspberry Pi. Note that, for the Thread demo, the + > operating system is the demo image. +3. [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. +4. [Git Version Control ](https://git-scm.com/downloads)[only required for + building images and development] + + > Clone the Silicon Labs Matter repo, then enter and sync all the necessary + > submodules with the following commands:
+ + > `$ git clone https://github.com/SiliconLabs/matter.git` + + > `$ cd matter` + + > `$ ./scripts/checkout_submodules.py --shallow --recursive --platform efr32` + +5. If you are using an EFR32MG2x device you will require a bootloader to run the + demo applications. When you flash your application image be sure to include a + bootloader as well (if one is not already present). Bootloader images are + provided on the [Matter Artifacts page](../general/ARTIFACTS.md). + +
+ +## **Windows-Specific Software Requirements:** + +  These requirements are in addition to those mentioned above, for Windows +only.
+ +  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 + +
+ +## **Mac-Specific Requirements (building own images):** + +  These requirements are in addition to those mentioned above for Mac OS +users building their own images.
+ +1. Install Homebrew + + > `$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` + +2. Install pkg-config, openssl, git-lfs + + > `$ brew install pkg-config openssl git-lfs` + +3. Install ARM GNU Toolchain (https://developer.arm.com/downloads/-/gnu-rm) +4. Add ARM GCC toolchain to the search path within `bootstrap.sh` by adding this + line of code: + + > `$ export PATH="/Applications/ARM/bin:$PATH"` + +
+ + Depending on your Mac processor, you will have to complete the following additional steps. + +### **Apple Silicon (M1) Software Requirements:** + +Users may also have to specify which `pkg-config`/`openssl` to use by adding +these lines of code to `bootstrap.sh` as well: + +> `$ export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"` + +> `$ export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig"` + +
+ +### **Intel Software Requirements:** + +> `$ cd /usr/local/lib/pkgconfig` + +> `$ cd ln -s ../../Cellar/openssl@1.1/1.1.1g/lib/pkgconfig/* .` + +`openssl@1.1/1.1.1g` may need to be replaced with the actual version of OpenSSL +installed by Brew. + +If using MacPorts, `port install openssl` is sufficient to satisfy this +dependency. + +
+ +## **Linux Specific Requirements:** + +On Debian-based Linux distributions such as Ubuntu, these dependencies can be +satisfied with the following: + +> `$ 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` + +
+ +## **Wi-Fi RS9116 Specific Requirements:** + +Before you run the demo or development on the RS9116 please be sure that you +update the RS9116 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) + +--- + +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/general/WIRESHARK.md b/docs/silabs/general/WIRESHARK.md new file mode 100644 index 00000000000000..6677c6ce0c19b5 --- /dev/null +++ b/docs/silabs/general/WIRESHARK.md @@ -0,0 +1,55 @@ +# Using Wireshark to Capture Network Traffic in Matter + +When developing a wireless application it is often useful to be able to +visualize the network traffic. [Wireshark](https://www.wireshark.org/) is a +great tool for this, but you can't use Wireshark alone. You first have to +capture the network traffic off a wireless network interface. Fortunately +Silicon Labs has provided an open source project for capturing network traffic +off its devices called the +[Java Packet Trace Library or Silabs PTI .jar](https://github.com/SiliconLabs/java_packet_trace_library) + +Here are the following steps for capturing and visualizing network traffic with +Wireshark and the Java Packet Trace Library: + +## 1. Clone and Build Silabs-PTI.jar Out of the Java Packet Trace Library + +The +[Java Packet Trace Library](https://github.com/SiliconLabs/java_packet_trace_library) +can be built locally for your development platform. First clone the repository +and then build the library according to the +[instructions](https://github.com/SiliconLabs/java_packet_trace_library/blob/master/README.md) + +## 2. Download Wireshark + +If you don't have Wireshark, you can +[download Wireshark for your development platform here](https://www.wireshark.org/). + +## 3. Follow Instructions for Wireshark Integration + +In order to capture from a Silicon Labs device like a WSTK you will need to use +the Silabs-PTI.jar utility you built in the previous step. You will further need +to integrate the execution of the utility into Wireskark through Wireshark's +`excap` interface. A complete guide to +[Wireshark Integration is provided here](https://github.com/SiliconLabs/java_packet_trace_library/blob/master/doc/wireshark.md). +You integrate the Silabs-PTI.jar utility into Wirehshark by adding a small +script into Wireshark's `excap` directory. Make sure that you make the script +executable using something like + +> `$ chmod 777 ` + +This will make it so that Wireshark can execute the script and integrate the +WSTK interfaces into its capture functionality. + +## 4. Run Wireshark and Discover and Capture using Silabs-PTI.jar + +In order to capture from an adapter such as a WSTK using the utility +Silabs-PTI.jar that you built in step 2, your adapter must be connected to the +network via Ethernet. If your adapter is not connected via Ethernet and only via +USB you will need to use the `silink` utility to make the adapter show up as a +localhost. + +Once your adapter is connected, you can test out the visibility of your WSTK on +the network by running Silabs-PTI.jar from the command line using the following +command: + +> `$ java -jar silabs-pti-.jar -discover` diff --git a/docs/silabs/general/ZAP.md b/docs/silabs/general/ZAP.md index 106d6d8deca483..6a799aacdc7233 100644 --- a/docs/silabs/general/ZAP.md +++ b/docs/silabs/general/ZAP.md @@ -21,7 +21,7 @@ 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 + over Thread or Wi-Fi - 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 @@ -62,10 +62,11 @@ the lock-app is left up to the application developer. ## 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 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 @@ -73,9 +74,8 @@ 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. +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. @@ -106,9 +106,14 @@ 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. +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. +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". @@ -130,7 +135,7 @@ 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. +a default value for attributes, commands and events for Endpoint 1. ![ZAP Attributes](./images/zap_attributes.png) @@ -158,5 +163,7 @@ 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 . ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/BUILD_FLASH_MAD.md b/docs/silabs/thread/BUILD_FLASH_MAD.md index 9ee6c5eefe424e..7eef051698d819 100644 --- a/docs/silabs/thread/BUILD_FLASH_MAD.md +++ b/docs/silabs/thread/BUILD_FLASH_MAD.md @@ -10,50 +10,39 @@ We have provided two ways to get the required image to flash the MAD. You can use one of the following options: 1. Use the pre-built image file -2. Build the image file from the '`connectedhomeip`' repository +2. Build the image file from the '`matter`' repository
-### **Using the Pre-Built Image File** +- ### **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 a pre-built -image file, you can skip forward to Step #2: Flashing the MAD. + All of the Matter Accessory Device image files are accessible through the -
- -### **Building the Matter Image File from the Repository** - -**1. Clone the Silicon Labs Matter repository** - - You should have already cloned the Silicon Labs Matter GitHub repository and have the right branch as part of building an RCP image. 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. + [Matter Artifacts Page](../general/ARTIFACTS.md). If you are using a + pre-built image file, you can skip forward to Step #2: Flashing the MAD. -You must have Git installed on your -local machine. To clone the repo 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 necessary submodules with -the following command: +
-> `$ cd matter`
`$ ./scripts/checkout_submodules.py --shallow --recursive --platform efr32` +- ### **Building the Matter Image File from the Repository** -
+ > **IMPORTANT:** A complete list of software requirements for Silicon Labs + > Matter 15.4 development is included on the + > [Matter Software Requirements](../general/SOFTWARE_REQUIREMENTS.md) page. + > Be sure that you have satisfied these requirements before proceeding. -**2. Build the Matter Accessory Device** + The Matter Accessory Device (lighting-app) can be built out of this repo. -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) + 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. + 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: + The build process puts all image files in the following location: -> \/matter/out/\/\ + > \/matter/out/\/\
@@ -65,8 +54,10 @@ the following instructions: 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. +your device. Bootloader images are provided on the +[Matter Artifacts page](../general/ARTIFACTS.md). +--- ----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/CHIP_TOOL.md b/docs/silabs/thread/CHIP_TOOL.md index 725ea98ef71a4f..544894e1d21f13 100644 --- a/docs/silabs/thread/CHIP_TOOL.md +++ b/docs/silabs/thread/CHIP_TOOL.md @@ -36,7 +36,7 @@ You can also use the full ChipTool command as usual (still using mattertool)
-### Open Thread Border Router (OTBR) +## 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) @@ -45,19 +45,19 @@ The pre-installed OTBR is configured for the infrastructure interface eth0. Bash script to modify, reinstall or update the OTBR: -> `otbrsetup` +> `$ otbrsetup` This bash script centralizes and simplifies the local OTBR installation. Available commands: -| **Command** | **Description** | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -| -h, --help | Prints help options | -| -if, --interface | 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 | +| **Command** | **Description** | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| -h, --help | Prints help options | +| -if, --interface | 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 Wi-Fi) | +| -u, --update | Update the OTBR installation after the repo is updated |
@@ -68,6 +68,8 @@ Available commands: Change infrastructure to wlan0: `$ otbrsetup -if wlan0 -s`
Rerun full install for eth0 interface: `$ otbrsetup -i` +## Upgrading the OpenThread Border Router (OTBR) + Change OTBR commit reference/version > `$ cd /home/ubuntu/ot-br-posix`
@@ -80,7 +82,7 @@ Change OTBR commit reference/version
-### Matter - ChipTool +## Upgrading the Matter - ChipTool For more information on the commit hashes used for this demo please consult the following page: @@ -108,7 +110,7 @@ Available commands: | 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 | +| bleWifi | For Matter Ble Wi-FI 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 | @@ -127,14 +129,14 @@ variables used by the script. 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 | +| **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 | Wi-Fi AP SSID that the end devices need to connect to | +| -p, --password STRING | Wi-Fi AP password | > These configurations are held until overwritten, cleared with cleanVars or > when Raspberry Pi reboots. @@ -177,5 +179,7 @@ and rename the following alias to your liking. > `$ alias otbrsetup=‘source $HOME/scripts/setupOTBR.sh’` ----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +--- + +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/DEMO_OVERVIEW.md b/docs/silabs/thread/DEMO_OVERVIEW.md index b43be39d09f9b7..b869fbcbd9139c 100644 --- a/docs/silabs/thread/DEMO_OVERVIEW.md +++ b/docs/silabs/thread/DEMO_OVERVIEW.md @@ -1,8 +1,8 @@ # Matter over Thread Demo Overview This section reviews the steps for running an example lighting-app for Matter -over Thread. See [this file](THREAD.md) for an introduction to the -Matter over Thread setup. +over Thread. See [this file](THREAD.md) 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 Bluetooth LE, and finally sending a basic @@ -10,10 +10,11 @@ OnOff command to the end device.
-## Prerequisites +## Step 0: Prerequisites -Before beginning your Matter project, you should have the software and systems described in -[Matter Hardware and Software Prerequisites](./THREAD_PREREQS.md). +Before beginning your Silicon Labs Matter project be sure you have satisfied all +of the [Matter Hardware](../general/HARDWARE_REQUIREMENTS.md) and +[Matter Software](../general/SOFTWARE_REQUIREMENTS.md) Requirements.
@@ -28,15 +29,16 @@ packets into Thread packets. The Thread packets are then routed to the Silicon Labs end device. See [How to use Matter Hub \(Raspberry Pi\) Image](./RASPI_IMG.md) for setup -instructions. +instructions.
## Step 2: Flash the RCP The Radio Co-Processor (RCP) is a Thread device that connects to the Raspberry -Pi via USB. To flash the RCP, connect it to your laptop via -USB. Thereafter, it should be connected to the Raspberry Pi via USB as well. Prebuilt RCP images are available for the demo +Pi via USB. To flash the RCP, connect it to your laptop via USB. Thereafter, it +should be connected to the Raspberry Pi via USB as well. Prebuilt RCP images are +available for the demo Information on flashing and optionally building the RCP is located here: [How To Build and Flash the RCP](RCP.md) @@ -46,10 +48,12 @@ Information on flashing and optionally building the RCP is located here: ## 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 controlled using the ChipTool. Prebuilt MAD images are available for the demo. +commissioned onto the Matter network and controlled using the ChipTool. Prebuilt +MAD images are available for the demo. -Information on flashing and optionally building the Matter Accessory device is located -here: [How To Build and Flash the Matter Accessory Device](./BUILD_FLASH_MAD.md) +Information on flashing and optionally building the Matter Accessory device is +located here: +[How To Build and Flash the Matter Accessory Device](./BUILD_FLASH_MAD.md)
@@ -68,5 +72,7 @@ Pi image:
----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +--- + +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/FAQ.md b/docs/silabs/thread/FAQ.md index d91df8dd627d14..511448391cc7fe 100644 --- a/docs/silabs/thread/FAQ.md +++ b/docs/silabs/thread/FAQ.md @@ -16,7 +16,7 @@ - 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: + Wi-Fi). 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) diff --git a/docs/silabs/thread/RASPI_IMG.md b/docs/silabs/thread/RASPI_IMG.md index 025022a21895a6..91f96abf9ff9d7 100644 --- a/docs/silabs/thread/RASPI_IMG.md +++ b/docs/silabs/thread/RASPI_IMG.md @@ -12,6 +12,12 @@ Silicon Labs end device. ## How to use the Silicon Labs Matter Raspberry Pi Image (Matter Hub) +> Note that if you have already downloaded the Raspberry Pi image and installed +> it, you may only need to update the image that you already have on your +> Raspberry Pi in order to use it with the current release. In this case you can +> follow the instructions on the [Matter Tool Page](CHIP_TOOL.md) to update your +> existing installation. +
### Step 1. Raspberry Pi Image Download @@ -21,21 +27,25 @@ 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) -> Please note that this image, even when zipped up, is quite large ~10GB so this download will take a while if you are on a slow connection. This image includes both the Ubuntu operating system as well as the OTBR and Chip-Tool, so there is a lot of sofware pre-packaged in this image, hence the size. +> Please note that this image, even when zipped up, is quite large ~5GB so this +> download will take a while if you are on a slow connection. This image +> includes both the Ubuntu operating system as well as the OTBR and Chip-Tool, +> so there is a lot of sofware pre-packaged in this image, hence the size.
### Step 2. Flashing your Raspberry Pi [Raspberry Pi Disk Imager](https://www.raspberrypi.com/software/) can be used to -flash the SD Card that contains the operating system for the Raspberry Pi. Under Operating System select 'Use Custom' and then select the .img file. +flash the SD Card that contains the operating system for the Raspberry Pi. Under +Operating System select 'Use Custom' and then select the .img file. 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 by unplugging it from the power source and plugging it back in. Then, wait at least 10 seconds for it to come up and start the -> SSH server. +> Raspberry Pi by unplugging it from the power source and plugging it back in. +> Then, wait at least 10 seconds for it to come up and start the SSH server.
@@ -44,12 +54,22 @@ used to flash the image to a micro SD card. The Raspberry Pi should be connected to a network - this could be Ethernet or a Wi-Fi network. -> NOTE: If you cannot connect your Rasberry Pi to a network over Wifi or Ethernet you do have the option to connect a monitor and keyboard the the Raspberry Pi and interact with it that way. In this case you do not need to connect your Raspberry Pi to a network as you can interface with it directly as you would with any computer running Ubuntu Linux. +> NOTE: If you cannot connect your Rasberry Pi to a network over Wi-Fi or +> Ethernet you do have the option to connect a monitor and keyboard the the +> Raspberry Pi and interact with it that way. In this case you do not need to +> connect your Raspberry Pi to a network as you can interface with it directly +> as you would with any computer running Ubuntu Linux. -The preference here is to use Ethernet, however if you are using Wi-Fi for your connection to the Raspberry Pi, please see [Connecting Raspberry Pi to Wi-Fi](https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-networking) for instructions on how to connect your Raspberry Pi to a Wi-Fi network. +The preference here is to use Ethernet, however if you are using Wi-Fi for your +connection to the Raspberry Pi, please see +[Connecting Raspberry Pi to Wi-Fi](https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-networking) +for instructions on how to connect your Raspberry Pi to a Wi-Fi network. -Once you have connected your Raspberry Pi to the network, you will want to connect to your Raspberry Pi over SSH. In order to do this you will need the IP address of your Raspberry Pi. Please see the [Finding Your Raspberry Pi page](../general/FIND_RASPI.md) for -more information on finding the Raspberry Pi on the local network. +Once you have connected your Raspberry Pi to the network, you will want to +connect to your Raspberry Pi over SSH. In order to do this you will need the IP +address of your Raspberry Pi. 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 @@ -70,5 +90,7 @@ 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) ----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +--- + +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/RCP.md b/docs/silabs/thread/RCP.md index 11c27e43af519c..3188f075e0b7c9 100644 --- a/docs/silabs/thread/RCP.md +++ b/docs/silabs/thread/RCP.md @@ -5,10 +5,10 @@ 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, connect it to your laptop directly by USB. +A complete list of supported hardware for the RCP is provided on the +[Matter Hardware Requirements](../general/HARDWARE_REQUIREMENTS.md) page. - +First, in order to flash the RCP, connect it to your laptop directly by USB.
@@ -18,8 +18,8 @@ We have provided two ways to get the required image to flash the RCP. You can use one of the following options: 1. Use the pre-built image `ot-rcp` image file -2. Build the image file from the '`ot-efr32`' repository, which is listed on - the [Matter Repositories and Commit Hashes page](../general/COMMIT_HASHES.md) +2. Build the image file from the '`ot-efr32`' repository, which is listed on the + [Matter Repositories and Commit Hashes page](../general/COMMIT_HASHES.md)
@@ -38,18 +38,20 @@ image file, you can skip forward to Step #2: Flashing the RCP. The ot-efr32 repo is located in Github here: https://github.com/SiliconLabs/ot-efr32. -You must have Git installed on your -local machine. To clone the repo use the following command: +You must have Git installed on your local machine. To clone the repo 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`
> `$ git submodule update --init` +> `$ cd ot-efr32` -After updating the submodules you can check out the correct branch or commit hash -for the system. Check the current branch and commit hash used here: +> `$ git submodule update --init` + +After updating the submodules you can check out 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 ` @@ -72,17 +74,20 @@ location: `/ot-efr32/build/` ## Step 2: Flash the RCP -Once you get the RCP image, either by downloading a prebuilt image or building the image file from the repo, you can flash it onto your device. This 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: +Once you get the RCP image, either by downloading a prebuilt image or building +the image file from the repo, you can flash it onto your device. This 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 the image, the device becomes the RCP. Disconnect it from you laptop and -connect it via USB to the Raspberry Pi. +Once you have flashed the image, the device becomes the RCP. 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. ----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file +--- + +[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) diff --git a/docs/silabs/thread/THREAD_PREREQS.md b/docs/silabs/thread/THREAD_PREREQS.md deleted file mode 100644 index 88a0e0ed294772..00000000000000 --- a/docs/silabs/thread/THREAD_PREREQS.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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 that contains the - > operating system for the Raspberry Pi. Note that, for the - Thread demo, the operating system is the demo image. -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 [only required for building images and development] - > Make sure Git is installed on the local machine that will be used to flash - > the devices so that the necessary repositories can be cloned locally and - > used as needed. -1. If you are using an EFR32MG2x device you will require a bootloader to run the demo applications. When you flash your application image be sure to include a bootloader as well (if one is not already present). Bootloader images are provided on the [Matter Artifacts page](../general/ARTIFACTS.md). - -
- -### Windows-Specific Software Requirements - -  These requirements are in addition to those mentioned above, for Windows only.
- -  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 - -

- -## Hardware Requirements - -1. Matter Hub (OTBR + ChipTool) - -  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' - -
- -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) - -
- -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) -

- - - **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) - ----- -[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) \ No newline at end of file diff --git a/docs/silabs/wifi/BUILD_CHIP_ENV.md b/docs/silabs/wifi/BUILD_CHIP_ENV.md index 780138d670d429..0a9d80f778857e 100644 --- a/docs/silabs/wifi/BUILD_CHIP_ENV.md +++ b/docs/silabs/wifi/BUILD_CHIP_ENV.md @@ -1,86 +1,30 @@ -# Build Environment using Linux +# Building Your Wi-Fi Matter End Device and the Chip-Tool -This section will go through the steps required to build the demo using Linux. +## Compiling the Lighting-app -> **Do not execute any commands on this page as ROOT (no _su_ required), unless -> specified** - -
- -## Prepare Linux Packages - -Update the latest packages by typing following commands in terminal: - -> `$ sudo apt update` - -> `$ sudo apt install` - -
- -## 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`
- - -
- -### 2. Matter codebase - -- Check out Matter codebase from GitHub: - - - Create a working directory. In this example it is named `git`: - - > `$ mkdir git` - - > `$ cd git` - - > `$ MATTER_WORKDIR=git` - - --> We will use $MATTER_WORKDIR later - - - Download the - [Matter codebase](https://github.com/SiliconLabs/matter.git) - from here as follows: - > `$ git clone https://github.com/SiliconLabs/matter.git` - -- Sync submodules by running the following commands: +The following commands are for building the example. Depending on which device +you are using, select the appropriate build command to run. - > `$ cd matter` +> Please note that these examples reference a specific board the BRD4161A. You +> may be using a different board like the BRD4186C, please change the board +> referenced in the build command to your specific board before running the +> command. - > `$ ./scripts/checkout_submodules.py --shallow --recursive --platform efr32` +Build command for RS911x + EFR32MG12: -- Environment Builds +> `$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/rs911x_lighting BRD4161A --wifi rs911x |& tee out/rs911x_lighting.out` - - Activate environment builds: - > `$ . scripts/bootstrap.sh` - - Create a directory where binaries will be updated: - > `$ mkdir out` +Build command for WF200 + EFR32MG12: -- **[Optional:** Increasing stack size **]**
  Navigate to - `git/matter` 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`**. +> `$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/wf200_lighting BRD4161A is_debug=false --wifi wf200 |& tee out/rs911x_lighting.out` -
+Build command for RS911x + EFR32MG24: -### 3. Compiling the Lighting-app +> `$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/rs911x_mg24_lighting BRD4186C disable_lcd=true show_qr_code=false use_external_flash=false --wifi rs911x` -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 + EFR32MG24: -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` +> `$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/rs911x_mg24_lighting BRD4186C disable_lcd=true show_qr_code=false use_external_flash=false --wifi wf200` Run the following: @@ -99,7 +43,7 @@ This is what you will flash into the EFR32.
-## Compiling ChipTool +## Compiling Chip-Tool - Build the ChipTool on a laptop which has Wi-Fi and Bluetooth LE - Run the following commands: @@ -110,7 +54,12 @@ This is what you will flash into the EFR32. This will build chiptool in `out/standalone` -Now you have all the binaries to flash onto the MG12 platform. +Now you have all the binaries to flash onto the Silicon Labs platform (MG12, +MG24, etc...). For more information on how to flash a Silicon Labs device please +consult the [Flashing Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md) +page. + +--- ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](./DEMO_OVERVIEW.md) diff --git a/docs/silabs/wifi/BUILD_PI_ENV.md b/docs/silabs/wifi/BUILD_PI_ENV.md index 16adbe73178ea5..08f745fced8dfc 100644 --- a/docs/silabs/wifi/BUILD_PI_ENV.md +++ b/docs/silabs/wifi/BUILD_PI_ENV.md @@ -1,5 +1,7 @@ # Using the Pre-Built Rasberry Pi "Matter Hub" Image -When using a Raspberry Pi as a controller in your Matter network you have two options + +When using a Raspberry Pi as a controller in your Matter network you have two +options # Building Environment using Raspberry Pi 4 @@ -8,32 +10,33 @@ To flash the Ubuntu OS onto the SD card: 1. Insert the flashed SD card (directly or using a card reader) into the laptop/PC that will run the Raspberry Pi Imager tool 2. Launch Raspberry Pi 4 Imager -3. Click on 'Choose OS' --> 'Other General-purpose OS' --> 'Ubuntu' --> 'Ubuntu 22.04 64-bit server OS' +3. Click on 'Choose OS' --> 'Other General-purpose OS' --> 'Ubuntu' --> 'Ubuntu + 22.04 64-bit server OS' 4. Click 'Storage' and select the 'SD card detect' 5. This Raspberry Pi 4's console can be accessed in multiple ways, refer to: - https://www.raspberrypi.com/documentation/computers/remote-access.html - In this guide, Raspberry Pi 4 is being accessed using Putty. -6. Enter the - details like User name, Password, SSID and its password to connect to - network. Click 'Save' + https://www.raspberrypi.com/documentation/computers/remote-access.html In + this guide, Raspberry Pi 4 is being accessed using Putty. +6. Enter the details like User name, Password, SSID and its password to connect + to network. Click 'Save' 7. 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 8. When it is done, click 'Continue'. 9. Remove the SD card from the reader and insert it into the Raspberry Pi as - shown below: + shown below: Inserting SD into Pi -On powering up the board, the red and green lights should start blinking. To start -using the Raspberry Pi: +On powering up the board, the red and green lights should start blinking. To +start using the Raspberry Pi: -1. Use this reference to find the IP address of your Raspberry Pi: [Finding Your Raspberry Pi](../general/FIND_RASPI.md) +1. Use this reference to find the IP address of your Raspberry Pi: + [Finding Your Raspberry Pi](../general/FIND_RASPI.md) 2. Once you find the IP address, launch Putty, select 'Session', enter the IP - address of the Raspberry Pi, and click 'Open' + address of the Raspberry Pi, and click 'Open' 3. 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", + 'Enter' If you don't give username and password default is user account + "ubuntu" and password "ubuntu", 4. Update the latest packages by running following commands in the terminal: @@ -44,37 +47,51 @@ using the Raspberry Pi: 5. 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' + > libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \ + > python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev'
> 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: -In [this link to the Project CHIP GitHub Site](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md), follow the instructions in -the section "Installing prerequisites on Raspberry Pi 4". +Finally, install some Raspberry Pi specific dependencies: + +In +[this link to the Project CHIP GitHub Site](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md), +follow the instructions in the section "Installing prerequisites on Raspberry Pi +4". ## Bluetooth Setup - Make sure BLE is up and running on Raspberry Pi. - Raspberry Pi internally has some issues with BLE that may cause - it to crash. Because BLE is used for - commissioning on Matter, make sure BLE is running. - `$ sudo systemctl status bluetooth.service` +Make sure BLE is up and running on Raspberry Pi. Raspberry Pi internally has +some issues with BLE that may cause it to crash. Because BLE is used for +commissioning on Matter, make sure BLE is running. + +> `$ sudo systemctl status bluetooth.service` + +To stop BLE if it is already running: + +> `$ sudo systemctl stop bluetooth.service` + +To restart the Bluetooth service, first enable it: + +> `$ sudo systemctl enable bluetooth.service` + +When you check the status of the Bluetooth service, it will be inactive because +it has been enabled but not restarted: + +> `$ sudo systemctl status bluetooth.service` - To stop BLE if it is already running: `$ sudo systemctl stop bluetooth.service` +Restart the service: - To restart the Bluetooth service, first enable it: - `$ sudo systemctl enable bluetooth.service` +> `$ sudo systemctl restart bluetooth.service` - When you check the status of the Bluetooth service, it will be inactive because it has been enabled but not restarted: - `$ sudo systemctl status bluetooth.service` +Now the status of the service should be active and running: - Restart the service: `$ sudo systemctl restart bluetooth.service` +> `$ sudo systemctl status bluetooth.service` - Now the status of the service should be active and running: `$ sudo systemctl status bluetooth.service` +--- ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](./DEMO_OVERVIEW.md) diff --git a/docs/silabs/wifi/FAQ.md b/docs/silabs/wifi/FAQ.md index ef31389639b780..d8fcdc19488cac 100644 --- a/docs/silabs/wifi/FAQ.md +++ b/docs/silabs/wifi/FAQ.md @@ -10,7 +10,7 @@ **Command leading to error:** - $ out/standalone/chip-tool pairing ble-wifi 1122 mySSID myPassword 20202021 3840 +> `$ out/standalone/chip-tool pairing ble-wifi 1122 mySSID myPassword 20202021 3840` > Where `mySSID` is **your AP's SSID** and `mypassword` is **your AP's > password**. @@ -33,14 +33,19 @@ **Procedure:** -1. Stop Bluetooth service: `$ systemctl stop bluetooth.service` +1. Stop Bluetooth service: + > `$ systemctl stop bluetooth.service` 2. Wait 20 seconds -3. Restart Bluetooth service: `$ sudo service bluetooth restart` -4. Unblock Bluetooth service: `$ rfkill unblock all` -5. Enable Bluetooth service: `$ sudo systemctl enable bluetooth` +3. Restart Bluetooth service: + > `$ sudo service bluetooth restart` +4. Unblock Bluetooth service: + > `$ rfkill unblock all` +5. Enable Bluetooth service: + > `$ sudo systemctl enable bluetooth` 6. Issue the pairing command: - `$ out/standalone/chip-tool pairing ble-wifi 1122 mySSID mypassword 20202021 3840` -
+ + > `$ out/standalone/chip-tool pairing ble-wifi 1122 mySSID mypassword 20202021 3840` + >
> Where `mySSID` is **your AP's SSID** and `mypassword` is **your AP's > password**. diff --git a/docs/silabs/wifi/RUN_DEMO.md b/docs/silabs/wifi/RUN_DEMO.md index 9cf4c2b39acdae..2d9cd5a90f0f89 100644 --- a/docs/silabs/wifi/RUN_DEMO.md +++ b/docs/silabs/wifi/RUN_DEMO.md @@ -4,14 +4,17 @@ 1. Plug the WSTK and EFR into the laptop. -2. Launch Ozone, Simplicity Studio or Simplicity Commander Standalone - this will display a GUI. If you are not using Ozone, you can follow the instructions to [Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md) - +2. Launch Ozone, Simplicity Studio or Simplicity Commander Standalone - this + will display a GUI. If you are not using Ozone, you can follow the + instructions to + [Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md) 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`' + 2. Select 'Device' as '`EFR32MG12PXXF1024`' or `EFR32MG24XX` depending on + the device you are using. 3. Click 'OK' 4. The 'Register set' tab will get filled automatically 5. 'Peripherals' tab need not be changed as it is optional @@ -32,6 +35,10 @@ through 'Browse', select the file named `chip-efr32-lighting-example.out` and click 'Next'. This is the image built in previous step. + > Note that you may be using a different board like the BRD4186C in which + > case your image will be in a directory corresponding to that board + > identifier. + 7. Make sure the next screen has 'Initial PC' selected as 'ELF Entry Point' - click 'Finish' @@ -40,7 +47,7 @@ 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 + > The Silabs chip, EFR32MG12 or EFR32MG24 will be erased and programmed 9. Run the image by clicking the 'Play' button on the top left (or press the F5 key) @@ -68,8 +75,8 @@ ## Demo Execution - Commissioning a Wi-Fi Device using ChipTool for Linux -> Commissioning can be done using ChipTool running either on -> Linux or Raspberry Pi +> Commissioning can be done using ChipTool running either on Linux or Raspberry +> Pi 1. Get the SSID and PSK of the Wi-Fi network (WPA2 - Security) you are connected to. @@ -85,34 +92,44 @@ > '\$SSID' is a placeholder for your Wi-Fi SSID and '\$PSK' is a placeholder > for the password of your Wi-Fi network. -4. To turn **on** the LED on the EFR32MG12:
  - `$ out/standalone/chip-tool onoff on 1122 1` -5. To turn **off** the LED on the EFR32MG12:
  - `$ out/standalone/chip-tool onoff off 1122 1` +3. To turn **on** the LED on the EFR32MG12: + > `$ out/standalone/chip-tool onoff on 1122 1` +4. To turn **off** the LED on the EFR32MG12: + > `$ out/standalone/chip-tool onoff off 1122 1` + +If there are any failures, run the following command and then re-run the +Chip-Tool command: -> If there are any failures, run the following command and then re-run the -> ChipTool command: `$ rm -rf /tmp/chip_*` +> `$ rm -rf /tmp/chip_*` -> If you are having difficulty getting the Chip-Tool to commission the device successfully, it may be because you have more than one network interface available to the Chip-Tool. The device on which you are running the Chip-Tool must be on the same Wi-Fi network as your RS9116 or WF200 and there cannot be another network interface on the device that is running the Chip-Tool. For instance, if you have an Ethernet connection as well as a Wi-Fi connection, you need to unplug the Ethernet connection and try running the Chip-Tool as in step #3 above. +If you are having difficulty getting the Chip-Tool to commission the device +successfully, it may be because you have more than one network interface +available to the Chip-Tool. The device on which you are running the Chip-Tool +must be on the same Wi-Fi network as your RS9116 or WF200 and there cannot be +another network interface on the device that is running the Chip-Tool. For +instance, if you have an Ethernet connection as well as a Wi-Fi connection, you +need to unplug the Ethernet connection and try running the Chip-Tool as in step +#3 above. -> 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-7 seconds. The LED0 and LED1 -> will flash 3 times and the QR code will appear again on the LCD screen. +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-7 seconds. The LED0 will flash 3 times and the QR code +will appear again on the LCD screen.
The commissioning command mentioned above does the following: -- ChipTool scans BLE and locates the Silicon Labs device that uses the specified - discriminator +- ChipTool scans BLE and locates the Silicon Labs device that uses the + specified discriminator - Sends the Wi-Fi SSID and Passkey -- The Silicon Labs device will join the Wi-Fi network and get an IPv4 address. It - then starts providing mDNS records on IPv4 and IPv6 -- ChipTool then locates the device over Wi-Fi and establishes - operational certificates +- The Silicon Labs device will join the Wi-Fi network and get an IPv4 address. + It then starts providing mDNS records on IPv4 and IPv6 +- ChipTool then locates the device over Wi-Fi and establishes operational + certificates - Future communications (tests) will then happen over Wi-Fi +--- ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](./DEMO_OVERVIEW.md) diff --git a/docs/silabs/wifi/SW_SETUP.md b/docs/silabs/wifi/SW_SETUP.md index 97667b96e5d31a..a3bc3978fb1588 100644 --- a/docs/silabs/wifi/SW_SETUP.md +++ b/docs/silabs/wifi/SW_SETUP.md @@ -1,17 +1,24 @@ # Software Setup and Preliminaries ## Using the Matter Accessory Device (MAD) Pre-Built Binaries -If you are just running the Matter demo, and are not interested in building the Matter Accessory Device images from scratch, you can download the MAD images for Wi-Fi from this software release on the [Artifacts Page](../general/ARTIFACTS.md) -Once you have downloaded the image you require for your device, you can skip forward to the [Running the Matter Demo over Wi-Fi page](./RUN_DEMO.md) +If you are just running the Matter demo, and are not interested in building the +Matter Accessory Device images from scratch, you can download the MAD images for +Wi-Fi from this software release on the +[Matter Artifacts Page](../general/ARTIFACTS.md) -Otherwise if you are planning to build the Wi-Fi images from scratch please continue with this documentation. +Once you have downloaded the image you require for your device, you can skip +forward to the [Running the Matter Demo over Wi-Fi page](./RUN_DEMO.md) +Otherwise if you are planning to build the Wi-Fi images from scratch please +continue with this documentation. ## Software Setup -If you have not downloaded or cloned this repository, you can run the following commands on a Linux terminal running on either Linux machine, WSL or -Virtual Machine to clone the repository and run bootstrap to prepare to build the sample application images. +If you have not downloaded or cloned this repository, you can run the following +commands on a Linux terminal running on either Linux machine, WSL or Virtual +Machine to clone the repository and run bootstrap to prepare to build the sample +application images. 1. To download the [SiliconLabs Matter codebase](https://github.com/SiliconLabs/matter.git) run @@ -33,8 +40,7 @@ Virtual Machine to clone the repository and run bootstrap to prepare to build th > `$ . scripts/bootstrap.sh` - Create a directory where binaries will be updated/compiled called - `out`: + Create a directory where binaries will be updated/compiled called `out`: > `$ mkdir out` @@ -46,10 +52,12 @@ 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` + +> `$ ./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` + +> `$ ./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: @@ -60,43 +68,28 @@ Run the following: 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 flash onto the EFR32. +This is what you will flash onto the EFR32. For more information on how to flash +the EFR32 please check out the page on +[Flashing a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md) ## Compiling the ChipTool -In order to control the Wi-Fi Matter Accessory Device you will have to compile and run the ChipTool on either a Linux, Mac or Raspberry Pi. The ChipTool builds faster on the Mac and Linux machines so that is recommended, but if you have access to a Raspberry Pi that will work as well. - -If you have not cloned this repository, you can run the following commands to clone the repository and set it up to build the ChipTool from source. - -1. Run the following commands on a terminal where you will run chip-tool (if not already performed above in Software Setup section): - - > `$ mkdir git` +In order to control the Wi-Fi Matter Accessory Device you will have to compile +and run the ChipTool on either a Linux, Mac or Raspberry Pi. The ChipTool builds +faster on the Mac and Linux machines so that is recommended, but if you have +access to a Raspberry Pi that will work as well. - > `$ cd git` - - > `$ MATTER_WORKDIR=git`    --> We will use $MATTER_WORKDIR later - - > `$ git clone https://github.com/SiliconLabs/matter.git` - -2. Bootstrapping (if not already performed above in Software Setup section): - - > `$ cd matter` - - > `$ git submodule update --init` - - > `$ . scripts/bootstrap.sh` - - Create a directory where chip-tool binary will be updated/compiled: - - > `$ mkdir out` +1. Build the Chip-Tool > `$ ./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 Wi-Fi](RUN_DEMO.md)' to flash the binaries and - execute the demo. + '[Running the Matter Demo over Wi-Fi](RUN_DEMO.md)' to flash the binaries + and execute the demo. + +--- ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](./DEMO_OVERVIEW.md) diff --git a/docs/silabs/wifi/WIFI_ANDROID.md b/docs/silabs/wifi/WIFI_ANDROID.md index e756036b03cfcb..ee4bcf6fe48086 100644 --- a/docs/silabs/wifi/WIFI_ANDROID.md +++ b/docs/silabs/wifi/WIFI_ANDROID.md @@ -1,4 +1,4 @@ -# Commissioning Wifi Device using Android +# Commissioning Wi-Fi Device using Android Commissioning can be done using an Android Phone through the following steps. @@ -19,21 +19,23 @@ Download pre-build application from the screen 1. Click on 'Light ON/OFF & Level Cluster' 1. 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 release -> the button - ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file + 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 release + the button + +--- + +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | +[Wi-Fi Demo](./DEMO_OVERVIEW.md) diff --git a/docs/silabs/wifi/WIFI_PREREQS.md b/docs/silabs/wifi/WIFI_PREREQS.md deleted file mode 100644 index de0182835a1a1e..00000000000000 --- a/docs/silabs/wifi/WIFI_PREREQS.md +++ /dev/null @@ -1,80 +0,0 @@ -# Matter Wi-Fi Prerequisites - -Silicon Labs Matter Wi-Fi 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 Wi-Fi 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 its Bluetooth capability, which is necessary for Matter commissioning. - -In addition to the EFR32MG12 and Wi-Fi boards, you will need to run the Matter -ChipTool. This can be built and run on a Linux or Mac laptop or -on a Raspberry Pi. - -The hardware that you will need for Silicon Labs Matter Wi-Fi development is as -follows: - -## EFR32MG12 + RS9116 Hardware Overview - -![Overview](./images/wifi_setup.png) - -## EFR32MG12 + WF200 Hardware Overview - -![EFR32MG12 + WF200 connection ](./images/MG12_WF200.jpg) - -
- -## 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/BRD4163A/BRD4164A/BRD4186C/BRD4187C daughter boards are supported - - [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board) - - [SLWRB4163A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4163a-efr32mg12-radio-board) - - [SLWRB4164A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4164a-efr32mg12-radio-board) - - [XG24-RB4186C](https://www.silabs.com/development-tools/wireless/xg24-rb4186c-efr32xg24-wireless-gecko-radio-board) - - [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board) - > BLE and Matter code run here - - Wi-Fi 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 Wi-Fi 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) - -
- -## Software - -- Ozone (optional) 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 (32 or 64 bit) version and install it - - Linux: - [Download Ozone](https://www.segger.com/downloads/jlink/Ozone_Linux_x86_64.deb) - and install it -- [Simplicity Studio or Simplicity Commander](../general/FLASH_SILABS_DEVICE.md) (optional) to flash images generated -- Raspberry Pi imager tool (optional): To flash an operating system or Raspberry Pi image on the SD card of the Raspberry Pi if you are using one to run the ChipTool. Note: The ChipTool may also be compiled and run on a Linux machine or Mac. [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) -- If you are using an EFR32MG2x device you will require a bootloader to run the demo applications. When you flash your application image be sure to include a bootloader as well (if one is not already present). Bootloader images are provided on the [Matter Artifacts page](../general/ARTIFACTS.md). - -
- -## 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) - ----- -[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](./DEMO_OVERVIEW.md) \ No newline at end of file