diff --git a/sld248-matter-overview-guides/images/matter-shell-enable.png b/sld248-matter-overview-guides/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld248-matter-overview-guides/images/matter-shell-enable.png and b/sld248-matter-overview-guides/images/matter-shell-enable.png differ diff --git a/sld248-matter-overview-guides/images/matter-shell-lock-app.jpeg b/sld248-matter-overview-guides/images/matter-shell-lock-app.jpeg deleted file mode 100644 index 5cc9ded..0000000 Binary files a/sld248-matter-overview-guides/images/matter-shell-lock-app.jpeg and /dev/null differ diff --git a/sld248-matter-overview-guides/images/matter-shell-lock-app.png b/sld248-matter-overview-guides/images/matter-shell-lock-app.png new file mode 100644 index 0000000..2d3c3dc Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-shell-lock-app.png differ diff --git a/sld248-matter-overview-guides/images/matter-shell-project-generation.jpeg b/sld248-matter-overview-guides/images/matter-shell-project-generation.jpeg deleted file mode 100644 index d850220..0000000 Binary files a/sld248-matter-overview-guides/images/matter-shell-project-generation.jpeg and /dev/null differ diff --git a/sld248-matter-overview-guides/images/matter-shell-project-generation.png b/sld248-matter-overview-guides/images/matter-shell-project-generation.png new file mode 100644 index 0000000..2a72028 Binary files /dev/null and b/sld248-matter-overview-guides/images/matter-shell-project-generation.png differ diff --git a/sld248-matter-overview-guides/images/solution-artifacts.png b/sld248-matter-overview-guides/images/solution-artifacts.png index 581c4bc..7755714 100644 Binary files a/sld248-matter-overview-guides/images/solution-artifacts.png 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 index c4faeb7..29403e5 100644 Binary files a/sld248-matter-overview-guides/images/solution-generation.png and b/sld248-matter-overview-guides/images/solution-generation.png differ diff --git a/sld248-matter-overview-guides/matter-solutions.md b/sld248-matter-overview-guides/matter-solutions.md index 7821b1d..7839bdf 100644 --- a/sld248-matter-overview-guides/matter-solutions.md +++ b/sld248-matter-overview-guides/matter-solutions.md @@ -2,7 +2,7 @@ ## 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). +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 Thread - SoC Lighting with external Bootloader FreeRTOS 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 @@ -12,7 +12,7 @@ To create a Matter Solution, proceed to the **Example Project Selection** sectio ## 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. +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 `Binaries` 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) @@ -27,3 +27,5 @@ To create an OTA file, first build a Matter example via solutions. Locate the re ``` 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. + +> **Note**: The GBL file generated by Solutions is unsigned by default. For all Matter devices, the GBL must be signed with your device's ECDSA signing key before being packaged into the OTA file, so the bootloader can verify its authenticity. See [Enabling Secure Upgrades](/matter/{build-docspace-version}/matter-ota/01-ota-bootloader#enabling-secure-upgrades) for step-by-step instructions. diff --git a/sld248-matter-overview-guides/serial-port-communications.md b/sld248-matter-overview-guides/serial-port-communications.md index dd6db65..06326c6 100644 --- a/sld248-matter-overview-guides/serial-port-communications.md +++ b/sld248-matter-overview-guides/serial-port-communications.md @@ -30,11 +30,11 @@ To run matter shell on the Silicon Labs Platform, refer to the [Software Require 7. Click the **Create New Project** option and create a project for the Matter Lock Application. - ![Silicon Labs - design](./images/matter-shell-lock-app.jpeg) + ![Silicon Labs - design](./images/matter-shell-lock-app.png) 8. In the Project Configuration window, click **Finish**. - ![Silicon Labs - design](./images/matter-shell-project-generation.jpeg) + ![Silicon Labs - design](./images/matter-shell-project-generation.png) 9. After creation of project, open the **Software Components** tab and, in the search bar, type _Matter Shell_ and install it. diff --git a/sld249-matter-prerequisites/matter-artifacts.md b/sld249-matter-prerequisites/matter-artifacts.md index 95ff347..04abcc5 100644 --- a/sld249-matter-prerequisites/matter-artifacts.md +++ b/sld249-matter-prerequisites/matter-artifacts.md @@ -4,37 +4,37 @@ This page provides links to pre-built software image "artifacts" that can be use 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.8.1 +https://github.com/SiliconLabs/matter_extension/releases/tag/v2.9.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.8.0-1.5-extension.zip +https://www.silabs.com/documents/public/software/SilabsMatterPi_2.9.0-1.6-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.8.1/ot-rcp-binaries-2.8.1-1.5.zip +https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.0/ot-rcp-binaries-2.9.0-1.6.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.8.1/matter-accessory-device-images_2.8.1-1.5.zip +https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.0/matter-accessory-device-images_2.9.0-1.6.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.8.1/bootloader_binaries_matter_extension_v2.8.1-1.5.zip +https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.0/bootloader_binaries_matter_extension_v2.9.0-1.6.zip ## 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.8.1/SiWx917_firmware_files_2.8.1-1.5.zip +https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.0/SiWx917_firmware_files_2.9.0-1.6.zip **Note**: @@ -52,12 +52,12 @@ https://github.com/SiliconLabs/matter_extension/releases/download/v2.8.1/SiWx917 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.8.1/siwx917_rcp_files.zip +https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.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.8.1/JLinkDevices.xml.zip) and [RS9117_SF_4MB_42bsp.elf](https://github.com/SiliconLabs/matter_extension/releases/download/v2.8.1/RS9117_SF_4MB_42bsp.elf.zip) files referenced in the instructions may be found in the Assets section of this page. +The [JLinkDevices.xml](https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.0/JLinkDevices.xml.zip) and [RS9117_SF_4MB_42bsp.elf](https://github.com/SiliconLabs/matter_extension/releases/download/v2.9.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/sld250-matter-references/custom-matter-device.md b/sld250-matter-references/custom-matter-device.md index 30342b2..1d94cce 100644 --- a/sld250-matter-references/custom-matter-device.md +++ b/sld250-matter-references/custom-matter-device.md @@ -7,6 +7,31 @@ Build a customizable lighting app using the Matter protocol. This guide covers the basics of building a customizable lighting application using Matter. +## Application Customization Models + +Matter Extension 2.9.0 migrates a subset of sample apps to the Curiously Recurring Template Pattern (CRTP) based architecture, which removes app manager and DataModelCallbacks files. All other sample apps keep the previous architecture until the patch release. + +Check your project in Project Explorer: + +| If you see… | Architecture | Where to add custom logic | +|---|---|---| +| `src/CustomerAppTask.cpp` and `autogen/AppTask.cpp` | **New** | Override `*Impl()` hooks in `CustomerAppTask`, do not edit `autogen/AppTask.cpp` | +| `src/DataModelCallbacks.cpp` and editable `src/AppTask.cpp` | **Legacy** | Callbacks in `DataModelCallbacks.cpp`, init and app logic in `src/AppTask.cpp` | + +**Sample apps on the new architecture in 2.9.0:** + +- Lighting +- Zigbee Matter Light +- On/Off Plug +- Thermostat +- Lock +- Light Switch +- Rangehood +- Platform Template +- Air Quality Sensor + +All other Silicon Labs Matter sample apps in this release use the legacy model. Related guides label steps as **New architecture** or **Legacy architecture** where they differ. + ## Using Matter with Clusters In Matter, commands can be issued by using a cluster. A cluster is a set of @@ -61,6 +86,8 @@ 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. +Depending on your sample application, edit the files as described in [Application Customization Models](#application-customization-models). New architecture apps route attribute changes through `CustomerAppTask` and `DMPostAttributeChangeCallbackImpl()`. Legacy architecture apps implement `MatterPostAttributeChangeCallback()` directly in `src/DataModelCallbacks.cpp`. + ## Adding a Cluster to a ZAP Configuration In the ZAP UI, navigate to the Level Control cluster. Make sure this cluster is @@ -79,13 +106,31 @@ is set to enabled. Set the default value of this attribute as 1. 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 +## React to Level Control Cluster Commands + +### New Architecture + +In a custom implementation of `DMPostAttributeChangeCallbackImpl()` in `src/CustomerAppTask.cpp`, add the following or similar code. This enables the application to react to the MoveToLevel commands. + + ```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) + { + sLightLED.SetLevel(*value); + } + } + ``` + +### Legacy Architecture 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) { @@ -133,7 +178,7 @@ In order to use a custom cluster in an application, follow these steps: "value": "true" } ``` -For an example, see [Sample ZAP file](https://github.com/SiliconLabsSoftware/matter_extension/blob/release_2.8-1.5/slc/apps/performance-test-app/thread/performance-test-app.zap) +For an example, see [Sample ZAP file](https://github.com/SiliconLabsSoftware/matter_extension/blob/v2.9.0/slc/apps/performance_test_app/thread/performance-test-app.zap) - Install the **Custom ZAP generation** component under **Silicon Labs Matter -> Stack** in the project's Component Editor. diff --git a/sld250-matter-references/matter-zap.md b/sld250-matter-references/matter-zap.md index f2324cc..880553c 100644 --- a/sld250-matter-references/matter-zap.md +++ b/sld250-matter-references/matter-zap.md @@ -205,5 +205,5 @@ In order to use a custom cluster in an application, follow these steps: "value": "true" } ``` -For an example, see [Sample ZAP file](https://github.com/SiliconLabsSoftware/matter_extension/blob/release_2.8-1.5/slc/apps/performance-test-app/thread/performance-test-app.zap) +For an example, see [Sample ZAP file](https://github.com/SiliconLabsSoftware/matter_extension/blob/v2.9.0/slc/apps/performance_test_app/thread/performance-test-app.zap) - Install the **Custom ZAP generation** component under **Silicon Labs Matter -> Stack** in the project's Component Editor. diff --git a/sld250-matter-references/versioning-release-maintenance.md b/sld250-matter-references/versioning-release-maintenance.md index 850d15b..ce9fac9 100644 --- a/sld250-matter-references/versioning-release-maintenance.md +++ b/sld250-matter-references/versioning-release-maintenance.md @@ -73,4 +73,5 @@ Update digits based on the following criteria: | v2.6.1-1.4 | 23-Jul-25 | 2025.6.1 | v3.5.1 | 1.4 | Maintained | | v2.7.0-1.4 | 25-Sep-25 | 2025.6.2 | v3.5.2 | 1.4 | Maintained | | v2.8.0-1.5 | 12-Jan-25 | 2025.12.0 | v4.0.0 | 1.5 | Maintained | -| v2.8.1-1.5 | 23-Mar-25 | 2025.12.2 | v4.0.1 | 1.5 | Active | +| v2.8.1-1.5 | 23-Mar-25 | 2025.12.2 | v4.0.1 | 1.5 | Maintained | +| v2.9.0-1.6 | 24-Jun-26 | 2026.6.0 | v4.1.0 | 1.6 | Active | diff --git a/sld253-matter-wifi/images/matter-shell-enable.png b/sld253-matter-wifi/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld253-matter-wifi/images/matter-shell-enable.png and b/sld253-matter-wifi/images/matter-shell-enable.png differ diff --git a/sld290-matter-wifi-getting-started-example/getting-started-efx32-ncp.md b/sld290-matter-wifi-getting-started-example/getting-started-efx32-ncp.md index 5260209..ec0d033 100644 --- a/sld290-matter-wifi-getting-started-example/getting-started-efx32-ncp.md +++ b/sld290-matter-wifi-getting-started-example/getting-started-efx32-ncp.md @@ -103,7 +103,7 @@ This section describes how to create a project for the EFR32 boards. 1. In Simplicity Studio, click **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 2. In the Project Configuration window, after selecting the board, click **Next**. - Set - @@ -111,7 +111,7 @@ This section describes how to create a project for the EFR32 boards. - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 3. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -122,7 +122,7 @@ This section describes how to create a project for the EFR32 boards. 4. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 5. When using Commander, select the kit and click on the **Flash** option in the left panel. Click on **Erase chip**. diff --git a/sld290-matter-wifi-getting-started-example/getting-started-with-soc.md b/sld290-matter-wifi-getting-started-example/getting-started-with-soc.md index 002b4af..2e94d21 100644 --- a/sld290-matter-wifi-getting-started-example/getting-started-with-soc.md +++ b/sld290-matter-wifi-getting-started-example/getting-started-with-soc.md @@ -74,7 +74,7 @@ In Simplicity Studio 6, create the Light Matter Accessory Devices (MAD): 1. In Simplicity Studio, click on **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 2. In the Project Configuration window, Select the board and click **Next**. ![Select Board](images/studio-select-board.png) @@ -83,7 +83,7 @@ In Simplicity Studio 6, create the Light Matter Accessory Devices (MAD): - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 3. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -94,7 +94,7 @@ In Simplicity Studio 6, create the Light Matter Accessory Devices (MAD): 4. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 5. When using Commander, select the kit and click the **Flash** option in the left panel. Click **Erase chip**. diff --git a/sld290-matter-wifi-getting-started-example/images/matter-shell-enable.png b/sld290-matter-wifi-getting-started-example/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld290-matter-wifi-getting-started-example/images/matter-shell-enable.png and b/sld290-matter-wifi-getting-started-example/images/matter-shell-enable.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-create-project.jpeg b/sld290-matter-wifi-getting-started-example/images/studio-create-project.jpeg deleted file mode 100644 index 5b58cc1..0000000 Binary files a/sld290-matter-wifi-getting-started-example/images/studio-create-project.jpeg and /dev/null differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-create-project.png b/sld290-matter-wifi-getting-started-example/images/studio-create-project.png new file mode 100644 index 0000000..480efc7 Binary files /dev/null and b/sld290-matter-wifi-getting-started-example/images/studio-create-project.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-open-vscode.png b/sld290-matter-wifi-getting-started-example/images/studio-open-vscode.png index 646cdc2..aac0f3d 100644 Binary files a/sld290-matter-wifi-getting-started-example/images/studio-open-vscode.png and b/sld290-matter-wifi-getting-started-example/images/studio-open-vscode.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.jpeg b/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.jpeg deleted file mode 100644 index d850220..0000000 Binary files a/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.jpeg and /dev/null differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.png b/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.png new file mode 100644 index 0000000..2a72028 Binary files /dev/null and b/sld290-matter-wifi-getting-started-example/images/studio-project-configuration.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/studio-select-board.png b/sld290-matter-wifi-getting-started-example/images/studio-select-board.png index c88f00b..7b89e92 100644 Binary files a/sld290-matter-wifi-getting-started-example/images/studio-select-board.png and b/sld290-matter-wifi-getting-started-example/images/studio-select-board.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/vscode-build-flash.png b/sld290-matter-wifi-getting-started-example/images/vscode-build-flash.png index 8c237b2..edf02b4 100644 Binary files a/sld290-matter-wifi-getting-started-example/images/vscode-build-flash.png and b/sld290-matter-wifi-getting-started-example/images/vscode-build-flash.png differ diff --git a/sld290-matter-wifi-getting-started-example/images/vscode-flash.jpeg b/sld290-matter-wifi-getting-started-example/images/vscode-flash.jpeg deleted file mode 100644 index 72baa0d..0000000 Binary files a/sld290-matter-wifi-getting-started-example/images/vscode-flash.jpeg and /dev/null differ diff --git a/sld290-matter-wifi-getting-started-example/images/vscode-flash.png b/sld290-matter-wifi-getting-started-example/images/vscode-flash.png new file mode 100644 index 0000000..4d15aab Binary files /dev/null and b/sld290-matter-wifi-getting-started-example/images/vscode-flash.png differ diff --git a/sld290-matter-wifi-getting-started-example/index.md b/sld290-matter-wifi-getting-started-example/index.md index be9f1a0..3df8272 100644 --- a/sld290-matter-wifi-getting-started-example/index.md +++ b/sld290-matter-wifi-getting-started-example/index.md @@ -8,7 +8,7 @@ To get started with Matter over Wi-Fi, download the latest version of Simplicity ## Setting up the Matter over Wi-Fi Development Environment -Refer to the [Release Notes](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.8.1) to know more about the latest releases from Silicon Labs. +Refer to the [Release Notes](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.9.0) to know more about the latest releases from Silicon Labs. To control the Matter Accessory Device, a controller is required which is termed as **chip-tool**. The chip-tool can be set up in two ways: diff --git a/sld291-matter-wifi-run-demo/build-efx32-application-using-studio.md b/sld291-matter-wifi-run-demo/build-efx32-application-using-studio.md index 71e80c8..9b7feea 100644 --- a/sld291-matter-wifi-run-demo/build-efx32-application-using-studio.md +++ b/sld291-matter-wifi-run-demo/build-efx32-application-using-studio.md @@ -9,7 +9,7 @@ This page provides a detailed description on how to create a Wi-Fi NCP project f 3. In Simplicity Studio, click **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 4. In the Project Configuration window, after selecting the board, click **Next**. - Set - @@ -17,7 +17,7 @@ This page provides a detailed description on how to create a Wi-Fi NCP project f - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 5. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -28,7 +28,7 @@ This page provides a detailed description on how to create a Wi-Fi NCP project f 7. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 8. When using Commander, select the kit and click the **Flash** option in the left panel. Click **Erase chip**. diff --git a/sld291-matter-wifi-run-demo/build-soc-application-using-studio.md b/sld291-matter-wifi-run-demo/build-soc-application-using-studio.md index d096793..fe5e7f4 100644 --- a/sld291-matter-wifi-run-demo/build-soc-application-using-studio.md +++ b/sld291-matter-wifi-run-demo/build-soc-application-using-studio.md @@ -5,7 +5,7 @@ In Simplicity Studio 6, create the Light MAD: 1. In Simplicity Studio, click **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 2. In the Project Configuration window, Select the board and click **Next**. ![Select Board](images/studio-select-board.png) @@ -14,7 +14,7 @@ In Simplicity Studio 6, create the Light MAD: - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 3. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -25,7 +25,7 @@ In Simplicity Studio 6, create the Light MAD: 5. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 6. When using Commander, select the kit and click the **Flash** option in the left panel. Click **Erase chip**. diff --git a/sld291-matter-wifi-run-demo/images/matter-shell-enable.png b/sld291-matter-wifi-run-demo/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld291-matter-wifi-run-demo/images/matter-shell-enable.png and b/sld291-matter-wifi-run-demo/images/matter-shell-enable.png differ diff --git a/sld291-matter-wifi-run-demo/images/studio-create-project.jpeg b/sld291-matter-wifi-run-demo/images/studio-create-project.jpeg deleted file mode 100644 index 5b58cc1..0000000 Binary files a/sld291-matter-wifi-run-demo/images/studio-create-project.jpeg and /dev/null differ diff --git a/sld291-matter-wifi-run-demo/images/studio-create-project.png b/sld291-matter-wifi-run-demo/images/studio-create-project.png new file mode 100644 index 0000000..480efc7 Binary files /dev/null and b/sld291-matter-wifi-run-demo/images/studio-create-project.png differ diff --git a/sld291-matter-wifi-run-demo/images/studio-open-vscode.png b/sld291-matter-wifi-run-demo/images/studio-open-vscode.png index 646cdc2..aac0f3d 100644 Binary files a/sld291-matter-wifi-run-demo/images/studio-open-vscode.png and b/sld291-matter-wifi-run-demo/images/studio-open-vscode.png differ diff --git a/sld291-matter-wifi-run-demo/images/studio-project-configuration.jpeg b/sld291-matter-wifi-run-demo/images/studio-project-configuration.jpeg deleted file mode 100644 index d850220..0000000 Binary files a/sld291-matter-wifi-run-demo/images/studio-project-configuration.jpeg and /dev/null differ diff --git a/sld291-matter-wifi-run-demo/images/studio-project-configuration.png b/sld291-matter-wifi-run-demo/images/studio-project-configuration.png new file mode 100644 index 0000000..2a72028 Binary files /dev/null and b/sld291-matter-wifi-run-demo/images/studio-project-configuration.png differ diff --git a/sld291-matter-wifi-run-demo/images/studio-select-board.png b/sld291-matter-wifi-run-demo/images/studio-select-board.png index c88f00b..7b89e92 100644 Binary files a/sld291-matter-wifi-run-demo/images/studio-select-board.png and b/sld291-matter-wifi-run-demo/images/studio-select-board.png differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-build-flash.png b/sld291-matter-wifi-run-demo/images/vscode-build-flash.png index 8c237b2..edf02b4 100644 Binary files a/sld291-matter-wifi-run-demo/images/vscode-build-flash.png and b/sld291-matter-wifi-run-demo/images/vscode-build-flash.png differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-debug-icon.png b/sld291-matter-wifi-run-demo/images/vscode-debug-icon.png index 68c31cf..74beb97 100644 Binary files a/sld291-matter-wifi-run-demo/images/vscode-debug-icon.png and b/sld291-matter-wifi-run-demo/images/vscode-debug-icon.png differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-debug-options.png b/sld291-matter-wifi-run-demo/images/vscode-debug-options.png index 8d1190c..1099467 100644 Binary files a/sld291-matter-wifi-run-demo/images/vscode-debug-options.png and b/sld291-matter-wifi-run-demo/images/vscode-debug-options.png differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-flash.jpeg b/sld291-matter-wifi-run-demo/images/vscode-flash.jpeg deleted file mode 100644 index 72baa0d..0000000 Binary files a/sld291-matter-wifi-run-demo/images/vscode-flash.jpeg and /dev/null differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-flash.png b/sld291-matter-wifi-run-demo/images/vscode-flash.png new file mode 100644 index 0000000..4d15aab Binary files /dev/null and b/sld291-matter-wifi-run-demo/images/vscode-flash.png differ diff --git a/sld291-matter-wifi-run-demo/images/vscode-start-debug.png b/sld291-matter-wifi-run-demo/images/vscode-start-debug.png index 7362d37..0f8b137 100644 Binary files a/sld291-matter-wifi-run-demo/images/vscode-start-debug.png and b/sld291-matter-wifi-run-demo/images/vscode-start-debug.png differ diff --git a/sld292-matter-wifi-enabling-features/build-soc-application-using-studio.md b/sld292-matter-wifi-enabling-features/build-soc-application-using-studio.md index d096793..fe5e7f4 100644 --- a/sld292-matter-wifi-enabling-features/build-soc-application-using-studio.md +++ b/sld292-matter-wifi-enabling-features/build-soc-application-using-studio.md @@ -5,7 +5,7 @@ In Simplicity Studio 6, create the Light MAD: 1. In Simplicity Studio, click **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 2. In the Project Configuration window, Select the board and click **Next**. ![Select Board](images/studio-select-board.png) @@ -14,7 +14,7 @@ In Simplicity Studio 6, create the Light MAD: - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 3. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -25,7 +25,7 @@ In Simplicity Studio 6, create the Light MAD: 5. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 6. When using Commander, select the kit and click the **Flash** option in the left panel. Click **Erase chip**. diff --git a/sld292-matter-wifi-enabling-features/images/matter-shell-enable.png b/sld292-matter-wifi-enabling-features/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld292-matter-wifi-enabling-features/images/matter-shell-enable.png and b/sld292-matter-wifi-enabling-features/images/matter-shell-enable.png differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-create-project.jpeg b/sld292-matter-wifi-enabling-features/images/studio-create-project.jpeg deleted file mode 100644 index 5b58cc1..0000000 Binary files a/sld292-matter-wifi-enabling-features/images/studio-create-project.jpeg and /dev/null differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-create-project.png b/sld292-matter-wifi-enabling-features/images/studio-create-project.png new file mode 100644 index 0000000..480efc7 Binary files /dev/null and b/sld292-matter-wifi-enabling-features/images/studio-create-project.png differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-open-vscode.png b/sld292-matter-wifi-enabling-features/images/studio-open-vscode.png index 646cdc2..aac0f3d 100644 Binary files a/sld292-matter-wifi-enabling-features/images/studio-open-vscode.png and b/sld292-matter-wifi-enabling-features/images/studio-open-vscode.png differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-project-configuration.jpeg b/sld292-matter-wifi-enabling-features/images/studio-project-configuration.jpeg deleted file mode 100644 index d850220..0000000 Binary files a/sld292-matter-wifi-enabling-features/images/studio-project-configuration.jpeg and /dev/null differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-project-configuration.png b/sld292-matter-wifi-enabling-features/images/studio-project-configuration.png new file mode 100644 index 0000000..2a72028 Binary files /dev/null and b/sld292-matter-wifi-enabling-features/images/studio-project-configuration.png differ diff --git a/sld292-matter-wifi-enabling-features/images/studio-select-board.png b/sld292-matter-wifi-enabling-features/images/studio-select-board.png index c88f00b..7b89e92 100644 Binary files a/sld292-matter-wifi-enabling-features/images/studio-select-board.png and b/sld292-matter-wifi-enabling-features/images/studio-select-board.png differ diff --git a/sld292-matter-wifi-enabling-features/images/vscode-build-flash.png b/sld292-matter-wifi-enabling-features/images/vscode-build-flash.png index 8c237b2..edf02b4 100644 Binary files a/sld292-matter-wifi-enabling-features/images/vscode-build-flash.png and b/sld292-matter-wifi-enabling-features/images/vscode-build-flash.png differ diff --git a/sld292-matter-wifi-enabling-features/images/vscode-flash.jpeg b/sld292-matter-wifi-enabling-features/images/vscode-flash.jpeg deleted file mode 100644 index 72baa0d..0000000 Binary files a/sld292-matter-wifi-enabling-features/images/vscode-flash.jpeg and /dev/null differ diff --git a/sld292-matter-wifi-enabling-features/images/vscode-flash.png b/sld292-matter-wifi-enabling-features/images/vscode-flash.png new file mode 100644 index 0000000..4d15aab Binary files /dev/null and b/sld292-matter-wifi-enabling-features/images/vscode-flash.png differ diff --git a/sld295-matter-api-reference/attributes.md b/sld295-matter-api-reference/attributes.md index 4e6654d..5483fb8 100644 --- a/sld295-matter-api-reference/attributes.md +++ b/sld295-matter-api-reference/attributes.md @@ -4,13 +4,19 @@ Attributes represent the current state of a device. For instance if the device i ## Attribute Changes -When a ZCL attribute is updated in the data model, the framework will call the `postAttributeChangeCallback`. If this callback is implemented by the device it will be informed of the attribute change. The device may react to the attribute change. For example, in `MatterPostAttributeChangeCallback` in `DataModelCallbacks.cpp` in [onoff-plug-app/src](https://github.com/SiliconLabs/matter_extension/tree/main/examples/onoff-plug-app/src), say we want to add some custom handler code to control an RGB LED when on/off attribute in the `On-Off` Cluster changes: +Depending on your sample app, instructions apply. For more information, refer to [Application customization models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). + +### New Architecture + +When a ZCL attribute is updated in the data model, the framework invokes the post-attribute-change path. The Silicon Labs Matter stack routes this as follows: `MatterPostAttributeChangeCallback` in `BaseApplication.cpp` → `AppTask::DMPostAttributeChangeCallback` in `autogen/AppTask.cpp` → your optional `DMPostAttributeChangeCallbackImpl()` override in `CustomerAppTask`. + +If this callback is implemented by the device, it is informed of the attribute change. The device may react to the attribute change. For example, in `DMPostAttributeChangeCallback` function the in `AppTask.cpp` file ([onoff-plug-app/src](https://github.com/SiliconLabsSoftware/matter_sdk/blob/main/examples/onoff-plug-app/silabs/src/AppTask.cpp)), if you want to add a custom handler code to control an RGB LED when on/off attribute in the `On-Off` Cluster changes, implement the following in `DMPostAttributeChangeCallbackImpl` in `src/CustomerAppTask.cpp`: ```cpp -void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, - uint8_t type, - uint16_t size, - uint8_t * value) +void DMPostAttributeChangeCallbackImpl(const chip::app::ConcreteAttributePath & attributePath, + uint8_t type, + uint16_t size, + uint8_t * value) { ClusterId clusterId = attributePath.mClusterId; AttributeId attributeId = attributePath.mAttributeId; @@ -18,7 +24,6 @@ void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) { - /* Custom code */ if (*value) { // turn on LED sl_led_turn_on((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); @@ -34,6 +39,36 @@ void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & } ``` +### Legacy Architecture + +When a ZCL attribute is updated in the data model, the framework calls `MatterPostAttributeChangeCallback()` in `src/DataModelCallbacks.cpp`. If this callback is implemented by the device it will be informed of the attribute change. For example, to control an RGB LED when the On/Off attribute changes: + +```cpp +void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, + uint8_t type, + uint16_t size, + uint8_t * value) +{ + ClusterId clusterId = attributePath.mClusterId; + AttributeId attributeId = attributePath.mAttributeId; + ChipLogProgress(Zcl, "Cluster callback: " ChipLogFormatMEI, ChipLogValueMEI(clusterId)); + + if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) + { + if (*value) + { // turn on LED + sl_led_turn_on((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); + } + else + {// turn off LED + sl_led_turn_off((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); + } + } + + //... +} +``` + ## Header File This file contains the high level namespaces and constant definitions for Attributes. In Simplicity Studio, this will be generated in the autogen/zap-generated/ folder of the matter project. diff --git a/sld295-matter-api-reference/event.md b/sld295-matter-api-reference/event.md index b20191b..6bbcf3a 100644 --- a/sld295-matter-api-reference/event.md +++ b/sld295-matter-api-reference/event.md @@ -2,7 +2,9 @@ Events are records of past state transitions such as a light device's on-off attribute changing from on to off. -The autogenerated file [```include/AppEvent.h```](https://github.com/SiliconLabs/matter_extension/blob/main/examples/template/include/AppEvent.h) houses the definition of the event object used by the application. It contains the event types, the structures for each event, and event handler. +The autogenerated file [```include/AppEvent.h```](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/examples/template/silabs/include/AppEvent.h) contains the definition of the event object used by the application. It includes the event types, the structures for each event, and event handler. + +**New architecture:** Custom event posting and handlers are overridden in the `CustomerAppTask` file, not in `autogen/AppTask.cpp`. ## Header File diff --git a/sld295-matter-api-reference/index.md b/sld295-matter-api-reference/index.md index b8c604a..960faa9 100644 --- a/sld295-matter-api-reference/index.md +++ b/sld295-matter-api-reference/index.md @@ -11,12 +11,16 @@ This section covers the various Application Programming Interfaces (APIs) that a ## Application APIs +For guidance on new vs legacy sample app architecture and where to add custom logic, see [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). + ### Initialization -The application 'Init' sequence lives in the ```AppTask.cpp``` file, and is called at the beginning of the application to ensure that all components are properly initialized and ready to operate. It sets up necessary callbacks, initializes hardware components, and handles any errors that may occur during the process. This function is crucial for the stable operation of the application. +**New architecture:** Default initialization is included in `autogen/AppTask.cpp`. Override `AppInitImpl()` and other `*Impl()` hooks in `src/CustomerAppTask.cpp` to customize behavior. + +**Legacy architecture:** The application Init sequence is included in `src/AppTask.cpp` and is called at the beginning of the application to ensure that all components are properly initialized and ready to operate. It sets up necessary callbacks, initializes hardware components, and handles any errors that may occur during the process. ```cpp CHIP_ERROR AppTask::Init() ``` -The ```AppTask.cpp``` file may also contain event handlers and helper code useful to the application. +The `AppTask.cpp` file may also contain event handlers and helper code useful to the application. diff --git a/sld296-matter-ecosystems/images/matter-shell-enable.png b/sld296-matter-ecosystems/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld296-matter-ecosystems/images/matter-shell-enable.png and b/sld296-matter-ecosystems/images/matter-shell-enable.png differ diff --git a/sld297-matter-aws-feature/index.md b/sld297-matter-aws-feature/index.md index 532b58b..bbba67f 100644 --- a/sld297-matter-aws-feature/index.md +++ b/sld297-matter-aws-feature/index.md @@ -95,7 +95,7 @@ User Setup (MQTT Explorer): - toggle - on - off - - Onoff-plug App + - Onoff Plug - Topic: command - Commands: - toggle diff --git a/sld388-matter-new-features/index.md b/sld388-matter-new-features/index.md index b94970e..fae0c99 100644 --- a/sld388-matter-new-features/index.md +++ b/sld388-matter-new-features/index.md @@ -1,5 +1,11 @@ # New Features +## New Features for v2.9.0-1.6 +- Quality-tested Matter 1.6 solution for Thread MG24 / MG26 / MG30, Wi-Fi SiWG917 SoC and SiWN917 NCP mode. +- Matter + AWS dual-stack support for 917 NCP boards. +- Added LTO build support for SiWG917 sleepy and non-sleepy Matter Wi-Fi applications +- Updated the GCC toolchain version to 14.2 release + ## New Features for v2.8.1-1.5 - PSRAM board support in Matter now uses WiseConnect components. To place specific code/data in PSRAM, enable the corresponding WiseConnect component for the section or region you want to relocate. diff --git a/sld405-matter-fundamentals-security/index.md b/sld405-matter-fundamentals-security/index.md index e4cbd29..fb9fbd4 100644 --- a/sld405-matter-fundamentals-security/index.md +++ b/sld405-matter-fundamentals-security/index.md @@ -263,7 +263,7 @@ This completes all the commissioning steps and now on the Matter Network. **Device Communication**: Communication between Matter Devices must be secured and encrypted using cryptographic keys and PBKDF. (SHALL) -**Software Updates**: Devices must support OTA firmware updates to allow vulnerabilities to be patched. (SHALL) +**Software Updates**: Devices must support a secure firmware upgrade mechanism so that vulnerabilities can be patched in the field (SHALL). This requirement is defined in Section 11.20.4.2 of the Matter Specification, version 1.5. On Silicon Labs platforms, it is implemented using the [Gecko Bootloader Secure Firmware Upgrade](https://docs.silabs.com/mcu-bootloader/latest/bootloader-user-guide-gsdk-4/09-gecko-bootloader-security-features#secure-firmware-upgrade) feature. Refer to [Matter OTA](/matter/{build-docspace-version}/matter-ota) for the Silicon Labs implementation. ### Other Security Specifications diff --git a/sld406-matter-light-switch-example/01-wifi-light-switch-example.md b/sld406-matter-light-switch-example/01-wifi-light-switch-example.md index 5a6fdec..b3c5bd8 100644 --- a/sld406-matter-light-switch-example/01-wifi-light-switch-example.md +++ b/sld406-matter-light-switch-example/01-wifi-light-switch-example.md @@ -56,7 +56,7 @@ To run the Light and Switch Example on SiWx917 SOC, software must be installed. 4. Open the Example Projects and Demos tab, select the **Matter** filter, and enter _Wi-Fi_ in **Filter on keywords**. - 5. Select the **Matter - Lighting over Wi-Fi** example, click **Create**, rename the project if you wish, and click **Finish**. + 5. Select the **Matter WiFi - SoC Lighting FreeRTOS** example, click **Create**, rename the project if you wish, and click **Finish**. 6. Once the project is created, the perspective changes to the Simplicity IDE. In the Project Explorer view, right-click the project and select **Build Project**. @@ -68,7 +68,7 @@ To run the Light and Switch Example on SiWx917 SOC, software must be installed. 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 select the **Matter - Light Switch over Wi-Fi** example instead. +2. Repeat the process with the second Dev board, but select the **Matter WiFi - SoC Light Switch FreeRTOS** example instead. ## Creating the Matter Network diff --git a/sld406-matter-light-switch-example/02-thread-light-switch-example.md b/sld406-matter-light-switch-example/02-thread-light-switch-example.md index 579db34..be62f0e 100644 --- a/sld406-matter-light-switch-example/02-thread-light-switch-example.md +++ b/sld406-matter-light-switch-example/02-thread-light-switch-example.md @@ -78,13 +78,13 @@ You now have a working Matter hub. Keep the PuTTY session open for the following 2. Once it displays in the **Devices** panel, select it. - 3. This will bring up the Example Projects and Demos tab, check the **Matter** filter under **Wireless Technology**, and enter *lighting* in the **Filter on keywords** box. Select the **Matter - SoC Lighting over Thread with external Bootloader Solution** and click **Create**. + 3. This will bring up the Example Projects and Demos tab, check the **Matter** filter under **Wireless Technology**, and enter *lighting* in the **Filter on keywords** box. Select the **Matter Thread - SoC Lighting with external Bootloader FreeRTOS** solution and click **Create**. ![Select the example project](resources/studio-6-matter-thread-demo-lighting-projects.png) 4. Name your project and click **Finish** (no other changes are required at this time). - 5. Once the solution is created, you will be redirected to the Projects view with the MatterLightOverThread.slcp file open. If not simply open the file yourself. + 5. Once the solution is created, you will be redirected to the Projects view with the matter_thread_soc_lighting_app_freertos.slcp file open. If not simply open the file yourself. ![Build the project](resources/studio-6-matter-project-demo.png) @@ -94,7 +94,7 @@ You now have a working Matter hub. Keep the PuTTY session open for the following 8. Disconnect the dev board from your development computer. -2. Repeat the process above with the second dev board but selecting the *Matter - SoC Light Switch over Thread* example instead. +2. Repeat the process above with the second dev board but selecting the *Matter Thread - SoC Light Switch FreeRTOS* example instead. ## Creating the Matter Network diff --git a/sld406-matter-light-switch-example/resources/studio-6-build.png b/sld406-matter-light-switch-example/resources/studio-6-build.png index 5a01c6a..afa1406 100644 Binary files a/sld406-matter-light-switch-example/resources/studio-6-build.png and b/sld406-matter-light-switch-example/resources/studio-6-build.png differ diff --git a/sld406-matter-light-switch-example/resources/studio-6-matter-project-demo.png b/sld406-matter-light-switch-example/resources/studio-6-matter-project-demo.png index 74786d1..bdbc2f8 100644 Binary files a/sld406-matter-light-switch-example/resources/studio-6-matter-project-demo.png and b/sld406-matter-light-switch-example/resources/studio-6-matter-project-demo.png differ diff --git a/sld406-matter-light-switch-example/resources/studio-6-matter-thread-demo-lighting-projects.png b/sld406-matter-light-switch-example/resources/studio-6-matter-thread-demo-lighting-projects.png index 3b0aeb7..a143933 100644 Binary files a/sld406-matter-light-switch-example/resources/studio-6-matter-thread-demo-lighting-projects.png and b/sld406-matter-light-switch-example/resources/studio-6-matter-thread-demo-lighting-projects.png differ diff --git a/sld406-matter-light-switch-example/resources/studio-6-select-device.png b/sld406-matter-light-switch-example/resources/studio-6-select-device.png index 20f5a40..8431274 100644 Binary files a/sld406-matter-light-switch-example/resources/studio-6-select-device.png and b/sld406-matter-light-switch-example/resources/studio-6-select-device.png differ diff --git a/sld407-matter-ota/01-ota-bootloader.md b/sld407-matter-ota/01-ota-bootloader.md index 6cf1b1a..3838c5e 100644 --- a/sld407-matter-ota/01-ota-bootloader.md +++ b/sld407-matter-ota/01-ota-bootloader.md @@ -4,6 +4,8 @@ The Matter OTA Software Update functionality on EFR32 devices requires the use o The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These instructions assume that you have installed Simplicity Studio 6, the Simplicity Commander tool (installed by default with Simplicity Studio), the GSDK and associated utilities, and that you are familiar with generating, compiling, and flashing an example application in the relevant version. +Note: All Silicon Labs Matter products must use the Secure Firmware Upgrade feature to meet Matter certification requirements. Generating the image file and creating the bootloloader for this feature requires extra steps such as setting "Require signed firmware upgrade files" in the Bootloader Core component Configuration in the bootloader project. See [Enabling Secure Upgrades](/matter/{build-docspace-version}/matter-ota/01-ota-bootloader#enabling-secure-upgrades) for step-by-step instructions. + ## Bootloader Project In Studio ### Creating the Project @@ -25,7 +27,22 @@ In the newly created project, select the project's .slcp file, click the **Softw Silicon Labs recommends installing the **GBL Compression (LZMA)** component under **Platform > Bootloader > Core**. This allows the bootloader to handle compressed GBL files. This component is required for internal storage bootloaders. -At this point, the project contains all the components necessary to support the Matter OTA Software Update functionality. Other components can now be added to support additional features such as Secure Boot. Refer to *UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher* for the description of various bootloader features and the steps to enable them. +At this point, the project contains all the components necessary to support the Matter OTA Software Update functionality. To additionally secure updates for production (Secure Boot and signed firmware upgrades), see [Enabling Secure Upgrades](#enabling-secure-upgrades) below. Refer to *UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher* for the full description of various bootloader features. + +## Enabling Secure Upgrades + +Securing OTA updates depends on two standard Gecko Bootloader features: Secure Boot and signed firmware upgrade files, both using an ECDSA-P256 key. Enabling them is a generic setup covered in *UG489: Silicon Labs Gecko Bootloader User's Guide* section 9 and [AN1218: Series 2 Secure Boot with RTSL](https://www.silabs.com/documents/public/application-notes/an1218-secure-boot-with-rtsl.pdf). + +The only Matter specific change is how you build the GBL: create it from the Secure Boot signed application image, not the plain `.s37` used elsewhere in Matter OTA pages, and pass the signing key with `--sign` (and the AES key with `--encrypt` if encrypting): + +```shell +commander gbl create chip-efr32-lighting-example.gbl \ + --app chip-efr32-lighting-example-signed.s37 \ + --sign signing-key \ + --encrypt encryption-key +``` + +Use this signed GBL when creating the Matter `.ota` file as described in [Matter OTA Software Update](./02-ota-software-update.md). ### Building and Flashing the Bootloader @@ -60,7 +77,7 @@ This example is for an internal storage bootloader for the Matter lighting app o - Build the GBL file for the update image and note its size. - - If using a series 3 board: + - If using a series 3 board: ```shell $ commander gbl4 create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37 ``` diff --git a/sld407-matter-ota/02-ota-software-update.md b/sld407-matter-ota/02-ota-software-update.md index 9500c12..0119413 100644 --- a/sld407-matter-ota/02-ota-software-update.md +++ b/sld407-matter-ota/02-ota-software-update.md @@ -67,6 +67,8 @@ See the following page for detailed steps: [build OTA application using studio]( commander gbl create chip-efr32-lighting-example.gbl --app chip-efr32-lighting-example.s37 ``` + > **Note**: The command above creates an unsigned GBL image. For Matter devices, add `--sign ` so the Gecko Bootloader can authenticate the GBL before it applies the update. See [Enabling Secure Upgrades](./01-ota-bootloader.md#enabling-secure-upgrades) for details. + - Create the Matter OTA file from the bootable image file: ```shell @@ -209,6 +211,8 @@ Combined OTA images are supported in both regular OTA and Multi-Chip OTA impleme 3. Application upgrade only. This should be a standalone as described in the sections above. +> **Note**: The commands above create unsigned GBL images. For Matter devices, add `--sign ` so the Gecko Bootloader can authenticate the GBL before it applies the update. See [Enabling Secure Upgrades](./01-ota-bootloader.md#enabling-secure-upgrades) for details. + >**Hint**: It can be useful to compress this image to reduce the size needed to OTA. This can be done via the optional flag `--compress lzma`. If you use LZMA compression for creating the OTA file, make sure that the bootloader has been built with the LZMA compress component. To create the .ota file, simply follow the method discussed above using the combined image: @@ -283,7 +287,7 @@ Build the project, and flash the binary file to your matter device. #### Application (New) -For the new application image, configure and set the Device software version and Device software version string to a higher number in Matter > Stack > Matter Core Components. For the purposes of this example the Matter sample application used is the MatterLightOverThread. +For the new application image, configure and set the Device software version and Device software version string to a higher number in Matter > Stack > Matter Core Components. For the purposes of this example the Matter sample application used is the matter_thread_soc_lighting_app_freertos. ![Matter app version number](./images/ota-tutorial-app-version-number.png) @@ -319,10 +323,12 @@ If your version supports Multi-chip OTA functionality, the following command com For either of these cases, the `--compress lzma` option can be used to reduce the size of the resulting image. Just ensure that the bootloader has been built with the LZMA compress component. +> **Note**: The commands above create unsigned GBL images. For Matter devices, add `--sign ` so the Gecko Bootloader can authenticate the GBL before it applies the update. See [Enabling Secure Upgrades](./01-ota-bootloader.md#enabling-secure-upgrades) for details. + Then, run the following command to create the .ota file. ```shell -commander ota create --type matter --input MatterLightOverThread.gbl --vendorid 0xFFF1 --productid 0x8005 --swstring "2.0" --swversion 2 --digest sha256 -o MatterLightOverThread.ota +commander ota create --type matter --input matter_thread_soc_lighting_app_freertos.gbl --vendorid 0xFFF1 --productid 0x8005 --swstring "2.0" --swversion 2 --digest sha256 -o matter_thread_soc_lighting_app_freertos.ota ``` ### Step 3: Setting up the Thread network and the OTA Provider application @@ -338,7 +344,7 @@ If instead the chip-tool is used, replace the "mattertool" with "chip-tool" and After that, start the Provider app and pass to it the path to the Matter OTA file created in the previous step: ```shell -chip-ota-provider-app -f ./MatterLightOverThread.ota +chip-ota-provider-app -f ./matter_thread_soc_lighting_app_freertos.ota ``` In a new separate terminal, run the following commands to provision the Provider: diff --git a/sld407-matter-ota/03-ota-software-update-soc.md b/sld407-matter-ota/03-ota-software-update-soc.md index 2266165..ae375ac 100644 --- a/sld407-matter-ota/03-ota-software-update-soc.md +++ b/sld407-matter-ota/03-ota-software-update-soc.md @@ -218,3 +218,9 @@ Example command:./provision.py write -ok ```shell ./scripts/tools/silabs/ota/ota_multi_image_tool.py create -v 0xFFF1 -p 0x8005 -vn 2 -vs "2.0" -da sha256 --enc_enable --input_ota_key "" --app-input-file SiWx917-lock-example.rps SiWx917-lock-example.ota ``` + +## Secure Upgrades on SiWx917 SoC + +Unlike EFR32 devices, the SiWx917 SoC does not use the Gecko Bootloader. The M4 application and Wi-Fi firmware are delivered as `.rps` images and verified by the SiWx917's own Security Bootloader. Enabling secure boot and provisioning the keys is a generic setup. Follow [AN1442: SiWx917 SoC Secure Boot with Anti-Rollback Protection](https://www.silabs.com/documents/public/application-notes/an1442-siwx917-soc-secure-boot-with-anti-rollback-protection.pdf) and *UG574: SiWx917 SoC Manufacturing Utility User Guide* to complete it. + +The Matter specific change is encrypting the OTA payload: Refer to the Encrypted Image Upgrade subsection above for provisioning the AES key. For the overall security model, see [Matter Secure Manufacturing](/matter/{build-docspace-version}/matter-secure-manufacturing). diff --git a/sld407-matter-ota/04-build-ota-application-using-studio.md b/sld407-matter-ota/04-build-ota-application-using-studio.md index 2f3f96e..ef957b6 100644 --- a/sld407-matter-ota/04-build-ota-application-using-studio.md +++ b/sld407-matter-ota/04-build-ota-application-using-studio.md @@ -13,7 +13,7 @@ In the Matter OTA Software Update scenario, the running image (OTA-A) and the up 3. In Simplicity Studio, click on **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 4. In the Project Configuration window, Select the board and click **Next**. ![Select Board](images/studio-select-board.png) @@ -22,7 +22,7 @@ In the Matter OTA Software Update scenario, the running image (OTA-A) and the up - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 5. Once the project is created, click the **Open in VS Code** option on the top right corner. ![Open project in VS Code](images/studio-open-vscode.png) @@ -33,7 +33,7 @@ In the Matter OTA Software Update scenario, the running image (OTA-A) and the up 7. Once the project is compiled successfully, the binaries can be flashed either using the **Simplicity Commander** from the tools or using the **Flash** option beside the **Build**. - ![Flash Project](images/vscode-flash.jpeg) + ![Flash Project](images/vscode-flash.png) 8. When using Commander, select the kit and click the **Flash** option in the left panel. Click **Erase chip**. @@ -50,7 +50,7 @@ In the Matter OTA Software Update scenario, the running image (OTA-A) and the up . In Simplicity Studio, click on **Matter**, under **Example Projects and Demos**, select a project, and click **Create**. ![Example Projects and Demos](images/studio-home-tab.png) - ![Example Projects and Demos](images/studio-create-project.jpeg) + ![Example Projects and Demos](images/studio-create-project.png) 2. In the Project Configuration window, Select the board and click **Next**. ![Select Board](images/studio-select-board.png) @@ -59,7 +59,7 @@ In the Matter OTA Software Update scenario, the running image (OTA-A) and the up - Select Target IDE. - Click **Finish**. - ![Finish project](images/studio-project-configuration.jpeg) + ![Finish project](images/studio-project-configuration.png) 3. In the newly created project, navigate to **Software Components > Silicon Labs Matter > Stack > Matter Core Components**, click **Configure**, and set the **Device software version** and **Device software version string** parameters to **2**. diff --git a/sld407-matter-ota/images/matter-shell-enable.png b/sld407-matter-ota/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld407-matter-ota/images/matter-shell-enable.png and b/sld407-matter-ota/images/matter-shell-enable.png differ diff --git a/sld407-matter-ota/images/studio-create-project.jpeg b/sld407-matter-ota/images/studio-create-project.jpeg deleted file mode 100644 index 5b58cc1..0000000 Binary files a/sld407-matter-ota/images/studio-create-project.jpeg and /dev/null differ diff --git a/sld407-matter-ota/images/studio-create-project.png b/sld407-matter-ota/images/studio-create-project.png new file mode 100644 index 0000000..480efc7 Binary files /dev/null and b/sld407-matter-ota/images/studio-create-project.png differ diff --git a/sld407-matter-ota/images/studio-open-vscode.png b/sld407-matter-ota/images/studio-open-vscode.png index 646cdc2..aac0f3d 100644 Binary files a/sld407-matter-ota/images/studio-open-vscode.png and b/sld407-matter-ota/images/studio-open-vscode.png differ diff --git a/sld407-matter-ota/images/studio-project-configuration.jpeg b/sld407-matter-ota/images/studio-project-configuration.jpeg deleted file mode 100644 index d850220..0000000 Binary files a/sld407-matter-ota/images/studio-project-configuration.jpeg and /dev/null differ diff --git a/sld407-matter-ota/images/studio-project-configuration.png b/sld407-matter-ota/images/studio-project-configuration.png new file mode 100644 index 0000000..2a72028 Binary files /dev/null and b/sld407-matter-ota/images/studio-project-configuration.png differ diff --git a/sld407-matter-ota/images/studio-select-board.png b/sld407-matter-ota/images/studio-select-board.png index c88f00b..7b89e92 100644 Binary files a/sld407-matter-ota/images/studio-select-board.png and b/sld407-matter-ota/images/studio-select-board.png differ diff --git a/sld407-matter-ota/images/vscode-build-flash.png b/sld407-matter-ota/images/vscode-build-flash.png index 8c237b2..edf02b4 100644 Binary files a/sld407-matter-ota/images/vscode-build-flash.png and b/sld407-matter-ota/images/vscode-build-flash.png differ diff --git a/sld407-matter-ota/images/vscode-flash.jpeg b/sld407-matter-ota/images/vscode-flash.jpeg deleted file mode 100644 index 72baa0d..0000000 Binary files a/sld407-matter-ota/images/vscode-flash.jpeg and /dev/null differ diff --git a/sld407-matter-ota/images/vscode-flash.png b/sld407-matter-ota/images/vscode-flash.png new file mode 100644 index 0000000..4d15aab Binary files /dev/null and b/sld407-matter-ota/images/vscode-flash.png differ diff --git a/sld407-matter-ota/index.md b/sld407-matter-ota/index.md index 67faa6a..508f793 100644 --- a/sld407-matter-ota/index.md +++ b/sld407-matter-ota/index.md @@ -6,3 +6,5 @@ The Over The Air (OTA) Software Update functionality is enabled by default for a - [**Matter OTA Software Update**](./02-ota-software-update.md) - [**Matter 917 SOC OTA Software Update**](./03-ota-software-update-soc.md) - [**Matter OTA Project in Simplicity Studio**](./04-build-ota-application-using-studio.md) + +Note:The Matter specification requires every certified device to support a secure firmware upgrade mechanism (Section 11.20.4.2 of the Matter Specification, version 1.5). On Silicon Labs platforms, this requirement is satisfied by the [Gecko Bootloader Secure Firmware Upgrade](https://docs.silabs.com/mcu-bootloader/latest/bootloader-user-guide-gsdk-4/09-gecko-bootloader-security-features#secure-firmware-upgrade) feature, and all Silicon Labs Matter products must use this feature to meet Matter certification requirements. \ No newline at end of file diff --git a/sld461-matter-secure-manufacturing/index.md b/sld461-matter-secure-manufacturing/index.md index ffd9d02..7412481 100644 --- a/sld461-matter-secure-manufacturing/index.md +++ b/sld461-matter-secure-manufacturing/index.md @@ -33,7 +33,7 @@ What should your Matter device include? ## Other Recommended Security Specifications -- Software updates: Devices must support secure OTA firmware updates to allow vulnerabilities to be patched. +- Software updates: Devices must support a secure firmware upgrade mechanism so that vulnerabilities can be patched in the field. This is a mandatory Matter requirement (Section 11.20.4.2 of the Matter Specification, version 1.5). All Silicon Labs Matter products must use the [Gecko Bootloader Secure Firmware Upgrade](https://docs.silabs.com/mcu-bootloader/latest/bootloader-user-guide-gsdk-4/09-gecko-bootloader-security-features#secure-firmware-upgrade) feature to meet this requirement. For implementation guidance, see [Matter OTA](/matter/{build-docspace-version}/matter-ota). - Debug interfaces should be disabled to only allow authorized access (fusing). For more information on the different functionalities available by Silicon Labs, refer to [AN1190: Series 2 Secure Debug](https://www.silabs.com/documents/public/application-notes/an1190-efr32-secure-debug.pdf). - Devices should have a verified boot process based on a root of trust to ensure firmware authenticity. Silicon Labs offers Secure Boot to ensure firmware authenticity. For further information on Secure Boot, refer to [AN1218: Series 2 Secure Boot with RTSL](https://www.silabs.com/documents/public/application-notes/an1218-secure-boot-with-rtsl.pdf). - DACs and operational private key confidentiality should be protected from remote attacks. diff --git a/sld477-matter-quick-start-demo/01-wifi-quick-start-demo.md b/sld477-matter-quick-start-demo/01-wifi-quick-start-demo.md index 1e96c6b..9ce14c2 100644 --- a/sld477-matter-quick-start-demo/01-wifi-quick-start-demo.md +++ b/sld477-matter-quick-start-demo/01-wifi-quick-start-demo.md @@ -4,7 +4,7 @@ This Quick-Start Guide will demo the out-of-box experience for adding an SiWx917 ## Software Requirements -- Simplicity Studio v6 with SiSDK - 2025.12.2 + Silicon Labs Matter - 2.8.1 + WiSeConnect - 4.0.1 +- Simplicity Studio v6 with SiSDK - 2026.6.0 + Silicon Labs Matter - 2.9.0 + WiSeConnect - 4.1.0 - Simplicity Connect mobile App on Smartphone ## Hardware Requirements @@ -38,7 +38,9 @@ Click the **Example Projects & Demos** tab and filter for *Matter*. ![Simplicity Studio Example Projects & Demos](./images/wifi-light-demo.png) -For this quick start guide, select the **Matter - SoC Siwx917 Lighting Example over Wi-Fi** demo. A number of other apps are also available including a Lock, Thermostat, Appliance, and Window Covering. When ready, click **Run** to flash the device. When the device is flashed, a QR code will appear on the WSTK screen. If no QR appears on the screen, the connectivity firmware may need to be updated. Follow the steps here for [Upgrading the Connectivity Firmware on SoC Devices](https://docs.silabs.com/matter/latest/matter-wifi-run-demo/loading-firmware-for-ncp-and-soc-boards#upgrading-the-connectivity-firmware-on-so-c-devices). +1. Select the **Matter WiFi - SoC Lighting FreeRTOS** demo. + > **Note**: A number of other apps are also available including a Lock, Thermostat, Appliance, and Window Covering. +2. When the project is ready, click **Run** to flash the device. When the device is flashed, a QR code will appear on the WSTK screen. If no QR appears on the screen, the connectivity firmware may require an update. Perform the steps for [Upgrading the Connectivity Firmware on SoC Devices](https://docs.silabs.com/matter/latest/matter-wifi-run-demo/loading-firmware-for-ncp-and-soc-boards#upgrading-the-connectivity-firmware-on-so-c-devices). ### Step 3: Prepare the Device for Commissioning @@ -83,13 +85,13 @@ For instructions on installing Simplicity Studio and the Silicon Labs Extension ### Step 1: Create a Matter Sample Project 1. Open Simplicity Studio and repeat the same steps as [above](#flashing-the-siwx917-soc-matter-accessory-device). -2. Instead of selecting **Run** for the demo, click **Create** for the **Matter - SoC Lighting over WiFi** example. -3. Review the Project Configuration and click **Finish**. Simplicity Studio creates a new Solution called MatterLightOverWiFiolution with the MatterLightOverWiFi project inside the workspace. +2. Click **Create** for the **Matter WiFi - SoC Lighting FreeRTOS** example. +3. Review the Project Configuration and click **Finish**. Simplicity Studio creates a new Solution called matter_wifi_soc_lighting_app_freertos_solution with the matter_wifi_soc_lighting_app_freertos project inside the workspace. 4. After the project is created, click the **Open in VS Code** button to open the project in the Silicon Labs Extension for the Visual Studio Code IDE. ### Step 2: Build the Project in the Silicon Labs Extension for the Visual Studio Code IDE -1. Once the MatterLightOverWiFiSolution is open, hover over the solution and click the **Build** button. +1. Once the matter_wifi_soc_lighting_app_freertos_solution is open, hover over the solution and click the **Build** button. ![Building the project](./images/studio-6-build.png) diff --git a/sld477-matter-quick-start-demo/02-thread-quick-start-demo.md b/sld477-matter-quick-start-demo/02-thread-quick-start-demo.md index f1a6260..5d86e1a 100644 --- a/sld477-matter-quick-start-demo/02-thread-quick-start-demo.md +++ b/sld477-matter-quick-start-demo/02-thread-quick-start-demo.md @@ -1,10 +1,12 @@ # Matter over Thread Quick-Start Demo -This Quick-Start Guide demonstrates the out-of-box experience for adding an EFR32MG24 Matter Accessory Device to ecosystems. Other boards are also supported. For the full list of Matter capable hardware, refer to the [Silicon Labs Matter Selector Guide](https://www.silabs.com/wireless/matter/selector-guide). This demo uses the **Matter - SoC Lighting over Thread** example application available in Simplicity Studio. The guide walks through flashing the EFR32 SoC device, commissioning it to an ecosystem using the Simplicity Connect mobile app, and controlling it from either Google Home or Apple Home apps. +This quick start guide demonstrates an out-of-box experience for adding an EFR32MG24 Matter Accessory Device to ecosystems. Other boards are also supported. For the full list of Matter compatible hardware, refer to the [Silicon Labs Matter Selector Guide](https://www.silabs.com/wireless/matter/selector-guide). + +This demo uses the **Matter Thread - SoC Lighting FreeRTOS** example application available in Simplicity Studio. The guide describes how to flash the EFR32 SoC device, commission it to an ecosystem using the Simplicity Connect mobile app, and control it from the Google Home or Apple Home app. ## Software Requirements -- Simplicity Studio v6 with SiSDK - 2025.12.2 + Silicon Labs Matter - 2.8.1 +- Simplicity Studio v6 with SiSDK - 2026.6.0 + Silicon Labs Matter - 2.9.0 - Simplicity Connect mobile App on Smartphone ## Hardware Requirements @@ -48,7 +50,9 @@ Type **lighting** into the keyword search and you will see the following screen. ![Simplicity Studio Example Projects & Demos](./images/studio-6-matter-thread-demo-lighting-projects.png) -For this quick start guide, select the **Matter - SoC Lighting over Thread** demo. A number of other apps are also available including a Lock, Thermostat, Appliance, and Window Covering. When ready, click **Run** to flash the device. When the device is flashed, a QR code will appear on the WSTK screen. +1. Select the **Matter Thread - SoC Lighting FreeRTOS** demo. + > **Note**: A number of other apps are also available including a Lock, Thermostat, Appliance, and Window Covering. +2. When the project is ready, click **Run** to flash the device. When the device is flashed, a QR code will appear on the WSTK screen. ### Step 3: Prepare the Device for Commissioning @@ -107,14 +111,14 @@ For instructions on installing Simplicity Studio and the Silicon Labs Extension ### Step 1: Create a Matter Sample Project 1. Open Simplicity Studio and repeat the same steps as [above](#flashing-the-efr32-soc-matter-accessory-device). -2. Instead of selecting **Run** for the demo, click **Create** for the **Matter - SoC Lighting over Thread with external Bootloader** example. -3. Review the Project Configuration and click **Finish**. Simplicity Studio creates a new Solution called MatterLightOverThreadSolution with the MatterLightOverThread project inside the workspace. +2. Click **Create** for the **Matter Thread - SoC Lighting with external Bootloader FreeRTOS** example. +3. Review the Project Configuration and click **Finish**. Simplicity Studio creates a new Solution called matter_thread_soc_lighting_app_series_2_freertos with the matter_thread_soc_lighting_app_freertos project inside the workspace. ![Creating a project](./images/studio-6-matter-project-demo.png) 4. After the project is created, click the **Open in VS Code** button to open the project in the Silicon Labs Extension for the Visual Studio Code IDE. ### Step 2: Build the Project in the Silicon Labs Extension for the Visual Studio Code IDE -1. Once the MatterLightOverThreadSolution is open, hover over the solution and click the **Build** button. +1. Once the matter_thread_soc_lighting_app_series_2_freertos solution is open, hover over the solution and click the **Build** button. ![Building the project](./images/studio-6-build.png) diff --git a/sld477-matter-quick-start-demo/images/flashing-studio-6.png b/sld477-matter-quick-start-demo/images/flashing-studio-6.png index 21922f5..3d255bc 100644 Binary files a/sld477-matter-quick-start-demo/images/flashing-studio-6.png and b/sld477-matter-quick-start-demo/images/flashing-studio-6.png differ diff --git a/sld477-matter-quick-start-demo/images/studio-6-build.png b/sld477-matter-quick-start-demo/images/studio-6-build.png index 5a01c6a..afa1406 100644 Binary files a/sld477-matter-quick-start-demo/images/studio-6-build.png and b/sld477-matter-quick-start-demo/images/studio-6-build.png differ diff --git a/sld477-matter-quick-start-demo/images/studio-6-matter-project-demo.png b/sld477-matter-quick-start-demo/images/studio-6-matter-project-demo.png index 74786d1..bdbc2f8 100644 Binary files a/sld477-matter-quick-start-demo/images/studio-6-matter-project-demo.png and b/sld477-matter-quick-start-demo/images/studio-6-matter-project-demo.png differ diff --git a/sld477-matter-quick-start-demo/images/studio-6-matter-thread-demo-lighting-projects.png b/sld477-matter-quick-start-demo/images/studio-6-matter-thread-demo-lighting-projects.png index 3b0aeb7..a143933 100644 Binary files a/sld477-matter-quick-start-demo/images/studio-6-matter-thread-demo-lighting-projects.png and b/sld477-matter-quick-start-demo/images/studio-6-matter-thread-demo-lighting-projects.png differ diff --git a/sld477-matter-quick-start-demo/images/studio-6-select-device.png b/sld477-matter-quick-start-demo/images/studio-6-select-device.png index 20f5a40..8431274 100644 Binary files a/sld477-matter-quick-start-demo/images/studio-6-select-device.png and b/sld477-matter-quick-start-demo/images/studio-6-select-device.png differ diff --git a/sld477-matter-quick-start-demo/images/successful-flash.png b/sld477-matter-quick-start-demo/images/successful-flash.png index d77ce74..68e8062 100644 Binary files a/sld477-matter-quick-start-demo/images/successful-flash.png and b/sld477-matter-quick-start-demo/images/successful-flash.png differ diff --git a/sld477-matter-quick-start-demo/images/vscode-build-flash.png b/sld477-matter-quick-start-demo/images/vscode-build-flash.png index 8c237b2..edf02b4 100644 Binary files a/sld477-matter-quick-start-demo/images/vscode-build-flash.png and b/sld477-matter-quick-start-demo/images/vscode-build-flash.png differ diff --git a/sld477-matter-quick-start-demo/images/wifi-light-demo.png b/sld477-matter-quick-start-demo/images/wifi-light-demo.png index 0ec1277..af002bf 100644 Binary files a/sld477-matter-quick-start-demo/images/wifi-light-demo.png and b/sld477-matter-quick-start-demo/images/wifi-light-demo.png differ diff --git a/sld5257-matter-provisioning/images/matter-shell-enable.png b/sld5257-matter-provisioning/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld5257-matter-provisioning/images/matter-shell-enable.png and b/sld5257-matter-provisioning/images/matter-shell-enable.png differ diff --git a/sld5257-matter-provisioning/images/solution-artifacts.png b/sld5257-matter-provisioning/images/solution-artifacts.png index 581c4bc..7755714 100644 Binary files a/sld5257-matter-provisioning/images/solution-artifacts.png and b/sld5257-matter-provisioning/images/solution-artifacts.png differ diff --git a/sld5257-matter-provisioning/images/solution-generation.png b/sld5257-matter-provisioning/images/solution-generation.png index c4faeb7..29403e5 100644 Binary files a/sld5257-matter-provisioning/images/solution-generation.png and b/sld5257-matter-provisioning/images/solution-generation.png differ diff --git a/sld5257-matter-provisioning/images/studio-thread-light.png b/sld5257-matter-provisioning/images/studio-thread-light.png index 0c120e1..4abdfb2 100644 Binary files a/sld5257-matter-provisioning/images/studio-thread-light.png and b/sld5257-matter-provisioning/images/studio-thread-light.png differ diff --git a/sld5257-matter-provisioning/provisioning-gui-tool.md b/sld5257-matter-provisioning/provisioning-gui-tool.md index f2d7fe3..5b33de3 100644 --- a/sld5257-matter-provisioning/provisioning-gui-tool.md +++ b/sld5257-matter-provisioning/provisioning-gui-tool.md @@ -86,7 +86,7 @@ In an existing installation of Simplicity Studio, the MPT can be installed from Before you can use the Matter Provisioning Tool GUI, you need to perform the steps below. -1. Using the Matter SDK, create a Matter Project that supports provisioning of certificates on the Device. Example of Projects: Matter - SoC Thermostat over Thread. +1. Using the Matter SDK, create a Matter Project that supports provisioning of certificates on the Device. Example of Projects: Matter Thread - SoC Thermostat FreeRTOS. 2. In Launcher perspective, select **Create New Project**, select the **Matter** filter, select **Project**, and then click **Next**. Specify a project name and then click **Finish**. diff --git a/sld5257-matter-provisioning/test-matter-certs-for-development.md b/sld5257-matter-provisioning/test-matter-certs-for-development.md index 1c3be5d..351f521 100644 --- a/sld5257-matter-provisioning/test-matter-certs-for-development.md +++ b/sld5257-matter-provisioning/test-matter-certs-for-development.md @@ -312,9 +312,9 @@ Incoming(4): ### Building a Sample Application - Studio - Matter Extension -#### Create a New Lighting Over Thread Project +#### Create a New Matter Thread - SoC Lighting with external Bootloader FreeRTOS Project -![Lighting over Thread example](images/studio-thread-light.png) +![Matter Thread - SoC Lighting with external Bootloader FreeRTOS example](images/studio-thread-light.png) #### Install Matter Device Attestation Credentials Component diff --git a/sld57-matter-landing-page/index.md b/sld57-matter-landing-page/index.md index af928f4..b477446 100644 --- a/sld57-matter-landing-page/index.md +++ b/sld57-matter-landing-page/index.md @@ -31,7 +31,7 @@ Want to get a Matter application up and running quickly? Here's a high-level ove 4. **[Optional] Customize Matter App Behavior and Logic** - Use Project Configurator and other Studio tools to customize your app logic: [Developing with Project Configurator](https://docs.silabs.com/ssv6ug/latest/ssv6-configure-project/) - - If necessary, add custom source files for your application logic + - Customize app behavior using the model your sample app provides — see [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). Refactored apps use `CustomerAppTask` and `autogen/AppTask.cpp`, all other apps use `DataModelCallbacks.cpp` and `src/AppTask.cpp`. - Follow documentation to develop a custom matter device with ZAP and corresponding callbacks: [Custom Matter Device Development](/matter/{build-docspace-version}/matter-references/custom-matter-device) 5. **Build and Flash** @@ -48,7 +48,7 @@ Want to get a Matter application up and running quickly? Here's a high-level ove ## Other Resources -**To see release notes** containing a list of features and known issues, go to [Matter Release Notes on Silicon Labs Matter Extension](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.8.1). +**To see release notes** containing a list of features and known issues, go to [Matter Release Notes on Silicon Labs Matter Extension](https://github.com/SiliconLabs/matter_extension/releases/tag/v2.9.0). **If you are new to Matter** or would like more information about Silicon Labs Matter-based products, see the [Matter content on silabs.com](https://www.silabs.com/wireless/matter). diff --git a/sld601-matter-application-development/images/ClusterLogic6.jpg b/sld601-matter-application-development/images/ClusterLogic6.jpg deleted file mode 100644 index cc951aa..0000000 Binary files a/sld601-matter-application-development/images/ClusterLogic6.jpg and /dev/null differ diff --git a/sld601-matter-application-development/images/ClusterLogic6.png b/sld601-matter-application-development/images/ClusterLogic6.png new file mode 100644 index 0000000..3013229 Binary files /dev/null and b/sld601-matter-application-development/images/ClusterLogic6.png differ diff --git a/sld601-matter-application-development/images/studio-lock-thread.png b/sld601-matter-application-development/images/studio-lock-thread.png index ddc25ec..81212a5 100644 Binary files a/sld601-matter-application-development/images/studio-lock-thread.png and b/sld601-matter-application-development/images/studio-lock-thread.png differ diff --git a/sld601-matter-application-development/index.md b/sld601-matter-application-development/index.md index c012e6d..fb44db8 100644 --- a/sld601-matter-application-development/index.md +++ b/sld601-matter-application-development/index.md @@ -1,6 +1,6 @@ # Introduction -This section covers application development topics. Silicon Labs will build out this section over time. For Matter v2.8.1, we provide: +This section covers application development topics. Silicon Labs will build out this section over time. For Matter v2.9.0, we provide: - [Matter Scenes Quick Start Guide](./matter-scenes-quick-start-guide) - [Matter Event and Timer Guide](./matter-event-timer-guide.md) diff --git a/sld601-matter-application-development/matter-application-cluster-logic.md b/sld601-matter-application-development/matter-application-cluster-logic.md index 6f25f04..4417f7b 100644 --- a/sld601-matter-application-development/matter-application-cluster-logic.md +++ b/sld601-matter-application-development/matter-application-cluster-logic.md @@ -18,9 +18,11 @@ To create the Matter Door Lock App, launch Simplicity Studio and connect a suppo ![Studio Launcher Window](./images/studio-device-create-project.jpeg) -Select **Create New Project**, then use the filter to search for "Matter". Locate the "Matter - SoC Lock over Thread with External Bootloader" project. Click **Next**, then select **Finish**. +1. Select **Create New Project**, then use the filter to search for "Matter". +2. Locate the "Matter Thread - SoC Lock with external Bootloader FreeRTOS" project. +3. Click **Next**, then select **Finish**. -![Matter SoC Lock over Thread Project](./images/studio-lock-thread.png) +![Matter Thread - SoC Lock with external Bootloader FreeRTOS Project](./images/studio-lock-thread.png) The sample application has been successfully created in Simplicity Studio. You can now proceed to Step 2. @@ -53,14 +55,23 @@ Now that the On/Off cluster has been successfully added to the Sample Door Lock - Attributes, commands, and events for the cluster are added to your application’s data model. - Code is generated for attribute storage, command handling, and event notification. -- Callback stubs are generated for you to implement application-specific behavior. -- You interact with the cluster by filling in these stubs and using the generated data structures. +- **New architecture**: implement application-specific behavior in `src/CustomerAppTask.cpp` by overriding `*Impl()` hooks (for example `DMPostAttributeChangeCallbackImpl()`), not by editing `autogen/AppTask.cpp`. +- **Legacy architecture**: Callback stubs are generated for you to implement application-specific behavior. You interact with the cluster by filling in these stubs and using the generated data structures. Additionally, a corresponding component is automatically added to your project. This occurs because enabling a cluster in ZAP updates your project configuration to include the necessary software components and libraries required to support that cluster’s functionality. For clusters, this functionality is implemented in the `/third_party/matter_sdk/src/app/clusters` directory. For the On/Off cluster, the server command handlers and related logic can be found in the `/on-off-server/on-off-server.cpp` file. ## Step 4: Add Application Logic -Locate your project's `src/AppTask.cpp` file. This file acts as the central hub for application-specific logic, initialization, and event processing in a Matter application on Silicon Labs platforms. Start by adding two helper functions: a one-shot timer to expire in 10 seconds and the `OnOffTmrExpiryHandler` handler function. +This guide uses the Lock sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models) to confirm which model your project uses. + +### New Architecture + +Application logic centers on AppTask, but refactored Matter projects split responsibilities: + +- `autogen/AppTask.cpp`: default implementation, regenerated on project upgrade (do not edit for application logic, use as reference only). +- `src/CustomerAppTask.cpp` and `include/CustomerAppTask.h`: your custom logic, add custom code and override `*Impl()` hooks here. + +In `src/CustomerAppTask.cpp`, add two helper functions: a one-shot timer to expire in 10 seconds and the `OnOffTmrExpiryHandler` handler function. ```C++ #include "app-common/zap-generated/attributes/Accessors.h" @@ -87,22 +98,55 @@ void OnOffTmrStart(){ } ``` -Make sure to include `app-common/zap-generated/attributes/Accessors.h` in your `AppTask.cpp` file so you can access cluster attributes. +Include `app-common/zap-generated/attributes/Accessors.h` in `CustomerAppTask.cpp`, so that you can access cluster attributes. -Next we will need an AppTask function to initiate the timer. Add the following function to your AppTask.cpp file: +Next we will need an AppTask function to initiate the timer. Declare `OnOffAttributeWriteStartTimer()` in `include/CustomerAppTask.h` and define it in `src/CustomerAppTask.cpp`: ```C++ -void AppTask::OnOffAttributeWriteStartTimer() +void OnOffAttributeWriteStartTimer() { OnOffTmrStart(); } ``` -This function will have to be defined in AppTask.h as well as part of the AppTask class. +Because you modify the OnOff attribute in `OnOffTmrExpiryHandler()`, restart the timer whenever the OnOff attribute changes. Override `DMPostAttributeChangeCallbackImpl()` in `CustomerAppTask` (the SDK routes attribute changes through `MatterPostAttributeChangeCallback` in `BaseApplication.cpp`, then `AppTask::DMPostAttributeChangeCallback` in autogen): + +```C++ +void DMPostAttributeChangeCallbackImpl(const chip::app::ConcreteAttributePath & attributePath, uint8_t type, uint16_t size, + uint8_t * value) +{ + ClusterId clusterId = attributePath.mClusterId; + AttributeId attributeId = attributePath.mAttributeId; + + if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id){ + OnOffAttributeWriteStartTimer(); + } + +} +``` + +Finally, add a call to `OnOffTmrStart()` at the end of your `AppInitImpl()` override in `CustomerAppTask.cpp` to start the attribute write sequence. The following image illustrates the code flow: + +![Code Flow](./images/ClusterLogic6.png) + +In the flowchart above, `OnOffAttributeWriteStartTimer()` calls `OnOffTmrStart()` to restart the timer. + +### Legacy Architecture + +Locate your project's src/AppTask.cpp file. This file acts as the central hub for application-specific logic, initialization, and event processing in a Matter application on Silicon Labs platforms. Start by adding two helper functions: a one-shot timer to expire in 10 seconds and the OnOffTmrExpiryHandler handler function. + +Include `app-common/zap-generated/attributes/Accessors.h` in your `AppTask.cpp` file, so that you can access cluster attributes. + +Add the timer start function to `AppTask.cpp` and declare it in `AppTask.h`: -Now, locate the `MatterPostAttributeChangeCallback()` function in the `src/DataModelCallbacks.cpp` file. This function is invoked by the application framework after an attribute value has been changed. Because you are modifying the OnOff attribute in the `OnOffTmrExpiryHandler()` function, use this callback to re-initiate the timer so that the attribute continues to toggle. To achieve this, call `AppTask::OnOffAttributeWriteStartTimer()`, which is part of the AppTask context. +```C++ +void AppTask::OnOffAttributeWriteStartTimer() +{ + OnOffTmrStart(); +} +``` -To implement this functionality, first obtain the AppTask instance using `AppTask::GetAppTask()`. Modify the `MatterPostAttributeChangeCallback()` function as shown below: +Now, locate the MatterPostAttributeChangeCallback() function in the src/DataModelCallbacks.cpp file. This function is invoked by the application framework after an attribute value has been changed. Because you are modifying the OnOff attribute in the OnOffTmrExpiryHandler() function, use this callback to re-initiate the timer so that the attribute continues to toggle. To achieve this, call AppTask::OnOffAttributeWriteStartTimer(), which is part of the AppTask context. ```C++ void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t type, uint16_t size, @@ -110,8 +154,6 @@ void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & { ClusterId clusterId = attributePath.mClusterId; AttributeId attributeId = attributePath.mAttributeId; - - // Auto-generated code if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id){ AppTask::GetAppTask().OnOffAttributeWriteStartTimer(); @@ -119,13 +161,10 @@ void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & } ``` -Make sure to #include "AppTask.h" at the top of the `DataModelCallbacks.cpp` file to call the `AppTask::GetAppTask()` function. For more information on the AppTask, refer to AppTask.h. -Finally, add a call to `OnOffTmrStart()` at the end of the `AppTask::AppInit()` function to start the attribute write sequence. The following image illustrates the code flow: +Make sure to #include "AppTask.h" at the top of the DataModelCallbacks.cpp file to call the AppTask::GetAppTask() function. For more information on the AppTask, refer to AppTask.h. -![Code Flow](./images/ClusterLogic6.jpg) - -In the flowchart above, `OnOffAttributeWriteStartTimer()` calls `OnOffTmrStart()` to restart the timer. +Finally, add a call to OnOffTmrStart() at the end of the AppTask::AppInit() function to start the attribute write sequence. ## Step 5: Interact with the On/Off Cluster diff --git a/sld601-matter-application-development/matter-event-timer-guide.md b/sld601-matter-application-development/matter-event-timer-guide.md index 7314026..d1bf386 100644 --- a/sld601-matter-application-development/matter-event-timer-guide.md +++ b/sld601-matter-application-development/matter-event-timer-guide.md @@ -3,7 +3,9 @@ ## Event Handler -The Matter event handler uses the FreeRTOS queue to transport a message from the producer to the consumer area. Events can be used to create an asynchronous message processing or an inter-task message communication. +The Matter event handler uses the FreeRTOS queue to transport a message from the producer to the consumer area. Events can be used to create asynchronous message processing or inter-task communication. + +Depending on your sample app, instructions apply. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). Steps to make an event work: @@ -55,6 +57,25 @@ struct AppEvent When creating an event and pushing it to the event queue at minimum, **Handler** and **Type** must be defined in order for the event to work. +### New Architecture + +Custom event posting and handlers are overridden in the `CustomerAppTask` file, not in `autogen/AppTask.cpp`. + +```C++ +void CreateObserverEvent(void) +{ + AppEvent active_mode_event = {}; + active_mode_event.Type = AppEvent::kEventType_Observer; + active_mode_event.Handler = SilabsSensors::SendSensorsValues; + + AppInstance().PostEvent(&active_mode_event); +} +``` + +### Legacy Architecture + +Post events from `src/AppTask.cpp`: + ```C++ void AppTask::CreateObserverEvent(void) { @@ -81,6 +102,43 @@ void SilabsSensors::SendSensorsValues(AppEvent * aEvent) **AppTaskMain** is dispatching all the events from the event list. +### New Architecture + +```C++ +void AppTask::AppTaskMain(void * pvParameter) +{ + AppEvent event; + QueueHandle_t sAppEventQueue = *(static_cast(pvParameter)); + + CHIP_ERROR err = AppInstance().Init(); + if (err != CHIP_NO_ERROR) + { + SILABS_LOG("AppTask.Init() failed"); + appError(err); + } + +#if !(defined(CHIP_CONFIG_ENABLE_ICD_SERVER) && CHIP_CONFIG_ENABLE_ICD_SERVER) + AppInstance().StartStatusLEDTimer(); +#endif + + AppInstance().RegisterObserver(); + + SILABS_LOG("App Task started"); + + while (true) + { + BaseType_t eventReceived = xQueueReceive(sAppEventQueue, &event, portMAX_DELAY); + while (eventReceived == pdTRUE) + { + AppInstance().DispatchEvent(&event); + eventReceived = xQueueReceive(sAppEventQueue, &event, 0); + } + } +} +``` + +### Legacy Architecture + ```C++ void AppTask::AppTaskMain(void * pvParameter) { @@ -130,7 +188,20 @@ chip::DeviceLayer::PlatformMgr().UnlockChipStack(); ### Callback -Timer callback. +### New Architecture + +Timer callback. Implement in `src/CustomerAppTask.cpp`. + +```C++ +void TestCallback(System::Layer * layer, void * aAppState) +{ + // Do something +} +``` + +### Legacy Architecture + +Timer callback. Implement in `src/AppTask.cpp`. ```C++ void AppTask::TestCallback(System::Layer * layer, void * aAppState) diff --git a/sld601-matter-application-development/matter-scenes-quick-start-guide.md b/sld601-matter-application-development/matter-scenes-quick-start-guide.md index 1637fab..cd97a33 100644 --- a/sld601-matter-application-development/matter-scenes-quick-start-guide.md +++ b/sld601-matter-application-development/matter-scenes-quick-start-guide.md @@ -37,7 +37,7 @@ The following hands-on tutorial walks through the process of storing and recalli ### Requirements -- Simplicity SDK 2025.12.2 + Matter extension 2.8.1 (or newer) +- Simplicity SDK 2026.6.0 + Matter extension 2.9.0 (or newer) - Raspberry Pi 4 + MatterHub Image - 1x Silabs WTSK EFR32xG21 (BRD4108B) in RCP configuration - 2x [EFR32xG24-DK2601B Dev Kit](https://www.silabs.com/development-tools/wireless/efr32xg24-dev-kit?tab=overview) @@ -52,7 +52,8 @@ The following hands-on tutorial walks through the process of storing and recalli #### ZAP Configuration -In Simplicity Studio, create a new MatterLightOverThread application. From the application .slcp file, navigate to _Configuration Tools_ > _ZCL Advanced Platform (ZAP)_. +1. In Simplicity Studio, create a new Matter Thread - SoC Lighting FreeRTOS application. +2. From the application .slcp file, navigate to _Configuration Tools_ > _ZCL Advanced Platform (ZAP)_. The Group Key Management cluster (under General) should already be enabled as a server on Endpoint 0. @@ -75,15 +76,15 @@ The component should look like this: ![scenes RGB PWM LED config](./images/scenes-RGB-PWM-LED-config.png) -The RGB PWM LED instance that has been created can be found in _MatterLightOverThread/autogen/sl_simple_rgb_pwm_led_instances.h_. +The RGB PWM LED instance that has been created can be found in _matter_thread_soc_lighting_app_freertos/autogen/sl_simple_rgb_pwm_led_instances.h_. -The documentation for the APIs that have been generated can be found here: [Simple RGB PWM LED Driver](https://docs.silabs.com/gecko-platform/latest/platform-driver/simple-rgb-pwm-led#simple-rgb-pwm-led-driver). The file that contains these APIs can be found in the directory: _MatterLightOverThread/simplicity_sdk_xxxx/platform/driver/leddrv/inc/sl_simple_rgb_pwm_led.h_. +The documentation for the APIs that have been generated can be found here: [Simple RGB PWM LED Driver](https://docs.silabs.com/gecko-platform/latest/platform-driver/simple-rgb-pwm-led#simple-rgb-pwm-led-driver). The file that contains these APIs can be found in the directory: _matter_thread_soc_lighting_app_freertos/simplicity_sdk_xxxx/platform/driver/leddrv/inc/sl_simple_rgb_pwm_led.h_. ### Step 2: Add the ColorTransformer Class The RGB PWM LED operates in the RGB color space; however, the Matter Color Control Cluster does not operate in the RGB color space, so a transformation is required to convert the RGB values into something that can be recognized by Matter. In this example, use the xyY color space as defined by the Commission Internationale de l’Éclairage (CIE) specification which is also recognized in the Matter specification. -Inside the src/ directory of the MatterLightOverThread project, create a new class called _ColorTransformer_ with the corresponding .cpp and .h files. Copy and paste the following to the *ColorTransformer.h* file. +Inside the src/ directory of the matter_thread_soc_lighting_app_freertos project, create a new class called _ColorTransformer_ with the corresponding .cpp and .h files. Copy and paste the following to the *ColorTransformer.h* file. :::collapsed{summary="Click to expand and view the ColorTransformer.h file"} ```c++ @@ -165,9 +166,13 @@ public: ### Step 3 Implement Callbacks -Make the following additions to the src/DataModelCallbacks.cpp file: +This guide uses the Lighting sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models) to confirm which model your project uses. -:::collapsed{summary="Click to expand and view the DataModelCallbacks.cpp file"} +#### New Architecture + +Make the following additions to `src/CustomerAppTask.cpp`: + +:::collapsed{summary="Click to expand and view the CustomerAppTask.cpp additions"} ```c++ // Color Transformer #include "ColorTransformer.h" @@ -192,7 +197,7 @@ bool xyFlag = false; ``` ::: -Then, inside `MatterPostAttributeChangeCallback` in _src/DataModelCallbacks.cpp_, implement the on/off functionality of the LED: +Inside `DMPostAttributeChangeCallbackImpl()` in _src/CustomerAppTask.cpp_, implement the on/off functionality of the LED: ```c++ if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) @@ -208,9 +213,6 @@ if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) #ifdef DIC_ENABLE dic_sendmsg("light/state", (const char *) (value ? (*value ? "on" : "off") : "invalid")); #endif // DIC_ENABLE - LightMgr().InitiateAction(AppEvent::kEventType_Light, *value ? LightingManager::ON_ACTION : LightingManager::OFF_ACTION); - - } ``` @@ -247,15 +249,93 @@ else if (clusterId == ColorControl::Id) } ``` -Lastly, it is necessary to initialize the LED. In src/AppTask.cpp, add the following: +It is necessary to initialize the LED. To do so, override AppInitImpl() in src/CustomerAppTask.cpp and add the following: + +```c++ +#include "sl_simple_rgb_pwm_led.h" +#include "sl_simple_rgb_pwm_led_instances.h" +#include "sl_led.h" +``` + +Inside `AppInitImpl()`: ```c++ +CHIP_ERROR AppInitImpl() +{ + CHIP_ERROR err = CHIP_NO_ERROR; +/* code to add */ + // Initialize LED + sl_led_init((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); + + // Set initial color to white and turn off + uint16_t red = 255; // max red + uint16_t green = 255; // no green + uint16_t blue = 255; // max blue + sl_led_set_rgb_color(&sl_simple_rgb_pwm_led_rgb_led0, red, green, blue); + sl_led_turn_off((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); +/* ----------- */ + +// Update the LCD with the Stored value. Show QR Code if not provisioned + return err; +} +``` + +This initializes the LED to be white. + +#### Legacy Architecture + +Make the following additions to `src/DataModelCallbacks.cpp`: + +:::collapsed{summary="Click to expand and view the DataModelCallbacks.cpp file"} +```c++ +// Color Transformer +#include "ColorTransformer.h" + +// Customer Application #include "sl_simple_rgb_pwm_led.h" #include "sl_simple_rgb_pwm_led_instances.h" #include "sl_led.h" +. +. +// Initialize color mode x-y +uint16_t cx = 0xFFFF; +uint16_t cy = 0xFFFF; + +// Initialize RGB +uint16_t r = 0xFFFF; +uint16_t g = 0xFFFF; +uint16_t b = 0xFFFF; + +// Initialize xy color mode flag +bool xyFlag = false; ``` +::: + +Inside `MatterPostAttributeChangeCallback` in _src/DataModelCallbacks.cpp_, implement the on/off functionality of the LED: + +```c++ +if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) + { +/* code to add */ + if (*value) { // turn on LED + sl_led_turn_on((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); + } else {// turn off LED + sl_led_turn_off((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); + } +/* ----------- */ + +#ifdef DIC_ENABLE + dic_sendmsg("light/state", (const char *) (value ? (*value ? "on" : "off") : "invalid")); +#endif // DIC_ENABLE + LightMgr().InitiateAction(AppEvent::kEventType_Light, *value ? LightingManager::ON_ACTION : LightingManager::OFF_ACTION); + + + } +``` + +Use the same Color Control cluster handling as in the **New architecture** section above. -Then, inside the init function `AppTask::Init()` of src/AppTask.cpp, add the following: +Initialize the LED in `src/AppTask.cpp`. Add the same includes, then inside `AppTask::Init()`: ```c++ CHIP_ERROR AppTask::Init() diff --git a/sld962-matter-aws-feature/aws-configuration-registration.md b/sld962-matter-aws-feature/aws-configuration-registration.md index 7d276af..83d9124 100644 --- a/sld962-matter-aws-feature/aws-configuration-registration.md +++ b/sld962-matter-aws-feature/aws-configuration-registration.md @@ -32,24 +32,39 @@ AWS IoT Core provides secure, bi-directional communication for Internet-connecte 7. Complete the following steps to create a thing and generate certificates for your Matter application to use in the `MatterAwsNvmCert.cpp` source file: - - Go to **All Devices > Things** and select **Create Things**. - ![Create Thing](./images/device-create-things.png) - - Select **Create Single Thing** and click **Next**. - - Under **Specific thing properties > Thing properties**, specify the thing name (this will be the `MATTER_AWS_CLIENT_ID` in `MatterAwsConfig.h`), then click **Next**. + - Go to **All Devices > Things** and select **Create Things**. + ![Create Thing](./images/device-create-things.png) + - Select **Create Single Thing** and click **Next**. + - Under **Specific thing properties > Thing properties**, specify the thing name (this will be the `MATTER_AWS_CLIENT_ID` in `MatterAwsConfig.h`), then click **Next**. ![Add Thing Name](./images/aws-add-thing-name.png) - - Under **Configure device certificate > Device Certificate**, select **Upload CSR**. - - In **Certificate signing request > Choose file** (Choose Client CSR generated by Openssl Certificate Creation in Step 6. e.g., `device.csr`). Click **Next**. - ![Upload CSR](./images/thing-upload-csr.png) - - Select the policy (e.g., `MATTER_AWS_POLICY`) created at Step 4. + - Under **Configure device certificate** > **Device Certificate**. + + - For 917 NCP Dual Stack: + - Select **Auto-generate a new certificate**. + ![Auto-generate a new certificate](./images/thing-auto-gen-aws-certs.png) + - Download the Amazon Root CA1. + - Download the Public and Private keys. + - Skip **Certificate signing request** step for 917 NCP Dual Stack. + + - For 917 NCP and 917 SoC: + - Select **Upload CSR**. + - Under**Certificate signing request**, click **Choose File**. (Choose Client CSR generated by Openssl Certificate Creation in Step 6. e.g., `device.csr`). + - Click **Next**. + ![Upload CSR](./images/thing-upload-csr.png) + + - Select the policy (e.g., `MATTER_AWS_POLICY`) created at Step 4. ![Attach Policy](./images/thing-attach-policy.png) - - Once the thing is successfully created, click **View certificate**. + - Once the thing is successfully created, click **View certificate**. ![View Certificate](./images/thing-view-certificate.png) - - Next: - - Activate the certificate. - - Download the certificate. - ![Activate and Download Certificate](./images/thing-activate-download-certificate.png) + - Next: + - Activate the certificate. + - Download the certificate. + ![Activate and Download Certificate](./images/thing-activate-download-certificate.png) + +8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA3.pem) and add it as CA certificate in `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp`. + +> **Note**: In this example, Amazon Root CA3 is used for 917 NCP and 917 Soc, and Amazon Root CA1 is used for 917 Dual Stack. -8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA3.pem) (We are using Amazon Root CA3) and add it as CA certificate in `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp`. All the certificate should be added in below format: ```cpp diff --git a/sld962-matter-aws-feature/build-matter-aws-dual-stack.md b/sld962-matter-aws-feature/build-matter-aws-dual-stack.md new file mode 100644 index 0000000..92f8984 --- /dev/null +++ b/sld962-matter-aws-feature/build-matter-aws-dual-stack.md @@ -0,0 +1,110 @@ +# Build Procedure for Matter + AWS Dual Stack + +This procedure details how to enable the dual-stack flavor of Matter + AWS in a 917 NCP project. This configuration uses IPv6 on the EFR32 host for Matter and IPv4 on the SiWx917 NWP for AWS cloud connectivity. + +For an architectural overview and flavor comparison, see [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md). + +For the standard Matter + AWS build (917 SoC or standard 917 NCP with host LwIP transport), see [Build Procedure for Matter + AWS](./build-matter-aws.md). + +> **Note:** Dual-stack Matter + AWS is currently supported on 917 NCP boards only (BRD4186C, BRD4187C, BRD4120A). + +## Prerequisites + +- A **917 NCP** Matter project or the reference example `matter_wifi_917_ncp_lock_app_dual_stack_freertos`. +- Matter Extension **2.9.0** or later, and WiseConnect SDK **4.1.0** or later installed in Simplicity Studio. +- AWS cloud configured according to [AWS installation](./aws-configuration-registration.md). +- Hardware and software requirements are met as described in [Matter + AWS Prerequisites](./index.md#prerequisites). + +## Add the AWS Server, Client ID, and Certificate Details + +AWS server, client ID, and Certificates are the same as the standard Matter + AWS flavor. Perform the steps in [Adding the AWS Server, Client ID, and Cluster Details](./build-matter-aws.md#adding-the-aws-server-client-id-and-cluster-details) in the standard build guide and refresh the Matter extension in Simplicity Studio. + +## Get started + +In Simplicity Studio, from the reference example, create a project using `matter_wifi_917_ncp_lock_app_dual_stack_freertos` (917 NCP Lock Dual Stack). + +## Add Dual-Stack Matter + AWS Components + +Configure the project using the Simplicity Studio Project Configurator. Following steps specifically describe about dual-stack, which is different from the [standard Matter + AWS build procedure](./build-matter-aws.md#adding-the-matter--aws-component). + + +### 1. Install Matter AWS with NWP Transport + +1. In the **Software Components** section, enter `aws` in the search box, and then click the search icon. + Search result displays the "AWS for Matter Wi-Fi" component. +2. Select the **AWS for Matter Wi-Fi** component (`matter_aws`) and then click on install. + +3. When prompted for the AWS transport dependency, select **Matter AWS NWP Transport (Si91x)** (`matter_aws_transport_nwp`). Do **not** select Matter AWS LwIP Transport.![Matter AWS NWP Transport Component](images/matter-aws-dependency-3.png) + +4. Select the dependencies for the Matter AWS component as shown in the images. The order of the dependencies can vary, in each case select the option with "+ AWS". + +![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) + +![X.509 Create certificates for Matter + AWS](images/matter-aws-dependency-5.png) + +![X.509 Use certificates for Matter + AWS](images/matter-aws-dependency-4.png) + +### 2. Install TLS 1.2 PRF (917 NCP Requirement) + +In **Software Components**, search for `TLS 1.2 PRF` and install the **TLS 1.2 PRF** component (`psa_crypto_tls12_prf`). + +This step is required for all 917 NCP Matter + AWS builds, including dual-stack. + +![TLS 1.2 PRF Component](images/tls-prf-component-install.png) + +## Build and Flash the Application + +1. Build the dual-stack Matter + AWS application in Simplicity Studio. + For 917 NCP flash and boot procedures, refer to the [917 NCP getting started documentation](/matter/{build-docspace-version}/matter-wifi-getting-started-example/getting-started-siwx917-rcp). +2. Flash the EFR32 host application and the SiWx917 NCP connectivity firmware as required for your board. + +## Verify the Build + +1. Confirm AWS connectivity from the device logs. + The `[MATTER_AWS]` messages displayed after device bootup: + ```console + [00:00:23.400][info ][SVR] [MATTER_AWS] connection callback started + [00:00:23.690][info ][SVR] [MATTER_AWS] MQTT connection status: 0 + [00:00:23.995][info ][SVR] [MATTER_AWS] MQTT sub request callback: 0 + ``` + +2. After subscribing to a topic in AWS IoT, publish logs appears in the device console and in the AWS IoT console. + +![Device Logs AWS](./images/aws-device-logs-thermostat-app.png) + +![AWS IoT App Data](./images/matter-aws-iot-app-data.png) + +3. Commission the device over **EFR32 BLE** and verify Matter control with chip-tool. +4. For end-to-end Matter and cloud testing steps, refer to [End-to-End Test of Matter + AWS Application](./index.md#end-to-end-test-of-matter--aws-application) and [Running the Matter Demo Over Wi-Fi](/matter/{build-docspace-version}/matter-wifi-run-demo). + +## Compile Using New Thing for Different Certificates + +Do not use the same client ID for multiple devices. + +To use AWS, update the following information: + +1. Add your AWS certificates in the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp` file. + - Provide the AWS Root CA key (https://www.amazontrust.com/repository/AmazonRootCA1.pem). + - Provide `device_certificate` and `device_key` with your device certificate and device key. For more details, refer to [OpenSSL Device Certificate Creation](./openssl-certificate-creation.md). + +2. Add your AWS server and client ID information to the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsConfig.h` file. + + - Provide `MATTER_AWS_SERVER_HOST` with your AWS Server name. + - Provide `MATTER_AWS_CLIENT_ID` with your device/thing ID. + +> **Note:** +> - The supported certificate type for the 917 NCP matter dual stack is RSA keys. +> - AWS Root CA used for the 917 NCP matter dual stack https://www.amazontrust.com/repository/AmazonRootCA1.pem + +## Troubleshooting + +- **Matter commissioning or IPv6 connectivity issues** + Ensure that `SLI_SI91X_ENABLE_IPV6=1` is defined and your network supports IPv6 SLAAC. See the IPv6 troubleshooting section in [Matter Wi-Fi FAQ](/matter/{build-docspace-version}/matter-faq/wifi-faq). + +- **AWS MQTT connection failures** + Ensure that IPv4 is enabled on the Matter Wi-Fi component, and AWS server details and credentials in `MatterAwsConfig.h` and `MatterAwsNvmCert.cpp` are correct. + +- **Build errors about conflicting transport** + Remove `matter_aws_transport_lwip` if exists; only one AWS transport component can be installed. + +For architectural context and supported board list, see [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md). diff --git a/sld962-matter-aws-feature/build-matter-aws.md b/sld962-matter-aws-feature/build-matter-aws.md index b03ce57..c78835c 100644 --- a/sld962-matter-aws-feature/build-matter-aws.md +++ b/sld962-matter-aws-feature/build-matter-aws.md @@ -13,20 +13,17 @@ Follow the steps below to set the AWS configuration in the Matter SDK. - Update the AWS server name at `#define MATTER_AWS_SERVER_HOST ""`. - Update the client ID at `#define MATTER_AWS_CLIENT_ID ""`. - - Update the cluster server information as shown in the table below, based on your app: - - | Application Type | Cluster Definition | - |------------------|--------------------| - | Thermostat | `#define ZCL_USING_THERMOSTAT_CLUSTER_SERVER` | - | Lighting | `#define ZCL_USING_ON_OFF_CLUSTER_SERVER` | - | Lock | `#define ZCL_USING_DOOR_LOCK_CLUSTER_SERVER` | - | Window Covering | `#define ZCL_USING_WINDOW_COVERING_CLUSTER_SERVER` | **MatterAwsConfig.h File:** ![MatterAwsConfig.h File](./images/matter-aws-config.png) -4. After making the above changes, refresh the `matter-extension` in Simplicity Studio. +4. Add your AWS certificates in the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp` file. + + - Provide the AWS Root CA key. + - Provide `device_certificate` and `device_key` with your device certificate and device key. For key generation details, refer to [AWS Thing Certificate Creation](./aws-configuration-registration.md). + +5. After making the above changes, refresh the `matter-extension` in Simplicity Studio. - In the **Home** tab, from the left panel, select **Settings**. ![Select Settings](images/aws-build-settings.jpg) - Click **SDKs**, ensure the correct version of the SDK is selected, and then click **Refresh** in the right side menu. @@ -51,10 +48,15 @@ To enable the component in Simplicity Studio, add the following components. 3. Next, select the dependencies for the Matter AWS component. > Note: The order can vary, but in every case select the option with "+ AWS". + When prompted for the AWS transport dependency, select **Matter AWS LWIP Transport** (`matter_aws_transport_lwip`). Do **not** select Matter AWS NWP Transport. + +![Matter AWS NWP Transport Component](images/matter-aws-dependency-2.png) + +![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) - ![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) +![X.509 Create certificates for Matter + AWS](images/matter-aws-dependency-5.png) - ![Public-Key Abstaction Layer for Matter + AWS](images/matter-aws-dependency-2.png) +![X.509 Use certificates for Matter + AWS](images/matter-aws-dependency-4.png) ### Additional Step Needed Only For 917 NCP @@ -100,4 +102,3 @@ Two devices should not use the same client ID. Use a different client ID for you - Provide `MATTER_AWS_SERVER_HOST` with your AWS Server name. - Provide `MATTER_AWS_CLIENT_ID` with your device/thing ID. - - Update `ZCL_USING_ON_OFF_CLUSTER_SERVER` with the cluster server details based on your app. diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-2.png b/sld962-matter-aws-feature/images/matter-aws-dependency-2.png index 001ec76..d353eab 100644 Binary files a/sld962-matter-aws-feature/images/matter-aws-dependency-2.png and b/sld962-matter-aws-feature/images/matter-aws-dependency-2.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-3.png b/sld962-matter-aws-feature/images/matter-aws-dependency-3.png new file mode 100644 index 0000000..28bbebf Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-3.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-4.png b/sld962-matter-aws-feature/images/matter-aws-dependency-4.png new file mode 100644 index 0000000..fb5c5f5 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-4.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-5.png b/sld962-matter-aws-feature/images/matter-aws-dependency-5.png new file mode 100644 index 0000000..e4c7048 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-5.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png b/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png new file mode 100644 index 0000000..a89c556 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png differ diff --git a/sld962-matter-aws-feature/images/matter-shell-enable.png b/sld962-matter-aws-feature/images/matter-shell-enable.png index 7ef6d66..7e122d7 100644 Binary files a/sld962-matter-aws-feature/images/matter-shell-enable.png and b/sld962-matter-aws-feature/images/matter-shell-enable.png differ diff --git a/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png b/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png new file mode 100644 index 0000000..f59c884 Binary files /dev/null and b/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png differ diff --git a/sld962-matter-aws-feature/index.md b/sld962-matter-aws-feature/index.md index 4eeefeb..6de5b16 100644 --- a/sld962-matter-aws-feature/index.md +++ b/sld962-matter-aws-feature/index.md @@ -9,6 +9,13 @@ - Remote users can install a cloud-specific application to receive notifications about the attribute status. +## Matter + AWS Flavors + +Matter + AWS is available in two build flavors: + +- **Standard flavor** — For **917 SoC** and **standard 917 NCP** boards. Uses the host LwIP stack for both Matter (IPv6) and AWS (IPv4) with `matter_lwip` and `matter_aws_transport_lwip`. See [Build Procedure for Matter + AWS](./build-matter-aws.md). +- **Dual-stack flavor (917 NCP)** — For **917 NCP** boards only. Uses a split-stack architecture: Matter over **IPv6** on the EFR32 host LwIP stack and AWS over **IPv4** on the SiWx917 NWP offload stack with `matter_dual_stack` and `matter_aws_transport_nwp`. See [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md) and [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md). + ## Matter + AWS Feature Diagram The following diagram shows end-to-end flow for Direct Internet Connectivity. @@ -24,7 +31,7 @@ official [Silicon Labs Matter hardware requirements](/matter/{build-docspace-version}/matter-prerequisites/hardware-requirements) documentation. -> **Note:** This is supported for 917 SoC and NCP boards only. +> **Note:** The standard flavor is supported for 917 SoC and NCP boards. The dual-stack flavor is supported for **917 NCP boards only** (EFR32 host + BRD4346A). ### Software Requirements @@ -55,7 +62,9 @@ Remote users are used to check the state of Matter devices. In this context, MQT ### Building Matter + AWS Application using Simplicity Studio -Follow the instructions in [Build Procedure for Matter + AWS](./build-matter-aws.md) to enable the MATTER + AWS feature in your application code. +Follow the steps in [Build Procedure for Matter + AWS](./build-matter-aws.md) to enable the Matter + AWS feature for the **standard flavor** (917 SoC and standard 917 NCP). + +For the **dual-stack flavor** on 917 NCP boards, follow [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md). ## End-to-End Test of Matter + AWS Application @@ -96,7 +105,7 @@ User Setup (MQTT Explorer): - toggle - on - off - - Onoff-plug App + - Onoff Plug - Topic: command - Commands: - toggle diff --git a/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md b/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md new file mode 100644 index 0000000..9ffb02d --- /dev/null +++ b/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md @@ -0,0 +1,99 @@ +# Matter + AWS Dual Stack Overview + +The dual-stack flavor of Matter + AWS is a Silicon Labs–specific configuration for 917 NCP (Network Co-Processor) designs. It enables Matter devices to connect locally to the Matter fabric over IPv6 through the EFR32 host and to AWS over IPv4 through the SiWx917 network wireless processor (NWP). + +> **Note:** Dual-stack here is not classic single-stack IPv4+IPv6 on one TCP/IP stack. It is a split-stack NCP architecture with separate network stacks on the host and the NWP. + +## When to Use the Dual-Stack Flavor + +Use the dual-stack flavor when all of the following apply: + +- Your design uses a 917 NCP board (EFR32 host + SiWx917 co-processor over SPI). +- You need Matter + AWS (Direct Internet Connectivity) on that NCP platform. +- Matter traffic must remain on IPv6 on the EFR32 host LwIP stack. +- AWS MQTT/TLS traffic must run over IPv4 on the SiWx917 NWP offload stack. + +For **917 SoC** or **standard 917 NCP** builds that use a single host LwIP stack for both Matter and AWS, use the [standard Matter + AWS build procedure](./build-matter-aws.md) instead. + +## Dual-Stack Architecture + +The following diagram shows how traffic is divided between the EFR32 host and the SiWx917 NWP. + +![Matter + AWS dual-stack architecture](./images/matter-aws-dual-stack-architecture.png) + +| Traffic path | Processor | Network stack | Protocol | +|--------------|-----------|---------------|----------| +| Matter fabric, mDNS, CASE | EFR32 host | Host LwIP | IPv6 | +| Wi-Fi radio association | SiWx917 NWP | Offload stack | — | +| AWS MQTT/TLS | SiWx917 NWP | `sl_si91x_socket` (NWP offload) | IPv4 | + +The EFR32 host and SiWx917 NWP communicate over the SPI NCP interface. The **Matter Dual Stack** component (`matter_dual_stack`) replaces the standard **Matter LwIP** component (`matter_lwip`) and defines the build macro `SL_MATTER_ENABLE_DUAL_STACK=1`. + +## Flavor Comparison + +| Setting | 917 SoC Matter + AWS | Standard 917 NCP Matter + AWS | 917 NCP Dual-Stack Matter + AWS | +|---------|----------------------|-------------------------------|----------------------------------| +| Network provider | `matter_lwip` | `matter_lwip` | **`matter_dual_stack`** | +| AWS transport | `matter_aws_transport_lwip` | `matter_aws_transport_lwip` | **`matter_aws_transport_nwp`** | +| MQTT/TLS path | Host LwIP altcp | Host LwIP altcp | NWP `sl_si91x_socket` | +| Matter protocol | IPv6 (host LwIP) | IPv6 (host LwIP) | IPv6 (host LwIP) | +| AWS/cloud protocol | IPv4 (host LwIP) | IPv4 (host LwIP) | IPv4 (NWP offload) | +| BLE for commissioning | SoC BLE | `matter_wifi_ble` (917) | **`matter_ble`** (EFR32 host) | +| IPv6 project define | via `matter_lwip` | via `matter_lwip` | **`SLI_SI91X_ENABLE_IPV6=1`** | +| Dual-stack build macro | — | — | **`SL_MATTER_ENABLE_DUAL_STACK=1`** | + +The AWS transport components **`matter_aws_transport_lwip`** and **`matter_aws_transport_nwp`** are mutually exclusive. Install exactly one transport with the **Matter AWS** component. + +## Component and Macro Checklist + +When building a dual-stack Matter + AWS application, verify the following: + +| Item | Dual-stack value | +|------|------------------| +| Network stack provider | `matter_dual_stack` (not `matter_lwip`) | +| AWS transport | `matter_aws_transport_nwp` (not `matter_aws_transport_lwip`) | +| BLE component | `matter_ble` (not `matter_wifi_ble`) | +| Matter Wi-Fi IPv4 setting | Enable `CHIP_DEVICE_CONFIG_ENABLE_IPV4` | +| Project define | `SLI_SI91X_ENABLE_IPV6=1` | +| Build macro (automatic) | `SL_MATTER_ENABLE_DUAL_STACK=1` (set by `matter_dual_stack`) | +| AWS dependencies | `mbedtls_x509_use_aws`, `mbedtls_x509_create_aws`, `mbedtls_entropy_default_aws` | +| 917 NCP TLS | `psa_crypto_tls12_prf` (TLS 1.2 PRF) | + +## Supported Hardware and Software + +### Hardware + +Dual-stack Matter + AWS is supported on **917 NCP Radio boards only(BRD4346A)**: + +- BRD4186C +- BRD4187C +- BRD4120A + +Standard Matter + AWS on 917 SoC and standard 917 NCP boards is documented separately. See [Prerequisites](./index.md#prerequisites) on the Matter + AWS index page. + +### Software + +- Matter Extension **2.9.0** or later +- WiseConnect SDK **4.1.0** or later +- Correct SiWx917 NCP connectivity firmware supporting dual network stack mode + +## Reference Example + +The Matter Extension provides a reference door lock application for dual-stack builds: + +- **Project:** `matter_wifi_917_ncp_lock_app_dual_stack_freertos` +- **Description:** Matter over Wi-Fi door lock with BLE on the EFR32 host (IPv6 on EFR32, IPv4 on SiWx917) + +This is currently the only Matter example project configured for the dual-stack flavor. + +## Limitations + +- **917 NCP only** — not supported on 917 SoC or standard single-stack 917 NCP AWS builds. +- **Single reference app** — only the lock app example is provided for dual-stack today. +- **Transport exclusivity** — do not install both `matter_aws_transport_lwip` and `matter_aws_transport_nwp` in the same project. + +## Next Steps + +- [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md): For component installation and project configuration. +- [Build Procedure for Matter + AWS (standard flavor)](./build-matter-aws.md): For 917 SoC and standard 917 NCP. +- [Matter + AWS index](./index.md): For AWS cloud setup, end-to-end testing, and shared configuration.