diff --git a/.github/workflows/00-Check-Code-Convention.yml b/.github/workflows/00-Check-Code-Convention.yml deleted file mode 100644 index 2ab0bfa..0000000 --- a/.github/workflows/00-Check-Code-Convention.yml +++ /dev/null @@ -1,94 +0,0 @@ -name: 00-Check-Code-Convention -on: - push: - branches-ignore: - - main - - master - - "tests/**" - pull_request: - branches: - - main - - master - - "release/**" - workflow_dispatch: - inputs: - branch: - description: 'Branch to test' - type: string - default: 'main' - -jobs: - job1: - name: Check coding convention - runs-on: ubuntu-22.04 #uncrustify 0.64 can not be compiled on ubuntu-24.04 - steps: - - name: Trigger - run: echo "Triggered by ${{github.event_name}} event" - - name: Check Branch Input - run: | - if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then - if [ -z "${{ github.event.inputs.branch }}" ]; then - echo "Branch input is required for manual trigger." - exit 1 - fi - fi - - name: Checkout - uses: actions/checkout@v4.1.7 - with: - ref: "${{ github.event_name == 'workflow_dispatch' && github.event.inputs.branch || github.ref }}" - submodules: true - fetch-depth: 0 - - name: Log Current Branch and Commit - run: | - echo "Current branch: $(git rev-parse --abbrev-ref HEAD)" - echo "Current commit: $(git rev-parse HEAD)" - - name: Install commit check tools - run: | - echo "Installing pre-commit ..." - python3 -m pip install pre-commit - echo "Installing uncrustify 0.64 from source code ..." - sudo apt-get install --no-install-recommends -y\ - binutils ca-certificates git cmake make \ - gcc g++ binutils libc6-dev - echo "Cloning Uncrustify repository..." - git clone -b uncrustify-0.64 --single-branch https://github.com/uncrustify/uncrustify.git - echo "Building and installing Uncrustify..." - mkdir ./uncrustify/build && cd ./uncrustify/build - cmake -D CMAKE_INSTALL_PREFIX=/usr/local -D CMAKE_BUILD_TYPE=RelWithDebInfo ../ - sudo make -j "$(nproc)" - sudo make install - echo "Uncrustify has been installed successfully!" - cd ../../ - sudo cp ./.github/coding-convention-tool/tools/uncrustify/uncrustify.cfg ./uncrustify/uncrustify.cfg - echo "Install clang-tidy" - sudo apt-get install clang-tidy - - name: Run test - run: | - pre-commit install --config .github/coding-convention-tool/.pre-commit-config.yaml - pre-commit run --config .github/coding-convention-tool/.pre-commit-config.yaml --all-files 2>&1 | tee CodingConventionTool.txt - git diff > code-fix.patch || echo "No changes to patch." - ls -lah code-fix.patch - - - name: Upload Result - uses: actions/upload-artifact@v4.3.4 - with: - name: CodingConventionResult - path: CodingConventionTool.txt - retention-days: 90 - - name: Upload Patch - uses: actions/upload-artifact@v4.3.4 - with: - name: code-fix.patch - path: code-fix.patch - retention-days: 90 - - name: Check log file to set status of the job - run: | - keywords=("Failed") - for keyword in "${keywords[@]}"; do - if grep -q "$keyword" CodingConventionTool.txt; then - echo "Keyword '$keyword' found in the file." - exit 1 - else - echo "Keyword '$keyword' not found in the file." - fi - done diff --git a/.github/workflows/02-Build-Firmware.yml b/.github/workflows/02-Build-Firmware.yml deleted file mode 100644 index 65eafe5..0000000 --- a/.github/workflows/02-Build-Firmware.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: 02-Build-Firmware - -on: - pull_request: - branches: - - main - - master - - "release/**" - workflow_dispatch: - inputs: - branch: - description: 'Branches to run the workflow on' - required: true - default: 'main' - -jobs: - FW_build: - runs-on: ubuntu-24.04 - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - ref: ${{ github.event.inputs.branch }} - - - name: Build Docker Image - run: docker build -t ${{ github.repository }}-build-env:latest . - - - name: Run Docker Container - run: docker run --rm -v ${{ github.workspace }}:/workspace ${{ github.repository }}-build-env:latest /bin/bash -c "cd /workspace && make all" - - - name: Clean up workspace - if: always() - run: sudo git clean -ffdx \ No newline at end of file diff --git a/sld119-matter-fundamentals/index.md b/sld119-matter-fundamentals/index.md new file mode 100644 index 0000000..c4aed0d --- /dev/null +++ b/sld119-matter-fundamentals/index.md @@ -0,0 +1,8 @@ +# Matter Fundamentals + +This section contains information for those not yet familiar with Matter. + +- [**Introduction to Matter**](/matter/{build-docspace-version}/matter-fundamentals-introduction): Offers an overview for those new to Matter. +- [**The Matter Data Model**](/matter/{build-docspace-version}/matter-fundamentals-data-model): Reviews the components of the Matter Data Model including nodes, endpoints, clusters, and device types. +- [**The Matter Interaction Model**](/matter/{build-docspace-version}/matter-fundamentals-interaction-model): Describes how the model defines the methods of communication between nodes, serving as the common language for node-to-node information transmission. +- [**Matter Security**](/matter/{build-docspace-version}/matter-fundamentals-security): Provides an overview of security for Matter as promoted by the Connectivity Standards Alliance. diff --git a/sld120-matter-wifi-getting-started/04-light-switch-step-by-step-example.md b/sld120-matter-wifi-getting-started/04-light-switch-step-by-step-example.md new file mode 100644 index 0000000..0786e13 --- /dev/null +++ b/sld120-matter-wifi-getting-started/04-light-switch-step-by-step-example.md @@ -0,0 +1,142 @@ +# Light and Switch Step-by-Step Example + +## Setting up the Matter Hub/Chip-Tool + +This procedure prepares the Raspberry Pi 4B (RPi4B) to become a Matter Hub. You should have downloaded the Matter Hub Raspberry Pi image and Raspberry Pi Imager as described in the [Overview](/matter/{build-docspace-version}/matter-overview). The Raspberry Pi image contains software called chip-tool, which provides a command-line interface into the Matter protocol. + +1. Install the Raspberry Pi Imager and insert the SD card into the PC to flash the image. + + 1. Open the Imager, select the Operating System as 'Custom OS' and browse for the Raspberry Pi Image. + + 2. Select the storage as an SD card. + + 3. Click the settings icon to configure the access point (AP) credentials, Hostname and user credentials. Make sure the 5 GHz Wi-Fi credentials of the dual-band AP are entered. + + 4. Click the 'write' option. **Note** this will erase all existing content on that SD card. + +2. Insert the SD card into Raspberry Pi 4B (RPi4B). + +3. Power-up the RPi4B. Once it is booted up, check the Raspberry Pi's IP address. Refer to [Finding Raspberry Pi IP address](/matter/{build-docspace-version}/matter-references/find-raspi) in the References chapter to get the IP address or enter the Hostname directly in PuTTY. + +4. Use PuTTY to connect to RPi4B. + + 1. The first time connecting to RPi4B, PuTTY will warn about a new host key or key fingerprint. Accept the key. + 2. The credentials (username: password) are the same given Step 1. + 3. Switch to root mode and navigate to path "/home/ubuntu/connectedhomeip/out/standalone" to find the chip-tool. + +Matter hub/chip-tool are ready and working. Keep the PuTTY session open for the following steps. + +## Creating the Matter Accessory Devices (MADs) + +> If using NCP hardware, make sure firmware is properly loaded to the NCP using instructions provided in: [Upgrading the Wi-Fi Connectivity Firmware](/matter/{build-docspace-version}/matter-wifi-run-demo/loading-firmware-for-ncp-and-soc-boards). + +1. In Simplicity Studio 5, create the Light MAD: + + 1. Switch to the Launcher view (if not already in it). + + 2. Connect one compatible dev board to the development computer. + + 3. Once it shows up in the Debug Adapters view, select it. + + 4. Open the Example Projects and Demos tab, select the **Matter** filter and enter "_Wi-Fi_" in **Filter on keywords**. + + 5. Select the _Matter - SoC Lighting over Wi-Fi_ example for RS9116, click **Create**, rename the project if you wish, and click **Finish**. + + 6. Once the project is created, the perspective changes to the Simplicity IDE perspective. In the Project Explorer view, right-click the project and select _Build Project_. + + 7. Once the project has compiled, in the Debug Adapters view right-click the board and select _Upload application_. + + 8. Select the _Application image path_ (Select the path for .s37 file in the path '\\project*name\GNU ARM v12.2.1 - Default') for the newly compiled project and a \_Bootloader image*. The EFR32MG24 devices must be programmed with a bootloader. Obtain those here: [Silicon Labs Matter Artifacts](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). + + 9. Disconnect the dev board from development computer. + + 10. **Optional**: Label this device (eg: my_light or my_switch) to make it easier to identify later. + +2. Repeat the process with the second Dev board, but selecting the _Matter - SoC Light Switch over Wi-Fi_ example instead. + +## Creating the Matter Network + +This procedure uses the chip-tool installed on the Matter Hub. Chip-tool includes many commands. The following are some that are used in this example: + +- `chip-tool ble-wifi pairing` +- `chip-tool onoff` +- `chip-tool toggle` +- `chip-tool accesscontrol` +- `chip-tool binding` + +In a PuTTY session to the Matter hub, use the chip-tool to commission the Matter light device.The various compatible boards will have different setups for their LED(s). Typically one LED (or a color channel, if RGB) will be used to indicate the network status of the device: + +- A short flash indicates the MAD is advertising to join a network + +- A rapid flash indicates the commissioning is in progress + +- Solid ON: the MAD is now in the network + +1. Power up the Matter Light device. + +2. Once it is powered up and booted, use the PuTTY session to commission the device using + + `./chip-tool pairing ble-wifi nodeID SSID PSK 20202021 3840` + + where `nodeID` is replaced with the desired ID (for example `./chip-tool pairing ble-wifi 1122 SlWifi 12345678 20202021 3840`). + +3. Make sure the SSID and PSK given here are of 2.4 GHz of the Dual Band AP. + + Be sure to note which nodeIDs are used for Matter light and Matter light_switch devices. These will be needed later for modifying the Matter light's ACL & the Matter light switch's binding table. + +4. Power up the Matter light switch device and commission it too, using a different `nodeID`. + +Now two Matter accessory devices (MADs) are on the network and ready to be used. + +## Controlling the Light MAD + +1. In a PuTTY session to the Matter hub, use the chip-tool to test the Matter light device. + + 1. Control the light status of the light MAD Using `./chip-tool onoff on nodeID 1`. You can also use `chip-tool onoff off` and `chip-tool toggle`. + 2. For dev board with buttons available, you can use BTN1 to toggle the light status locally. + +2. In a PuTTY session to the Matter hub, use the chip-tool to bind the light_switch MAD to the light MAD, thus allowing the switch to control the light. + + 1. First, modify the Access Control List (ACL) of the Matter light device. This list determines which device in the network the Matter light device will react to. Use: `./chip-tool accesscontrol write acl '[ { "fabricIndex" : 1 , "privilege" : 5 , "authMode" : 2 , "subjects" : [`**`112233`**`] , "targets" : null } , { "fabricIndex" : 1 , "privilege" : 3 , "authMode" : 2 , "subjects" : [`**`nodeID-switch`**`], "targets" : null }]'`**`nodeID-light 0`**, where the highlighted parameters are: + + - **112233**: The node ID of the controller. This is always 112233. + + - **nodeID-switch**: The node ID of the Matter light switch device. + + - **nodeID-light**: The node ID of the Matter light device. + + - **0**: The endpoint in the Matter light device that holds the ACL. This is always 0. + + To read the ACL for a Matter device use: `./chip-tool accesscontrol read acl`**`nodeID 0`**, where the highlighted parameters are: + + - **nodeID**: The nodeID of the Matter device (Light or Light_switch) to read the ACL contents from. + + - **0**: The endpoint in the Matter device that holds the ACL. This is always 0. + + 2. Second, bind the switch's write command to the light. This is done by updating the binding table of the Matter light_switch device. This can be done using the command: `./chip-tool binding write binding '[ { "fabricIndex" : 1 , "node" :`**`nodeID-light`**,`"endpoint" :`**`1`**,`"cluster" :`**`cluster-ID`**`} ]'`**`nodeID-switch 1`**, where the highlighted parameters are: + + - **nodeID-light**: The node ID of the Matter light device. + + - **1**: The application endpoint in the light. This is always 1. + + - **cluster-ID**: The ID of the cluster to be controlled. Currently supported clusters are on/off(ID: 6) and level control(ID: 8). + + - **nodeID-switch**: The node ID of the switch. + + - **1**: This is the application endpoint in the switch that holds the binding table. This is always 1. + + The binding table from a Matter device can be read using: `./chip-tool binding read binding`**`nodeID-switch 1`**, where the highlighted parameters are: + + - **nodeID-switch**: The node ID of the Matter switch. + + - **1**: The application endpoint in the switch that holds the binding table. This is always 1. + +3. With the binding complete, a button press (BTN1) on Matter light switch device should now toggle the light or control the level of Matter light device. The button functionality is as follows: + + - **On/Off Binding** + - **BTN1 short press**: To toggle the light on the Matter light device. + + - **Level Control Binding** + - By default, step direction is UP. + - **BTN0 short press + BTN1 short press**: Inverts the step direction (i.e., UP to DOWN and vice versa). + - **BTN1 long press**: Moves the level UP or DOWN according to the step direction diff --git a/sld120-matter-wifi-getting-started/05-example-applications-demos.md b/sld120-matter-wifi-getting-started/05-example-applications-demos.md new file mode 100644 index 0000000..48c9195 --- /dev/null +++ b/sld120-matter-wifi-getting-started/05-example-applications-demos.md @@ -0,0 +1,13 @@ +# Example Applications and Demos + +The Silicon Labs Matter Extension offers example applications to help in getting started with Matter. The first two of these are used in this guide's step-by-step example: + +- Matter SoC Light over Wi-Fi + +- Matter SoC Light Switch over Wi-Fi + +- Matter SoC Window Cover over Wi-Fi + +- Matter SoC Lock over Wi-Fi + +- Matter SoC Thermostat over Wi-Fi diff --git a/sld120-matter-wifi-getting-started/07-next-steps-other-resources.md b/sld120-matter-wifi-getting-started/07-next-steps-other-resources.md new file mode 100644 index 0000000..932dd2e --- /dev/null +++ b/sld120-matter-wifi-getting-started/07-next-steps-other-resources.md @@ -0,0 +1,17 @@ +# Next Steps + +Now that you have gotten a sense of what goes into making a Matter network, you can begin to customize MADs and other features for your own purposes. The [Developers' Guide](/matter/{build-docspace-version}/matter-developers-guide-overview) contains more detail than was provided in this Quick-Start guide, and also contains information on a number of special development topics. Your Matter Extension package contains a number of other Matter examples that you can use as a starting point, the first two of which were used in this example. + +- Matter SoC Light over Wi-Fi + +- Matter SoC Light Switch over Wi-Fi + +- Matter SoC Window Cover over Wi-Fi + +- Matter SoC Lock over Wi-Fi + +- Matter SoC Thermostat over Wi-Fi + +If you need support you can contact Silicon Labs through the [Silicon Labs Community](https://community.silabs.com/s/topic/0TO1M000000qHZgWAM/matter). Our engineers and community will be happy to help! You may also find answers here: + +- [Silicon Labs Matter articles](https://community.silabs.com/s/topic/0TO1M000000qHZgWAM/matter?tabset-178da=2) diff --git a/sld120-matter-wifi-getting-started/index.md b/sld120-matter-wifi-getting-started/index.md new file mode 100644 index 0000000..58ffdbd --- /dev/null +++ b/sld120-matter-wifi-getting-started/index.md @@ -0,0 +1,6 @@ +# Matter over Wi-Fi Quick-Start Guide + +These pages describe how to create a simple Matter network in which you can use a switch to control a light. + +You should have obtained hardware and installed software as described in the [Overview](/matter/{build-docspace-version}/matter-overview). Once you have done so, +you can begin the [step-by-step instructions](./04-light-switch-step-by-step-example.md). diff --git a/sld132-matter-thread-getting-started/03-light-switch-step-by-step-example.md b/sld132-matter-thread-getting-started/03-light-switch-step-by-step-example.md new file mode 100644 index 0000000..423cd76 --- /dev/null +++ b/sld132-matter-thread-getting-started/03-light-switch-step-by-step-example.md @@ -0,0 +1,235 @@ +# Matter over Thread Light and Switch Step-by-Step Example + +This tutorial was created with the Matter Extension of the Simplicity SDK (SiSDK). Going forward, the latest Matter Extension will be released through the Simplicity SDK (SiSDK). + +## Setting up the Matter hub + +1. Prepare a compatible dev board to become your Matter hub's ot-rcp (see details in the [introduction](./index.md)): + + 1. Start Simplicity Studio 5 with the latest SiSDK and Silicon Labs Matter SiSDK Extension installed (see details in the [Overview](/matter/{build-docspace-version}/matter-overview#software-requirements)). + + ![the Matter extension](./resources/image1.png) + + 2. Connect the dev board to your development computer. + + 3. Once it shows up in the Debug Adapters view, select it. + + ![Debug Adapters view](resources/image2.png) + + 4. Go to the Example Projects and Demos tab. Select the *OpenThread* filter and enter "*openthread rcp*" in the **Filter on keywords** box. Select the *OpenThread - RCP* example and click *Run*. + + ![Example projects and demos view](resources/image3.png) + + 5. Disconnect the dev board and connect it to your RPi4B. + +2. Prepare the Raspberry Pi 4B (RPi4B) to become a Matter hub: + + 1. Download and extract the Matter hub Raspberry Pi image (see details under [Software requirements](/matter/{build-docspace-version}/matter-overview#software-requirements)). + + 2. Flash the image to the desired SD card. Please note this will erase all existing content on that SD card: + + 1. Under **Operating System**, click **CHOOSE OS**. Scroll down and choose the last option, **Use custom**. Browse to your extracted **SilabsMatterPi.img** file and select it. + + ![Raspberry Pi interface](resources/image4.png) + + 2. Under **Storage**, click **CHOOSE STORAGE**. Select your target SD card. If it does not show up, make sure it is inserted properly and not in use by other software and retry this step. + + ![Raspberry Pi Storage selection](resources/image5.png) + + 3. Click **WRITE** and confirm the action by clicking **YES**. Wait for the process to finish writing to the SD card and verifying the results. + + ![Raspberry Pi write to SD card](resources/image6.png) + + 3. Insert the SD card in your Raspberry Pi 4B (RPi4B) and connect it to your network by Ethernet (Wi-Fi cannot be used for this example). + + 4. Power-up the RPi4B. Once it is booted up, check your local network DHCP IP address allocation rules to determine the RPi4B's assigned IP address. You may also use networking tools such as *nmap* to find your RPi4B’s IP assigned address. + + 5. Use PuTTY to connect to your RPi4B. + + 1. The first time you connect to your RPi4B, PuTTY will warn you about a new host key or key fingerprint. Accept the key. + + ![Warning from PuTTY](resources/image7.png) + + 2. The default credentials are **ubuntu**:**ubuntu** (username:password). **Note**: In PuTTY, you can set the default username to **ubuntu** under *Connection > Data > Auto-login username*. + + ![PuTTY Configuration](resources/image8.png) + + 3. You may be prompted to change the password. + + 6. Verify that your *ot-rcp* board is visible in your RPi4B. It should show up as a *ttyUSB****n*** or a *ttyACM****n*** in */dev/.* where ***n*** indicates the port's number (ex: */dev/ttyACM0*). + + ![Verifying the ot-rcp board](resources/image9.png) + + **Note**: If your RCP shows up with a number other than 0, the otbr-agent file will need to be updated. + +You now have a working Matter hub. Keep the PuTTY session open for the following steps. + +## Creating the Matter Accessory Devices (MADs) + +1. In Simplicity Studio 5, create the light MAD: + + 1. Switch to the Launcher view (if not already in it). + + 2. Connect one compatible dev board to your development computer. This example uses a BRD4186C. + + 3. Once it shows up in the Debug Adapters view, select it. + + 4. Go to the Example Projects and Demos tab, turn off *Demos*, check the *Matter* filter under *Wireless Technology* and enter "*thread*" in the *Filter on keywords* box. + + ![Select the example project](resources/image10.png) + + 5. Select the *Matter - SoC Light over Thread* example and click **Create**. Name your project and click **Finish** (no other changes are required at this time). + + ![Create the project](resources/image11.png) + + 6. Once the project is created, right-click it in the Project Explorer view and select *Build Project*. + + ![Build the project](resources/image12.png) + + 7. Once the compilation is done, right-click the dev board in the Debug Adapters view and select *Upload application...* + + ![Upload application](resources/image13.png) + + 8. Select the *Application image path* for your newly compiled project and a *Bootloader image*. Bootloader images are provided in the zip file referenced on the [Silicon Labs Matter Artifacts page](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). Unzip and reference the extracted location. Check "Erase chip before uploading image". + + ![Application image upload](resources/image14.png) + + **Note**: If you are unsure of the path for the newly created binary, you can find the project’s path in the project’s *Properties* window under *Resource*. The binary is typically located inside the *{solution folder}\|{project name folder}\|{GNU ARM v??? folder}\|{project name binary}.s37*. For example, you would find the binary for a Matter light over Thread project with the default name here: *{solution folder}\|MatterLightOverThread\|GNU ARM v10.3.1 - Default\|MatterLightOverThread.s37*. + + **Note**: You should only need to upload a bootloader image and erase the chip once. Subsequent application uploads do not need the bootloader image or chip erasure. + + ![Image location](resources/image15.png) + + 9. If you are using a dev board with a WSTK, you should now see a QR code displayed on the WSTK's LCD. + + 10. Disconnect the dev board from your development computer. + + 11. **Optional**: you may want to label this device as your light or switch, as appropriate, to make it easier to identify later. + +2. Repeat the process above with the second dev board but selecting the *Matter - SoC Light Switch over Thread* example instead. + +## Creating the Matter Network + +The *mattertool* is a convenient wrapper script that allows you to easily perform common steps using *chip-tool*. Chip-tool provides a command-line interface into the Matter protocol. mattertool and chip-tool are installed in the Matter Hub image file. + +mattertool provides many commands at your disposal. These are some important ones used in this example: + +- *mattertool startThread* + +- *mattertool bleThread* + +- *mattertool on* + +- *mattertool off* + +- *mattertool toggle* + +You can use the command *mattertool help* to display the available commands. With some commands (such as on, off, and toggle), you may also want to specify which node ID to interact with. You can do this by adding the *-n nodeID* parameter after a command, such as *mattertool on -n 5678*. + +The *mattertool* also allows you to perform any of the commands you can normally use directly with the *chip-tool*. + +1. In a PuTTY session to the Matter hub, use the *mattertool* to create your network. + + 1. Start the Thread network with: *mattertool startThread*. This will output the Thread dataset. + + ![Mattertool start](resources/image16.png) + + 2. If you need the Thread dataset in the future (such as after a power cycle), you can use *mattertool getThreadDataset*. + +## Connecting MADs to the Matter hub + +1. In a PuTTY session to the Matter hub, use the *mattertool* to commission your Matter light switch device. + + 1. Connect to a power source your Matter light switch device. + + >**Notes**: Only power-up one device at a time to ensure proper commissioning since no discriminator is used to keep this example simple. + + >If this device previously failed commissioning or was on a Thread network, you may need to perform a factory reset before doing this process. + + >The Matter devices will stop advertising after ~15 minutes. Make sure to complete the commissioning before the advertising has expired. If unsure, power cycle the MAD. + + 2. Once the MAD is powered and booted up, use the PuTTY session to commission the device using 'mattertool bleThread -n nodeID', where 'nodeID' is replaced with the desired ID. In the resulting log, you should see a line similar to: + + `[1683785224.525598][1455:1461] CHIP:CTL: Commission called for node ID 0x000000000000637E`, indicating the nodeID (in this example, `0x637E`) of the newly commissioned device. + + ![Output example](resources/image17.png) + + >**Note**: If you do not specify a *nodeID*, one will be assigned automatically. Make sure to take note of what nodeID assigned to your Matter light switch & Matter light devices. These will be needed later for modifying the Matter light's ACL & the Matter light switch's binding table. + + 3. Power up the Matter light device and commission it as well, by following the previous steps for this MAD but using a different *nodeID* . + +You now have two Matter devices on your network ready to be used + +## Controlling the Light MAD + +The various compatible boards will have different setups for their LED(s). Typically, one LED (or a color channel, if RGB) is used to indicate the network status of the device: + +- Short blink: indicates the MAD is advertising to join a network. + +- Half/half blink: indicates the BLE steps are in progress. + +- Long blink: indicates joining the Thread network. + +- Solid on: indicates the MAD is now in the network. + +For example, on the dev board *xG24-DK2601B EFR32xG24* (also known as *BRD2601*), the red channel of *LED0* is used to indicate the network status. The green channel of *LED0* is used to indicate the light status. + +![Boards and features](resources/image18.png) + +1. In a PuTTY session to your Matter hub, use the *mattertool* to test your Matter light device. + + 1. Using `mattertool on -n nodeID` (similarly, `mattertool off` and `mattertool toggle` can also be used) you can control the light status of your Matter light device. + + ![Controlling the Light MAD](resources/image19.png) + + 2. For dev board with buttons available, you can use BTN1 to toggle the light status locally. + +2. In a PuTTY session to your Matter hub, use the *mattertool* to bind your Matter light switch device to your Matter light device, thus allowing the switch to control the light. + + 1. First, you will need to modify the Access Control List (ACL) of your Matter light device. This list determines which device in the network your Matter light device will react to. Modify your Matter light device's ACL using: `mattertool accesscontrol write acl '[ { "fabricIndex" : 1 , "privilege" : 5 , "authMode" : 2 , "subjects" : [`**`112233`**`] , "targets" : null } , { "fabricIndex" : 1 , "privilege" : 3 , "authMode" : 2 , "subjects" : [`**`nodeID-switch`**` ], "targets" : null }]' `**`nodeID-light 0`**, where the highlighted parameters are: + + - **112233**: The node ID of the controller (OTBR). This is always 112233. + + - **nodeID-switch**: The node ID of the Matter light switch device in base 10 (ex: 43690 for 0xAAAA). + + - **nodeID-light**: The node ID of the Matter light device in hex (ex: 0xBBBB). + + - **0**: The endpoint in the Matter light device that holds the ACL. This is always 0. + + ![Modifying the access control list](resources/image20.png) + + **Note**: The ACL table action is a read/modify/write step. If you accidentally remove the chip-tool entry, this will prevent further control of the device, requiring a factory reset. + + You can read the ACL for a Matter device using: *mattertool accesscontrol read acl* ***nodeID*** ***0***, where the highlighted parameters are: + + - **nodeID**: The nodeID of the Matter device you wish to read the ACL contents from. + + - **0**: The endpoint in the Matter device that holds the ACL. This is always 0. + + ![Reading the ACL](resources/image21.png) + + 2. Second, you need to bind the switch's write command to the light. This is done by updating the binding table of your Matter light switch device. You do this with: `mattertool binding write binding '[ { "fabricIndex" : 1 , "node" :`**`nodeID-light`**,` "endpoint" : `**`1`**,`"cluster" :`**`6`**`} ]'`**`nodeID-switch 1`**, where the highlighted parameters are: + + - **nodeID-light**: The node ID of the Matter light device. + + - **1**: The application endpoint in the light. In the Silabs examples, this is always 1. + + - **6**: The on/off cluster in the light. This is always 6. + + - **nodeID-switch**: The node ID of the switch. + + - **1**: This is the application endpoint in the switch that holds the binding table. In the Silabs examples, this is always 1. + + ![Bind the switch to the light](resources/image22.png) + + **Note**: As with the ACL table step, the binding table action is a read/modify/write step. If you accidentally remove the chip-tool entry, this will prevent further control of the device, requiring a factory reset. + + You can read the binding table from a Matter device using: `mattertool binding read binding`**`nodeID-switch 1`**, where the highlighted parameters are: + + - **nodeID-switch**: The node ID of the Matter switch. + + - **1**: The application endpoint in the switch that holds the binding table. In the Silabs examples, this is always 1. + + ![Reading the binding table](resources/image23.png) + + With the binding complete, a button press on the Matter light switch device should now toggle the light status in the Matter light device. diff --git a/sld132-matter-thread-getting-started/04-example-applications-demos.md b/sld132-matter-thread-getting-started/04-example-applications-demos.md new file mode 100644 index 0000000..96d8e32 --- /dev/null +++ b/sld132-matter-thread-getting-started/04-example-applications-demos.md @@ -0,0 +1,15 @@ +# Example Applications and Demos + +The Silicon Labs Matter SiSDK Extension offers example applications to help you get started with Matter, the first two of these are used in this guide's step-by-step example: + +- Matter SoC Light over Thread + +- Matter SoC Light Switch over Thread + +- Matter SoC Window Cover over Thread + +- Matter SoC Lock over Thread + +- Matter SoC Thermostat over Thread + +![Example project selection](resources/image24.png) diff --git a/sld132-matter-thread-getting-started/05-next-steps-other-resources.md b/sld132-matter-thread-getting-started/05-next-steps-other-resources.md new file mode 100644 index 0000000..189c6a3 --- /dev/null +++ b/sld132-matter-thread-getting-started/05-next-steps-other-resources.md @@ -0,0 +1,23 @@ +# Next Steps + +Now that you have gotten a sense of what goes into making a Matter network, you can +begin to customize MADs and other features for your own purposes. The [Developers' Guide](/matter/{build-docspace-version}/matter-developers-guide-overview) contains more detail than was provided in this Quick-Start guide, +and also contains information on a number of special development topics. Your Matter +Extension package contains a number of other Matter examples that you can use as a starting point, the first two +of which were used in this example. + +- Matter SoC Light over Thread + +- Matter SoC Light Switch over Thread + +- Matter SoC Window Cover over Thread + +- Matter SoC Lock over Thread + +- Matter SoC Thermostat over Thread + +![Example project selection](resources/image24.png) + +If you need support you can contact Silicon Labs through the [Silicon Labs Community](https://community.silabs.com/s/topic/0TO1M000000qHZgWAM/matter). Our engineers and community will be happy to help! You may also find answers here: + +- [Silicon Labs Matter articles](https://community.silabs.com/s/topic/0TO1M000000qHZgWAM/matter?tabset-178da=2) diff --git a/sld132-matter-thread-getting-started/index.md b/sld132-matter-thread-getting-started/index.md new file mode 100644 index 0000000..0a2e5ab --- /dev/null +++ b/sld132-matter-thread-getting-started/index.md @@ -0,0 +1,56 @@ +# Matter over Thread Quick-Start Guide + +These pages describe how to create a simple Matter network in which you can use a switch to control a light, described in more detail below under [A Typical Setup](#a-typical-setup). + +You should have obtained hardware and installed software as described in the [Quick-Start Guide Overview](/matter/{build-docspace-version}/matter-overview). The Matter over Thread demo requires an additional device to be used as the Hub's radio co-processor (RCP). You will therefore need some additional hardware and software. + +## Radio Co-Processor Prerequisites + +### Hardware + +- 1x radio co-processor (RCP) compatible with RCP firmware images. Images are available for the following boards: + + - EFR32xG24: BRD2601, BRD2703, BRD4186, BRD4187 + +### Software + +The Matter hub OpenThread RCP (ot-rcp) must be programmed with a bootloader and firmware image to act as the ot-rcp for the Raspberry Pi. You can obtain a copy of the latest version here: [Silicon Labs Matter Artifacts](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). + +## A Typical Setup + +A typical simple Matter over Thread network setup is shown in the following +image. + +![Matter 15.4 Setup](./resources/thread-overview.png) + +The setup consists of the following four elements: + +1. A **Controller** such as an app running on a phone or the chip-tool running + on a Linux box or Raspberry Pi. +2. An Open Thread Border Router (**OTBR**) running on a Linux box or Raspberry + Pi. +3. A Radio Co-Processor (**RCP**), which the OTBR uses to communicate with the + Thread network (not shown). This is attached to the Raspberry Pi. +4. An End Device such as a light or switch, which is the Matter Accessory + Device (**MAD**). + +The flow of the setup described above is as follows: + +1. The controller commissions the End Device directly over Bluetooth – this + makes the End Device join the Thread network and the Matter "Fabric". +2. After commissioning, the Bluetooth connection is terminated and all further + communication is done over Matter. +3. The controller sends ZCL commands, such as the OnOff Toggle, and the End + Device performs the corresponding action, such as turning the End Device's + LED on or off + +A Matter network can be built in a number of ways using a combination of Silicon +Labs hardware, a Raspberry Pi, and any external controller (MacBook, Ubuntu, +Android, etc.) + +The suggested method, and the one illustrated in this quick-start guide, involves using a Raspberry Pi to function as both the +controller and the OTBR, with a Silicon Labs device as the MAD. + +An alternate configuration is to use a MacBook as the controller, a Raspberry Pi +as the OTBR, and a Silicon Labs Device as the MAD. This requires additional +routing between the controller and OTBR. diff --git a/sld246-matter-faq/index.md b/sld246-matter-faq/index.md new file mode 100644 index 0000000..78012f1 --- /dev/null +++ b/sld246-matter-faq/index.md @@ -0,0 +1,6 @@ +# Silicon Labs Matter FAQ + +This section provides the following FAQs and troubleshooting information. + +- [Thread FAQ](./thread-faq.md) +- [Wi-Fi FAQ](./wifi-faq.md) \ No newline at end of file diff --git a/sld246-matter-faq/thread-faq.md b/sld246-matter-faq/thread-faq.md new file mode 100644 index 0000000..ed7293b --- /dev/null +++ b/sld246-matter-faq/thread-faq.md @@ -0,0 +1,22 @@ +# Frequently Asked Questions for Matter over Thread + +## Demo + +- Why are the `mattertool` commands not working after all the steps? + + - 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). + - Make sure the images being used to flash the Raspberry Pi, RCP and MAD are correct. + +- How can I find the IP address of my Raspberry Pi? + + - First, make sure the Raspberry Pi is connected to a network (ethernet or Wi-Fi). This page has more information: + [Setting up the Matter Hub (Raspberry Pi)](/matter/{build-docspace-version}/matter-thread/raspi-img) + - Refer to this page for general questions on finding the Raspberry Pi on your network: [Finding your Raspberry Pi](/matter/{build-docspace-version}/matter-references/find-raspi) + - For more detailed information, refer to this page: + [Raspberry Pi Remote Access](https://www.raspberrypi.com/documentation/computers/remote-access.html) + +- How can I use a crystal value different than the default (39.0 MHz) for my device? + + - When using an alternative crystal value (i.e.: different than 39.0 MHz), updating the clock speed for both the HFXO and DPLL values is needed and both must match, where the DPLL is set to 2x the HFXO value. These values are used by the RAIL library to determine the radio frequency and the proper timings for the BLE packets. + - If the DPLL value is left unchanged with a modified HFXO, the radio will be on the right frequency but the BLE packet timings will not be correct, which will cause issues within a few packets due to BLE's strict timing requirements. diff --git a/sld246-matter-faq/wifi-faq.md b/sld246-matter-faq/wifi-faq.md new file mode 100644 index 0000000..f769693 --- /dev/null +++ b/sld246-matter-faq/wifi-faq.md @@ -0,0 +1,215 @@ +# Frequently Asked Questions and Troubleshooting for Matter over Wi-Fi + +## Troubleshooting + +### 1. Bluetooth connection fails when trying to commission the system through the chip-tool + +**Command leading to error:** + +`$ 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**. + +**Error example:** + +```log +[1659464425.856025][34818:34823] CHIP:DL: HandlePlatformSpecificBLEEvent 16386 +[1659464425.856035][34818:34823] CHIP:IN: Clearing BLE pending packets. +[1659464425.856055][34818:34823] CHIP:IN: BleConnection Error: ../../examples/chip-tool/third_party/connectedhomeip/src/platform/Linux/bluez/Helper.cpp:1775: CHIP Error 0x000000AC: Internal error +``` + +> This error indicates that the Bluetooth connection between your system and +> laptop is failing. Follow the given procedure and then retry the chip-tool +> commissioning command. + +**Procedure:** + +1. Stop Bluetooth service: + + ```shell + $ systemctl stop bluetooth.service + ``` + +2. Wait 20 seconds +3. Restart Bluetooth service: + + ```shell + $ sudo service bluetooth restart + ``` + +4. Unblock Bluetooth service: + + ```shell + $ rfkill unblock all + ``` + +5. Enable Bluetooth service: + + ```shell + $ sudo systemctl enable bluetooth + ``` + +6. Issue the pairing command: + + ```shell + $ 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**. + +### 2. Unsupported certificate format error + +> When trying to commission the system, if an `Unsupported certificate format` +> error (example below) is encountered, follow the procedure stated below. + +**Error example:** + +```log +[1659631352.672826][5076:5076] CHIP:TOO: Run command failure: ../../examples/chip-tool/third_party/connectedhomeip/src/controller/CHIPDeviceController.cpp:1275: CHIP Error 0x00000050: Unsupported certificate format +``` + +**Procedure:** + +- Delete the existing certificates on your laptop with the following command + run from the `/connectedhomeip` directory: + + ```shell + $ /bin/rm /tmp/chip_* + ``` + +- Issue the commissioning command + +### 3. WLAN connection fails from RS9116 during commissioning when channel 13 is selected on the AP + +The required channel becomes available for connection when the WLAN connection region is configured during compilation to one that supports the channel, such as for Japan for channel 13. + +In order to use the desired channel, before building, make sure the WLAN connection region is configured correctly by reviewing/modifying the following lines in **/examples/platform/silabs/efr32/rs911x/rsi_wlan_config.h**: + +```c +//Make sure this is set to RSI_ENABLE +#define RSI_SET_REGION_SUPPORT RSI_ENABLE + +// Note that the channels available for WLAN connection depend on the region selected +// Make sure this is set to 1 to configure from RSI_REGION_CODE value below +// 0: region configurations taken from beacon +// 1: region configurations taken from user +#define RSI_SET_REGION_FROM_USER_OR_BEACON 1 + +// 0 : Default Region domain +// 1 : US +// 2 : EUROPE +// 3 : JAPAN +#define RSI_REGION_CODE 3 +``` + +### 4. Incorrect firmware version + +```shell +cd ./third_party/silabs/wiseconnect-wifi-bt-sdk/firmware +``` + +You will get appropriate firmware in the above mentioned path. + +Note: + +1. How to check the current firmware version? + + > You can find the currently used firmware version in the DUT log. + +2. How to check whether you are using correct firmware version or not? + + > Compare last 5 digits of firmware version mentioned in the above path with the currently used firmware version. + +### 5. Apple HomePod associated failures + +If there is an Apple HomePod on the network paired with a Thread device, and a commissioning failure is seen with error `3000001`: + +> Either remove the Apple HomePod from the network, or unpair it from all Thread devices, before re-trying the commissioning. + +### 6. Commissioning failure at step 18 + +1. Verify router configuration specifically related to IPV6 SLAAC, Internet Group Management Protocol (IGMP) snooping. +2. Delete all the files of chip-tool /tmp folder. (`rm -rf /tmp/chip_*`) +3. After checking the router configuration, factory-reset your access point. + +### 7. Commissioning failure at step 16 + +Verify the access point settings, SSID, PSK, security type, REGION, CHANNEL. + +### 8. Inconsistent logs + +Verify external power is supplied to rs911x + +### 9. To enable different security options on AP/Router + +1. Get the router address by entering `route -n` or ifconfig of ipconfig. +2. Enter the router address in the browser and enter the appropriate username and password. +3. Select the appropriate band. +4. In security, select type (WPA / WPA2 / WPA3). + +### 10. CHIP Logs are not available on MG12 + WF200 due to image size constraints + +Due to apps taking up more space than available flash on the MG12 + WF200 device combination, `chip_logging=false` needs to be included on the command line while building the app image, to disable CHIP logs and thereby reduce the image size. + +This prevents debugging the code on the MG12 + WF200 device combination. + +In order to work around this constraint, disable either the LCD or the use of QR codes, depending on your debugging needs. Disabling one of these will sufficiently reduce the image size to allow CHIP Logging to be enabled. + +If you disabled QR Codes, you may use the `chip-tool` for commissioning the device. + +If you disabled the LCD and need to debug with QR Codes, the URL to display the QR Code will be printed in the device logs. + +Disable LCD and enable CHIP Logging: +`./scripts/examples/gn_efr32_example.sh examples/lock-app/efr32 out/wf200_lock_app BRD4161A is_debug=false disable_lcd=true --wifi wf200 |& tee out/wf200_lock_app.log` + +Disable QR Code and enable CHIP Logging: +`./scripts/examples/gn_efr32_example.sh examples/lock-app/efr32 out/wf200_lock_app BRD4161A is_debug=false show_qr_code=false --wifi wf200 |& tee out/wf200_lock.log` + +### 11. MG24 device sometimes loses its connection to Ozone during OTA Update with RS9116 + +While performing an OTA Update with the EFR32MG24 + RS9116 device combination, when the device is reset and bootloading begins with the new image, the Ozone Debugger sometimes loses its connection. + +There are two possible workarounds to this: + +1. Immediately re-attach the device to the console when the connection is lost. + +2. Download the RTT Viewer application instead and use it to view the logs during OTA Update. + +### 12. MG24 device sometimes fails to bootload with the new image during OTA Update with WF200 + +While performing an OTA Update with the EFR32MG24 + WF200 device combination using the external flash, when the device is reset and bootloading begins with the new image, the device sometimes starts up with the existing image instead of the newly downloaded one. + +When this happens, perform the following steps to run the OTA Update successfully: + +1. Disconnect the WF200 Expansion Board from the EFR32MG24. + +2. Go To the Simplicity Commander's folder path in the command prompt and run this command: + + ```shell + commander.exe extflash read --range 0x00:+ + ``` + +3. Reconnect the WF200 Expansion Board to the EFR32MG24 and reset the device. + +4. Re-run the OTA Update process from the beginning. + +### 13. Connectivity Issues with SiWX917 SoC with Low-Power Applications while flashing firmware/application image + +Sometimes, firmware/application updates fail while flashing, and the logs display "Could not connect debugger. Could not connect to target device," indicating that the application processor is in a low power state with no flash access. Try one of the following solutions, then retry the firmware/application update: + +Toggle the power switch towards **AEM** (Advanced Energy Monitoring) on the WPK/WSTK board, or + +Perform the following sequence of steps: + +1. Press and hold the **ISP** button on the radio board and the **RESET** button on the WPK/WSTK board simultaneously. + +2. Release the **RESET** button on the WPK/WSTK board. + +3. Release the **ISP** button on the radio board. + +4. Click **Erase chip** to erase the flash. + +5. Press the **RESET** button on the WPK/WSTK board again. + +6. Retry flashing the firmware/application. diff --git a/sld247-matter-overview/index.md b/sld247-matter-overview/index.md new file mode 100644 index 0000000..ef878e3 --- /dev/null +++ b/sld247-matter-overview/index.md @@ -0,0 +1,106 @@ +# Quick-Start Guides for Matter over Thread and Matter over Wi-Fi + +## Overview + +The procedures here describe how to make a simple network of a light, a switch, and a Matter hub, and to use the switch to control the light. First, set up your hardware and software as described below. Then you will follow a step by step procedure to: + +- Create a Matter hub on a Raspberry Pi. +- Compile and load a light and a switch example application onto two Silicon Labs development boards to make light and switch Matter Accessory Devices (MADs). +- Create a Matter network with the MADs and the Matter hub. +- Test the light through the Matter hub. +- Bind the switch MAD to the light MAD, so that the switch can control the light. + +## Initial Setup + +Both the Matter over Wi-Fi and Matter over Thread demos require that you have set up a simple development environment with Simplicity Studio, +two EFR32MG24-based development boards, and a Raspberry Pi used as a Matter hub. The following requirements are common to both demos. The Thread demo also requires a radio co-processor (RCP) as part of the Matter hub. The requirements for this are provided in the [introduction to the Thread demo](/matter/{build-docspace-version}/matter-light-switch-example/02-thread-light-switch-example). + +### Hardware Requirements + +#### Matter Hub + +- 1 Raspberry Pi 4B +- 1x high speed, 64 GB SD card + +#### Matter Devices + +**Matter Over Wi-Fi Accessory Device Requirements for NCP Mode** + +The Silicon Labs Matter over Wi-Fi NCP mode demo and development requires two boards: the Silicon Labs EFR32 Radio board to run the Matter code and either the RS9116, SiWx917, or WF200 to run the Wi-Fi protocol stack. + +The following boards are supported for the Matter over Wi-Fi demos and development: + +- **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) + - MG24 with WSTK: [xG24-PK6009A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-10-dbm?tab=overview) + - BRD4187C / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm + - [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board) + - MG24 with WSTK: [xG24-PK6010A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-20-dbm?tab=overview) +- **Wi-Fi NCP Dev Kits & boards** + - **RS9116** + - SB-EVK1 / Single Band Wi-Fi Development Kit / 2.4GHz + - [RS9116X-SB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit) + - SB-EVK2 / Single Band Wi-Fi Development Kit / 2.4GHz + - [RS9116X-SB-EVK2](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk2-development-kit) + - DB-EVK1 / Dual Band Wi-Fi Development Kit / 2.4GHz & 5GHz + - [RS9116X-DB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-db-evk-development-kit) + - **SiWx917 NCP** + - SiWx917 NCP Mode / Wi-Fi Expansion Board / 2.4GHz + - BRD8045A (B0 Expansion v2.0) + - **WF200** + - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz + - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) + - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz + - [SLEXP8023A](https://www.silabs.com/development-tools/wireless/wi-fi/wfm200-wifi-expansion-kit) + - Interconnect board (included in the Wi-Fi kits) + - SPI Cable (included in the RS9116 kit) + - Jumper Cables (included in the RS9116 kit) + +**Matter Over Wi-Fi Accessory Device Requirements for SoC Mode** + +The Silicon Labs Matter over Wi-Fi demo and development for SoC mode requires the SiWx917 SoC board that supports Matter over Wi-Fi in a single-chip package. The integrated MCU is dedicated for peripheral and application-related processing (Matter), while the ThreadArch® runs the wireless and networking protocol stacks. + +Pre-built images for the SiWx917 connectivity firmware are available per the instructions on the [Matter Artifacts page](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). The following boards are supported for the Matter over Wi-Fi demos and development: + +- **Wi-Fi SoC Boards** + - SiWx917 / BRD4002A / Wireless Starter Kit + - SiWx917 Soc Mode + - SiWx917 SoC / Common Flash Radio Board / 2.4GHz + - BRD4338A - B0 common flash v2.0 + +### Software Requirements + +**Simplicity Studio 5**: Download and install Simplicity Studio 5 for your operating system from the Silicon Labs [Simplicity Studio page](https://www.silabs.com/developers/simplicity-studio). While the installation process is easy to follow, instructions are provided in the Simplicity Studio v5 [Getting Started section](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-getting-started/install-ss-5-and-software). + +**Ozone - The J-Link Debugger**: [Ozone](https://www.segger.com/products/development-tools/ozone-j-link-debugger/) is a full-featured graphical debugger for embedded applications. With Ozone, it is possible to debug any embedded application on C/C++ source and assembly level. + +**Simplicity Commander**: [Simplicity Commander](/matter/{build-docspace-version}/matter-references/flash-silabs-device#simplicity-commander) is a utility that provides GUI and command line access to the debug features of an EFM32 device. It allows you to flash firmware, update the kit firmware, and lock or unlock debug access. + +**Tera Term**: [Tera Term](https://osdn.net/projects/ttssh2/releases/) is the terminal emulator for Microsoft Windows that supports serial port, telnet, and SSH connections. + +**Silicon Labs Matter SiSDK Extension**: Once Simplicity Studio 5 is installed, you will be prompted to install the Simplicity SDK, formerly released as Gecko SDK (GSDK). Here you should also install the Matter Enablement Package by making sure the extension is checked, as shown. + +![Installing the Matter Extension](./resources/install-package-advanced-device.png) + +**Installation of Wi-Fi SDK and WiSeConnect Packages**: The following packages will be installed during the installation of Simplicity Studio. Refer to [Package Installation](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation). + +**Matter Hub Raspberry Pi Image**: A copy of the pre-built image from the Silicon Labs web services can be downloaded in this [zipfile](https://www.silabs.com/documents/public/software/SilabsMatterPi_2.5.0-1.4-extension.zip). **Note** this is a large file and will take some time to download. + +>**Note:** The Matter hub for Matter over Thread requires an additional device, a radio co-processor. See [the introduction to the Matter over Thread demo](/matter/{build-docspace-version}/matter-light-switch-example/02-thread-light-switch-example) for more information. + +**Matter Bootloader Image**: The EFR32MG24 devices must be programmed with a bootloader. Obtain those here: [Silicon Labs Matter Artifacts](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). + +**SSH Client**: Managing the Matter hub often requires connecting to it remotely. An SSH client is needed to follow the step-by-step example in this document (PuTTY is used). Install software such as [PuTTY](https://www.putty.org/), Terminal, or a similar application for access to the Raspberry Pi-based Matter hub. + +**SD Card-Flashing Software**: Many different applications can be used to prepare an SD card for the Raspberry Pi, such as the [Raspberry Pi Imager](https://www.raspberrypi.com/documentation/computers/getting-started.html#install-using-imager) and [balenaEtcher](https://www.balena.io/etcher). The step-by-step example in this document uses the Raspberry Pi Imager. + +### Visual Studio Code Development + +In addition to creating and building your Matter project within Simplicity Studio, Silicon Labs also provides Visual Studio Code (VSCode) IDE integration. + +For more information on development within Visual Studio Code, please visit [Visual Studio Code Enablement](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-vscode-ide/). + +## Next Steps + +Now that your environment is set up, you can proceed to the create a [Matter over Wi-Fi Quick-Start demo](/matter/{build-docspace-version}/matter-quick-start-demo/01-wifi-quick-start-demo) or a [Matter over Thread Quick-Start demo](/matter/{build-docspace-version}/matter-quick-start-demo/02-thread-quick-start-demo). diff --git a/sld247-matter-overview/resources/install-package-advanced-device.png b/sld247-matter-overview/resources/install-package-advanced-device.png new file mode 100644 index 0000000..ffbfdd2 Binary files /dev/null and b/sld247-matter-overview/resources/install-package-advanced-device.png differ diff --git a/sld248-matter-overview-guides/code-size-savings.md b/sld248-matter-overview-guides/code-size-savings.md new file mode 100644 index 0000000..69c668e --- /dev/null +++ b/sld248-matter-overview-guides/code-size-savings.md @@ -0,0 +1,19 @@ +# Code Savings Guide for Building Matter Applications + +Silicon Labs' Matter example applications come out of the box with various ease-of-life components allowing for a smoother development process (LCD functionality, debugging capability, Matter shell, etc). These components bring along with them some increase in the size of resulting application's image. + +To reduce the total size of your application's image while still maintaining basic core Matter functionality, you can take a few steps: + +1. Remove optional components in from the Matter Project in Studio that may not be needed for a certain application. For example, removing the components Matter Display and Matter QR Code Display will save flash by disabling the LCD screen. +2. Remove any excess printing from the application. In practice, this can include removing the Matter Shell component and RTT Logging from the Matter device. +3. Install the `matter_no_debug` and/or `matter_no_lcd_shell` components. This will automatically take care of removing these extra features (`matter_no_lcd_shell`) as well as implement the defines and configuration values (`matter_no_debug`) to achieve optimal image size reduction at the click of a button. +4. Remove clusters from the zap configuration. Example applications have clusters enabled to support both Thread and Wi-Fi transport layers such as the Diagnostics clusters. It is important to note that certain device types require different Matter Clusters. Be sure to check the [Matter Specifications](https://csa-iot.org/developer-resource/specifications-download-request/) to confirm which Matter Clusters are required for your device type. +5. Install the `Enable Link time optimization` (LTO) component. This will allow the compiler to optimize the code better by removing unused functions and variables. Currently, this component is not visible by default in the SLCP file as it is tagged as Evaluation. To enable this component, ensure that the **Evaluation** filter is enabled by selecting it in the **Quality** dropdown menu as shown below. + + ![LTO Plugin](images/slcp-quality-drop-menu.png) + + Once this is toggled on, simply enter *gcc* in the keyword search, and you will find **Enable Link time optimization** under **Platform > Toolchain**. + + ![LTO Plugin](images/gcc-lto-component.png) + + Once the component is installed, LTO will be leveraged by GCC to reduce the code size of the built application. diff --git a/sld248-matter-overview-guides/images/Add-sdk-path.png b/sld248-matter-overview-guides/images/Add-sdk-path.png new file mode 100644 index 0000000..1bea8b8 Binary files /dev/null and b/sld248-matter-overview-guides/images/Add-sdk-path.png differ diff --git a/sld248-matter-overview-guides/images/Add-sdk.png b/sld248-matter-overview-guides/images/Add-sdk.png new file mode 100644 index 0000000..076d8dc Binary files /dev/null and b/sld248-matter-overview-guides/images/Add-sdk.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-SoC-Kermit.png b/sld248-matter-overview-guides/images/SiWx917-SoC-Kermit.png new file mode 100644 index 0000000..be4bb15 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-SoC-Kermit.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-Preferences.png b/sld248-matter-overview-guides/images/SiWx917-soc-Preferences.png new file mode 100644 index 0000000..a20e8ba Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-Preferences.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-board-selection.png b/sld248-matter-overview-guides/images/SiWx917-soc-board-selection.png new file mode 100644 index 0000000..11a38cf Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-board-selection.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-build-wifi-project.png b/sld248-matter-overview-guides/images/SiWx917-soc-build-wifi-project.png new file mode 100644 index 0000000..4a26294 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-build-wifi-project.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-create-wifi-projects.png b/sld248-matter-overview-guides/images/SiWx917-soc-create-wifi-projects.png new file mode 100644 index 0000000..6ed9b39 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-create-wifi-projects.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-debug-adapter.png b/sld248-matter-overview-guides/images/SiWx917-soc-debug-adapter.png new file mode 100644 index 0000000..f3d3c35 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-debug-adapter.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-debug.png b/sld248-matter-overview-guides/images/SiWx917-soc-debug.png new file mode 100644 index 0000000..c52a698 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-debug.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-flash-program.png b/sld248-matter-overview-guides/images/SiWx917-soc-flash-program.png new file mode 100644 index 0000000..294a49c Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-flash-program.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-flash-todevice.png b/sld248-matter-overview-guides/images/SiWx917-soc-flash-todevice.png new file mode 100644 index 0000000..b495217 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-flash-todevice.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-install-manager.png b/sld248-matter-overview-guides/images/SiWx917-soc-install-manager.png new file mode 100644 index 0000000..e369fc9 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-install-manager.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-isp-binary-selection.png b/sld248-matter-overview-guides/images/SiWx917-soc-isp-binary-selection.png new file mode 100644 index 0000000..00edbe0 Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-isp-binary-selection.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-project-wizard.png b/sld248-matter-overview-guides/images/SiWx917-soc-project-wizard.png new file mode 100644 index 0000000..20d75ce Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-project-wizard.png differ diff --git a/sld248-matter-overview-guides/images/SiWx917-soc-slpb.png b/sld248-matter-overview-guides/images/SiWx917-soc-slpb.png new file mode 100644 index 0000000..4ed72bc Binary files /dev/null and b/sld248-matter-overview-guides/images/SiWx917-soc-slpb.png differ diff --git a/sld248-matter-overview-guides/images/address-encryption.png b/sld248-matter-overview-guides/images/address-encryption.png new file mode 100644 index 0000000..6f1f663 Binary files /dev/null and b/sld248-matter-overview-guides/images/address-encryption.png differ diff --git a/sld248-matter-overview-guides/images/all-products-selection.png b/sld248-matter-overview-guides/images/all-products-selection.png new file mode 100644 index 0000000..524db94 Binary files /dev/null and b/sld248-matter-overview-guides/images/all-products-selection.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-add-device.png b/sld248-matter-overview-guides/images/amazon-alexa-add-device.png new file mode 100644 index 0000000..3ec5dcc Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-add-device.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-app-added.png b/sld248-matter-overview-guides/images/amazon-alexa-app-added.png new file mode 100644 index 0000000..0f37a2d Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-app-added.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-app.png b/sld248-matter-overview-guides/images/amazon-alexa-app.png new file mode 100644 index 0000000..5ee6099 Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-app.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-application-added-to-group.png b/sld248-matter-overview-guides/images/amazon-alexa-application-added-to-group.png new file mode 100644 index 0000000..6e093db Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-application-added-to-group.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-device-selection.png b/sld248-matter-overview-guides/images/amazon-alexa-device-selection.png new file mode 100644 index 0000000..95bad3d Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-device-selection.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-logos.png b/sld248-matter-overview-guides/images/amazon-alexa-logos.png new file mode 100644 index 0000000..7178986 Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-logos.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-scan-qr-code.png b/sld248-matter-overview-guides/images/amazon-alexa-scan-qr-code.png new file mode 100644 index 0000000..a32ae7b Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-scan-qr-code.png differ diff --git a/sld248-matter-overview-guides/images/amazon-alexa-select-group.png b/sld248-matter-overview-guides/images/amazon-alexa-select-group.png new file mode 100644 index 0000000..48a8ff0 Binary files /dev/null and b/sld248-matter-overview-guides/images/amazon-alexa-select-group.png differ diff --git a/sld248-matter-overview-guides/images/apple-home-app-add-accessory.png b/sld248-matter-overview-guides/images/apple-home-app-add-accessory.png new file mode 100644 index 0000000..f9ecccf Binary files /dev/null and b/sld248-matter-overview-guides/images/apple-home-app-add-accessory.png differ diff --git a/sld248-matter-overview-guides/images/apple-home-app-scan-qr-code.png b/sld248-matter-overview-guides/images/apple-home-app-scan-qr-code.png new file mode 100644 index 0000000..803c157 Binary files /dev/null and b/sld248-matter-overview-guides/images/apple-home-app-scan-qr-code.png differ diff --git a/sld248-matter-overview-guides/images/apple-home-app.png b/sld248-matter-overview-guides/images/apple-home-app.png new file mode 100644 index 0000000..19e612f Binary files /dev/null and b/sld248-matter-overview-guides/images/apple-home-app.png differ diff --git a/sld248-matter-overview-guides/images/application-upload-erase-flash.png b/sld248-matter-overview-guides/images/application-upload-erase-flash.png new file mode 100644 index 0000000..4d01d17 Binary files /dev/null and b/sld248-matter-overview-guides/images/application-upload-erase-flash.png differ diff --git a/sld248-matter-overview-guides/images/attestation-overview.png b/sld248-matter-overview-guides/images/attestation-overview.png new file mode 100644 index 0000000..a0b069c Binary files /dev/null and b/sld248-matter-overview-guides/images/attestation-overview.png differ diff --git a/sld248-matter-overview-guides/images/certificate-authentication.png b/sld248-matter-overview-guides/images/certificate-authentication.png new file mode 100644 index 0000000..680ddd6 Binary files /dev/null and b/sld248-matter-overview-guides/images/certificate-authentication.png differ diff --git a/sld248-matter-overview-guides/images/click-add-extensions.png b/sld248-matter-overview-guides/images/click-add-extensions.png new file mode 100644 index 0000000..98814c1 Binary files /dev/null and b/sld248-matter-overview-guides/images/click-add-extensions.png differ diff --git a/sld248-matter-overview-guides/images/click-browse.png b/sld248-matter-overview-guides/images/click-browse.png new file mode 100644 index 0000000..77d7d96 Binary files /dev/null and b/sld248-matter-overview-guides/images/click-browse.png differ diff --git a/sld248-matter-overview-guides/images/click-manage-sdks-efx-board.png b/sld248-matter-overview-guides/images/click-manage-sdks-efx-board.png new file mode 100644 index 0000000..fe79adc Binary files /dev/null and b/sld248-matter-overview-guides/images/click-manage-sdks-efx-board.png differ diff --git a/sld248-matter-overview-guides/images/commander-click-flash-button.png b/sld248-matter-overview-guides/images/commander-click-flash-button.png new file mode 100644 index 0000000..7d7db33 Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-click-flash-button.png differ diff --git a/sld248-matter-overview-guides/images/commander-flash-map.png b/sld248-matter-overview-guides/images/commander-flash-map.png new file mode 100644 index 0000000..796a56b Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-flash-map.png differ diff --git a/sld248-matter-overview-guides/images/commander-flash-success-efr32.png b/sld248-matter-overview-guides/images/commander-flash-success-efr32.png new file mode 100644 index 0000000..421e97f Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-flash-success-efr32.png differ diff --git a/sld248-matter-overview-guides/images/commander-flash-success-soc.png b/sld248-matter-overview-guides/images/commander-flash-success-soc.png new file mode 100644 index 0000000..a0a3d7e Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-flash-success-soc.png differ diff --git a/sld248-matter-overview-guides/images/commander-flash-success.png b/sld248-matter-overview-guides/images/commander-flash-success.png new file mode 100644 index 0000000..3737fda Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-flash-success.png differ diff --git a/sld248-matter-overview-guides/images/commander-select-board.png b/sld248-matter-overview-guides/images/commander-select-board.png new file mode 100644 index 0000000..50c50ba Binary files /dev/null and b/sld248-matter-overview-guides/images/commander-select-board.png differ diff --git a/sld248-matter-overview-guides/images/commissioning-overview.png b/sld248-matter-overview-guides/images/commissioning-overview.png new file mode 100644 index 0000000..e325a3e Binary files /dev/null and b/sld248-matter-overview-guides/images/commissioning-overview.png differ diff --git a/sld248-matter-overview-guides/images/commissioning-steps1-4.png b/sld248-matter-overview-guides/images/commissioning-steps1-4.png new file mode 100644 index 0000000..0cce7f8 Binary files /dev/null and b/sld248-matter-overview-guides/images/commissioning-steps1-4.png differ diff --git a/sld248-matter-overview-guides/images/commissioning-steps5-7.png b/sld248-matter-overview-guides/images/commissioning-steps5-7.png new file mode 100644 index 0000000..a144df5 Binary files /dev/null and b/sld248-matter-overview-guides/images/commissioning-steps5-7.png differ diff --git a/sld248-matter-overview-guides/images/commissioning-steps8-10.png b/sld248-matter-overview-guides/images/commissioning-steps8-10.png new file mode 100644 index 0000000..89db9ee Binary files /dev/null and b/sld248-matter-overview-guides/images/commissioning-steps8-10.png differ diff --git a/sld248-matter-overview-guides/images/control-device-through-cloud.png b/sld248-matter-overview-guides/images/control-device-through-cloud.png new file mode 100644 index 0000000..cb81e04 Binary files /dev/null and b/sld248-matter-overview-guides/images/control-device-through-cloud.png differ diff --git a/sld248-matter-overview-guides/images/create-project-click-finish.png b/sld248-matter-overview-guides/images/create-project-click-finish.png new file mode 100644 index 0000000..c69fe79 Binary files /dev/null and b/sld248-matter-overview-guides/images/create-project-click-finish.png differ diff --git a/sld248-matter-overview-guides/images/create-project-lock-click-finish.png b/sld248-matter-overview-guides/images/create-project-lock-click-finish.png new file mode 100644 index 0000000..032fd5d Binary files /dev/null and b/sld248-matter-overview-guides/images/create-project-lock-click-finish.png differ diff --git a/sld248-matter-overview-guides/images/create-project-select-efx-example.png b/sld248-matter-overview-guides/images/create-project-select-efx-example.png new file mode 100644 index 0000000..5a85abb Binary files /dev/null and b/sld248-matter-overview-guides/images/create-project-select-efx-example.png differ diff --git a/sld248-matter-overview-guides/images/create-project-select-efx-lock-example.png b/sld248-matter-overview-guides/images/create-project-select-efx-lock-example.png new file mode 100644 index 0000000..9d31f33 Binary files /dev/null and b/sld248-matter-overview-guides/images/create-project-select-efx-lock-example.png differ diff --git a/sld248-matter-overview-guides/images/create-project-verify-efx-general-information.png b/sld248-matter-overview-guides/images/create-project-verify-efx-general-information.png new file mode 100644 index 0000000..33806aa Binary files /dev/null and b/sld248-matter-overview-guides/images/create-project-verify-efx-general-information.png differ diff --git a/sld248-matter-overview-guides/images/dcl-overview.png b/sld248-matter-overview-guides/images/dcl-overview.png new file mode 100644 index 0000000..05989dc Binary files /dev/null and b/sld248-matter-overview-guides/images/dcl-overview.png differ diff --git a/sld248-matter-overview-guides/images/debug-application-debug-options.png b/sld248-matter-overview-guides/images/debug-application-debug-options.png new file mode 100644 index 0000000..111ccba Binary files /dev/null and b/sld248-matter-overview-guides/images/debug-application-debug-options.png differ diff --git a/sld248-matter-overview-guides/images/debug-application-switch-to-debug-mode.png b/sld248-matter-overview-guides/images/debug-application-switch-to-debug-mode.png new file mode 100644 index 0000000..d96a030 Binary files /dev/null and b/sld248-matter-overview-guides/images/debug-application-switch-to-debug-mode.png differ diff --git a/sld248-matter-overview-guides/images/device-configuration.png b/sld248-matter-overview-guides/images/device-configuration.png new file mode 100644 index 0000000..7e70184 Binary files /dev/null and b/sld248-matter-overview-guides/images/device-configuration.png differ diff --git a/sld248-matter-overview-guides/images/dic-aws-ota.png b/sld248-matter-overview-guides/images/dic-aws-ota.png new file mode 100644 index 0000000..418ae23 Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-aws-ota.png differ diff --git a/sld248-matter-overview-guides/images/dic-control-part.png b/sld248-matter-overview-guides/images/dic-control-part.png new file mode 100644 index 0000000..8cfe46e Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-control-part.png differ diff --git a/sld248-matter-overview-guides/images/dic-extension-refresh-1.png b/sld248-matter-overview-guides/images/dic-extension-refresh-1.png new file mode 100644 index 0000000..56c5827 Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-extension-refresh-1.png differ diff --git a/sld248-matter-overview-guides/images/dic-extension-refresh.png b/sld248-matter-overview-guides/images/dic-extension-refresh.png new file mode 100644 index 0000000..7abdd9f Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-extension-refresh.png differ diff --git a/sld248-matter-overview-guides/images/dic-flow.png b/sld248-matter-overview-guides/images/dic-flow.png new file mode 100644 index 0000000..6624cd1 Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-flow.png differ diff --git a/sld248-matter-overview-guides/images/dic-status-sharing.png b/sld248-matter-overview-guides/images/dic-status-sharing.png new file mode 100644 index 0000000..037e931 Binary files /dev/null and b/sld248-matter-overview-guides/images/dic-status-sharing.png differ diff --git a/sld248-matter-overview-guides/images/download-aws-ota-through-cloud.png b/sld248-matter-overview-guides/images/download-aws-ota-through-cloud.png new file mode 100644 index 0000000..b4dd68b Binary files /dev/null and b/sld248-matter-overview-guides/images/download-aws-ota-through-cloud.png differ diff --git a/sld248-matter-overview-guides/images/export-path-for-cli-build.png b/sld248-matter-overview-guides/images/export-path-for-cli-build.png new file mode 100644 index 0000000..402e27a Binary files /dev/null and b/sld248-matter-overview-guides/images/export-path-for-cli-build.png differ diff --git a/sld248-matter-overview-guides/images/flash-binary-to-efx32-device.png b/sld248-matter-overview-guides/images/flash-binary-to-efx32-device.png new file mode 100644 index 0000000..70cad72 Binary files /dev/null and b/sld248-matter-overview-guides/images/flash-binary-to-efx32-device.png differ diff --git a/sld248-matter-overview-guides/images/flows-data-to-matter-devices.png b/sld248-matter-overview-guides/images/flows-data-to-matter-devices.png new file mode 100644 index 0000000..1d64cf8 Binary files /dev/null and b/sld248-matter-overview-guides/images/flows-data-to-matter-devices.png differ diff --git a/sld248-matter-overview-guides/images/gcc-lto-component.png b/sld248-matter-overview-guides/images/gcc-lto-component.png new file mode 100644 index 0000000..63ca203 Binary files /dev/null and b/sld248-matter-overview-guides/images/gcc-lto-component.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-account-prompt.png b/sld248-matter-overview-guides/images/google-home-app-account-prompt.png new file mode 100644 index 0000000..3865dc9 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-account-prompt.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-add-device.png b/sld248-matter-overview-guides/images/google-home-app-add-device.png new file mode 100644 index 0000000..b5db28e Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-add-device.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-connected.png b/sld248-matter-overview-guides/images/google-home-app-connected.png new file mode 100644 index 0000000..024c4f8 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-connected.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-connecting.png b/sld248-matter-overview-guides/images/google-home-app-connecting.png new file mode 100644 index 0000000..10fc8b1 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-connecting.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-give-app-name.png b/sld248-matter-overview-guides/images/google-home-app-give-app-name.png new file mode 100644 index 0000000..007422b Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-give-app-name.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-light-added.png b/sld248-matter-overview-guides/images/google-home-app-light-added.png new file mode 100644 index 0000000..79b15c6 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-light-added.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-looking-for-device.png b/sld248-matter-overview-guides/images/google-home-app-looking-for-device.png new file mode 100644 index 0000000..6eab34c Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-looking-for-device.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-matter-enabled-device.png b/sld248-matter-overview-guides/images/google-home-app-matter-enabled-device.png new file mode 100644 index 0000000..d5b5ec5 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-matter-enabled-device.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-new-device.png b/sld248-matter-overview-guides/images/google-home-app-new-device.png new file mode 100644 index 0000000..0c23da3 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-new-device.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-select-home.png b/sld248-matter-overview-guides/images/google-home-app-select-home.png new file mode 100644 index 0000000..327af88 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-select-home.png differ diff --git a/sld248-matter-overview-guides/images/google-home-app-select-room.png b/sld248-matter-overview-guides/images/google-home-app-select-room.png new file mode 100644 index 0000000..a5ebc44 Binary files /dev/null and b/sld248-matter-overview-guides/images/google-home-app-select-room.png differ diff --git a/sld248-matter-overview-guides/images/icd-config.png b/sld248-matter-overview-guides/images/icd-config.png new file mode 100644 index 0000000..eb4724e Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-config.png differ diff --git a/sld248-matter-overview-guides/images/icd-enable-icd-cluster.png b/sld248-matter-overview-guides/images/icd-enable-icd-cluster.png new file mode 100644 index 0000000..6e7fd89 Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-enable-icd-cluster.png differ diff --git a/sld248-matter-overview-guides/images/icd-install-icd-component.png b/sld248-matter-overview-guides/images/icd-install-icd-component.png new file mode 100644 index 0000000..278b959 Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-install-icd-component.png differ diff --git a/sld248-matter-overview-guides/images/icd-install-low-power.png b/sld248-matter-overview-guides/images/icd-install-low-power.png new file mode 100644 index 0000000..4e664ff Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-install-low-power.png differ diff --git a/sld248-matter-overview-guides/images/icd-open-zap.png b/sld248-matter-overview-guides/images/icd-open-zap.png new file mode 100644 index 0000000..8729077 Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-open-zap.png differ diff --git a/sld248-matter-overview-guides/images/icd-project-generation.png b/sld248-matter-overview-guides/images/icd-project-generation.png new file mode 100644 index 0000000..0ac7b24 Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-project-generation.png differ diff --git a/sld248-matter-overview-guides/images/icd-resolve-conflicts.png b/sld248-matter-overview-guides/images/icd-resolve-conflicts.png new file mode 100644 index 0000000..80befdb Binary files /dev/null and b/sld248-matter-overview-guides/images/icd-resolve-conflicts.png differ diff --git a/sld248-matter-overview-guides/images/install-credentials-component.png b/sld248-matter-overview-guides/images/install-credentials-component.png new file mode 100644 index 0000000..c18ce24 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-credentials-component.png differ diff --git a/sld248-matter-overview-guides/images/install-gecko-sdk-step-1.png b/sld248-matter-overview-guides/images/install-gecko-sdk-step-1.png new file mode 100644 index 0000000..bf46002 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-gecko-sdk-step-1.png differ diff --git a/sld248-matter-overview-guides/images/install-gecko-sdk-step-2.png b/sld248-matter-overview-guides/images/install-gecko-sdk-step-2.png new file mode 100644 index 0000000..7205bb1 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-gecko-sdk-step-2.png differ diff --git a/sld248-matter-overview-guides/images/install-gecko-sdk-step-3.png b/sld248-matter-overview-guides/images/install-gecko-sdk-step-3.png new file mode 100644 index 0000000..d948cb4 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-gecko-sdk-step-3.png differ diff --git a/sld248-matter-overview-guides/images/install-wc3-ext-add-sdk-extensions-window.png b/sld248-matter-overview-guides/images/install-wc3-ext-add-sdk-extensions-window.png new file mode 100644 index 0000000..f43b37c Binary files /dev/null and b/sld248-matter-overview-guides/images/install-wc3-ext-add-sdk-extensions-window.png differ diff --git a/sld248-matter-overview-guides/images/install-wiseconnect-3-ext-manage-sdks-trust-popup.png b/sld248-matter-overview-guides/images/install-wiseconnect-3-ext-manage-sdks-trust-popup.png new file mode 100644 index 0000000..b0415d1 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-wiseconnect-3-ext-manage-sdks-trust-popup.png differ diff --git a/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-1.png b/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-1.png new file mode 100644 index 0000000..bf46002 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-1.png differ diff --git a/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-2.png b/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-2.png new file mode 100644 index 0000000..58b8858 Binary files /dev/null and b/sld248-matter-overview-guides/images/install-wiseconnect-sdk-step-2.png differ diff --git a/sld248-matter-overview-guides/images/internal-flash-layout.png b/sld248-matter-overview-guides/images/internal-flash-layout.png new file mode 100644 index 0000000..138c6de Binary files /dev/null and b/sld248-matter-overview-guides/images/internal-flash-layout.png differ diff --git a/sld248-matter-overview-guides/images/lighting-over-thread-example.png b/sld248-matter-overview-guides/images/lighting-over-thread-example.png new file mode 100644 index 0000000..981e4d3 Binary files /dev/null and b/sld248-matter-overview-guides/images/lighting-over-thread-example.png differ diff --git a/sld248-matter-overview-guides/images/matter-apple-application-info.png b/sld248-matter-overview-guides/images/matter-apple-application-info.png new file mode 100644 index 0000000..de94808 Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-apple-application-info.png differ diff --git a/sld248-matter-overview-guides/images/matter-apple-application-setup-code.png b/sld248-matter-overview-guides/images/matter-apple-application-setup-code.png new file mode 100644 index 0000000..71ba02f Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-apple-application-setup-code.png differ diff --git a/sld248-matter-overview-guides/images/matter-google-add-setup-code.png b/sld248-matter-overview-guides/images/matter-google-add-setup-code.png new file mode 100644 index 0000000..121653a Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-google-add-setup-code.png differ diff --git a/sld248-matter-overview-guides/images/matter-rtt-qr-code-link.png b/sld248-matter-overview-guides/images/matter-rtt-qr-code-link.png new file mode 100644 index 0000000..2044b49 Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-rtt-qr-code-link.png differ diff --git a/sld248-matter-overview-guides/images/matter-shell-command-send.png b/sld248-matter-overview-guides/images/matter-shell-command-send.png new file mode 100644 index 0000000..51ac327 Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-shell-command-send.png differ diff --git a/sld248-matter-overview-guides/images/matter-shell-enable.png b/sld248-matter-overview-guides/images/matter-shell-enable.png new file mode 100644 index 0000000..7ef6d66 Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-shell-enable.png differ diff --git a/sld248-matter-overview-guides/images/memory-footprint-report.png b/sld248-matter-overview-guides/images/memory-footprint-report.png new file mode 100644 index 0000000..152b4ca Binary files /dev/null and b/sld248-matter-overview-guides/images/memory-footprint-report.png differ diff --git a/sld248-matter-overview-guides/images/memory-usage-report.png b/sld248-matter-overview-guides/images/memory-usage-report.png new file mode 100644 index 0000000..2677788 Binary files /dev/null and b/sld248-matter-overview-guides/images/memory-usage-report.png differ diff --git a/sld248-matter-overview-guides/images/mg12-wf200.jpg b/sld248-matter-overview-guides/images/mg12-wf200.jpg new file mode 100644 index 0000000..db1c0b5 Binary files /dev/null and b/sld248-matter-overview-guides/images/mg12-wf200.jpg differ diff --git a/sld248-matter-overview-guides/images/mg21-si917-board.jpg b/sld248-matter-overview-guides/images/mg21-si917-board.jpg new file mode 100644 index 0000000..b510054 Binary files /dev/null and b/sld248-matter-overview-guides/images/mg21-si917-board.jpg differ diff --git a/sld248-matter-overview-guides/images/mount-efr32.png b/sld248-matter-overview-guides/images/mount-efr32.png new file mode 100644 index 0000000..881ae46 Binary files /dev/null and b/sld248-matter-overview-guides/images/mount-efr32.png differ diff --git a/sld248-matter-overview-guides/images/mount-expansion.png b/sld248-matter-overview-guides/images/mount-expansion.png new file mode 100644 index 0000000..f498308 Binary files /dev/null and b/sld248-matter-overview-guides/images/mount-expansion.png differ diff --git a/sld248-matter-overview-guides/images/mount-soc.png b/sld248-matter-overview-guides/images/mount-soc.png new file mode 100644 index 0000000..dba2402 Binary files /dev/null and b/sld248-matter-overview-guides/images/mount-soc.png differ diff --git a/sld248-matter-overview-guides/images/mqtt-explorer-1.png b/sld248-matter-overview-guides/images/mqtt-explorer-1.png new file mode 100644 index 0000000..ac0bcaf Binary files /dev/null and b/sld248-matter-overview-guides/images/mqtt-explorer-1.png differ diff --git a/sld248-matter-overview-guides/images/mqtt-explorer-2.png b/sld248-matter-overview-guides/images/mqtt-explorer-2.png new file mode 100644 index 0000000..770828f Binary files /dev/null and b/sld248-matter-overview-guides/images/mqtt-explorer-2.png differ diff --git a/sld248-matter-overview-guides/images/mqtt-explorer-3.png b/sld248-matter-overview-guides/images/mqtt-explorer-3.png new file mode 100644 index 0000000..3f94c4a Binary files /dev/null and b/sld248-matter-overview-guides/images/mqtt-explorer-3.png differ diff --git a/sld248-matter-overview-guides/images/mqtt-explorer-4.png b/sld248-matter-overview-guides/images/mqtt-explorer-4.png new file mode 100644 index 0000000..b934d08 Binary files /dev/null and b/sld248-matter-overview-guides/images/mqtt-explorer-4.png differ diff --git a/sld248-matter-overview-guides/images/mqtt-explorer-5.png b/sld248-matter-overview-guides/images/mqtt-explorer-5.png new file mode 100644 index 0000000..ac317ba Binary files /dev/null and b/sld248-matter-overview-guides/images/mqtt-explorer-5.png differ diff --git a/sld248-matter-overview-guides/images/optimize-lcd-sleepy.png b/sld248-matter-overview-guides/images/optimize-lcd-sleepy.png new file mode 100644 index 0000000..3378f6c Binary files /dev/null and b/sld248-matter-overview-guides/images/optimize-lcd-sleepy.png differ diff --git a/sld248-matter-overview-guides/images/overview-tab-efx32.png b/sld248-matter-overview-guides/images/overview-tab-efx32.png new file mode 100644 index 0000000..5554b39 Binary files /dev/null and b/sld248-matter-overview-guides/images/overview-tab-efx32.png differ diff --git a/sld248-matter-overview-guides/images/payload-encryption.png b/sld248-matter-overview-guides/images/payload-encryption.png new file mode 100644 index 0000000..fc5900c Binary files /dev/null and b/sld248-matter-overview-guides/images/payload-encryption.png differ diff --git a/sld248-matter-overview-guides/images/project-created-efx32.png b/sld248-matter-overview-guides/images/project-created-efx32.png new file mode 100644 index 0000000..884ce5c Binary files /dev/null and b/sld248-matter-overview-guides/images/project-created-efx32.png differ diff --git a/sld248-matter-overview-guides/images/samsung-app-add-device.png b/sld248-matter-overview-guides/images/samsung-app-add-device.png new file mode 100644 index 0000000..791a312 Binary files /dev/null and b/sld248-matter-overview-guides/images/samsung-app-add-device.png differ diff --git a/sld248-matter-overview-guides/images/samsung-app-commissioning.png b/sld248-matter-overview-guides/images/samsung-app-commissioning.png new file mode 100644 index 0000000..d9e8ffe Binary files /dev/null and b/sld248-matter-overview-guides/images/samsung-app-commissioning.png differ diff --git a/sld248-matter-overview-guides/images/samsung-app-select-partner.png b/sld248-matter-overview-guides/images/samsung-app-select-partner.png new file mode 100644 index 0000000..5acacca Binary files /dev/null and b/sld248-matter-overview-guides/images/samsung-app-select-partner.png differ diff --git a/sld248-matter-overview-guides/images/samsung-light-added.png b/sld248-matter-overview-guides/images/samsung-light-added.png new file mode 100644 index 0000000..06d027c Binary files /dev/null and b/sld248-matter-overview-guides/images/samsung-light-added.png differ diff --git a/sld248-matter-overview-guides/images/samsung-register-device.png b/sld248-matter-overview-guides/images/samsung-register-device.png new file mode 100644 index 0000000..e113a95 Binary files /dev/null and b/sld248-matter-overview-guides/images/samsung-register-device.png differ diff --git a/sld248-matter-overview-guides/images/sd-into-pi.png b/sld248-matter-overview-guides/images/sd-into-pi.png new file mode 100644 index 0000000..dfe023c Binary files /dev/null and b/sld248-matter-overview-guides/images/sd-into-pi.png differ diff --git a/sld248-matter-overview-guides/images/select-binary-to-flash-efx32.png b/sld248-matter-overview-guides/images/select-binary-to-flash-efx32.png new file mode 100644 index 0000000..9940b33 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-binary-to-flash-efx32.png differ diff --git a/sld248-matter-overview-guides/images/select-commander.png b/sld248-matter-overview-guides/images/select-commander.png new file mode 100644 index 0000000..52cd10f Binary files /dev/null and b/sld248-matter-overview-guides/images/select-commander.png differ diff --git a/sld248-matter-overview-guides/images/select-efx-board.png b/sld248-matter-overview-guides/images/select-efx-board.png new file mode 100644 index 0000000..8e11766 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-efx-board.png differ diff --git a/sld248-matter-overview-guides/images/select-flash-option-efr32-commander.png b/sld248-matter-overview-guides/images/select-flash-option-efr32-commander.png new file mode 100644 index 0000000..8659720 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-flash-option-efr32-commander.png differ diff --git a/sld248-matter-overview-guides/images/select-flash-option-in-commander.png b/sld248-matter-overview-guides/images/select-flash-option-in-commander.png new file mode 100644 index 0000000..df3e151 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-flash-option-in-commander.png differ diff --git a/sld248-matter-overview-guides/images/select-flash-option-soc-commander.png b/sld248-matter-overview-guides/images/select-flash-option-soc-commander.png new file mode 100644 index 0000000..5d954b9 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-flash-option-soc-commander.png differ diff --git a/sld248-matter-overview-guides/images/select-jlink-rtt-logging.png b/sld248-matter-overview-guides/images/select-jlink-rtt-logging.png new file mode 100644 index 0000000..3fc54c6 Binary files /dev/null and b/sld248-matter-overview-guides/images/select-jlink-rtt-logging.png differ diff --git a/sld248-matter-overview-guides/images/selected-gsdk.png b/sld248-matter-overview-guides/images/selected-gsdk.png new file mode 100644 index 0000000..d40c9d3 Binary files /dev/null and b/sld248-matter-overview-guides/images/selected-gsdk.png differ diff --git a/sld248-matter-overview-guides/images/selected-sdk.png b/sld248-matter-overview-guides/images/selected-sdk.png new file mode 100644 index 0000000..3b7e723 Binary files /dev/null and b/sld248-matter-overview-guides/images/selected-sdk.png differ diff --git a/sld248-matter-overview-guides/images/shell-ttl-cable-soc.png b/sld248-matter-overview-guides/images/shell-ttl-cable-soc.png new file mode 100644 index 0000000..9308a9b Binary files /dev/null and b/sld248-matter-overview-guides/images/shell-ttl-cable-soc.png differ diff --git a/sld248-matter-overview-guides/images/si917-board.png b/sld248-matter-overview-guides/images/si917-board.png new file mode 100644 index 0000000..cac1701 Binary files /dev/null and b/sld248-matter-overview-guides/images/si917-board.png differ diff --git a/sld248-matter-overview-guides/images/simplicity-commander-flash-bootloader.png b/sld248-matter-overview-guides/images/simplicity-commander-flash-bootloader.png new file mode 100644 index 0000000..a79a8c9 Binary files /dev/null and b/sld248-matter-overview-guides/images/simplicity-commander-flash-bootloader.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-ncp-powermeasurement-pins.png b/sld248-matter-overview-guides/images/siwx917-ncp-powermeasurement-pins.png new file mode 100644 index 0000000..24cf76d Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-ncp-powermeasurement-pins.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-radio-wstk.png b/sld248-matter-overview-guides/images/siwx917-radio-wstk.png new file mode 100644 index 0000000..52c10c5 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-radio-wstk.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-soc-fwflash-option.png b/sld248-matter-overview-guides/images/siwx917-soc-fwflash-option.png new file mode 100644 index 0000000..5962cd4 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-soc-fwflash-option.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-soc-launcher-tab.png b/sld248-matter-overview-guides/images/siwx917-soc-launcher-tab.png new file mode 100644 index 0000000..d7cea55 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-soc-launcher-tab.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-soc-radio-board.png b/sld248-matter-overview-guides/images/siwx917-soc-radio-board.png new file mode 100644 index 0000000..82be950 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-soc-radio-board.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-soc-targetconnectionlost.png b/sld248-matter-overview-guides/images/siwx917-soc-targetconnectionlost.png new file mode 100644 index 0000000..44147b4 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-soc-targetconnectionlost.png differ diff --git a/sld248-matter-overview-guides/images/siwx917-target-ozone.png b/sld248-matter-overview-guides/images/siwx917-target-ozone.png new file mode 100644 index 0000000..aecc952 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917-target-ozone.png differ diff --git a/sld248-matter-overview-guides/images/siwx917soc-attachtorunningprogram.png b/sld248-matter-overview-guides/images/siwx917soc-attachtorunningprogram.png new file mode 100644 index 0000000..ff0ca23 Binary files /dev/null and b/sld248-matter-overview-guides/images/siwx917soc-attachtorunningprogram.png differ diff --git a/sld248-matter-overview-guides/images/slcp-quality-drop-menu.png b/sld248-matter-overview-guides/images/slcp-quality-drop-menu.png new file mode 100644 index 0000000..3978d9d Binary files /dev/null and b/sld248-matter-overview-guides/images/slcp-quality-drop-menu.png differ diff --git a/sld248-matter-overview-guides/images/solution-artifacts.png b/sld248-matter-overview-guides/images/solution-artifacts.png new file mode 100644 index 0000000..581c4bc Binary files /dev/null and b/sld248-matter-overview-guides/images/solution-artifacts.png differ diff --git a/sld248-matter-overview-guides/images/solution-generation.png b/sld248-matter-overview-guides/images/solution-generation.png new file mode 100644 index 0000000..c4faeb7 Binary files /dev/null and b/sld248-matter-overview-guides/images/solution-generation.png differ diff --git a/sld248-matter-overview-guides/images/status-shared-to-cloud.png b/sld248-matter-overview-guides/images/status-shared-to-cloud.png new file mode 100644 index 0000000..8201eae Binary files /dev/null and b/sld248-matter-overview-guides/images/status-shared-to-cloud.png differ diff --git a/sld248-matter-overview-guides/images/studio-project.png b/sld248-matter-overview-guides/images/studio-project.png new file mode 100644 index 0000000..fe28dcd Binary files /dev/null and b/sld248-matter-overview-guides/images/studio-project.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-matter-cli.png b/sld248-matter-overview-guides/images/tera-term-matter-cli.png new file mode 100644 index 0000000..4c0119c Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-matter-cli.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-select-jlink-port.png b/sld248-matter-overview-guides/images/tera-term-select-jlink-port.png new file mode 100644 index 0000000..ace6b7d Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-select-jlink-port.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-select-serial-port.png b/sld248-matter-overview-guides/images/tera-term-select-serial-port.png new file mode 100644 index 0000000..6910ce0 Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-select-serial-port.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-select-speed.png b/sld248-matter-overview-guides/images/tera-term-select-speed.png new file mode 100644 index 0000000..f7573a8 Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-select-speed.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-selection-in-terminal.png b/sld248-matter-overview-guides/images/tera-term-selection-in-terminal.png new file mode 100644 index 0000000..c622034 Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-selection-in-terminal.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-terminal-setup.png b/sld248-matter-overview-guides/images/tera-term-terminal-setup.png new file mode 100644 index 0000000..9af5b8c Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-terminal-setup.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-tty-record.png b/sld248-matter-overview-guides/images/tera-term-tty-record.png new file mode 100644 index 0000000..6a95f59 Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-tty-record.png differ diff --git a/sld248-matter-overview-guides/images/tera-term-uart-logging.png b/sld248-matter-overview-guides/images/tera-term-uart-logging.png new file mode 100644 index 0000000..eb56c8e Binary files /dev/null and b/sld248-matter-overview-guides/images/tera-term-uart-logging.png differ diff --git a/sld248-matter-overview-guides/images/thread-overview.png b/sld248-matter-overview-guides/images/thread-overview.png new file mode 100644 index 0000000..c20a9c5 Binary files /dev/null and b/sld248-matter-overview-guides/images/thread-overview.png differ diff --git a/sld248-matter-overview-guides/images/wifi-9116-gpio-connections.png b/sld248-matter-overview-guides/images/wifi-9116-gpio-connections.png new file mode 100644 index 0000000..9907009 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-9116-gpio-connections.png differ diff --git a/sld248-matter-overview-guides/images/wifi-9116-powermeter-wifimodule.png b/sld248-matter-overview-guides/images/wifi-9116-powermeter-wifimodule.png new file mode 100644 index 0000000..6becba3 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-9116-powermeter-wifimodule.png differ diff --git a/sld248-matter-overview-guides/images/wifi-9116-powerprofiler.png b/sld248-matter-overview-guides/images/wifi-9116-powerprofiler.png new file mode 100644 index 0000000..0cfc4cf Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-9116-powerprofiler.png differ diff --git a/sld248-matter-overview-guides/images/wifi-code-edit.png b/sld248-matter-overview-guides/images/wifi-code-edit.png new file mode 100644 index 0000000..5670f3a Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-code-edit.png differ diff --git a/sld248-matter-overview-guides/images/wifi-efr-energy-profiler.png b/sld248-matter-overview-guides/images/wifi-efr-energy-profiler.png new file mode 100644 index 0000000..9782280 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-efr-energy-profiler.png differ diff --git a/sld248-matter-overview-guides/images/wifi-efr-power-energyprofiler.png b/sld248-matter-overview-guides/images/wifi-efr-power-energyprofiler.png new file mode 100644 index 0000000..c0003ec Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-efr-power-energyprofiler.png differ diff --git a/sld248-matter-overview-guides/images/wifi-expansion-board-power-pins.png b/sld248-matter-overview-guides/images/wifi-expansion-board-power-pins.png new file mode 100644 index 0000000..cf96a32 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-expansion-board-power-pins.png differ diff --git a/sld248-matter-overview-guides/images/wifi-powerprofiler-start.png b/sld248-matter-overview-guides/images/wifi-powerprofiler-start.png new file mode 100644 index 0000000..76500fd Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-powerprofiler-start.png differ diff --git a/sld248-matter-overview-guides/images/wifi-powerprofiler.png b/sld248-matter-overview-guides/images/wifi-powerprofiler.png new file mode 100644 index 0000000..860e3b2 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-powerprofiler.png differ diff --git a/sld248-matter-overview-guides/images/wifi-powersave-overview.png b/sld248-matter-overview-guides/images/wifi-powersave-overview.png new file mode 100644 index 0000000..5dbfeaf Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-powersave-overview.png differ diff --git a/sld248-matter-overview-guides/images/wifi-setup.png b/sld248-matter-overview-guides/images/wifi-setup.png new file mode 100644 index 0000000..4ca47f9 Binary files /dev/null and b/sld248-matter-overview-guides/images/wifi-setup.png differ diff --git a/sld248-matter-overview-guides/images/zap-attributes.png b/sld248-matter-overview-guides/images/zap-attributes.png new file mode 100644 index 0000000..07d1f9e Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-attributes.png differ diff --git a/sld248-matter-overview-guides/images/zap-commands.png b/sld248-matter-overview-guides/images/zap-commands.png new file mode 100644 index 0000000..6e7e959 Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-commands.png differ diff --git a/sld248-matter-overview-guides/images/zap-endpoint-1.png b/sld248-matter-overview-guides/images/zap-endpoint-1.png new file mode 100644 index 0000000..56d5513 Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-endpoint-1.png differ diff --git a/sld248-matter-overview-guides/images/zap-endpoint.png b/sld248-matter-overview-guides/images/zap-endpoint.png new file mode 100644 index 0000000..9f46e85 Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-endpoint.png differ diff --git a/sld248-matter-overview-guides/images/zap-intro.png b/sld248-matter-overview-guides/images/zap-intro.png new file mode 100644 index 0000000..f391a5a Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-intro.png differ diff --git a/sld248-matter-overview-guides/images/zap-troubleshooting.png b/sld248-matter-overview-guides/images/zap-troubleshooting.png new file mode 100644 index 0000000..c41ea6f Binary files /dev/null and b/sld248-matter-overview-guides/images/zap-troubleshooting.png differ diff --git a/sld248-matter-overview-guides/index.md b/sld248-matter-overview-guides/index.md new file mode 100644 index 0000000..224ef20 --- /dev/null +++ b/sld248-matter-overview-guides/index.md @@ -0,0 +1,12 @@ +# Overview Guides + +The Overview pages offer a general review of Matter topics including: + +- [Matter Commissioning](matter-commissioning.md) +- [Matter Intermittently Connected Devices (ICD)](matter-icd.md) +- [Matter Over Thread ICD End Devices](ot-icd-end-device.md) +- [Matter Serial Port Communication (Matter Shell)](serial-port-communications.md) +- [Matter SLC CLI Setup and Build Instructions](matter-slc-cli.md) +- [Matter Solutions](matter-solutions.md) +- [Code Size Savings](code-size-savings.md) +- [SMG to Matter Extension (SLC/Simplicity Studio) Project Migration Guide](matter-smg-migration-guide.md) diff --git a/sld248-matter-overview-guides/matter-commissioning.md b/sld248-matter-overview-guides/matter-commissioning.md new file mode 100644 index 0000000..8776988 --- /dev/null +++ b/sld248-matter-overview-guides/matter-commissioning.md @@ -0,0 +1,102 @@ +# Commissioning + +## Overview + +In Matter, Commissioning is the process in which the Matter device joins an existing Matter fabric. There are two main roles in the commissioning process a Commissioner, for example a matterhub, and a Commissionee, for example a Matter light. + +## Onboarding Information + +For a Matter device to commission onto the network, the Matter device needs to have an onboarding payload. Below is the most critical information stored in the onboarding payload: + +- Vendor ID (VID): 16-bit value +- Product ID (PID): 16-bit value +- Discriminator value: 12-bit integer value to distinguish advertising devices +- Passcode: 27-bit unsigned integer used during commissioning +- Discovery Capabilities bitmask: 8-bit bitmask containing information about devices, available technology, and device discovery + +The Onboarding payload can come in a variety of different formats: + +- QR Code +- QR Code Payload which is the string outputted when scanning the QR Code which will be in the format MT:Y.K9042C00KA0648G00 +- Manual Pairing Code which would look something like this: 749701123365521327694 + +The ConnectedhomeIP's CHIP-TOOL has some added commands that can help you parse the setup payload: ./chip-tool payload parse-setup-payload [chip_tool_guide.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/chip_tool_guide.md). + +## Initiate the Commissioning Process + +The commissioning process supports two potential starting points: + +1. The device is already on the network +2. The device needs network credentials for Wi-Fi or Thread (requires Bluetooth LE (BLE) support) + +The current Matter revision supports Ethernet, Wi-Fi, and Thread devices. + +- Ethernet devices get into the operational network when their Ethernet cable is connected. Therefore, the devices are normally already on the network before commissioning. +- Wi-Fi and Thread devices must have credentials configured before the devices can be joined into the operational network. This is normally done over BLE. + +This page focuses on Wi-Fi and Thread. The first step for these devices is to enter commissioning mode, following one of two scenarios: + +| Scenario Name | Description | +| ------------------------- | ----------- | +| Standard | Device automatically goes into the commissioning mode on power-up. Beneficial for limited UI devices (such as light bulbs). | +| User-Directed | Device only enters commissioning mode when initiated by the user. Helpful for devices that have user interfaces or for which commissioning should not be initiated without a user present. | + +The following figure provides an overview of the commissioning process and the actions each role performs. + +## Device Discovery + +Depending on the network topology and Matter device implementation, there are a few ways to implement device discovery: + +- Bluetooth Low Energy (BLE): This is the method used in the example below. Note that if the Matter device utilizes Thread, it **must** also support BLE for the purpose of discovery and commissioning as you cannot solely use Thread-based commissioning and Device Discovery. +- Wi-Fi (IEEE 802.11-2020): This method utilizes Soft-AP functionality. +- Over IP if device is already on an IP network. This method utilizes discovery service like DNS-SD conveying credentials over IP. + +The following figure provides an overview of the commissioning process and the actions each role performs. + +![Commissioning Overview](./images/commissioning-overview.png) + +## Password Authenticated Session Establishment (PASE) + +For Matter devices to ensure the utmost security, the Matter Commissionee and Commissioner establish a secure channel of communication. Here, the Commissioner and the Commissionee establish a password-authenticated session establishment where they derive encryption keys. Once this session is established, all other messages will be encrypted with the PASE derived keys. This connection is timed and confined between the Commissionee and the Commissioner, and is meant to establish a secure connection between the two devices to communicate with one another. + +## Device Attestation + +Once the PASE has occurred, the Commissioner needs to check that the Commissionee is a certified Matter device. This process is called Device Attestation. First, the Commissioner will request the Commissionee to provide device information required in the Device Attestation process. The Commissioner will validate that the information it received from the Commissionee is accurate. The Commissioner will do this by retrieving the Commissionee's PAA (Product Attestation Authority) certificate from the [Distributed Compliance Ledger (DCL)](/matter/{build-docspace-version}/matter-dcl) and the the Commissioner will validate the Commissionee credentials. For more information on Device Attestation pleas, see [Device Attestation](/matter/{build-docspace-version}/matter-device-attestation). + +## Node Operational Credentials (NOC) + +The Commissioner will either generate or obtain a Node Operational Certificate (NOC) and will install the operational credentials into the Commissionee. The NOC contains a set of credentials that the Matter Nodes can use to identify themselves within a Matter Fabric. The NOC includes the Node Operational Identifier (Operational Node ID). The NOC is encrypted with Node Operational Key Pair generated by the Commissionee. The NOC can be revoked by the administrator, and with that, all bindings and fabric configurations will also be removed from the node. + +## Certificate Authenticated Session Establishment (CASE) + +To establish a secure connection after commissioning, the CASE is used to derive an encryption key that will be used to establish a secure communication between the Commissioner/Administrator and the Commissionee. Once this key is established, all unicast messages between the Commissioner/Administrator and the Commissionee are encrypted using the CASE keys. + +## Example Commissioning Flow + +Below is an example Commissioning flow, where the onboarding payload is in the form of a Matter QR Code, and the Device Discovery is done through BLE Beaconing. This will put together all the pieces of Commissioning mentioned above. + +![Steps 1-4](./images/commissioning-steps1-4.png) + +In step 1, the Matter device must enter commissioning mode in one of the two scenarios described above. This means that the Matter Node will start its BLE Advertisements, alerting devices around that it is ready to commission. + +Usually, a mobile phone serves as the administrator. Step 2 is to use the mobile phone to scan the QR code of the Matter device. The QR code is used as a passcode to set up a secured BLE connection. + +Step 3 is to set up the BLE beaconing and connection between the mobile phone and the Matter device, so that the commissioning information can be exchanged through the BLE connection channel. + +As the connection should be secure, step 4 is to secure the connection through password-authenticated session establishment (**PASE**). The passcode derived from the QR code is used as an input for this process. The output is the security key used by the connection. + +![Steps 5-7](./images/commissioning-steps5-7.png) + +After the secured connection is established, step 5 is to verify the Matter device's manufacturer certificate and compliance status through Device Attestation. Each Matter device must have a device certificate, more specifically the DAC, programmed before it is shipped. The mobile phone, acting as administrator, reads the device certificate through the commissioning channel, then communicates with a remote database to validate the certificate and the compliance status of the device. The remote database is called the Distributed Compliance Ledger (**DCL**). + +Step 6 is to install the operational certificate for the device. The administrator either obtains the certificate from the remote server or generates the certificate locally and then transfers the certificate to the device. The administrator also configures the Access Control List (**ACL**) with the list of administrators. + +After operational security is configured, step 7 is to configure the operational network for the device. For Wi-Fi devices, the SSID and the password are configured. For Thread devices, the PAN ID, network key, and other parameters are configured. + +![Steps 8-10](./images/commissioning-steps8-10.png) + +In step 8, the device starts to join the operational network with the configured parameters. + +Once the device is attached to the network (step 9), it can be discovered through Service Registration Protocol (**SRP**). To control that device, you must establish a secured connection through the Certification Authorized Session Establishment (**CASE**) process. + +After the CASE session is established, the Matter device is commissioned successfully and can communicate with other devices in the Matter network (step 10). diff --git a/sld248-matter-overview-guides/matter-icd.md b/sld248-matter-overview-guides/matter-icd.md new file mode 100644 index 0000000..0339e56 --- /dev/null +++ b/sld248-matter-overview-guides/matter-icd.md @@ -0,0 +1,385 @@ +# Matter Intermittently Connected Devices (ICD) + +Matter introduces the concept of Intermittently Connected Devices (ICD) in the SDK and in the specification. An Intermittently Connected Device is the Matter representation of a device that is not always reachable. This covers battery-powered devices that disable their underlying hardware when in a low-power mode or devices that can be disconnected from the network, like a phone app. + +This page focuses on features designed to improve the performance and reliability of battery-powered devices. Matter ICD functionality can be enabled with the `matter_icd_management` component. The Matter light-switch and lock examples are ICDs by default. + +## Creating an ICD Example via Simplicity Studio + +### Enabling/Building + +To begin creating an OpenThread ICD example, create a generic Matter over Thread solution example via the **New Project Wizard**. Lighting solution example will be used for demonstration purposes. + +**Lock and Light-Switch applications come out-of-box with ICD enabled. The low power component can be added by user.** + +1. Create project. + + ![Project Generation](images/icd-project-generation.png) + +2. Navigate to the **Configuration Tools** section and open the **ZCL Advanced Platform (ZAP)**. + + ![ICD ZAP](images/icd-open-zap.png) + +3. Search for the ICD Management cluster and enable for **Server**. You will receive a warning that the corresponding component was unable to be installed. This is due to component conflicts within Simplicity Studio. + + ![ICD Cluster](images/icd-enable-icd-cluster.png) + +4. Navigate to the **Software Components** tab and confirm that the ICD Management Server Cluster component is installed (enabling the ICD Management cluster should automatically trigger its installation). + + ![ICD Component](images/icd-install-icd-component.png) + +5. Replace all subsequent conflicting components via the ensuing pop-up options (See below). This will install the necessary Thread Network Layer (MTD) component and ICD source code. This will also remove the conflicting Thread Network Layer (FTD) component. + + ![ICD Component Conflicts](images/icd-resolve-conflicts.png) + +**Recommended: Install the `matter_platform_low_power` component to achieve further energy savings. See details below.** + +ICD functionality should be installed and ready to build. Build the project as you would a normal example and flash the resulting binary to your specified end device. You should be able to commission the device the same way as non-ICD examples using the QR code URL (generated within the RTT logs at startup or **BTN0** press). + +## **Power Saving Components** + +### **Minimal Power Consumption** + +The Lower Power Mode is an optional component, installing it will disable: + +- Matter Shell +- OpenThread CLI +- LCD and QR Code + +## ICD Configurations + +The ICD feature-set offers two types of configurations: cluster configurations and subscription configurations. +The cluster configurations are exposed through the ICD Manager Cluster interface. +The subscription configurations are exposed through various Matter components configurations and public APIs of the Matter SDK. + +### ICD Management Cluster + +The ICD Management Cluster enables configuration of the ICD’s behavior. It is required for an ICD to have this cluster enabled on endpoint 0. + +The ICDM Cluster exposes three configuration attributes that enable to configure an ICD. + +:::custom-table{width=20%,8%,12%,60%} +| Attribute | Type | Constraints | Description | +|-|-|-|-| +| IdleModeInterval | uint32 | 1 to 64800 | Maximum interval in seconds or milliseconds the server can stay in idle mode | +| ActiveModeInterval | uint32 | min 300 | Minimum interval in milliseconds the server will stay in active mode | +| ActiveModeThreshold | uint32 | min 300 | Minimum amount of time in milliseconds the server typically will stay active after network activity when in active mode | +::: + +### Configuration Attributes + +The ICD Management Cluster exposes three configuration attributes. +These configurations are independent from the underlying transport configurations. +These configurations can be changed by modifying the configuration of the `ICD Server Configuration` component or directly by setting values in `sl_matter_icd_config.h`. + +```cpp + #define SL_IDLE_MODE_DURATION_S = 600 // 10min Idle Mode Interval + #define SL_ACTIVE_MODE_INTERVAL = 1000 // 1s Active Mode Interval + #define SL_ACTIVE_MODE_THRESHOLD = 500 // 500ms Active Mode Threshold +``` + +### ICD Check-In Protocol Use-Case + +The ICD Check-In Protocol use case is used by ICDs to maintain a known relationship in case subscriptions with clients are lost. +This includes how a client shares a Check-In token (symmetric key) with the ICD, when Check-In messages are sent and how the Check-In Protocol requirements are respected. + +The Check-In Protocol is a fail-safe mechanism which allows an ICD to notify a registered client that it is available for communication when all subscriptions between the client and ICD are lost. +A subscription can be lost for several reasons, such as: + +- The ICD might not have full RAM retention when it is in an idle state. +- When the ICD is powered off to change the battery. +- Power or network outage causing the connection between the client and the ICD to be interrupted. +- The client is unavailable for any reason (e.g. during a software update or hosted on a mobile device that is sometimes out-of-home). + +The Check-In message is sessionless and relies on a shared secret that has been given to the ICD during the registration of the client using the ICD Management cluster. +For more information on the ICD Check-In Protocol use-case, see the associated specification section. + +### User Active Mode Trigger + +Since ICDs are not immediately responsive, they require a means to render them available for communication within user initiated use cases. +Some of the user initiated use cases are: + +- Opening a new commissioning window to add another administrator. +- Reconfiguration of an existing fabric (e.g. IPKs, NOC rotation, ACL changes). +- Reconfiguration of cluster functionality (e.g. ICD Management, Bindings, Groups, Scenes). +- Removal of a device from a fabric. +- Changes to the device's settings. + +To enable these user initiated use cases, ICDs need to provide a way for a user to put them in active mode and render them responsive. +The User Active Mode Trigger feature in the ICD Management cluster indicates whether a particular device implements an active mode trigger. + +## **Configuration** + +To change default values corresponding to Matter ICD examples, modify them in either: + +1. `config/sl_matter_icd_config.h` +2. ICD component configurator + +![ICD Configuration](images/icd-config.png) + +### Subscription Configurations + +#### Subscription Maximum Interval Negotiation + +The subscription mechanism is used by ecosystems and controllers to receive attribute change updates and liveness checks. +The maximum interval of a subscription request is what defines the frequency at which a device will send a liveness check if there are no attribute changes. + +Within the subscription request / response model, a device has the opportunity to decide the maximum interval at which it will send its liveness check (Empty Report Update). The device can set a maximum interval within this range if and only if it is an ICD: + +```shell +MinIntervalRequested ≤ MaxInterval ≤ MAX(IdleModeInterval, MaxIntervalRequested) +``` + +The following table shows the subscribe response fields. +| Action Field | Type | Description | +|-|-|-| +| SubscriptionId | uint32 | identifies the subscription | +| MaxInterval | uint16 | the final maximum interval for the subscription in seconds | + +The Matter SDK provides a default implementation that allows an ICD to negotiate its MaxInterval. +The goal of the algorithm is to set the MaxInterval to the IdleModeInterval. + +```cpp +#if CHIP_CONFIG_ENABLE_ICD_SERVER + + // Default behavior for ICDs where the wanted MaxInterval for a subscription is the IdleModeInterval + // defined in the ICD Management Cluster. + // Behavior can be changed with the OnSubscriptionRequested function defined in the application callbacks + + // Default Behavior Steps : + // If MinInterval > IdleModeInterval, try to set the MaxInterval to the first interval of IdleModeIntervals above the + // MinInterval. + // If the next interval is greater than the MaxIntervalCeiling, use the MaxIntervalCeiling. + // Otherwise, use IdleModeInterval as MaxInterval + + // GetPublisherSelectedIntervalLimit() returns the IdleModeInterval if the device is an ICD + uint32_t decidedMaxInterval = GetPublisherSelectedIntervalLimit(); + + // Check if the PublisherSelectedIntervalLimit is 0. If so, set decidedMaxInterval to MaxIntervalCeiling + if (decidedMaxInterval == 0) + { + decidedMaxInterval = mMaxInterval; + } + + // If requestedMinInterval is greater than the IdleTimeInterval, select next active up time as max interval + if (mMinIntervalFloorSeconds > decidedMaxInterval) + { + uint16_t ratio = mMinIntervalFloorSeconds / static_cast(decidedMaxInterval); + if (mMinIntervalFloorSeconds % decidedMaxInterval) + { + ratio++; + } + + decidedMaxInterval *= ratio; + } + + // Verify that decidedMaxInterval is an acceptable value (overflow) + if (decidedMaxInterval > System::Clock::Seconds16::max().count()) + { + decidedMaxInterval = System::Clock::Seconds16::max().count(); + } + + // Verify that the decidedMaxInterval respects MAX(GetPublisherSelectedIntervalLimit(), MaxIntervalCeiling) + uint16_t maximumMaxInterval = std::max(GetPublisherSelectedIntervalLimit(), mMaxInterval); + if (decidedMaxInterval > maximumMaxInterval) + { + decidedMaxInterval = maximumMaxInterval; + } + + // Set max interval of the subscription + mMaxInterval = static_cast(decidedMaxInterval); + +#endif // CHIP_CONFIG_ENABLE_ICD_SERVER +``` + +If the default implementation does not fit within the use-case, +an implementation can override the default implementation. +The first step is to implement the `ApplicationCallback` class from the `ReadHandler.h` header. + +```cpp +/* + * A callback used to interact with the application. + */ +class ApplicationCallback +{ +public: + virtual ~ApplicationCallback() = default; + /* + * Called right after a SubscribeRequest has been parsed and processed. This notifies an interested application + * of a subscription that is about to be established. It also provides an avenue for altering the parameters of the + * subscription (specifically, the min/max negotiated intervals) or even outright rejecting the subscription for + * application-specific reasons. + * + * TODO: Need a new IM status code to convey application-rejected subscribes. Currently, a Failure IM status code is sent + * back to the subscriber, which isn't sufficient. + * + * To reject the subscription, a CHIP_ERROR code that is not equivalent to CHIP_NO_ERROR should be returned. + * + * More information about the set of paths associated with this subscription can be retrieved by calling the appropriate + * Get* methods below. + * + * aReadHandler: Reference to the ReadHandler associated with the subscription. + * aSecureSession: A reference to the underlying secure session associated with the subscription. + * + */ + virtual CHIP_ERROR OnSubscriptionRequested(ReadHandler & aReadHandler, Transport::SecureSession & aSecureSession) + { + return CHIP_NO_ERROR; + } + /* + * Called after a subscription has been fully established. + */ + virtual void OnSubscriptionEstablished(ReadHandler & aReadHandler){}; + /* + * Called right before a subscription is about to get terminated. This is only called on subscriptions that were terminated + * after they had been fully established (and therefore had called OnSubscriptionEstablished). + * OnSubscriptionEstablishment(). + */ + virtual void OnSubscriptionTerminated(ReadHandler & aReadHandler){}; + }; +``` + +The second step is registering the callback object to the Interaction Model Engine. + +```cpp +// Register ICD subscription callback to match subscription max intervals to its idle time interval +chip::app::InteractionModelEngine::GetInstance()->RegisterReadHandlerAppCallback(&mICDSubscriptionHandler); +``` + +#### Persistent Subscriptions + +Persistent subscriptions were added to Matter as a means to ensure that an ICD can re-establish its subscription and by extension its secure session to a subscriber in the event of a power cycle. +When a device accepts a subscription request, it will persist the subscription. +When the device reboots, it will try to re-establish its subscription with the subscriber. +If the subscription is torn down during normal operations or if the re-establishment fails, +the subscription will be deleted. + +Persistent subscriptions are enabled by default on all Silicon Labs sample applications. + +#### Subscription Timeout Resumption + +Matter also provides a retry mechanism for devices to try to re-establish a lost subscription with a client. This feature should not be used on an ICD since it can significantly reduce battery life. This functionality is disabled by default in all Matter sample apps, if necessary it can be enabled by directly editing the project's .slcp file and setting to the `CHIP_CONFIG_SUBSCRIPTION_TIMEOUT_RESUMPTION` configuration value to `1`. + +#### Subscription Synchronization + +To avoid forcing an ICD to become active multiple times, the Matter SDK allows an ICD to synchronize its subscription reporting and send all the reports at the same time. The mecansim syncrhonizes the maximum interval of the all subscription to only require the ICD to become active one. This functionality can be enabled by enabling the Synchronous Reports in the Matter Core Components configuration (`CHIP_CONFIG_SYNCHRONOUS_REPORTS_ENABLED` in `sl_matter_config.h`). + +## ICD Device Types + +Matter introduces two types of ICDs. + +- Short Idle Time ICDs +- Long Idle Time ICDs + +### Short Idle Time ICDs + +Short Idle Time ICDs are battery powered devices that can always be reached by clients. +This means that their polling intervals are small enough to guarantee that a message sent from a client will be able to reach the ICD without any synchronization. +A door lock, for example, is typicaly a short idle time ICD because it needs to be able to receive commands from clients at any given time. +These devices are usually not the initiators in the communication flow. + +#### Requirements + +This section lists the requirements that Short Idle Time ICDs must respect to be certifiable. + +1. The ICD Management Cluster must be present on the Root Endpoint (0) with mandatory attributes. +2. The transport slow poll configuration must be smaller or equal to 15s. +This requirement is not enforced in Matter 1.3 since LIT ICD are not certifiable. +Once LIT ICD officially launch, this will be a mandatory requirement. + +Support of the ICD Check-In Protocol use-case and the user active mode trigger is optional for SIT ICDs. + +#### Configurations + +These are recommended configurations based on the state of the current implementation of SIT ICDs. +The recommended configurations are likely to change with the Matter 1.4 release. + +**ICD Default configurations** + +- Enable ICD Server: TRUE +- Subscription Timeout Resumption: FALSE +- Subscription Synchronization: TRUE + +**ICD Matter Configuration flags** + +Configuration parameters of the ICD Server Configuration component (sl_matter_icd_config.h): + +```cpp + #define SL_IDLE_MODE_DURATION_S = 600 // 10min Idle Mode Interval + #define SL_ACTIVE_MODE_INTERVAL = 10000 // 10s Active Mode Interval + #define SL_ACTIVE_MODE_THRESHOLD = 1000 // 1s Active Mode Threshold +``` + +**Openthread Configuration flags** + +Configuration parameters of the ICD Server Configuration component (sl_matter_icd_config.h): + +```cpp +#define SL_OT_IDLE_INTERVAL 5000 // 5s Idle Intervals +#define SL_OT_ACTIVE_INTERVAL 500 // 500ms Active Intervals +``` + +> **Note**: Wi-Fi polling configuration are dictated by the Access Point and cannot be changed at the Matter level. + +### Long Idle ICDs + +Long Idle Time ICDs are battery powered devices that require synchronization between the client and the ICD for communication to succeed. +A sensor device is an example of a device that are typically a long idle time ICD. + +Long Idle Time ICDs are ready for integration in the Matter 1.3 release. The core feature-set for ICDs has been implemented through the `ICDManager`. +LIT ICDs should be certifiable with the Matter 1.4 release. +Splitting the two milestones in different releases is to allow more in depth interoperability testing to validate the proposed feature-set achieves it's power consumption and usability goals. + +#### Requirements + +This section lists the requirements that Long Idle Time ICDs must respect to be certifiable. + +1. The ICD Management Cluster must be present on the Root Endpoint (0) with mandatory attributes. +2. The `LITS` (Long Idle Time Support) feature map must be set to 1. + + All required features, attributes and commands required by this feature map must also be present. + +3. The `CIP` (Check-In Protocol support) feature map must be set to 1. + + All required attributes and commands required by this feature map must also be present. + +4. The `UAT` (User Active Mode Trigger support) feature map must be set to 1. + + All required attributes and commands required by this feature map must also be present. + +5. The `ActiveModeThreshold` cannot be lower than 5 seconds. + +#### Configurations + +These are recommended configurations based on the state of the current implementation of LIT ICDs. +The recommended configurations are likely to change with the Matter 1.4 release. + +**ICD Default configurations** + +- Enable ICD Server: TRUE +- Subscription Timeout Resumption: FALSE +- Subscription Synchronization: TRUE +- ICD Slow Polling Limit Enforcement: TRUE +- Matter Report on Entering Active: TRUE +- Matter LIT Configuration: TRUE + +The last three parameters are configuration parameters in the Matter Core Components (`ICDServerBuildConfig.h`) + +**ICD Matter Configuration flags** + +Configuration parameters of the ICD Server Configuration component (`sl_matter_icd_config.h`): + +```cpp + #define SL_IDLE_MODE_DURATION_S = 3600 // 60min Idle Mode Interval + #define SL_ACTIVE_MODE_INTERVAL = 0 // 0s Active Mode Interval + #define SL_ACTIVE_MODE_THRESHOLD = 5000 // 5s Active Mode Threshold +``` + +**Openthread Configuration flags** + +Configuration parameters of the ICD Server Configuration component (`sl_matter_icd_config.h`): + +```cpp +#define SL_OT_IDLE_INTERVAL 3600000 // 60mins Idle Polling Interval +#define SL_OT_ACTIVE_INTERVAL 1000 // 1s Active Polling Interval +``` diff --git a/sld248-matter-overview-guides/matter-logging-configuration.md b/sld248-matter-overview-guides/matter-logging-configuration.md new file mode 100644 index 0000000..fa0f2c5 --- /dev/null +++ b/sld248-matter-overview-guides/matter-logging-configuration.md @@ -0,0 +1,19 @@ +# Matter Logging Configurations + +Device logs are enabled by default on UART instead of JLink RTT, and will be fully captured on the Serial Terminal. + +To configure the Serial Terminal, follow steps 13 to 17 in the [Serial Port Settings](serial-port-communications.md). + +After flashing the device and setting up the Serial Terminal, you will see the device logs displayed on the Serial Terminal. + +![Silicon Labs - design](./images/tera-term-uart-logging.png) + +## Switching To RTT + +To redirect device logs from UART to JLink RTT, enable the `matter_log_rtt` component. + +![Silicon Labs - design](./images/select-jlink-rtt-logging.png) + +To set the JLink RTT on SiWx917 SoC, follow the steps mention in [Setup SiWx917 SoC](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). + +> **Note:** `matter_log_uart` and `matter_log_rtt` components cannot be selected simultaneously. diff --git a/sld248-matter-overview-guides/matter-slc-cli.md b/sld248-matter-overview-guides/matter-slc-cli.md new file mode 100644 index 0000000..adf1d12 --- /dev/null +++ b/sld248-matter-overview-guides/matter-slc-cli.md @@ -0,0 +1,5 @@ +# Creating Matter Applications using SLC CLI + +**Silicon Labs Configurator (SLC)**: SLC offers command-line access to application configuration and generation functions. [Software Project Generation and Configuration with SLC-CLI](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-tools-slc-cli/) provides instructions on downloading and using the SLC-CLI tool. + +Instructions on how to build Matter projects using SLC CLI can be found in the README section of [Matter Extension Repo](https://github.com/SiliconLabsSoftware/matter_extension/tree/release_2.5-1.4) diff --git a/sld248-matter-overview-guides/matter-smg-migration-guide.md b/sld248-matter-overview-guides/matter-smg-migration-guide.md new file mode 100644 index 0000000..bcfd077 --- /dev/null +++ b/sld248-matter-overview-guides/matter-smg-migration-guide.md @@ -0,0 +1,86 @@ +# SMG to Matter Extension (SLC/Simplicity Studio) Project Migration Guide + +This page provides instructions on how to migrate an already created project from SMG to an SLC-based project in Simplicity Studio. + +These instructions assume that you have installed Simplicity Studio ([Getting Started with Simplicity Studio](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-getting-started/)) and have an SMG project. + +1. Install the same release of GSDK used to create the SMG project and the mapped Matter extension in Simplicity Studio. The following table shows what GSDK and Matter Extension to should be used depending on the SMG version of the project that you are trying to migrate.  + + |**SMG Version**|**Matter Extension Version**|**GSDK Version**| + | :-: | :-: | :-: | + |[1.1.0-1.1](https://github.com/SiliconLabs/matter/releases/tag/v1.1.0-1.1)|[v2.0.0](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.0.0)|[v4.3.0](https://github.com/SiliconLabs/gecko_sdk/tree/v4.3.0)| + |[2.0.0-1.1](https://github.com/SiliconLabs/matter/releases/tag/v2.0.0-1.1)|[v2.1.0](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.1.0)|[v4.3.1](https://github.com/SiliconLabs/gecko_sdk/releases/tag/v4.3.1)| + |[2.1.0-1.1](https://github.com/SiliconLabs/matter/releases/tag/v2.1.0-1.1)|[v2.1.1](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.1.1)|[v4.3.2](https://github.com/SiliconLabs/gecko_sdk/releases/tag/v4.3.2)| + |[2.2.0-1.2](https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2)|[v2.2.0](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.2.0) (Older Extension versions do not fully work with GSDK 4.4.x)|[v4.4.0](https://github.com/SiliconLabs/gecko_sdk/releases/tag/v4.4.0)| + |[2.3.0-1.3](https://github.com/SiliconLabs/matter/releases/tag/v2.3.0-1.3)|[v2.3.0-1.3](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.3.0)|[v2024.6.0](https://github.com/SiliconLabs/simplicity_sdk/releases/tag/v2024.6.0)| + + †Steps to add GSDK and Matter extension to Simplicity Studio. Refer to [Install SDK Extensions](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-getting-started/install-sdk-extensions). + + 1. Once Simplicity Studio 5 is installed, you will be prompted to install the Gecko SDK Suite (GSDK). Install the Matter extension by making sure the extension is checked. This will install the latest GSDK as well as the Matter extension. + 2. If using an older version of a GSDK corresponding to the SMG version of your project, install by: Install > Manage Installed Packages > SDKs. Click the menu option next to the GSDK version and change the desired version. + 3. If you have changes in GSDK and want to use the same GSDK from SMG, complete step 1 and then install your specific GSDK by: Preferences > Simplicity Studio (dropdown) > SDKs > Add SDK. Browse to the SDK location. Trust the contents of this GSDK. Download the respective Matter extension for that GSDK from the [Matter extension release page](https://github.com/SiliconLabs/matter_extension/releases), unzip it (make sure to keep `matter_extension` as the folder name) and add the Matter extension to the previously added GSDK: Preferences > Simplicity Studio (dropdown) > SDKs > (Select SDK) > Add Extension, and browse to the extension location. Trust the contents of the extension. +2. Create a sample app with the same board and same type. Select Simplicity IDE as project generator.  + - For example, if SMG project is the lighting app for thread using board BRD4161A, select BRD4161A in the New Project Wizard and then select SoC Lighting over thread in the Example project selection page. + - For example, if SMG project is the lock app for wi-fi RS9116 using board BRD4187C, select BRD4187C in the New Project Wizard and then select NCP Lock over Wifi (with RS9116 in the description) in the Example project selection page. +3. **Build Flags:** Simplicity Studio has components that map to the build flags option in SMG build scripts. To configure the project through the component library, click the **SOFTWARE COMPONENTS** tab. A number of filters, as well as a keyword search, are available to help you explore the various component categories. Users can install/uninstall components to enable and disable certain functionalities.   + + The mapping is as follows: + + :::custom-table{width=30%,70%} + |**Build Flag**|**Simplicity Studio Component**| + | :- | :- | + |chip\_build\_libshell|Matter Shell| + |chip\_logging|Matter Core Components, click the gear icon (configuration) and select the required logging level| + |chip\_openthread\_ftd|Stack (FTD) Configure| + |enable\_heap\_monitoring|Memory Monitoring| + |enable\_openthread\_cli|OpenThread CLI| + |kvs\_max\_entries|Matter Core Components, click the gear icon (configuration) and modify the Maximum amount of KVS Entries value. Default 255. Threshold: 30 <= kvs\_max\_entries <= 255| + |show\_qr\_code|Matter QR Code Display| + |chip\_enable\_icd\_server|ICD Management Server Cluster| + |use\_rs9116, use\_SiWx917, use\_wf200|Select the appropriate series-1, series-2, or Siw917Soc boards, and select respective projects in new project wizard.| + |'import("//with\_pw\_rpc.gni")'|Will be introduced in Matter extension v2.3.0-1.3 release| + |ota\_periodic\_query\_timeout\_sec|OTA Requestor, click the gear icon (configuration) and modify the  OTA Requestor periodic timeout| + |rs91x\_wpa3\_transition| :para[Add the following statement to the project's SLCP file:] :para[define:] :para[- name:] :para[WIFI\_ENABLE\_SECURITY\_WPA3\_TRANSITION] :para[value: "1"]| + |slc\_gen\_path|Already part of project. No need to do anything| + |sl\_pre\_gen\_path|Already part of project. No need to do anything| + |sl\_matter\_version|Matter Core Components, click on gear icon(configuration) and select Device software version | + |sl\_matter\_version\_str|Matter Core Components, click on gear icon(configuration) and select Device software version string| + |sl\_hardware\_version|Matter Core Components, click on gear icon(configuration) and select Device hardware version | + ::: + + :::custom-table{width=30%,70%} + |**Presets**|**Simplicity Studio Component**| + | :- | :- | + |icd| Icd Management Server Cluster | + |low-power| Lower Power Mode | + |additional\_data\_advertising|GATT Additional Advertising| + |use\_ot\_lib|OpenThread Certification Libraries| + |use\_chip\_lwip\_lib|Matter LwIP| + |release| Install Matter No Debug, remove Matter LCD| + |uart\_log| :para[Add the following statement to the project's SLCP file:] :para[define:] :para[- name: SILABS\_LOG\_OUT\_UART] :para[value: "1"] | + |slc\_generate|Already part of project. No need to do anything| + |slc\_reuse\_files|Already part of project. No need to do anything| + |bootloader|Already part of project. No need to do anything| + ::: + +4. Once the application is created in Simplicity Studio, the user can locate all the project files in the **Project Explorer** menu on the left. +5. ZAP Changes: + 1. If there are ZAP changes for the project, from the Project Explorer menu, replace the ZAP file located at `config/common/.ZAP` with the SMG project ZAP file. + 2. To install the cluster components for enabled clusters, click the .slcp from the Project Explorer menu > Configuration Tools > Open **Zigbee Cluster Configurator**. + 3. Select **Enabled Clusters** from the **Filters** dropdown in ZAP GUI. + 4. Go through the list of enabled clusters and if shown a warning, click **Install** to get the respective cluster components installed. + + ![ZAP](images/zap-troubleshooting.png) + +6. If there are code changes in the project files such as files located in `include/` and `src/`, replace the files from the SMG project to the respective `include/` and `src/` directories. +7. The Matter stack and platform source files can be found in the Project Explorer menu under the `matter_` directory. You can move over all the files changed from the SMG project to the Simplicity Studio project. +8. If you have created new source files, then depending on the IDE, you will need to: + - For Simplicity Studio IDE: copy them to respective locations in the Simplicity Studio project. + - For IAR EW: Make use of the `Add File` mechanism. + - For CMake or Makefile: Add using a custom CMake/Makefile subfile as described in their readmes or comments. +9. Your project should be ready to build and flash. + +## Troubleshooting + +1. If you receive a ZAP feature level error from Simplicity Studio, add the latest ZAP by following [these instructions](https://docs.silabs.com/ZAP-tool/1.0.0/ZAP-users-guide/update-ZAP). +2. Get familiar with [Simplicity Studio Project Configurator](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/project-configurator). diff --git a/sld248-matter-overview-guides/matter-solutions.md b/sld248-matter-overview-guides/matter-solutions.md new file mode 100644 index 0000000..3f2c8a8 --- /dev/null +++ b/sld248-matter-overview-guides/matter-solutions.md @@ -0,0 +1,29 @@ +# Matter Solutions + +## General + +Matter solutions allow the user to generate multiple projects at once, to generate a combined solution/binary and allow multiple post-build operations to provide flexibility and unison when developing a Matter example or application. For example, with the Matter Lighting over Thread with Bootloader Solution a user can generate a Matter Bootloader, a Matter Lighting example, and the combined Bootloader + Example production image. Solutions will also generate a .gbl binary for the users to make use of and create an .ota software image update binary (directions listed below). + +## Solution Creation + +To create a Matter Solution, proceed to the **Example Project Selection** section of Simplicity Studio's **New Project Wizard**. On the left side, ensure that **Example Projects** is toggled off, **Solution Examples** is toggled on, and **Matter** under the **Technology** section is checked. Then, select the application example you wish to create a project from. + +![Solution Generation](./images/solution-generation.png) + +## Solution Building + +Building via solutions behaves just like a normal project. Just ensure the top-level solution is selected and build! Artifacts from the resulting projects can be found within the `artifact` directory under each distinct project within the solution. Users selecting to build _just_ the sample application may get an error at the end of their build assuming the bootloader was built with it as well. Disregard this notification. + +![Solution Artifacts](./images/solution-artifacts.png) + +## OTA Creation + +Due to certain limitations with the way our Matter examples are built within Simplicity Studio, OTA file generation must be conducted by the user via the command line. + +To create an OTA file, first build a Matter example via solutions. Locate the resulting .gbl file within the `artifact` directory. This will be used as an argument to the GBL creation script. Then, locate the directory that holds the Matter Extension within the SiSDK in Simplicity Studio. The location should be similar to: `/Users/User/SimplicityStudio/SDKs/simplicity_sdk/extension/matter_extension`. Once found, open a terminal at this location and run the command: + +```bash +./src/app/ota_image_tool.py create -v 0xFFF1 -p 0x8005 -vn -vs -da sha256 / / +``` + +Where `SoftwareVersion` and the `SoftwareVersionString` correspond to the CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION and CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING parameters the project has been compiled with. And where `ResultingOtaFileName` is the name of the OTA file you wish to generate, `PathToArtifactDirectory` is the location of your artifact directory within your project, and `GblFile` is the name of the GBL file that was produced after building the solution. The OTA file should now have been populated within the `artifact` directory in Simplicity Studio. diff --git a/sld248-matter-overview-guides/ot-icd-end-device.md b/sld248-matter-overview-guides/ot-icd-end-device.md new file mode 100644 index 0000000..0cbfb42 --- /dev/null +++ b/sld248-matter-overview-guides/ot-icd-end-device.md @@ -0,0 +1,56 @@ +# Matter Intermittently Connected Devices over OpenThread + +This page explains how Matter OpenThread Intermittently Connected Devices (ICDs) work and how to configure an ICD example. + +## Overview + +Matter provides an Intermittently Connected Device (ICD) operating mode to extend the battery life of power-limited devices. +The Matter ICD manager leverages subscription report synchronization and OpenThread functionalities to allow devices to sleep for set periods +without disrupting their Matter sessions. + +Currently, in Matter v1.2, only ICD with Short Idle Time (SIT) is supported. ICD SIT are devices that SHOULD be configured with a Slow Polling Interval shorter than or equal to 15 seconds. For example, in a typical scenario for door locks and window coverings, commands need to be sent to the ICD with a use-case imposed latency requirement. Typically, devices that are Short Idle Time ICDs are not initiators in the communication flow. + +## Operating Modes + +ICDs have two operating modes: Idle and Active. An ICD alternates normally between the Idle mode and Active mode based on the `IdleModeInterval` and `ActiveModeInterval` respectively. + +When the device is in *Active Mode*, the ICD is set into a fast-polling interval for maximum responsiveness. +The `CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL` parameter communicates the maximum sleep interval of a node in active mode. + +Any of the following device states will start or keep the ICD in *Active Mode*: + +- A commissioning window is open +- An exchange context is awaiting a response or ack +- The fail-safe is armed + +Any of the following events can trigger the start of the *Active Mode* interval or extend it by one `ActiveModeThreshold`: + +- A message needs to be sent +- A message was received +- An implemented user action occurred + +Once the active mode is triggered, the ICD stays in this mode for a minimum duration of `ActiveModeInterval` +When the active interval has elapsed and none of the aforementioned states are active, the device will switch its operating mode to the Idle Mode. + +In *Idle mode*, the ICD will poll its associated router at its slow-polling interval to see if another device has tried to communicate with it while it was sleeping. +If no event occurs, the ICD stays in its idle mode for the entirety of the `IdleModeInterval`. +The `CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL` parameter communicates the slow-polling interval and therefore the maximum sleep interval of the node in idle mode. This parameter affects both the minimum power consumption and maximum latency. + +## Thread Communication + +In order to receive messages that were sent while the ICD was sleeping, the ICD relies on its associated Thread router which buffers any incoming messages. +The Thread router will send all buffered messages to the ICD when it polls the router at the end of its slow-polling interval. + +## Configuration + +Matter exposes some defines to configure the polling intervals of the OpenThread stack in both Idle and Active modes. + +:::custom-table{width=14%,31%,26%,9%,20%} +| Parameter Name | Define | Description | Default Value | Maximum Allowed Value | +| - | - | - | - | - | +| SlowPollInterval | CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL (`SL_OT_IDLE_INTERVAL`) | Interval, in milliseconds, at which the thread radio will poll its network in idle mode. | 15000 ms | <= IdleModeInterval | +| FastPollInterval | CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL (`SL_OT_ACTIVE_INTERVAL`) | Interval, in milliseconds, at which the thread radio will poll its network in active mode. | 200 ms | < ActiveModeInterval | + +For Matter configuration, see the [Matter ICD](/matter/{build-docspace-version}/matter-overview-guides/matter-icd#configuration) documentation. + +To build an ICD example application within Simplicity Studio, see [Matter ICD Example Guide](/matter/{build-docspace-version}/matter-overview-guides/matter-icd#enabling-building). diff --git a/sld248-matter-overview-guides/serial-port-communications.md b/sld248-matter-overview-guides/serial-port-communications.md new file mode 100644 index 0000000..c17b2c3 --- /dev/null +++ b/sld248-matter-overview-guides/serial-port-communications.md @@ -0,0 +1,122 @@ +# Serial Port Communication on the Silicon Labs Platform (Matter Shell) + +The matter-shell exposes the configuration and the management APIs via the matter command line interface (matter CLI). This interface can be used to change the state of the device. + +## Hardware Requirements + +To run matter shell on the Silicon Labs Platform, refer to the [Hardware Requirements](/matter/{build-docspace-version}/matter-prerequisites/hardware-requirements). + +## Software Requirements + +To run matter shell on the Silicon Labs Platform, refer to the [Software Requirements](/matter/{build-docspace-version}/matter-prerequisites/software-requirements). + +## Execute Matter Shell on Silicon Labs Platform + +1. [Download](https://www.silabs.com/developers/simplicity-studio) and install Simplicity Studio. + +2. To install the software packages for Simplicity Studio, refer to [Software Package Installation](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-software-packages). + +3. Log in to Simplicity Studio and connect the EFR32MG2x or SiWx917 SOC board to the computer. + +4. Go to the **All Products** section. + + ![Silicon Labs - design](./images/all-products-selection.png) + +5. Type and select the radio board from the displayed list and click **Start**. + + ![Silicon Labs - design](./images/select-efx-board.png) + +6. The Launcher page will display the selected radio board's details. + + ![Silicon Labs - design](./images/overview-tab-efx32.png) + +7. Verify the following in the **General Information** section: + - The Debug Mode is **Onboard Device (MCU)**. + - The Preferred SDK is the version you selected earlier. + + ![Silicon Labs - design](./images/create-project-verify-efx-general-information.png) + +8. Open the **Example Projects and Demos** tab and create a project for the Matter Lock Application. + + ![Silicon Labs - design](./images/create-project-select-efx-lock-example.png) + +9. In the New Project Wizard window, click **Finish**. + + ![Silicon Labs - design](./images/create-project-lock-click-finish.png) + +10. After creation of project, open the **Software Components** tab and, in the search bar, type _Matter Shell_ and install it. + + ![Silicon Labs - design](./images/matter-shell-enable.png) + +11. Build the project after enabling the **Matter Shell** component. + +12. After a successful build, commission the device as described in [Commission Matter Platform](/matter/{build-docspace-version}/matter-wifi-run-demo/use-case-execution#creating-the-matter-network). + +13. Open Tera Term and under **New connection**, select **Serial**, and in the dropdown, select the **JLink** port, and click **OK**. + + ![Silicon Labs - design](./images/tera-term-select-jlink-port.png) + +14. In the menu bar, click **Setup > Terminal**. + + ![Silicon Labs - design](./images/tera-term-selection-in-terminal.png) + +15. Inside **Terminal**, set the values below and click **OK**. + + - Terminal Size : 80 * 24 + - New-Line + - Receive : CR+LF + - Transmit : CR+LF + + ![Silicon Labs - design](./images/tera-term-terminal-setup.png) + +16. In the menu bar, click **Setup > Serial port**. + + ![Silicon Labs - design](./images/tera-term-select-serial-port.png) + +17. Increase the speed to **115200** and click **New setting**. + + ![Silicon Labs - design](./images/tera-term-select-speed.png) + +18. In the menu bar, click **File > TTY Record**. Create any empty file with extension ".tty" and click **Save**. + + ![Silicon Labs - design](./images/tera-term-tty-record.png) + +19. After creating the tty file, press **Enter** to open the **matterCli** terminal. + + ![Silicon Labs - design](./images/tera-term-matter-cli.png) + +20. Send any command through the **matterCli** terminal, from the below list of commands: + + - doorlock event door-state-change "DoorState" + - Door State List + - DoorOpen = 0 + - DoorClosed = 1 + - DoorJammed = 2 + - DoorForcedOpen = 3 + - DoorUnspecifiedError = 4 + - DoorAjar = 5 + - doorlock event lock-alarm "AlarmCode" + - Alarm Code List + - LockJammed = 0 + - LockFactoryReset = 1 + - LockRadioPowerCycle = 3 + - WrongCodeEntryLimit = 4 + - FrontEsceutcheonRemoved = 5 + - DoorForcedOpen = 6 + - DoorAjar = 7 + - ForcedUser = 8 + - onboardingcodes ble, command will show QR Code. + + ![Silicon Labs - design](./images/matter-shell-command-send.png) + +21. After changing DoorState and AlarmCode in **matterCli**, run the commands below using chip-tool on Raspberry PI to verify the event. + + - To Read Door State + + ./chip-tool doorlock read-event door-state-change "node_id" "endpoint" + + - To Read Alarm Code + + ./chip-tool doorlock read-event door-lock-alarm "node_id" "endpoint" + + **Note**: Type **help** in matterCli terminal for more information about supported features. diff --git a/sld249-matter-prerequisites/hardware-requirements.md b/sld249-matter-prerequisites/hardware-requirements.md new file mode 100644 index 0000000..c717dc5 --- /dev/null +++ b/sld249-matter-prerequisites/hardware-requirements.md @@ -0,0 +1,145 @@ +# Matter Hardware Requirements + +To run Matter over Thread or over Wi-Fi requires some Silicon Labs hardware in order to run demos and do development. Following are the hardware requirements for both Thread and Wi-Fi use cases broken down by platform and transport protocol. + +The following sections describe the hardware that may be used for Matter+OpenThread (Matter Hub and Accessory Device) and for Matter+Wi-Fi (Accessory Device). The EFR32MG24/MG26 is the preferred starting point for Matter MCUs (including the Matter Hub RCP and both Accessory Devices). It provides Secure Vault and can use the internal flash of the device to store an upgrade image. The EFR32MG24/MG26 is recommended for running the [Matter over Thread and Matter over Wi-Fi Quick-Start guides](/matter/{build-docspace-version}/matter-overview). + +## 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. To do so you will need: + +**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](./matter-artifacts.md). + +**Radio Co-Processor (RCP)** + +The Matter Hub needs a 15.4 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 running the RCP firmware. To build an image for a board that is not listed here, 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](./matter-artifacts.md): + +**Note:** The EFR32MG24/MG26 is the preferred starting point for Matter MCUs. It provides Secure Vault and can use the internal flash of the device to store an upgrade image. + +- **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) + +- **MG26 boards:** + - BRD4116A / 2.4GHz@10dBm + - BRD4117A / 2.4GHz@20dBm + - BRD4118A / 2.4GHz@20dBm + - BRD2608A + - BRD2709A + +- **MGM26 boards:** + - BRD4350A + - BRD4351A + +## Matter Over Thread Accessory Device Requirements + +The Matter Accessory Device (MAD) is the actual device that the Matter application firmware (such as the Matter Light or Matter Switch) runs on. Several different platforms for the MAD are supported. Pre-built binary images for the MADs are provided on the [Matter Artifacts page](./matter-artifacts.md). Silicon Labs supports development of MADs for Matter over Thread on the following platforms: + +**Note:** The EFR32MG24/MG26 is the preferred starting point for Matter MCUs. It provides Secure Vault and can use the internal flash of the device to store an upgrade image. + +- **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 + - BRD2601B / MG24 Explorer Kit + - [XG24-DK2601B](https://www.silabs.com/development-tools/wireless/efr32xg24-dev-kit?tab=overview) + - BRD4319A / SLWSTK6006A / Wireless Starter Kit/ 2.4GHz@20dBm + + **Note**: Only the A00 revision of this board is supported, other revisions do not have enough RAM to run Matter. + + - BRD4316A / SLWSTK6006A / Wireless Start Kit / 2.4GHz@10dBm + - [XGM240-RB4316A](https://www.silabs.com/development-tools/wireless/xgm240-rb4316a-xgm240p-module-radio-board?tab=overview) + - BRD4317A / SLWSTK6006A / Wireless Starter Kit/ 2.4GHz@20dBm + - [XGM240-RB4317A](https://www.silabs.com/development-tools/wireless/xgm240-rb4317a-xgm240p-module-radio-board?tab=overview) + +- **MG26 boards** + - BRD4116A / 2.4GHz@10dBm + - BRD4117A / 2.4GHz@20dBm + - BRD4118A / 2.4GHz@20dBm + - BRD2608A + - BRD2709A + +- **MGM26 boards:** + - BRD4350A + - BRD4351A + +## Matter Over Wi-Fi Accessory Device Requirements + +### Matter Over Wi-Fi Accessory Device Requirements for NCP Mode + +The Silicon Labs Matter over Wi-Fi NCP mode demo and development requires two boards: the Silicon Labs EFR32 Radio board to run the Matter code and either the RS9116, SiWx917, or WF200 to run the Wi-Fi protocol stack. Pre-built images for the EFR32, and also for SiWx917 or RS9116 connectivity firmware, are provided on the [Matter Artifacts page](./matter-artifacts.md). + +**Notes:** + +1. The EFR32MG24/MG26 is the preferred starting point for Matter MCUs. It provides Secure Vault and can use the internal flash of the device to store an upgrade image. +2. The WF200 connectivity firmware image is included in the EFR32MG24 images on the [Matter Artifacts page](./matter-artifacts.md) for running with the WF200 in NCP mode. The Matter application downloads the connectivity firmware onto the WF200 on first-time startup. + +The following boards are supported for the Matter over Wi-Fi demos and development: + +- **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) + - MG24 with WSTK : [xG24-PK6009A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-10-dbm?tab=overview) + - BRD4187C / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm + - [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board) + - MG24 with WSTK : [xG24-PK6010A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-20-dbm?tab=overview) + +- **Wi-Fi NCP Dev Kits & boards** + - **RS9116** + - SB-EVK1 / Single Band Wi-Fi Development Kit / 2.4GHz + - [RS9116X-SB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit) + - SB-EVK2 / Single Band Wi-Fi Development Kit / 2.4GHz + - [RS9116X-SB-EVK2](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk2-development-kit) + - DB-EVK1 / Dual Band Wi-Fi Development Kit / 2.4GHz & 5GHz + - [RS9116X-DB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-db-evk-development-kit) + - **SiWx917 NCP** + - SiWx917 NCP Mode / Wi-Fi Expansion Board / 2.4GHz + - BRD8045A (B0 Expansion v2.0) + - **WF200** + - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz + - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) + - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz + - [SLEXP8023A](https://www.silabs.com/development-tools/wireless/wi-fi/wfm200-wifi-expansion-kit) +- Interconnect board (included in the Wi-Fi kits) +- Interconnect board (included in the Wi-Fi kits) +- SPI Cable (included in the RS9116 kit) +- Jumper Cables (included in the RS9116 kit) + +### Matter over Wi-Fi Accessory Device Requirements for SoC Mode + +The Silicon Labs Matter over Wi-Fi demo and development for SoC mode requires the SiWx917 SoC board that supports Matter over Wi-Fi in a single-chip package. The integrated MCU is dedicated for peripheral and application-related processing (Matter), while the ThreadArch® runs the wireless and networking protocol stacks. + +Pre-built images for the SiWx917 connectivity firmware are available as per the instructions on the [Matter Artifacts page](./matter-artifacts.md). The following boards are supported for the Matter over Wi-Fi demos and development: + +- **Wi-Fi SoC boards** + + - BRD4338A / SiWx917 Wi-Fi 6 and Bluetooth LE 8 MB Flash SoC Pro Kit - SiWx917-PK6031A + - BRD2605A / SiWx917 Wi-Fi 6 and Bluetooth LE Dev Kit - SiWx917-DK2605A + - BRD4342A / SiWx917 Wi-Fi 6 and Bluetooth LE 8 MB Flash + 8 MB ext PSRAM Radio Board with an internal RF switch - SiWx91x-RB4342A + + **Note**: Refer to [SiWx917 SoC](https://www.silabs.com/development-tools/wireless/wi-fi/siwx917-pro-kit?tab=techdocs) for more details. + +### Additional Matter Over Wi-Fi Hardware Requirements + +In addition to your Matter over Wi-Fi Accessory Device, you need the following for both running the demo and for development: + +- Windows/Linux/MacOS computer with a USB port +- USB cable for connecting WSTK Board to Computer +- Raspberry Pi with a >32 GB SD Card +- Access point with Internet access +- microSD card (>=32GB) (if using Raspberry Pi) +- **[Optional]** Android Mobile phone (If using the chip-tool on Android) +- Interconnect board (included in the RS9116 kit) +- SPI Cable (included in the RS9116 kit) +- Jumper Cables (included in the RS9116 kit) diff --git a/sld249-matter-prerequisites/index.md b/sld249-matter-prerequisites/index.md new file mode 100644 index 0000000..e4ec863 --- /dev/null +++ b/sld249-matter-prerequisites/index.md @@ -0,0 +1,7 @@ +# Prerequisites + +If you have already obtained the hardware and software for the [Matter over Thread and Matter over Wi-Fi Quick-Start guides](/matter/{build-docspace-version}/matter-overview), you already have most of what you need. These pages offer more hardware alternatives and provide additional Detail. + +These pages explain the [hardware](./hardware-requirements.md) and [software](./software-requirements.md) prerequisites for working with the Silicon Labs Matter products. + +The [artifacts page](./matter-artifacts.md) 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. diff --git a/sld249-matter-prerequisites/matter-artifacts.md b/sld249-matter-prerequisites/matter-artifacts.md new file mode 100644 index 0000000..4a29850 --- /dev/null +++ b/sld249-matter-prerequisites/matter-artifacts.md @@ -0,0 +1,73 @@ +# 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. + +Images for the items listed below are available under the "Assets" section at the bottom of this page: + +https://github.com/SiliconLabs/matter_extension/releases/tag/v2.6.0 + +## 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 chip-tool. Note the image is ~7GB 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_2.5.0-1.4-extension.zip + +## 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_extension/releases/download/v2.6.0/ot-rcp-binaries-2.6.0-1.4.zip + +## Matter Accessory Device Images + +The Matter Accessory Device Images are used to turn an EFR into a Matter device. These are pre-built binary images for the Matter Demo. Matter Accessory Device Images are located in the Assets section of this page: + +https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/matter-accessory-device-images_2.6.0-1.4.zip + +## Matter Bootloader Binaries + +All Silicon Labs board supporting Matter require that a bootloader binary is flashed to the device along with the application image. Bootloader binaries for all of the Matter supported devices are available here: + +https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/bootloader_binaries_matter_extension_v2.6.0-1.4.zip + +## RS9116 Firmware + +The RS9116 firmware (`rs9116_firmware_files_with_rev.zip`) is used to update the RS9116 which can be found in the Assets section of this page: + +https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/rs9116_firmware_files_with_rev_2.6.0-1.4.zip + +**Note**: +RS9116 chip/module needs to be flashed with proper firmware as mentioned below: + +- `RS916.x.x.x.x.x.rps - This firmware image is valid for RS9116 1.5 revision chip/module` +- `RS9116.x.x.x.x.x.rps - This firmware image is valid for RS9116 1.4/1.3 revision chip/module` + +## SiWx917 Firmware for SiWN917 NCP and SiWG917 SOC + +The SiWx917 firmware(SiWx917_firmware_files.zip) is used to update the SiWN917 NCP and SiWG917 SOC which can be found in the Assets section of this page: + +https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/SiWx917_firmware_files_2.6.0-1.4.zip + +**Note**: + +- SiWN917 NCP board need to be flashed with proper firmware as mentioned below: + + - `SiWG917-B.2.x.X.X.X.rps - This firmware image is valid for BRD8045A (B0 Expansion v2.0) board` + +- SiWG917 SoC boards need to be flashed with proper firmware as mentioned below: + + - `SiWG917-B.2.x.X.X.X.rps - This firmware image is valid for BRD4338A(B0 common flash v2.0) board` + +## Matter SiWx917 RCP Linux app and Configuration file + +The SiWx917 RCP folder (siwx917_rcp_files.zip) contains the Matter Linux all-cluster-app, which can be run on a Raspberry Pi, and the wfx-sdio-overlay.dts file, a Device Tree Source file used to configure the SDIO interface on the Raspberry Pi to detect and communicate with the SiWx917 RCP. + +https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/siwx917_rcp_files.zip + +## SiWx917 SoC Configuration Files For JLink RTT Logging + +To check device logs on JLink RTT for the Matter Application on the SiWx917 SoC, the **JLink RTT** must be configured for the SiWx917 SoC device by following the instructions on the [JLink RTT SOC Support](/matter/{build-docspace-version}/matter-wifi-enabling-features/jlink-soc-setup) for SiWx917 SoC. + +The [JLinkDevices.xml](https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/JLinkDevices.xml.zip) and [RS9117_SF_4MB_42bsp.elf](https://github.com/SiliconLabs/matter_extension/releases/download/v2.6.0/RS9117_SF_4MB_42bsp.elf.zip) files referenced in the instructions may be found in the Assets section of this page. + +>**Note**: For EFR32MG2x devices, JLink RTT Logging support is already enabled. diff --git a/sld249-matter-prerequisites/software-requirements.md b/sld249-matter-prerequisites/software-requirements.md new file mode 100644 index 0000000..eff9ed4 --- /dev/null +++ b/sld249-matter-prerequisites/software-requirements.md @@ -0,0 +1,51 @@ +# Matter Software Requirements + +This page provides information on the required softwares tools, packages, and firmware for developing Silicon Labs Matter over Thread and Wi-Fi devices. + +## Software Tools Required + +Below are the software tools both optional and required for developing Matter over Thread and Matter over Wi-Fi applications in both NCP and SoC mode: + +1. [Silicon Labs Simplicity Studio](https://www.silabs.com/developers/simplicity-studio) + + Simplicity Studio is the main IDE and development platform provided by Silicon Labs. + +2. (Optional) [Ozone - The J-Link Debugger for Windows](https://www.segger.com/products/development-tools/ozone-j-link-debugger/) + + Ozone is a full-featured graphical debugger for embedded applications. With Ozone it is possible to debug any embedded application on C/C++ source and assembly level. + +3. (Optional) [Simplicity Commander](https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip) + + Simplicity Commander is a utility that provides GUI and command line access to the debug features of an EFM32 device. It allows you to flash firmware, update the kit firmware, and lock, or unlock debug access. + +4. (Optional) [Tera Term](https://osdn.net/projects/ttssh2/releases/) + + Tera Term is the terminal emulator for Microsoft Windows that supports serial port, telnet and SSH connections. + +5. (Optional) SSH Client ([PuTTY](https://www.putty.org/), Terminal, or similar): + + SSH client is used to communicate with the Raspberry Pi over a secure shell. + +6. [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. + +## Software Packages Required for Wi-Fi EFR32 NCP Devices + +1. [SiSDK package](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-gecko-sdk-extension), which can be installed as part of the Simplicity Studio tool installation. + +2. [WiSeConnect SDK v2.x for RS9116 NCP](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-wiseconnect-sdk-v2x-or-v3x-extension), which can be installed as part of the Simplicity Studio tool installation. + +3. [WiSeConnect SDK v3.x for SiWx917 NCP](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-wiseconnect-sdk-v2x-or-v3x-extension), which can be installed as part of the Simplicity Studio tool installation. + +4. [Firmware for RS9116 NCP](./matter-artifacts.md#rs9116-firmware) + +5. [Firmware for SiWx917 NCP](./matter-artifacts.md#siwx917-firmware-for-siwn917-ncp-and-siwg917-soc) + +## Software Packages Required for Wi-Fi SiWx917 SoC Devices + +1. [SiSDK package](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-gecko-sdk-extension), which can be installed as part of the Simplicity Studio tool installation. + +2. [WiSeConnect SDK v3.x](/matter/{build-docspace-version}/matter-wifi-getting-started-example/software-installation#installation-of-wiseconnect-sdk-v2x-or-v3x-extension), which can be installed as part of the Simplicity Studio tool installation. + +3. [Firmware for SoC](./matter-artifacts.md#siwx917-firmware-for-siwn917-ncp-and-siwg917-soc) diff --git a/sld250-matter-references/commit-hashes.md b/sld250-matter-references/commit-hashes.md new file mode 100644 index 0000000..aa2100c --- /dev/null +++ b/sld250-matter-references/commit-hashes.md @@ -0,0 +1,29 @@ +# Matter Commit Hashes + +## Repositories + +The following repositories, branches, and commit hashes are to be used together in this release of the Silicon Labs Matter Out of Box Experience. + +### Open Thread Border Router (OTBR) + +| Repo | Branch | Commit Hash | +| ------------------------------------------ | ------ | ---------------------------------------- | +| https://github.com/SiliconLabs/ot-br-posix | main | 42f98b27b | + +### Radio Co-Processor (RCP) + +| Repo | Branch | Commit Hash | +| --------------------------------------- | ------ | ---------------------------------------- | +| https://github.com/SiliconLabs/ot-efr32 | main | e75c76737 | + +### Matter chip-tool + +| Repo | Branch | Commit Hash | +| ----------------------------------------------- | ------ | ---------------------------------------- | +| https://github.com/openthread/openthread | main | 7074a43e4 | + +### Connectivity Standards Alliance connectedhomeip (Matter) + +| Repo | Branch | Commit Hash | +| ----------------------------------------------- | ------ | ---------------------------------------- | +| https://github.com/project-chip/connectedhomeip | master | d140d5c8775 | diff --git a/sld250-matter-references/custom-matter-device.md b/sld250-matter-references/custom-matter-device.md new file mode 100644 index 0000000..8a92246 --- /dev/null +++ b/sld250-matter-references/custom-matter-device.md @@ -0,0 +1,127 @@ +# Custom Matter Device Development + +Build a customizable lighting app using the Matter protocol. + +## Overview + +This guide covers 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 + +In Studio, navigate to the ZAP UI in your project by double clicking the zap file +located at `config/zap/lighting-app.zap`. + +On the left 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 side of the application +brings 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 a lighting application 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 a +lighting application does not 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. + +## 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 generate.py script above. + +## React to Level Control Cluster Commands in ZclCallbacks + +In the MatterPostAttributeCallback function in ZclCallbacks, add the following +line of code or a similar line. This will give the application the ability to react to +MoveToLevel commands. You can define platform-specific behavior for a +MoveToLevel action. + + ```cpp + 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. + +```shell +$ mattertool levelcontrol read current-level 1 1 // Returns 1 +``` + +```shell +$ mattertool levelcontrol move-to-level {desired_level} 0 1 1 {node_ID} 1 +``` + +```shell +$ mattertool levelcontrol read current-level 1 1 // Returns 10 +``` + +For more information on running a Silicon Labs lighting example on a Thunderboard Sense 2 see you can view documentation in the Silicon Labs Matter GitHub Repo. + +## Defining a Custom Cluster + +Create an XML file with custom cluster definitions. For an example, see [Sample MEI Cluster](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml). In ZAP click 'Extensions' and add the XML file. The newly defined cluster can then be enabled in any endpoint under the domain for which it was defined (for example General), its Commands and Attributes can be managed like those of any other cluster. diff --git a/sld250-matter-references/find-raspi.md b/sld250-matter-references/find-raspi.md new file mode 100644 index 0000000..7ef4327 --- /dev/null +++ b/sld250-matter-references/find-raspi.md @@ -0,0 +1,60 @@ +# How to find your Raspberry Pi on the Network + +## Finding the IP address of your Raspberry Pi + +Sometimes it can be difficult to find your Raspberry Pi on the network. One way of interacting with the Raspberry Pi is to connect a keyboard, mouse, and monitor to it. The preferred method, however, is over SSH. For this, you will need to know the IP address of your Raspberry Pi. + +This is a [good tutorial](https://raspberryexpert.com/find-raspberry-pi-ip-address/) on how to find the IP address. + +### Mac / Linux + +***Nmap*** + +The use of nmap on the Mac may require a software download. +Use nmap with the following command: + +```shell + $ sudo nmap -sn .0/24` +``` + +Example: `sudo nmap -sn 1-.4.148.0/24`, Among other returned values, you will see something: + +```shell + $ Nmap scan report for ubuntu.silabs.com (10.4.148.44) + $ Host is up (0.00025s latency). + $ MAC Address: E4:5F:01:7B:CD:12 (Raspberry Pi Trading) +``` + +And this is the Raspberry Pi at 10.4.148.44. + +***Arp*** + +Alternatively, use Arp with the following command: + +```shell + $ arp -a \| grep -i "b8:27:eb\|dc:a6:32"` +``` + +### Windows + +In the command prompt, use `nslookup` to fnd your Raspberry Pi. + +Example: `nslookup ubuntu` + +## Connecting to your Raspberry Pi over SSH + +### Mac / Linux / Windows + +Once you have found your Raspberry Pi's IP address, you can use Secure Shell (SSH) to connect to it over the command line with the following command: + +```shell + $ ssh @ +``` + +Example: + +```shell + $ ssh ubuntu@10.4.148.44 +``` + +`password: raspberrypi or ubuntu` When prompted provide the raspberry pi's password, in the case of the Silicon Labs Matter Hub image the username is `ubuntu` and the password is either `ubuntu` or ``. (Note that if you are logging into your Raspberry Pi for the first time you may be asked to change the default password to a password of your choosing.) diff --git a/sld250-matter-references/flash-silabs-device.md b/sld250-matter-references/flash-silabs-device.md new file mode 100644 index 0000000..4eb7f2c --- /dev/null +++ b/sld250-matter-references/flash-silabs-device.md @@ -0,0 +1,24 @@ +# How to Flash a Silicon Labs Device + +Once you have an image built, you can flash it onto your EFR or SiWx917 device (either a development board or the Thunderboard Sense 2) over USB connected to your development machine. This can be done using either Simplicity Studio or the standalone Simplicity Commander. + +## Simplicity Studio + +Simplicity Studio is a complete development environment and tool suite. It has the ability to discover USB-connected development boards and flash them. + +- [Download Simplicity Studio](https://www.silabs.com/developers/simplicity-studio). +- Building application Using Simplicity Studio: + - [Build Application for EFR32](/matter/{build-docspace-version}/matter-wifi-run-demo/build-efx32-application-using-studio) + - [Build Application for SoC](/matter/{build-docspace-version}/matter-wifi-run-demo/build-soc-application-using-studio) +- Flash application Using Simplicity Studio: + - [Build Application for EFR32 Step 9](/matter/{build-docspace-version}/matter-wifi-run-demo/build-efx32-application-using-studio) + - [Build Application for SoC Step 9](/matter/{build-docspace-version}/matter-wifi-run-demo/build-soc-application-using-studio) +- [Simplicity Studio Reference Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-building-and-flashing/flashing) + +## Simplicity Commander + +Links to download Simplicity Commander's standalone versions are included below. Full documentation on Simplicity Commander is included in the [Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf) + +- Linux: https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip +- Mac: https://www.silabs.com/documents/public/software/SimplicityCommander-Mac.zip +- Windows: https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip diff --git a/sld250-matter-references/images/address-encryption.png b/sld250-matter-references/images/address-encryption.png new file mode 100644 index 0000000..6f1f663 Binary files /dev/null and b/sld250-matter-references/images/address-encryption.png differ diff --git a/sld250-matter-references/images/application-upload-erase-flash.png b/sld250-matter-references/images/application-upload-erase-flash.png new file mode 100644 index 0000000..4d01d17 Binary files /dev/null and b/sld250-matter-references/images/application-upload-erase-flash.png differ diff --git a/sld250-matter-references/images/attestation-overview.png b/sld250-matter-references/images/attestation-overview.png new file mode 100644 index 0000000..a0b069c Binary files /dev/null and b/sld250-matter-references/images/attestation-overview.png differ diff --git a/sld250-matter-references/images/certificate-authentication.png b/sld250-matter-references/images/certificate-authentication.png new file mode 100644 index 0000000..680ddd6 Binary files /dev/null and b/sld250-matter-references/images/certificate-authentication.png differ diff --git a/sld250-matter-references/images/commander-flash-map.png b/sld250-matter-references/images/commander-flash-map.png new file mode 100644 index 0000000..796a56b Binary files /dev/null and b/sld250-matter-references/images/commander-flash-map.png differ diff --git a/sld250-matter-references/images/commissioning-overview.png b/sld250-matter-references/images/commissioning-overview.png new file mode 100644 index 0000000..e325a3e Binary files /dev/null and b/sld250-matter-references/images/commissioning-overview.png differ diff --git a/sld250-matter-references/images/commissioning-steps1-4.png b/sld250-matter-references/images/commissioning-steps1-4.png new file mode 100644 index 0000000..0cce7f8 Binary files /dev/null and b/sld250-matter-references/images/commissioning-steps1-4.png differ diff --git a/sld250-matter-references/images/commissioning-steps5-7.png b/sld250-matter-references/images/commissioning-steps5-7.png new file mode 100644 index 0000000..a144df5 Binary files /dev/null and b/sld250-matter-references/images/commissioning-steps5-7.png differ diff --git a/sld250-matter-references/images/commissioning-steps8-10.png b/sld250-matter-references/images/commissioning-steps8-10.png new file mode 100644 index 0000000..89db9ee Binary files /dev/null and b/sld250-matter-references/images/commissioning-steps8-10.png differ diff --git a/sld250-matter-references/images/dcl-overview.png b/sld250-matter-references/images/dcl-overview.png new file mode 100644 index 0000000..05989dc Binary files /dev/null and b/sld250-matter-references/images/dcl-overview.png differ diff --git a/sld250-matter-references/images/door-lock-attributes.png b/sld250-matter-references/images/door-lock-attributes.png new file mode 100644 index 0000000..dc49b4d Binary files /dev/null and b/sld250-matter-references/images/door-lock-attributes.png differ diff --git a/sld250-matter-references/images/door-lock-commands.png b/sld250-matter-references/images/door-lock-commands.png new file mode 100644 index 0000000..0fc3a79 Binary files /dev/null and b/sld250-matter-references/images/door-lock-commands.png differ diff --git a/sld250-matter-references/images/edit-endpoint.png b/sld250-matter-references/images/edit-endpoint.png new file mode 100644 index 0000000..0b4447a Binary files /dev/null and b/sld250-matter-references/images/edit-endpoint.png differ diff --git a/sld250-matter-references/images/endpoint-0.png b/sld250-matter-references/images/endpoint-0.png new file mode 100644 index 0000000..daf4b98 Binary files /dev/null and b/sld250-matter-references/images/endpoint-0.png differ diff --git a/sld250-matter-references/images/endpoint-1.png b/sld250-matter-references/images/endpoint-1.png new file mode 100644 index 0000000..68bd389 Binary files /dev/null and b/sld250-matter-references/images/endpoint-1.png differ diff --git a/sld250-matter-references/images/internal-flash-layout.png b/sld250-matter-references/images/internal-flash-layout.png new file mode 100644 index 0000000..138c6de Binary files /dev/null and b/sld250-matter-references/images/internal-flash-layout.png differ diff --git a/sld250-matter-references/images/multiple-endpoints.png b/sld250-matter-references/images/multiple-endpoints.png new file mode 100644 index 0000000..5ec5a90 Binary files /dev/null and b/sld250-matter-references/images/multiple-endpoints.png differ diff --git a/sld250-matter-references/images/payload-encryption.png b/sld250-matter-references/images/payload-encryption.png new file mode 100644 index 0000000..fc5900c Binary files /dev/null and b/sld250-matter-references/images/payload-encryption.png differ diff --git a/sld250-matter-references/images/studio-project.png b/sld250-matter-references/images/studio-project.png new file mode 100644 index 0000000..fe28dcd Binary files /dev/null and b/sld250-matter-references/images/studio-project.png differ diff --git a/sld250-matter-references/images/thread-overview.png b/sld250-matter-references/images/thread-overview.png new file mode 100644 index 0000000..c20a9c5 Binary files /dev/null and b/sld250-matter-references/images/thread-overview.png differ diff --git a/sld250-matter-references/images/tutorial1.png b/sld250-matter-references/images/tutorial1.png new file mode 100644 index 0000000..8ccf996 Binary files /dev/null and b/sld250-matter-references/images/tutorial1.png differ diff --git a/sld250-matter-references/images/tutorial2.png b/sld250-matter-references/images/tutorial2.png new file mode 100644 index 0000000..f72d89c Binary files /dev/null and b/sld250-matter-references/images/tutorial2.png differ diff --git a/sld250-matter-references/images/wireshark-capture-1.png b/sld250-matter-references/images/wireshark-capture-1.png new file mode 100644 index 0000000..d087e0d Binary files /dev/null and b/sld250-matter-references/images/wireshark-capture-1.png differ diff --git a/sld250-matter-references/images/wireshark-capture-2.png b/sld250-matter-references/images/wireshark-capture-2.png new file mode 100644 index 0000000..2953631 Binary files /dev/null and b/sld250-matter-references/images/wireshark-capture-2.png differ diff --git a/sld250-matter-references/images/wireshark-capture-3.png b/sld250-matter-references/images/wireshark-capture-3.png new file mode 100644 index 0000000..ae93bb6 Binary files /dev/null and b/sld250-matter-references/images/wireshark-capture-3.png differ diff --git a/sld250-matter-references/images/wireshark-capture-4.png b/sld250-matter-references/images/wireshark-capture-4.png new file mode 100644 index 0000000..c359f72 Binary files /dev/null and b/sld250-matter-references/images/wireshark-capture-4.png differ diff --git a/sld250-matter-references/images/zap-attributes.png b/sld250-matter-references/images/zap-attributes.png new file mode 100644 index 0000000..07d1f9e Binary files /dev/null and b/sld250-matter-references/images/zap-attributes.png differ diff --git a/sld250-matter-references/images/zap-commands.png b/sld250-matter-references/images/zap-commands.png new file mode 100644 index 0000000..6e7e959 Binary files /dev/null and b/sld250-matter-references/images/zap-commands.png differ diff --git a/sld250-matter-references/images/zap-endpoint-1.png b/sld250-matter-references/images/zap-endpoint-1.png new file mode 100644 index 0000000..56d5513 Binary files /dev/null and b/sld250-matter-references/images/zap-endpoint-1.png differ diff --git a/sld250-matter-references/images/zap-endpoint.png b/sld250-matter-references/images/zap-endpoint.png new file mode 100644 index 0000000..9f46e85 Binary files /dev/null and b/sld250-matter-references/images/zap-endpoint.png differ diff --git a/sld250-matter-references/images/zap-intro.png b/sld250-matter-references/images/zap-intro.png new file mode 100644 index 0000000..f391a5a Binary files /dev/null and b/sld250-matter-references/images/zap-intro.png differ diff --git a/sld250-matter-references/images/zcl-welcome.png b/sld250-matter-references/images/zcl-welcome.png new file mode 100644 index 0000000..5627e8b Binary files /dev/null and b/sld250-matter-references/images/zcl-welcome.png differ diff --git a/sld250-matter-references/index.md b/sld250-matter-references/index.md new file mode 100644 index 0000000..39ae2bf --- /dev/null +++ b/sld250-matter-references/index.md @@ -0,0 +1,13 @@ +# References + +The reference pages provide detailed information and instructions on these topics. + +- [Matter Commit Hashes](commit-hashes.md) +- [How to Flash a Silicon Labs Device](flash-silabs-device.md) +- [Matter Versioning Scheme and Release Maintenance](versioning-release-maintenance.md) +- [How to Find Your Raspberry Pi](find-raspi.md) +- [Using Development Tools in Simplicity Studio](using-studio.md) +- [Building a Custom Matter Device](custom-matter-device.md) +- [Building a Multi-Endpoint Device](multi-endpoint-device.md) +- [Using ZAP, the ZCL Advanced Platform](matter-zap.md) +- [Using Wireshark with Matter](matter-wireshark.md) diff --git a/sld250-matter-references/matter-ep.md b/sld250-matter-references/matter-ep.md new file mode 100644 index 0000000..8978f39 --- /dev/null +++ b/sld250-matter-references/matter-ep.md @@ -0,0 +1,14 @@ +# Using Simplicity Studio's Energy Profiler with Matter + +Simplicity Studio's Energy Profiler allows the developer to see a graphical view +of their device's 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 inside Simplicity +Studio, 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/) diff --git a/sld250-matter-references/matter-gatt.md b/sld250-matter-references/matter-gatt.md new file mode 100644 index 0000000..27b8b79 --- /dev/null +++ b/sld250-matter-references/matter-gatt.md @@ -0,0 +1,44 @@ +# Using Simplicity Studio's GATT Configurator with Matter + +The Simplicity Studio Bluetooth LE (BLE) GATT Configurator is an Advanced Configurator +within the Simplicity Studio Project Configuration suite. For more information on +using the +[Simplicity Studio Project Configurator in Matter refer to this guide](./matter-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. + +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.](./matter-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. diff --git a/sld250-matter-references/matter-pintool.md b/sld250-matter-references/matter-pintool.md new file mode 100644 index 0000000..33b2088 --- /dev/null +++ b/sld250-matter-references/matter-pintool.md @@ -0,0 +1,51 @@ +# Using Simplicity Studio's Pintool and Project Configuration with Matter + +At some point during product development you may need to move your project over to your custom hardware. In this case, +you will likely need to change the pinout and hardware configuration 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. Locate 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 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. In Simplicity Studio click `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. Select the `Empty C++ Project` example and click **Next**. + +1. Click **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, 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. Copy these files +into your Matter project so that they can be used in place of the ones provided +in the example. diff --git a/sld250-matter-references/matter-wireshark.md b/sld250-matter-references/matter-wireshark.md new file mode 100644 index 0000000..72e1193 --- /dev/null +++ b/sld250-matter-references/matter-wireshark.md @@ -0,0 +1,178 @@ +# Using Wireshark to Capture Network Traffic in Matter + +When developing a wireless application, it is often useful to visualize the network traffic. This is either to study the communication between devices or to debug networking issues. Below are the most common ways to debug networking issues: + +- Use Wireshark with the Matter Wireshark dissector +- Use logging to dump out the unencrypted network traffic from the device itself +- Use Silicon Labs' Network Analyzer to analyze the underlying Thread (+BLE for commissioning) traffic + +## Use Wireshark Together with the Matter Wireshark Dissector + +[Wireshark](https://www.wireshark.org/) is a great tool for analyzing network packets, but the default Wireshark offering does not include decoding of Matter Network Packets. To enable Matter decoding, you must capture the network traffic using a wireless network interface. You also need to provide Wireshark with something called a Matter dissector for Wireshark to understand the Matter protocol and dissect Matter network packages. + +Below are the steps to capture and visualize network traffic with Wireshark and the Matter Wireshark dissector: + +## 1. Rebuild the Matter Application and CHIP-tool Using CHIP_CONFIG_SECURITY_TEST_MODE + +The Matter protocol implements strict and mandatory security requirements. These include end-to-end message encryption, which prevents network packets from being analyzed even if captured. To analyze Matter network traffic for development purposes, we must disable this feature from all devices involved in the network traffic to analyze. These devices include CHIP-tool running on a Matter controller or Matter End Devices. + +To do this, you must rebuild the firmware for the involved devices with __CHIP_CONFIG_SECURITY_TEST_MODE__ enabled. + +For example, with a Silicon Labs sample Matter application developed using the Matter Extension, you can enable this option within the header file _CHIPProjectConfig.h_: + +~~~ +// For convenience, Chip Security Test Mode can be enabled and the +// requirement for authentication in various protocols can be disabled. +// +// WARNING: These options make it possible to circumvent basic Chip security functionality, +// including message encryption. Because of this they MUST NEVER BE ENABLED IN PRODUCTION BUILDS. +// +#define CHIP_CONFIG_SECURITY_TEST_MODE 1 +~~~ + +__IMPORTANT NOTICE: disable security ONLY for development purposes only. This option MUST always be DISABLED for production (default).__ + +## 2. Capture Matter Network Traffic Using a Sniffer + +After disabling network security, you need to capture the specific network traffic you need to analyze. This will depend on the networking protocol you use to transport Matter messages. + +For example, if you use Matter over Thread, you need a Thread sniffer, and if you use Matter over Wi-Fi, you need to capture Wi-Fi traffic. + +With Matter over Thread, you can sniff Thread traffic using a Silicon Labs WSTK and the Network Analyzer from Simplicity Studio v5. For this, you can refer to section 5.4 of [QSG170: Silicon Labs OpenThread QuickStart Guide](https://www.silabs.com/documents/public/quick-start-guides/qsg170-openthread-sdk-quick-start-guide.pdf). + +After capturing Thread network traffic, export it as a PCAPNG file, which is a file format that can be read by Wireshark. At this point, you can only see Thread traffic since Wireshark currently cannot decode the Matter layer of the network packet yet: + +![Wireshark Missing Encoding](images/wireshark-capture-1.png) + +## 3. Follow instructions on the CSA Matter Dissector Repository to Build/Install Wireshark and the Dissector + +For Wireshark to decode Matter network packets, you need to add a protocol dissector designed for Matter specifically. + +The CSA has a Matter Dissector project that can be used by Wireshark to decode Matter packets. To use it, follow the CSA guide: [Matter-Dissector: Wireshark plugin for parsing Matter protocol messages](https://github.com/project-chip/matter-dissector/tree/main). Note that at the time of this writing, this dissector only works on Linux and the quality is still experimental. + +Here are the steps to properly set up and run Wireshark with Matter dissector: + +1. Setup your workspace. + + ```shell + mkdir ~/my_folder + cd ~/my_folder + ``` + + On your Linux machine, create a new folder. This folder will contain both Wireshark and Matter Dissector repositories. Doing this will help the setup scripts to run by default and avoid PATH issues. + +2. Install dependencies and build Wireshark. + + ``` + cd ~/my_folder + sudo apt-get build-dep wireshark + git clone https://gitlab.com/wireshark/wireshark.git + cd wireshark + git checkout release-3.6 + mkdir build + cd build + cmake .. + make + sudo make install + sudo ldconfig + ``` + +3. Clone, build, and install the Matter dissector. + + ```shell + cd ~/my_folder + git clone git@github.com:project-chip/matter-dissector.git + cd matter-dissector + make + make install + ``` + +## 4. Do a Test Run with the Matter Dissector to Verify Everything Runs Correctly + +After building and installing both Wireshark and Matter dissector, it is a good idea to do a test run with an example capture file. + +To do this, run: + +```shell +cd ~/my_folder/ +cd matter-dissector +make test +``` + +You should see Wireshark opening and decoding a sample Matter network capture file: + +![Wireshark Sample Matter Capture](images/wireshark-capture-2.png) + +## 5. Add Security Keys (When Applicable) for Wireshark to Decrypt Messages + +The Matter dissector should be able to decode Matter traffic once the security has been disabled. However, Wireshark still needs to decode the underlying network transport if any encryption is involved. + +In the case of Matter over Thread, Wireshark needs the Thread network key. You can get the Thread network key from the OpenThread CLI of a device on the network. For example: + +```shell +matterCli> otcli networkkey +otcli networkkey + +ae34121ba022213d60d892cbf5a72081 +Done +``` + +After obtaining the Thread network key, add this key to Wireshark for it to decode Thread network traffic. To do this, choose Edit > Preferences > Protocols > IEEE 802.15.4: + +![Wireshark Protocols](images/wireshark-capture-3.png) + +Add the network key you just acquired as **Decryption key** and select **OK**: + +![Wireshark Add Key](images/wireshark-capture-4.png) + +## 6. Analyze Matter Traffic Captured in Step 2 + +At this point, Wireshark is ready to decrypt and analyze the Matter traffic (with security disabled) that you captured earlier. + +You can now use Wireshark to open the PCAPNG file you exported at __step 2__ and proceed to do Matter network analysis. + +## Use Logging to Dump Out the Network Traffic + +Since Matter is open-source software, you have access to the end device source code and can see incoming and outgoing messages when they are not encrypted. This allows you to dump out this unencrypted network traffic (for development purposes only) using any other communication channel. This includes but is not limited to RTT log or UART log. + +You can view unencrypted Matter messages within the function _SessionManager::PrepareMessage_. At this point, you can either implement a method for network traffic dump or use Matter's existing infrastructure for messages trace (highly recommended). + +If you choose the latter option, here are the steps: + +### 1. Enable Matter Transport Trace + +You need to enable this option within _CHIPBuildConfig.h_: + +~~~ +CHIP_CONFIG_TRANSPORT_TRACE_ENABLED +~~~ + +With this enabled, Matter will begin tracing unencrypted messages. One of the places where unencrypted message trace takes place within Matter SDK includes: + +~~~ +// Trace before any encryption +MATTER_LOG_MESSAGE_SEND(chip::Tracing::OutgoingMessageType::kGroupMessage, &payloadHeader, &packetHeader, + chip::ByteSpan(message->Start(), message->TotalLength())); + +CHIP_TRACE_MESSAGE_SENT(payloadHeader, packetHeader, destination_address, message->Start(), message->TotalLength()); +~~~ + +### 2. Implement Method to Dump Out Network Traffic + +To do this, you need to implement a method to dump out network traffic. + +For this, you need to implement the function _HandleTransportTrace()_, which is already called to perform message tracing by the Matter SDK when you enable CHIP_CONFIG_TRANSPORT_TRACE_ENABLED. + +Here is its prototype: + +~~~ +void HandleTransportTrace(const char * type, const void * data, size_t size); +~~~ + +After _HandleTransportTrace()_ is properly implemented for message tracing, you should see unencrypted messages on the communication channel you chose earlier (UART, RTT, etc.). + +## Use Silicon Labs' Network Analyzer to Analyze the Underlying Thread and BLE Network Traffic + +To analyze BLE network traffic, refer to [AN1317: Using Network Analyzer with Bluetooth® Low Energy and Mesh](https://www.silabs.com/documents/public/application-notes/an1317-network-analyzer-with-bluetooth-mesh-le.pdf). + +For Thread network analysis, refer to section 5.4 of [QSG170: Silicon Labs OpenThread QuickStart Guide](https://www.silabs.com/documents/public/quick-start-guides/qsg170-openthread-sdk-quick-start-guide.pdf). diff --git a/sld250-matter-references/matter-zap.md b/sld250-matter-references/matter-zap.md new file mode 100644 index 0000000..5cd305d --- /dev/null +++ b/sld250-matter-references/matter-zap.md @@ -0,0 +1,197 @@ +# ZCL Advanced Platform (ZAP) Tool for Matter + +## Overview + +EFR32 example applications provide a baseline demonstration of a lock device, +built using the Matter SDK and the Silicon Labs SDK. It can be controlled +by a CHIP controller over OpenThread network. + +The EFR32 device can be commissioned over Bluetooth Low Energy (BLE) where the +device and the CHIP controller will exchange security information with the +Rendez-vous procedure. Thread Network credentials are provided to the EFR32 +device which will then join the network. + +The LCD on the Silicon Labs WSTK shows a QR Code containing the needed +commissioning information for the BLE connection and starting the Rendez-vous +procedure. + +The lock example is intended to serve both as a means to explore the workings of +CHIP, and a template for creating real products on the Silicon Labs platform. + +Each Matter application consists of the following layers: + +- Matter SDK: Source code necessary to communicate through the Matter network over Thread or 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 + endpoint + - Identify cluster is an example of a Utility Cluster. Given a Node + ID, it can be used to Blink LED0 to the corresponding Silicon Labs WSTK + - Application Clusters: + - These clusters represent functionalities specific to a given + application + - Door Lock Cluster is an example of an Application specific cluster. + This cluster contains commands to lock and unlock a door(door-lock is represented by an LED), with options to set passwords and lock schedules + +## Clusters + +Every Matter Application uses multiple clusters leveraged from the Zigbee +Cluster Library (ZCL). A cluster can be seen as a building block for the Data +Model of a Matter application. Clusters contains attributes, commands, and +events. Attributes are customizable variables specified by the Zigbee Advanced +Platform (ZAP) tool. Commands are sent to the application, which may respond with +data, LED flickering, lock actuation, etc. Events are notifications sent out by +the server. + +An application can have multiple Matter endpoints. Application endpoints +generally refer to one device, and inherits its information from the "cluster" +it belongs to. Utility clusters are required to be on the endpoint with ID 0. +Application clusters are assigned to endpoints with IDs 1 and higher. + +Some applications have callbacks that are left to be implemented by the device +manufacturer. For example, the storage and management of users and credentials in +the lock-app is left up to the application developer. + +>**Note**: When enabling clusters in a Matter project within Simplicity Studio, users should always modify the cluster within the **ZCL Advanced Platform (ZAP)** and _not_ manually install the corresponding cluster component within the **Software Components** tab. + +## ZAP Tool + +The ZAP tool is built and maintained by Silicon Labs and developers in the ZAP +open source 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 no longer present as a submodule in the Matter repo. The ZAP tool can be downloaded as a binary from GitHub or optionally you can clone the entire ZAP repo and build the ZAP binary from scratch. + +ZAP binaries can be downloaded from the latest ZAP release here: + +`https://github.com/project-chip/zap/releases/latest` + +Optionally, the ZAP tool can be cloned using the following git command. This will create a +root level zap folder in your current directory. + +`$ git clone https://github.com/project-chip/zap.git` + +The ZAP tool can be invoked using the `run_zaptool.sh` script located in the Matter repo at `./scripts/tools/zap/run_zaptool.sh`. Before you run this script you have to provide the location of the ZAP instance to be run. This is either the binary that you downloaded or the binary that you built from scratch in the ZAP repo. You can do this by setting the `ZAP_INSTALL_PATH` environment variable +like this: + +`$ export ZAP_INSTALL_PATH=(path to your instance of the ZAP binary)` + +The `run_zaptool.sh` script can be invoked without arguments, or, you can +provide the path to a ZAP file to be opened upon launch. + +In the following examples, the ZAP file for the lock-app has been chosen. + +`$ ./scripts/tools/zap/run_zaptool.sh ($PATH_TO_ZAP_FILE)` + +ZAP files for the various sample applications are included in the sample applications `data_model` directory such as + +`./examples/lighting-app/silabs/data_model/lighting-thread-app.zap`. + +This shows the output of the `run_zaptool` script with no arguments. To load a new +zap file, click the application menu for Electron (Upper left corner of the +screen for macs), then click "Open File". Then navigate to the desired .zap +file. + +![ZAP Introduction Page](images/zcl-welcome.png) + +This shows the output of the run_zaptool script with a zap file given as an +argument, or after a .zap file has been opened in the ZAP UI. An Electron +application will open, pre-loaded with the information from the .zap file +provided as a command line argument. + +![ZAP Endpoint](images/endpoint-0.png) + +The Out of the box (OOB) example lock application has 2 endpoints. Endpoint 0 is +called the root node. It contains all Service and Device management clusters. In +general, any cluster or feature that is not specific to a device type belongs in +Endpoint 0. Examples of clusters one might find in Endpoint 0: Device Descriptor +cluster, Network Diagnostics cluster. + +Endpoint 1 contains information specific to the device type. Conveniently, the +ZAP tool offers a Door lock cluster, which contains Commands (lock, unlock, set +credential, and so on) and Attributes (Lock state, Require PIN) that a standard door +lock application might use. + +More endpoints can be added. Each endpoint acts like a port on a network +interface. + +Endpoints contain clusters which are bundles of device functionality. Clusters +have both a Client and a Server interface. In general the Client interface sends +commands and the Server interface receives them. For instance a Light would +implement the Server side of the on/off clusters. A Switch would implement the +Client side of the same cluster. + +Click on Endpoint 1 on the left hand side of the application. The door lock +cluster should already be enabled as "Server". + +![ZAP Endpoint 1](images/endpoint-1.png) + +## Attributes + +Attributes are analogous to member variables of a class. Each attribute is +provided with generated setter/getter code from the ZAP tool. They can be +enabled or disabled for each cluster on a Matter endpoint. Some attributes are +required to be enabled, else the application will not function properly. There +is an option to add attributes to either the server code or client code. The ZAP +tool also allows you choose a storage space for attributes. Attributes can be +stored in standard RAM, Non-volatile memory or external memory. Each attribute +has a type, some are standard C types and some have specially defined enums. +Each attribute can be provided with a default starting value value. + +Click the settings wheel to enable/disable, choose a storage option, and choose +a default value for attributes, commands and events for Endpoint 1. + +![ZAP Attributes](images/door-lock-attributes.png) + +## Commands + +Commands can be enabled/disabled like attributes. Some commands are required for +an application to function properly. Many of the functions run when a command is +received are implemented on the server side. But some of these are left up to +the application to define. In the EFR32 lock example, the set/get user and +credential functions are customizable as each implementation of a lock might +store these differently. + +![ZAP Commands](images/door-lock-commands.png) + +## Generation of Code + +Once you have chosen the cluster options, save the current ZAP configuration using the application menu in the upper left corner. + +Before v1.1.0-1.1 you needed to click the Generate button to generate code. Now, code is generated automatically in the save function. You will be prompted to choose a save location for the generated ZAP code. In the Silicon Labs Matter repository, the lock-app generated files belong in matter/zzz_generated/lock-app/zap-generated. + +## New Tutorial Button + +This new feature helps you understand all the steps needed to create a new endpoint. + +Click the **Tutorial** button at the top-right side, between the **Preview** and the **Settings** buttons. + +A pop-up displays with instructions for next steps. + +![Tutorial start page](images/tutorial1.png) + +These steps guide you on the components of this tool, the effects of each component, and the points you need to consider carefully when creating a new endpoint. + +![Tutorial end page](images/tutorial2.png) + +At the final step, a notification asks if you want to keep the endpoint you just created. Select what you want to finish the tutorial. + +## Multiple ZCL Device Types per Endpoint + +This is a new Matter-only feature where you can select more than one ZCL device type per endpoint. The addition of multiple device types will add the cluster configurations within the device types to the endpoint configuration. + +You can select multiple ZCL device types per endpoint, but there is only one **Primary Device** as in the below image. + +![Edit endpoint](images/edit-endpoint.png) + +The image above shows that endpoint 2 has more than one device type selected. The **Primary Device** denotes the primary device type that the endpoint will be associated with. The primary device type is always present at index 0 of the list of device types selected so selecting a different primary device type will change the ordering of the device types selected. The device type selections also have constraints based on the Data Model specification. ZAP protects you from choosing invalid combinations of device types on an endpoint using these constraints. + +![Multiple endpoints](images/multiple-endpoints.png) + +The image above is what the multiple device type endpoints looks like after configured. On the left-hand side, it shows the list of all clusters sequentially in order, and on the other side are clusters that are ready to be configured. + +## Defining a Custom Cluster + +Create an XML file with custom cluster definitions, for an example see [Sample MEI Cluster](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml). In ZAP click 'Extensions' and add the XML file. The newly defined cluster can then be enabled in any endpoint under the domain for which it was defined (for example General), its Commands and Attributes can be managed like those of any other cluster. diff --git a/sld250-matter-references/multi-endpoint-device.md b/sld250-matter-references/multi-endpoint-device.md new file mode 100644 index 0000000..766d8bc --- /dev/null +++ b/sld250-matter-references/multi-endpoint-device.md @@ -0,0 +1,5 @@ +# Creating a Multiple Endpoint Matter Device in Studio + +Matter products can have multiple device types spread out across different endpoints. The following guide walks the user through adding a lighting endpoint to the standard lock example in Simplicity Studio. + +[Develop a Lock + Light Example with Matter](https://github.com/SiliconLabs/matter_applications/blob/master/matter_thread_ww2023_mat-204_lock_light_mad/README.md). \ No newline at end of file diff --git a/sld250-matter-references/using-studio.md b/sld250-matter-references/using-studio.md new file mode 100644 index 0000000..4adcfb5 --- /dev/null +++ b/sld250-matter-references/using-studio.md @@ -0,0 +1,18 @@ +# Development Tools in Simplicity Studio + +Simplicity Studio contains a number of integrated tools that you can use with projects created within that environment. + +## Bluetooth GATT Configurator + +The Simplicity Studio Bluetooth LE (BLE) GATT Configurator is an Advanced Configurator within the Simplicity Studio Project Configuration suite. 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`. See the Simplicity Studio v5 User's Guide for more information on using the [BLE GATT Configurator](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/bluetooth-gatt-configurator). + +## Energy Profiler + +Simplicity Studio's Energy Profiler allows you to see a graphical view of your device's energy usage over time. This can be very useful when developing an energy-friendly device. + +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/latest/ss-5-users-guide-tools-energy-profiler/). + +## Custom Hardware Configuration + +At some point during product development you may need to move your project over to your custom hardware. In this case, you will likely need to change the pinout and hardware configuration in the example project to reflect your own custom project. You can do this using the Pin Tool. The Simplicity Studio 5 User's Guide contains full documentation using the [Pin Tool](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/pin-tool). diff --git a/sld250-matter-references/versioning-release-maintenance.md b/sld250-matter-references/versioning-release-maintenance.md new file mode 100644 index 0000000..1b36aeb --- /dev/null +++ b/sld250-matter-references/versioning-release-maintenance.md @@ -0,0 +1,73 @@ +# Matter Versioning and Release Maintenance + +**Silicon Labs Matter GitHub is being phased out in favor of using the Matter SiSDK Extension that is available through Simplicity Studio and standalone via SLC-CLI.** + +## Versioning Scheme + +- **FORMAT: vMAJOR.MINOR.PATCH\_VERSION-PRE\_RELEASE** + +- Silicon Labs versions e.g., 3.0.0 + +- Connectivity Standards Alliance Matter version e.g., 1.1 + +- [Optional] Prerelease flag e.g., alpha.1 + +**Example:** v3.0.0-1.1-alpha.1 + +Update digits based on the following criteria: + +- **Major** + + - Connectivity Standards Alliance ups the major version number, or + + - Major GSDK/SiSDK version supported, or + + - Miscellaneous breaking change + +- **Minor** + + - Minor GSDK/SiSDK version supported, or + + - Silabs updates e.g., new sample app, documentation, bug fixes, or + + - Silabs hardware platform added + +- **Patch** + + - Patch GSDK/SiSDK version supported, or + + - Targeted bug fixes + +- **Pre-Release** + + - As needed, e.g. release after TE1 can be called v2.3.2-1.2-alpha.1 + + - To identify targeted feature requests/SQA quality level testing + + - alpha level quality to identify non-standard SQA level testing + + - beta level quality to identify certain SQA testing, but still in early development + +## Release Maintenance + +### Matter Extension + +| **Release**|**Date**|**GSDK/SiSDK**|**WiSeConnect 3 SDK**|**Matter Spec Version**|**Status** | +|--------------|----------------|--------------------------------|----------|-----|------------| +| v1.0.1-1.0 | 19-Dec-22 | v4.2.0 | N/A | 1.0 | Obsolete | +| v1.0.3-1.0 | 3-Feb-23 | v4.2.1 | N/A | 1.0 | Obsolete | +| v1.0.4-1.0 | 16-Feb-23 | v4.2.1 | N/A | 1.0 | Obsolete | +| v1.0.5-1.0 | 10-Mar-23 | v4.2.2, v4.2.3, v4.2.4, v4.2.5 | N/A | 1.0 | Monitored | +| v2.0.0-1.1 | 8-June-23 | v4.3.0 | N/A | 1.1 | Obsolete | +| v2.1.0-1.1 | 27-July-23 | v4.3.1 | v3.0.10 | 1.1 | Obsolete | +| v2.1.1-1.1 | 9-Oct-23 | v4.3.2, v4.3.3 | v3.1.0 | 1.1 | Monitored | +| v2.2.0-1.2 | 13-Dec-23 | v4.4.0, v4.4.1 | v3.1.1 | 1.2 | Obsolete | +| v2.2.1-1.2 | 10-Apr-24 | v4.4.1, v4.4.2 | v3.1.4 | 1.2 | Maintained | +| v2.3.0-1.3 | 18-June-24 | 2024.6.0 | v3.3.0 | 1.3 | Obsolete | +| v2.3.1-1.3 | 14-August-24 | 2024.6.1 | v3.3.1 | 1.3 | Obsolete | +| v2.3.2-1.3 | 10-Oct-24 | 2024.6.2 | v3.3.2 | 1.3 | Maintained | +| v2.4.0-1.4 | 11-Nov-24 | 2024.6.2 | v3.3.4 | 1.4 | Maintained | +| v2.5.0-1.4 | 18-Dec-24 | 2024.12.0 | v3.4.0 | 1.4 | Obsolete | +| v2.5.1-1.4 | 12-Feb-25 | 2024.12.1 | v3.4.1 | 1.4 | Obsolete | +| v2.5.2-1.4 | 10-Apr-25 | 2024.12.2 | v3.4.2 | 1.4 | Maintained | +| v2.6.0-1.4 | 18-Jun-25 | 2025.6.0 | v3.5.0 | 1.4 | Active | diff --git a/sld251-matter-thread/build-flash-mad.md b/sld251-matter-thread/build-flash-mad.md new file mode 100644 index 0000000..a07e47d --- /dev/null +++ b/sld251-matter-thread/build-flash-mad.md @@ -0,0 +1,48 @@ +# How to Build and Flash the Matter Accessory Device (MAD) + +The Matter Accessory Device, such as the lighting-app, is the actual Matter device that you will commission onto the Matter network and control using the chip-tool. + +## Step 1: Get the Image File to Flash the MAD + +Use one of the following options to get the required image to flash the MAD: + +1. Use the pre-built image file from either Simplicity Studio or Silicon Labs Matter GitHub. +2. Build the image file from Simplicity Studio or out of the Silicon Labs Matter GitHub `matter` repository. + +### Using the Pre-Built Image File + +Prebuilt image files are available both on GitHub and inside Simplicity Studio. + +#### Simplicity Studio + +To find the demos within Simplicity Studio, even if you do not have a device connected: + +1. In Simplicity Studio, click the Launcher in the upper right hand corner. +2. Under **Get Started**, choose **All Products**. +3. Choose a board to start with such as **BRD4186C Rev A01** and click **Start**. This will bring up the Launcher window for that part. +4. In the top navigation, choose **Example Projects & Demos**. +5. In the left hand navigation, choose **Matter** to show all the Matter demos. +6. The demos are marked as "demo" and allow you to "run" them. Projects can be "created". +7. Choose the demo you wish to use, and click **Run** to flash it onto your board. + +#### Silicon Labs GitHub + +If you are interested in using prebuilt image files from GitHub, all of the Matter Accessory Device image files are accessible through the [Matter Artifacts page](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). If you are using a pre-built image file, you can skip forward to Step 2 below. + +If you are coming from Simplicity Studio, you may have already installed the demo image in Simplicity Studio, in which case you can skip forward to the next step. + +### Building the Matter Image File + +There are two ways to build a Matter Accessory Device image file. You can build it using the Silicon Labs Matter GitHub Repo or you can build it using Simplicity Studio. The entire build process for Simplicity Studio is covered in the [Matter Over Thread Quick Start Guide](/matter/{build-docspace-version}/matter-light-switch-example/02-thread-light-switch-example). +There are two ways to build a Matter Accessory Device image file. You can build it using the Silicon Labs Matter GitHub Repo or you can build it using Simplicity Studio. The entire build process for Simplicity Studio is covered in the [Matter Over Thread Quick Start Guide](/matter/{build-docspace-version}/matter-light-switch-example/02-thread-light-switch-example). + +- [Build Using the Matter GitHub Repo](https://github.com/SiliconLabs/matter/blob/latest/examples/lighting-app/silabs/efr32/README.md) +- [Build Using Simplicity Studio](/matter/{build-docspace-version}/matter-light-switch-example/02-thread-light-switch-example) + +## Step 2: Flash the Matter Accessory Device + +For more information on how to flash your Silicon Labs development platform, see the following instructions: [How to Flash a Silicon Labs Device](/matter/{build-docspace-version}/matter-references/flash-silabs-device). +For more information on how to flash your Silicon Labs development platform, see the following instructions: [How to Flash a Silicon Labs Device](/matter/{build-docspace-version}/matter-references/flash-silabs-device). + +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. Bootloader images are provided on the [Matter Artifacts page](/matter/{build-docspace-version}/matter-prerequisites/matter-artifacts). diff --git a/sld251-matter-thread/chip-tool.md b/sld251-matter-thread/chip-tool.md new file mode 100644 index 0000000..e0a763b --- /dev/null +++ b/sld251-matter-thread/chip-tool.md @@ -0,0 +1,187 @@ +# Using the Mattertool (chip-tool) + +The following commands show how to start a new Thread network from the local OTBR, commission an EFR32 Matter End Device (Matter Accessory Device), and then send the on/off commands with the `mattertool` automated script. The `mattertool` script provides an interface into various chip-tool and otbr commands used to create and interact with a Matter network. + +## Basic Mattertool Commands + +:::custom-table{width=20%,50%,30%} +| **Context** | **Command** | **Usage** | +| -------------- | ------------------------ | ------------------------------------------------------------------------- | +| `Initialization` | `mattertool startThread` | Start a Thread network on the OTBR | +| `Commissioning` | `mattertool bleThread` | Start Commissioning a Matter Device using the chip-tool | +| `Commissioning` | `mattertool pairing ble-thread `| Commission a Matter Device with provided pincode and discriminator | +| `Commissioning` | `mattertool pairing code ` | Commission a Matter Device on the IPv6 local network with pairing code | +| `Multi-fabric` | `mattertool pairing open-commissioning-window