Pull request #35: V0.2.0 doc updates

Merge in WMN_TOOLS/matter from v0.2.0-doc-updates to silabs Squashed commit of the following: commit ece0b96ad6bd2a79c110ce3f286f2c600dbc2f31 Author: Mathieu Kardous <[email protected]> Date: Tue Aug 16 11:53:05 2022 -0400 update submodule checkout command commit 8431661578b8a80b447d9673d042be3ea8c9eeed Merge: d48392a8d 19ccdb8ae Author: DOMAINA\elsherh <[email protected]> Date: Tue Aug 16 10:52:17 2022 -0400 Merge branch 'v0.2.0-doc-updates' of https://stash.silabs.com/scm/wmn_tools/matter into v0.2.0-doc-updates commit d48392a8dc96b13a1b2d5e54fdb3f3615fc75359 Author: DOMAINA\elsherh <[email protected]> Date: Tue Aug 16 10:50:40 2022 -0400 added latest updates to SETUP.md commit 19ccdb8ae8af3f2e8b53573611d7ebc616bb2717 Author: Rehan Rasool <[email protected]> Date: Tue Aug 16 10:47:38 2022 -0400 Re-add OTA documentation link commit c8e79e983949b6bf3d345e9577ac4d366959845d Author: Rehan Rasool <[email protected]> Date: Tue Aug 16 10:26:29 2022 -0400 Add reference to VS Code extensions commit 492eaa1927ead3030a9074cae8652c712679b395 Merge: 7ec88b609 40466c356 Author: DOMAINA\elsherh <[email protected]> Date: Tue Aug 16 10:39:15 2022 -0400 Conflicts resolved commit 7ec88b6094996e67ad169167958dc0664f322a67 Author: DOMAINA\elsherh <[email protected]> Date: Tue Aug 16 09:35:09 2022 -0400 had to remove a line .... oops commit 019e40724f7460ee371a8dfa18d0bf9cc0b96726 Author: DOMAINA\elsherh <[email protected]> Date: Tue Aug 16 09:32:56 2022 -0400 modified SETUP.md by adding additional installation steps commit bb71d1915537249bb0fc8e246d94d7fc7238e568 Author: DOMAINA\elsherh <[email protected]> Date: Mon Aug 15 17:20:16 2022 -0400 Added Requirements for VScode Environment Setup commit d784a7f57e4d4b05fa0babe2d600e68215b0b9f3 Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 15:28:27 2022 -0400 Change file encoding to UTF-8, not sure how it got changed previously to UTF-8-BOM which was resulting in it not rendering properly commit 7f409513b38e4bafa548ecb5aa7da49570f022f0 Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 15:13:50 2022 -0400 Readd anchor link commit a796309d3c4fb2bbc210db1a157205248785194f Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 15:07:29 2022 -0400 Fix typo commit 9aa2e76fde5edf79925cfe48a4d14825b8650a79 Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 15:01:17 2022 -0400 Make filename extension lowercase commit 455e2d56c28b238c3c204031a5a4ec8a2c7487a6 Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 14:57:14 2022 -0400 Add build, flash, debug links in main silabs readme commit 8af152f3d34242977fc4c9669b9bca62f5f1c512 Author: Rehan Rasool <[email protected]> Date: Mon Aug 15 14:38:32 2022 -0400 Make VS Code doc headings consistent with other doc headings commit 8b10446d7c79d8a194909054fd686697b4e21adc Author: Ezra Hale <[email protected]> Date: Mon Aug 15 13:40:47 2022 -0400 updates from Catherine commit 779a7220ec5fa851c19599f5fa5209765c2cee8c Author: Ezra Hale <[email protected]> Date: Mon Aug 15 11:19:53 2022 -0400 updated some grammar issues etc... commit 11a7256f09e4dad30f5b35d9ce93ce7393b2253b Author: Junior Martinez <[email protected]> Date: Mon Aug 15 11:05:28 2022 -0400 restore wiseconnect commit hash to the expected one commit 5e3d4ab62e0ba18b0011becfa179b2d26e4cd563 Author: DOMAINA\elsherh <[email protected]> Date: Sat Aug 13 17:26:13 2022 -0400 added documentation for Debugging and Flashing the MATTER Examples on vscode. >> jira : MATTER-21 commit cfb41fc1a54d3a1b180a67ef74c02dc02345d52a Author: Shayna Kaushal <[email protected]> Date: Thu Aug 11 15:53:12 2022 -0400 rs9116 firmware path ... and 12 more commits
SiliconLabs · Jan 24, 2024 · b6f9552 · b6f9552
1 parent 179d116
commit b6f9552
Show file tree

Hide file tree

Showing 29 changed files with 461 additions and 596 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
diff --git a/docs/silabs/README.md b/docs/silabs/README.md
@@ -23,26 +23,30 @@
        [Running Matter Demo over Wifi using Android](wifi/WIFI_ANDROID.md)
        <br><br>
 
-4. Reference Guides
+4. 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)
+         <!-- TODO: [Logs](dev/vscode/LOGS.md) --> <br><br>
+
+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) <br><br>
-
-5. Frequently Asked Questions (FAQ)
+
+6. Frequently Asked Questions (FAQ) / Troubleshooting
+
     - [Thread FAQ](thread/FAQ.md)
     - [Wifi FAQ](wifi/FAQ.md)
 
 <!--
 (WIP)
-Matter Setup for Development
-Download Silicon Labs Matter Repo
-Setup VSCode
-Create a new sample application
-Build ( 1 task)
-Debug (1 task)
-Edit
+Configure
 ZAP (Standalone) (1 task)
 Pin Tool (Studio) (1 task)
 BLE Configurator (Studio) (1 task)

diff --git a/docs/silabs/dev/setup/VSCODE_SETUP.md b/docs/silabs/dev/setup/VSCODE_SETUP.md
diff --git a/docs/silabs/dev/vscode/BUILD.md b/docs/silabs/dev/vscode/BUILD.md
@@ -0,0 +1,68 @@
+# Building in VS Code
+
+This section covers building the binaries required for [ Flashing ](FLASH.md) and
+[ Debugging ](DEBUG.md) the target Matter Accessory Devices.
+
+<a name="linMac"></a>
+
+## Linux/Mac
+
+### Step 1:
+
+Use the shortcut (Ctrl + Shift + P) to trigger the command pallet.
+
+### Step 2:
+
+Search for "run build task" and select the "Run Build Task" option.
+
+### Step 3:
+
+A new drop down menu will appear, select "Build efr32 example".
+
+### Step 4:
+
+On the next menu select an EFR32 example to build.
+
+### Step 5:
+
+Select the appropriate target board.
+
+![](../../images/build_efr32_example.gif)
+
+## Windows
+
+Building for Windows requires one extra step prior to running the build example
+task.
+
+### Step 1:
+
+Press (Ctrl + Shift + P) to trigger the command pallet.
+
+### Step 2:
+
+Search for "run build task" and select "Run build task" from the drop
+down menu.
+
+### Step 3:
+
+On the next menu, select "Windows setup" from the options.
+
+### Step 4:
+
+The next menu contains two options, "setup" and
+"cleanup". Select _setup_ in order to initiate the setup process or _cleanup_ to
+clean up the environment after building the examples. This step installs crucial
+packages that are required to build the examples such as openssl. if openssl
+is not detected, an installation will be initiated in a new window. Follow the installation prompts in order for the setup to be successful.
+
+### Step 5:
+
+This step is identical to the steps for building on Linux/Mac, Refer to
+that [ section ](#linMac).
+
+## ![](../../images/win_run_setup.gif)
+
+
+-----
+
+[Table of Contents](../../README.md)
diff --git a/docs/silabs/dev/vscode/DEBUG.md b/docs/silabs/dev/vscode/DEBUG.md
@@ -0,0 +1,53 @@
+# Debugging in VS Code
+
+This section covers remote Debugging (GDB jlink) of Matter Examples in VS Code.
+
+## Requirements
+
+1. C/C++ Extension Pack (_vscode extension_) - language support
+2. Cortex-Debug (_vscode extension_) - GDB debugger support
+3. ARM GCC Toolchain
+   (https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) -
+   required arm-none-eabi tools
+4. J-Link Software Tools - required J-Link GDB Server for J-Link based debuggers
+   (https://www.segger.com/downloads/jlink)
+
+## Settings
+
+Before starting a debug session please ensure the following:
+
+<ol>
+<div style="text-align: justify"> 
+  <li> A path to "arm-none-eabi-gdb.exe" is provided in the "Settings.Json" file under the "cortex-debug.gdbPath.windows" property.</li>  
+  <li> A path to the GDB jlink server executable is provided in the launch.Json file for the property "serverpath". Find this property under the configuration name "Debug efr32 example app"</li>
+</ol>
+
+## Debugging
+
+<ol>
+
+### Step 1:
+
+Use the shortcut (Ctrl + Shift + P) to trigger the command pallet.
+
+### Step 2:
+
+A drop down menu will appear along with a prompt. Please
+select the "Debug efr32 example app" and Start Debugging, or press F5 on
+your keyboard.
+
+### Step 3:
+
+Select the example you want to debug.
+
+### Step 4:
+
+Select the desired target device, from the drop down menu.
+
+![](../../images/debug_session.gif)
+
+## </ol>
+
+-----
+
+[Table of Contents](../../README.md)
diff --git a/docs/silabs/dev/vscode/FLASH.md b/docs/silabs/dev/vscode/FLASH.md
@@ -0,0 +1,49 @@
+# Flashing EFR32 Examples in VS Code
+
+This section covers flashing efr32 examples to target devices.
+
+## Requirements
+
+1. Simplicity Commander - The Standalone Utility to flash the target devices can
+   be found in the following links:
+   [installer for windows](https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip),
+   [installer for MAC](https://www.silabs.com/documents/public/software/SimplicityCommander-Mac.zip),
+   [installer for Linux](https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip).
+   please ensure the proper directories are added to the PATH.
+2. Python - Ensure that Python is installed and the proper directories are
+   added to the PATH.
+
+## Flashing
+
+<ol>
+
+### Step 1:
+
+Use the shortcut (Ctrl + Shift + P) to trigger the command pallet.
+
+### Step 2:
+
+Search for "run build task" and select "Run build task" from the drop
+down menu.
+
+### Step 3:
+
+Select "Flash efr32 example" from the options.
+
+### Step 4:
+
+On the next down menu, please choose the proper example to flash to your
+target device. The example must have an "out" directory that contains a
+binary file with the ".out" extension.
+
+### Step 4:
+
+The final prompt will ask the user to choose the target device. Please select the target device.
+
+## ![](../../images/flash_efr32_example.gif)
+
+</ol>
+
+-----
+
+[Table of Contents](../../README.md)
diff --git a/docs/silabs/dev/vscode/LOGS.md b/docs/silabs/dev/vscode/LOGS.md
@@ -0,0 +1,7 @@
+# Logs in VS Code
+
+TODO
+
+---
+
+[Table of Contents](../../README.md)
diff --git a/docs/silabs/dev/vscode/SETUP.md b/docs/silabs/dev/vscode/SETUP.md
@@ -0,0 +1,34 @@
+# Setup VS Code environment
+
+## Requirements
+
+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`
+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)
+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
+8. ARM GCC Toolchain
+   (https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) -
+   required arm-none-eabi tools
+9. J-Link Software Tools - required J-Link GDB Server for J-Link based debuggers
+   (https://www.segger.com/downloads/jlink)
+10. Python - (https://www.python.org/downloads/)
+
+## 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/dev/vscode/TASKS.md b/docs/silabs/dev/vscode/TASKS.md
@@ -0,0 +1,13 @@
+# Tasks in VS Code
+
+VS Code offers a great way for developers to customize their development
+environment through the use of "tasks". The following key tasks have been
+provided to facilitate the development experience.
+
+1. [Build](BUILD.md)
+2. [Flash](FLASH.md)
+3. [Debug](DEBUG.md) <br><br>
+
+-----
+
+[Table of Contents](../../README.md)
diff --git a/docs/silabs/general/ARTIFACTS.md b/docs/silabs/general/ARTIFACTS.md
@@ -1,26 +1,38 @@
-
-
 # Matter Software Artifacts
-This page provides links to pre-built software image "artifacts" that can be used to set up the Matter Demo for the Thread and Wi-Fi use cases.
+
+This page provides links to pre-built software image "artifacts" that can be
+used to set up the Matter Demo for the Thread and Wi-Fi use cases.
 
 <br>
 
 ## Matter Hub Raspberry Pi Image
-The Matter Hub image is intended to be flashed onto an SD card for a Raspberry Pi. The Matter Hub Image provides both an Open Thread Border Router and the Matter "ChipTool". Note the image is ~10GB in size so depending on your internet connection this download may take some time. Start the Matter Hub Raspberry Pi image download here:
+
+The Matter Hub image is intended to be flashed onto an SD card for a Raspberry
+Pi. The Matter Hub Image provides both an Open Thread Border Router and the
+Matter "ChipTool". Note the image is ~10GB in size so depending on your internet
+connection this download may take some time. Start the Matter Hub Raspberry Pi
+image download here:
 
 https://www.silabs.com/documents/public/software/SilabsMatterPi.zip
 
 <br>
 
-## Radio Co-Processor (RCP) Images 
-The Radio Co-Processor firmware is used to turn an EFR into an RCP that can be used with a Raspberry Pi to allow the Raspberry Pi's Open Thread Border Router to access the Thread network. Radio Co-Processor (RCP) images are available in the Assets section of this page: 
+## Radio Co-Processor (RCP) Images
+
+The Radio Co-Processor firmware is used to turn an EFR into an RCP that can be
+used with a Raspberry Pi to allow the Raspberry Pi's Open Thread Border Router
+to access the Thread network. Radio Co-Processor (RCP) images are available in
+the Assets section of this page:
 
 https://github.com/SiliconLabs/matter/releases/tag/v0.1.0
 
 <br>
 
 ## Matter Accessory Device Images
-The Matter Accessory Device Images are used to turn an EFR into a Matter device. These are pre-built binary images for the Matter Demo. Matter Accessory Device Images are located in the Assets section of this page: 
+
+The Matter Accessory Device Images are used to turn an EFR into a Matter device.
+These are pre-built binary images for the Matter Demo. Matter Accessory Device
+Images are located in the Assets section of this page:
 
 https://github.com/SiliconLabs/matter/releases/tag/v0.1.0
 
@@ -34,9 +46,20 @@ Matter Chip Tool .apk file is located here: http://silabs.com
 -->
 
 ## RS9116 Firmware
-The RS9116 firmware is used to update the RS9116, and is located in GitHub here: 
 
-https://github.com/SiliconLabs/wiseconnect-wifi-bt-sdk/tree/2.5.0/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
+`/connectedhomeip` directory:
+
+> $ /third_party/silabs/wiseconnect-wifi-bt-sdk/firmware
+
+<!-- The RS9116 firmware is used to update the RS9116, and is located in GitHub here:
+
+https://github.com/SiliconLabs/wiseconnect-wifi-bt-sdk/tree/2.5.0/firmware -->
+
+<br>
+
+---
 
-----
-[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md)
+[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) |
+[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md)
diff --git a/docs/silabs/images/Flash_efr32_example.gif b/docs/silabs/images/Flash_efr32_example.gif
diff --git a/docs/silabs/images/build_efr32_example.gif b/docs/silabs/images/build_efr32_example.gif
diff --git a/docs/silabs/images/debug_session.gif b/docs/silabs/images/debug_session.gif
diff --git a/docs/silabs/images/run_build_task.jpg b/docs/silabs/images/run_build_task.jpg
diff --git a/docs/silabs/images/run_build_task_step_2.jpg b/docs/silabs/images/run_build_task_step_2.jpg
diff --git a/docs/silabs/images/run_build_task_step_3.jpg b/docs/silabs/images/run_build_task_step_3.jpg
diff --git a/docs/silabs/images/run_build_task_step_4.jpg b/docs/silabs/images/run_build_task_step_4.jpg
diff --git a/docs/silabs/images/win_run_setup.gif b/docs/silabs/images/win_run_setup.gif
diff --git a/docs/silabs/thread/BUILD_FLASH_MAD.md b/docs/silabs/thread/BUILD_FLASH_MAD.md
@@ -36,10 +36,10 @@ 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 submodules with
+Once you have cloned the repo, enter the repo and sync all the necessary submodules with
 the following command:
 
-> `$ cd matter` <br> `$ git submodule update --init --recursive`
+> `$ cd matter` <br> `$ ./scripts/checkout_submodules.py --shallow --recursive --platform efr32`
 
 <br>
 

diff --git a/docs/silabs/thread/FAQ.md b/docs/silabs/thread/FAQ.md
@@ -4,7 +4,7 @@
 
 -   Why are the `mattertool` commands not working after all the steps?
 
-    -   You should check if the Radio Co-Processor (RCP) image was build and/or
+    -   You should check if the Radio Co-Processor (RCP) image was built and/or
         flashed correctly to the device
     -   Make sure you see a QR code on the display of the Matter Accessory
         Device (MAD)
@@ -25,5 +25,7 @@
 
 <br>
 
-----
-[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) | [Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md)
+---
+
+[Table of Contents](../README.md) | [Thread Demo](./DEMO_OVERVIEW.md) |
+[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md)
diff --git a/docs/silabs/thread/RASPI_IMG.md b/docs/silabs/thread/RASPI_IMG.md
@@ -44,6 +44,8 @@ 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.
+
 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

diff --git a/docs/silabs/thread/RCP.md b/docs/silabs/thread/RCP.md
@@ -46,7 +46,7 @@ local machine. To clone the repo use the following command:
 Once you have cloned the repo, enter the repo and sync all the submodules with
 the following command:
 
-> `$ cd ot-efr32` <br> > `$ git submodule update --init --recursive`
+> `$ cd ot-efr32` <br> > `$ 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: