diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 66213740ba1736..bc24cfa5ae4082 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -65,6 +65,7 @@ body: - release_2.1.0-1.1 - release_2.2.0-1.2-alpha.1 - release_2.2.0-1.2 + - release_2.3.0-1.3-alpha.1 validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index 70dd368767bb2c..36118040c518ad 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -58,6 +58,7 @@ body: - release_2.1.0-1.1 - release_2.2.0-1.2-alpha.1 - release_2.2.0-1.2 + - release_2.3.0-1.3-alpha.1 validations: required: true diff --git a/README.md b/README.md index dc30013c9da636..694ca026607ead 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,12 @@ Device: SiWx917 SoC This repo contains documentation, demos, examples and all the code needed for Matter Accessory Device development on both Thread and Wi-Fi. The Thread development use cases differs from Wi-Fi because the Thread protocol requires the use of an Open Thread Border Router (OTBR). - To get started with the Thread demo and development see - [Matter Thread](https://siliconlabs.github.io/matter/2.2.0-1.2-alpha.1/thread/DEMO_OVERVIEW.html) + [Matter Thread](https://siliconlabs.github.io/matter/2.3.0-1.3-alpha.1/thread/DEMO_OVERVIEW.html) - To get started with the Wi-Fi demo and development see - [Matter Wi-Fi](https://siliconlabs.github.io/matter/2.2.0-1.2-alpha.1/wifi/DEMO_OVERVIEW.html) + [Matter Wi-Fi](https://siliconlabs.github.io/matter/2.3.0-1.3-alpha.1/wifi/DEMO_OVERVIEW.html) The full documentation set starts here: -[Silicon Labs Matter GitHub Documentation](https://siliconlabs.github.io/matter/2.2.0-1.2-alpha.1) +[Silicon Labs Matter GitHub Documentation](https://siliconlabs.github.io/matter/2.3.0-1.3-alpha.1) --- diff --git a/docs/silabs/NEW_FEATURES.md b/docs/silabs/NEW_FEATURES.md index 8cc5160bfb9fdb..2f349f02627fec 100644 --- a/docs/silabs/NEW_FEATURES.md +++ b/docs/silabs/NEW_FEATURES.md @@ -91,7 +91,7 @@ With 1.1, devices will remain in Active Mode until the commissioning is complete The timer starts after the last communication. For this feature to take affect, there needs to be at least one message coming in or going out. If the device just polls its thread router and nothing else happens, this doesn't come into play. - For more details see the [Openthread Sleepy End Device](./general/OT_SLEEPY_END_DEVICE.md) section. + For more details see the [Openthread Sleepy End Device](./thread/OT_SLEEPY_END_DEVICE.md) section. ### Matter Sleepy End Devices over Wi-Fi diff --git a/docs/silabs/README.md b/docs/silabs/README.md index ac98d3f0e9f624..4c916297837dc7 100644 --- a/docs/silabs/README.md +++ b/docs/silabs/README.md @@ -50,7 +50,7 @@ 2. [Security Overview](general/SECURITY.md) 3. [Matter Attestation Credentials for EFR32](../../silabs_examples/credentials/README.md) 4. [Matter Intermittently Connected Devices](general/MATTER_ICD.md) - 5. [Matter Sleepy End Devices over Openthread](general/OT_SLEEPY_END_DEVICE.md) + 5. [Matter Sleepy End Devices over Openthread](thread/OT_SLEEPY_END_DEVICE.md) 6. [Matter OTA Software Update](general/OTA_SOFTWARE_UPDATE.md) 9. Reference Guides diff --git a/docs/silabs/general/ARTIFACTS.md b/docs/silabs/general/ARTIFACTS.md index 1dbeb9a098a179..66d49390dbd907 100644 --- a/docs/silabs/general/ARTIFACTS.md +++ b/docs/silabs/general/ARTIFACTS.md @@ -1,7 +1,9 @@ # Matter Software Artifacts This page provides links to pre-built software image artifacts that can be -used to set up the Matter Demo for the Thread and Wi-Fi use cases. The majority of these artifacts can be found under the "Assets" section on the release page here: +used to set up the Matter Demo for the Thread and Wi-Fi use cases. + +Images for the items listed below are available under the "Assets" section at the bottom of this page: https://github.com/SiliconLabs/matter/releases/tag/2.3.0-1.3-alpha.1 @@ -48,44 +50,42 @@ https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/bootl ## RS9116 Firmware -The RS9116 firmware (rs9116_firmware_files_with_rev.zip) is used to update the RS9116 which can be found here: +The RS9116 firmware (rs9116_firmware_files_with_rev_2.3.0-1.3-alpha.1.zip) is used to update the RS9116 which can be found in the Assets section of this page: https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/rs9116_firmware_files_with_rev_2.3.0-1.3-alpha.1.zip **Note**: RS9116 chip/module needs to be flashed with proper firmware as mentioned below: + - `RS916.x.x.x.x.x.rps - This firmware image is valid for RS9116 1.5 revision chip/module` - `RS9116.x.x.x.x.x.rps - This firmware image is valid for RS9116 1.4/1.3 revision chip/module` ## SiWx917 Firmware for SiWx917 NCP -The SiWx917 firmware(SiWx917NCP_firmware_files.zip) is used to update the SiWx917 NCP which can be found here: +The SiWx917 firmware(SiWx917NCP_firmware_files_2.3.0-1.3-alpha.1.zip) is used to update the SiWx917 NCP which can be found in the Assets section of this page: https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/SiWx917NCP_firmware_files_2.3.0-1.3-alpha.1.zip **Note**: SiWx917 NCP board need to be flashed with proper firmware as mentioned below: -- `SiWG917-A.2.9.X.X.X.rps - This firmware image is valid for BRD8036A (A0 Expansion v1.1) board` +- `SiWG917-B.2.X.X.X.X.rps - This firmware image is valid for BRD4346A board` ## SiWx917 Firmware for SiWx917 SoC -The SiWx917 firmware (SiWx917SOC_firmware_files.zip) along with WiSeConnect 3 SDK is used to update the SiWx917 SoC which can be found here: +The SiWx917 firmware (SiWx917SOC_firmware_files_2.3.0-1.3-alpha.1.zip) along with WiSeConnect 3 SDK is used to update the SiWx917 SoC which can be found in the Assets section of this page: https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/SiWx917SOC_firmware_files_2.3.0-1.3-alpha.1.zip **Note**: SiWx917 SoC boards need to be flashed with proper firmware as mentioned below: -- `SiWG917-A.2.9.X.X.X.rps - This firmware image is valid for BRD4325B(A0 dual flash 1.1) and BRD4325B(A0 dual flash 1.2) boards` -- `SiWG917-B.2.9.X.X.X.rps - This firmware image is valid for BRD4325C(B0 common flash v1.2), BRD4325G(B0 Stacked Flash + External PSRAM v1.2) and BRD4338A(B0 common flash v2.0) boards` -## SiWx917 SoC Configuration Files for Flashing the Matter Application +- `SiWG917-B.2.X.X.X.X.rps - This firmware image is valid for BRD4338A(B0 common flash v2.0) board` + +## SiWx917 SoC Configuration Files For JLink RTT Logging -In order to flash the Matter Application on the SiWx917 SoC, the Ozone Debugger must -be configured for the SiWx917 SoC device by following the instructions on the [Ozone Environment Setup for SiWx917 SoC page](../wifi/SiWx917_Enablement_For_Ozone.md). +In order to check device logs 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](../wifi/JLINK_GUIDE_917.md). -The **JLinkDevices.xml** and **ELF** files referenced in the instructions may be found -here: +The [JLinkDevices.xml](https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/JLinkDevices.xml) and **.elf** files referenced in the instructions may be found in the Assets section of this page. -https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/JLinkDevices.xml -https://github.com/SiliconLabs/matter/releases/download/v2.3.0-1.3-alpha.1/RS9117_SF_4MB_42bsp.elf \ No newline at end of file +**Note**:- For EFR32MG2x devices, JLink RTT Logging support is already available. diff --git a/docs/silabs/general/CODE_SIZE_SAVINGS.md b/docs/silabs/general/CODE_SIZE_SAVINGS.md index 1a9aaa497277c9..536156c9c05f58 100644 --- a/docs/silabs/general/CODE_SIZE_SAVINGS.md +++ b/docs/silabs/general/CODE_SIZE_SAVINGS.md @@ -1,5 +1,5 @@ -# Code Savings Guide for Matter Applications +# Code Savings Guide for Building Matter Applications -* Remove unnecessary clusters from the zap configuration. Example applications have clusters enabled to support both Thread and WiFi transport layers such as the Diagnostics clusters. +* Remove unnecessary clusters from the zap configuration. Example applications have clusters enabled to support both Thread and WiFi transport layers such as the Diagnostics clusters. -* Remove optional features in Matter that may not be needed for a certain application. In the EFR32 build [script](https://github.com/SiliconLabs/matter/blob/latest/scripts/examples/gn_build_example.sh), there are additional build arguments that are added to either add or remove optional Matter features. For example, added a build argument disable_lcd=true will save flash by disabling the lcd screen. +* Remove optional features in Matter that may not be needed for a certain application. In the EFR32 build script, there are additional build arguments that are added to either add or remove optional Matter features. For example, added a build argument disable_lcd=true will save flash by disabling the lcd screen. \ No newline at end of file diff --git a/docs/silabs/general/COMMISSIONING.md b/docs/silabs/general/COMMISSIONING.md index e0706eb37330c8..3c0842cb652fe8 100644 --- a/docs/silabs/general/COMMISSIONING.md +++ b/docs/silabs/general/COMMISSIONING.md @@ -1,4 +1,4 @@ -# Matter Commissioning +# Commissioning ## Overview @@ -7,10 +7,10 @@ The commissioning process supports two potential starting points: 1. The device is already on the network 2. The device needs network credentials for Wi-Fi or Thread (requires Bluetooth LE (BLE) support) -The current Matter revision supports Ethernet, Wi-Fi, and Thread devices. +The current Matter revision supports Ethernet, Wi-Fi, and Thread devices. - Ethernet devices get into the operational network when their Ethernet cable is connected. Therefore the devices are normally already on the network before commissioning. -- Wi-Fi and Thread devices must have credentials configured before the devices can be joined into the operational network. This is normally done over BLE. +- Wi-Fi and Thread devices must have credentials configured before the devices join into the operational network. This is normally done over BLE. This page focuses on Wi-Fi and Thread. The first step for these devices is to enter commissioning mode, following one of two scenarios: @@ -19,7 +19,7 @@ This page focuses on Wi-Fi and Thread. The first step for these devices is to en | Standard | Device automatically goes into the commissioning mode on power-up. Beneficial for limited UI devices (such as light bulbs) | | User-Directed | Device only enters commissioning mode when initiated by the user. Helpful for devices that have user interfaces or for which commissioning should not be initiated without a user present. | -The following figure provides an overview of the commissioning process and the actions each role performs. +The following figure provides an overview of the commissioning process and the actions each role performs. ![Commissioning Overview](./images/CommissioningOverview.png) @@ -27,14 +27,13 @@ The following figure provides an overview of the commissioning process and the a ![Steps 1-4](./images/CommissioningSteps1-4.png) -In step 1, the Matter device must enter commissioning mode in one of the two scenarios -described above. +In step 1, the Matter device must enter commissioning mode in one of the two scenarios described above. Usually, a mobile phone serves as the administrator. Step 2 is to use the mobile phone to scan the QR code of the Matter device. The QR code is used as a passcode to set up a secured BLE connection. -Step 3 is to set up the BLE beaconing and connection between the mobile phone and the Matter device, so that the commissioning information can be exchanged through the BLE connection channel. +Step 3 is to set up the BLE beaconing and connection between the mobile phone and the Matter device, so that the commissioning information can be exchanged through the BLE connection channel. -As the connection should be secure, step 4 is to secure the connection in a process known as password-authenticated session establishment (**PACE**). The passcode derived from the QR code is used as an input for this process. The output is the security key used by the connection. +As the connection should be secure, step 4 is to secure the connection in a process known as password-authenticated session establishment (**PASE**). The passcode derived from the QR code is used as an input for this process. The output is the security key used by the connection. ![Steps 5-7](./images/CommissioningSteps5-7.png) @@ -42,12 +41,12 @@ After the secured connection is established, step 5 is to verify the Matter devi Step 6 is to install the operational certificate for the device. The administrator either obtains the certificate from the remote server or generates the certificate locally and then transfers the certificate to the device. The administrator also configures the Access Control List (**ACL**) with the list of administrators. -After operational security is configured, step 7 is to configure the operational network for the device. For Wi-Fi devices, the SSID and the password are configured. For Thread devices, the PAN ID, network key, and other parameters are configured. +After operational security is configured, step 7 is to configure the operational network for the device. For Wi-Fi devices, the SSID and the password are configured. For Thread devices, the PAN ID, network key, and other parameters are configured. ![Steps 8-10](./images/CommissioningSteps8-10.png) -In step 8, the device starts to join the operational network with the configured parameters. +In step 8, the device starts to join the operational network with the configured parameters. -Once the device is attached to the network (step 9), it can be discovered through Service Registration Protocol (**SRP**). To control that device, you must establish a secured connection through the Certification Authorized Session Establishment (**CASE**) process. +Once the device is attached to the network (step 9), it can be discovered through Service Registration Protocol (**SRP**). To control that device, you must establish a secured connection through the Certification Authorized Session Establishment (**CASE**) process. -After the CASE session is established, the Matter device is commissioned successfully and can communicate with other devices in the Matter network (step 10). +After the CASE session is established, the Matter device is commissioned successfully and can communicate with other devices in the Matter network (step 10). diff --git a/docs/silabs/general/COMMIT_HASHES.md b/docs/silabs/general/COMMIT_HASHES.md index 493a25413b3abc..b88b7eddb8ce0a 100644 --- a/docs/silabs/general/COMMIT_HASHES.md +++ b/docs/silabs/general/COMMIT_HASHES.md @@ -7,13 +7,19 @@ in this release of the Silicon Labs Matter Out of Box Experience | Repo | Branch | Commit Hash | | ------------------------------------------ | ------ | ---------------------------------------- | -| https://github.com/SiliconLabs/ot-br-posix | main | bb565ca0164981f58a2659222c30917399703a9b | +| https://github.com/SiliconLabs/ot-br-posix | main | 42f98b27bc7f54951c860cd98ce5ff7c7fedc68c | ## Radio Co-Processor (RCP) | Repo | Branch | Commit Hash | | --------------------------------------- | ---------- | ---------------------------------------- | -| https://github.com/SiliconLabs/ot-efr32 | matter_sve | 038475dcc21c51448d35309496a2f7401eb2ccfe | +| https://github.com/SiliconLabs/ot-efr32 | main | e75c767374a6a6fccd62f024c7217762ae652891 | + +## Openthread + +| Repo | Branch | Commit Hash | +| --------------------------------------- | ---------- | ---------------------------------------- | +| https://github.com/openthread/openthread | main | 7074a43e4577d32d5535d52e7940ed2ea7e3a528 | ## Connectivity Standards Alliance (CSA) connectedhomeip (Matter) @@ -25,10 +31,10 @@ in this release of the Silicon Labs Matter Out of Box Experience | Repo | Branch | Commit Hash | | ----------------------------------------------- | ------------------------ | ----------------- | -| https://github.com/SiliconLabs/matter | release_2.3.0-1.3-alpha.1 | \ | +| https://github.com/SiliconLabs/matter | release_2.3.0-1.3-alpha.1 | c36f4a7745ac0092982933987c694a6b605de35d | ## Matter Accessory Device (MAD) | Repo | Branch | Commit Hash | | ----------------------------------------------- | ------------------------ | ----------------------| -| https://github.com/SiliconLabs/matter | release_2.3.0-1.3-alpha.1 | \ | +| https://github.com/SiliconLabs/matter | release_2.3.0-1.3-alpha.1 | c36f4a7745ac0092982933987c694a6b605de35d| diff --git a/docs/silabs/general/CUSTOM_MATTER_DEVICE.md b/docs/silabs/general/CUSTOM_MATTER_DEVICE.md index 83e34919da7662..d0104f13d3d16a 100644 --- a/docs/silabs/general/CUSTOM_MATTER_DEVICE.md +++ b/docs/silabs/general/CUSTOM_MATTER_DEVICE.md @@ -31,7 +31,6 @@ application example. ```shell $ ./scripts/tools/zap/run_zaptool.sh examples/lighting-app/lighting-common/lighting-app.zap ``` - On the left side of the application, there is a tab for Endpoint 0 and Endpoint 1. Endpoint 0 is known as the root node. This endpoint is akin to a "read me first" endpoint that describes itself and the other endpoints that make @@ -53,7 +52,7 @@ your application to the full power of the Matter SDK. For example, if a lighting application only includes single color LEDs instead of RGB LEDs, it might make sense to disable the Color Control cluster in the ZAP configuration. Similarly, if a -lighting application doesn't take advantage of the Level Control cluster, +lighting application does not take advantage of the Level Control cluster, which allows you to customize current flow to an LED, it might make sense to disable the Level Control cluster. @@ -64,11 +63,10 @@ generate ZAP code. ```shell $ ./scripts/tools/zap/generate.py examples/lighting-app/lighting-common/lighting-app.zap -o zzz_generated/lighting-app/zap-generated/ ``` - ## Receiving Matter Commands All Matter commands reach the application through the intermediate function -MatterPostAttributeChangeCallback(). When a request is made by a Matter client, +`MatterPostAttributeChangeCallback()`. When a request is made by a Matter client, the information contained in the request is forwarded to a Matter application through this function. The command can then be dissected using conditional logic to call the proper application functions based on the most recent command @@ -113,6 +111,7 @@ MoveToLevel action. LightMgr().InitiateActionLight(AppEvent::kEventType_Light, action_type, endpoint, *value); } ``` + ## Send a MoveToLevel Command and Read the CurrentLevel Attribute Rebuild the application and load the new executable on your EFR32 device. Send @@ -133,4 +132,4 @@ $ mattertool levelcontrol read current-level 1 1 // Returns 10 ``` For more information on running a Silicon Labs lighting example on a Thunderboard Sense 2 see -[sl-newlight/efr32](https://github.com/SiliconLabs/matter/blob/latest/silabs_examples/sl-newLight/efr32/README.md). +[sl-newlight/efr32](https://github.com/SiliconLabs/matter/blob/latest/silabs_examples/sl-newLight/efr32/README.md). diff --git a/docs/silabs/general/EP.md b/docs/silabs/general/EP.md index 854a055585b9db..8978f39973cc5f 100644 --- a/docs/silabs/general/EP.md +++ b/docs/silabs/general/EP.md @@ -7,7 +7,7 @@ developing an energy-friendly device. Using Energy Profiler with Matter is the same as any other protocol except that you need to start the usage from within Energy Profiler inside Simplicity Studio, rather than using an existing Simplicity Studio project, since your -Matter project will not have been created inside Simplicity Studio. +Matter project will not have been created inside Simplicity Studio. Complete documentation on using the Simplicity Studio Energy Profiler is provided in the diff --git a/docs/silabs/general/FIND_RASPI.md b/docs/silabs/general/FIND_RASPI.md index c5b46d1f2d2aa7..2aa2f34653c394 100644 --- a/docs/silabs/general/FIND_RASPI.md +++ b/docs/silabs/general/FIND_RASPI.md @@ -2,20 +2,59 @@ ## Finding the IP address of your Raspberry Pi -Sometimes it can be difficult to find your Raspberry Pi on the network. One way of interacting with the Raspberry Pi is connecting a keyboard, mouse and monitor to it. The preferred method, however, is over SSH. For this, you will need to know the IP address of your Raspberry Pi. +Sometimes it can be difficult to find your Raspberry Pi on the network. One way of interacting with the Raspberry Pi is to connect a keyboard, mouse, and monitor to it. The preferred method, however, is over SSH. For this, you will need to know the IP address of your Raspberry Pi. This is a [good tutorial](https://raspberryexpert.com/find-raspberry-pi-ip-address/) on how to find the IP address. +### Mac / Linux -| Platform | Strategy | -| -------- | -------- | -| Mac / Linux | ***Nmap***
  The use of nmap on the Mac may require a software download.
  Use nmap with the following command:
   `sudo nmap -sn .0/24`

  Example: `sudo nmap -sn 1-.4.148.0/24`

  Among other returned values, you will see:
    `Nmap scan report for ubuntu.silabs.com (10.4.148.44)`
    `Host is up (0.00025s latency).`
    `MAC Address: E4:5F:01:7B:CD:12 (Raspberry Pi Trading)`

  And this is the Raspberry Pi at 10.4.148.44

***Arp***
  Alternatively, use Arp with the following command:
   `arp -a \| grep -i "b8:27:eb\|dc:a6:32"` | -| Windows | In the command prompt, use `nslookup` to fnd your Raspberry Pi.
  Example: `nslookup ubuntu` | +***Nmap*** -
+The use of nmap on the Mac may require a software download. +Use nmap with the following command: + +```shell + $ sudo nmap -sn .0/24` +``` + +Example: `sudo nmap -sn 10.4.148.0/24`, Among other returned values, you will see something: + +```shell + $ Nmap scan report for ubuntu.silabs.com (10.4.148.44) + $ Host is up (0.00025s latency). + $ MAC Address: AA:BB:CC:11:22:33 (Raspberry Pi Trading) +``` + +And this is the Raspberry Pi at 10.4.148.44. + +***Arp*** + +Alternatively, use Arp with the following command: + +```shell + $ arp -a \| grep -i "CC:BB:22\|DC:a6:32"` +``` + +### Windows + +In the command prompt, use `nslookup` to fnd your Raspberry Pi. + +Example: `nslookup ubuntu` ## Connecting to your Raspberry Pi over SSH -| Platform | Strategy | -| -------- | -------- | -| Mac / Linux / Windows | Once you have found your Raspberry Pi's IP address, you can use Secure Shell (SSH) to connect to it over the command line with the following command:
  `ssh @`

Example:
  `ssh ubuntu@10.4.148.44`
 `password: raspberrypi`

When prompted provide the raspberry pi's password, in the case of the Silicon Labs Matter Hub image the username is ***ubuntu*** and the password is ***raspberrypi*** | +### Mac / Linux / Windows + +Once you have found your Raspberry Pi's IP address, you can use Secure Shell (SSH) to connect to it over the command line with the following command: + +```shell + $ ssh @ +``` + +Example: + +```shell + $ ssh ubuntu@10.4.148.44 +``` + +`password: raspberrypi or ubuntu` When prompted provide the raspberry pi's password, in the case of the Silicon Labs Matter Hub image the username is `ubuntu` and the password is either `ubuntu` or ``. (Note that if you are logging into your Raspberry Pi for the first time you may be asked to change the default password to a password of your choosing.) \ No newline at end of file diff --git a/docs/silabs/general/FLASH_SILABS_DEVICE.md b/docs/silabs/general/FLASH_SILABS_DEVICE.md index 5019e3b9e70494..e799b3549d01b4 100644 --- a/docs/silabs/general/FLASH_SILABS_DEVICE.md +++ b/docs/silabs/general/FLASH_SILABS_DEVICE.md @@ -1,28 +1,19 @@ # How to Flash a Silicon Labs Device -Once you have an image built, you can flash it onto your EFR or SiWx917 SOC device (either a development board or the Thunderboard Sense 2) over USB connected to your development machine. This can be done using either Simplicity Studio or Ozone J-Link Debugger or the standalone Simplicity Commander. - -
+Once you have an image built, you can flash it onto your EFR or SiWx917 device (either a development board or the Thunderboard Sense 2) over USB connected to your development machine. This can be done using Simplicity Commander. ## Simplicity Commander -Links to download Simplicity Commander's standalone versions are included below. Full documentation on Simplicity Commander is included in the [Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf) - - Linux: https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip - - Mac: https://www.silabs.com/documents/public/software/SimplicityCommander-Mac.zip - - Windows: https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip -To Flash the bootloader and Matter Pre-built Binaries, refer to: [Flashing using Commander](./FLASHING_USING_COMMANDER.md) +Links to download Simplicity Commander's standalone versions are included below. Full documentation on Simplicity Commander is included in the [Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf) -## Simplicity Studio: -Simplicity Studio is a complete development environment and tool suite. It has the ability to discover USB connected development boards and flash them. -- [Download Simplicity Studio](https://www.silabs.com/developers/simplicity-studio) -- [Simplicity Studio Reference Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-building-and-flashing/flashing) +- Linux: https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip +- Mac: https://www.silabs.com/documents/public/software/SimplicityCommander-Mac.zip +- Windows: https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip -## (Optional) Ozone J-Link Debugger: -Multi-platform debugger and performance analyzer for J-Link and J-Trace -- Download for: [Windows](https://www.segger.com/downloads/jlink/Ozone_Setup_Windows_x64.exe) | [Mac](https://www.segger.com/downloads/jlink/Ozone_macOS_Universal.pkg) | [Linux](https://www.segger.com/downloads/jlink/Ozone_Linux_x86_64.deb) -- [Flashing and debug procedure for Ozone](../wifi/RUN_DEMO_SiWx917_SoC.md) +To Flash the bootloader and Binaries, refer [Flashing using Commander](./FLASHING_USING_COMMANDER.md) ## (Optional) J-Link RTT for Logging: + Multi-platform Logging software for device logs. Links to download J-Link RTT for logging are included below - Linux: https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb - Mac: https://www.segger.com/downloads/jlink/JLink_MacOSX_universal.pkg diff --git a/docs/silabs/general/FLASH_SILABS_SiWx917_SOC_DEVICE.md b/docs/silabs/general/FLASH_SILABS_SiWx917_SOC_DEVICE.md index 7133a3f534dcfb..7290b31451ab7e 100644 --- a/docs/silabs/general/FLASH_SILABS_SiWx917_SOC_DEVICE.md +++ b/docs/silabs/general/FLASH_SILABS_SiWx917_SOC_DEVICE.md @@ -1,6 +1,6 @@ # How to Flash a SiWx917 SoC Device -Once you have an image built, you can flash it onto your SiWx917 SoC device over USB connected to your development machine. This can be done using Simplicity Studio, Simplicity Commander or Ozone Debugger. +Once you have an image built, you can flash it onto your SiWx917 SoC device over USB connected to your development machine. This can be done using Simplicity Commander. ## Simplicity Commander @@ -8,17 +8,8 @@ Links to download Simplicity Commander's standalone versions are included below. - Linux: https://www.silabs.com/documents/public/software/SimplicityCommander-Linux.zip - Mac: https://www.silabs.com/documents/public/software/SimplicityCommander-Mac.zip - Windows: https://www.silabs.com/documents/public/software/SimplicityCommander-Windows.zip -To Flash the bootloader and Binaries, refer [Flashing using Commander](./FLASHING_USING_COMMANDER.md) -## Simplicity Studio: -Simplicity Studio is a complete development environment and tool suite. It has the ability to discover USB connected development boards and flash them. -- [Download Simplicity Studio](https://www.silabs.com/developers/simplicity-studio) -- [Simplicity Studio Reference Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-building-and-flashing/flashing) - -## Ozone J-Link Debugger: -- Multi-platform debugger and performance analyzer for J-Link and J-Trace - - Download for: [Windows](https://www.segger.com/downloads/jlink/Ozone_Setup_Windows_x64.exe) | [Mac](https://www.segger.com/downloads/jlink/Ozone_macOS_Universal.pkg) | [Linux](https://www.segger.com/downloads/jlink/Ozone_Linux_x86_64.deb) -- [Flashing and debug procedure for Ozone](../wifi/RUN_DEMO_SiWx917_SoC.md) +To Flash the bootloader and binaries, refer to the [Flashing using Commander](./FLASHING_USING_COMMANDER.md) guide. ## (Optional) J-Link RTT for Logging: Multi-platform Logging software for device logs. Links to download J-Link RTT for logging are included below diff --git a/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md b/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md index 14b2dbf56a93f7..2c197757c9447a 100644 --- a/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md +++ b/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md @@ -98,7 +98,7 @@ An Untimed Write Transaction requires only the Write Request Action and the Writ Untimed and timed Write Transactions differ in their restrictions. All actions in timed transactions are unicast-only, whereas Untimed Write Request Actions may be multicast but require the Suppress Response flag to be set to prevent the network from flooding with status responses. -## The Invoke Interaction +## Invoke Interaction ![Diagram of a Timed Invoke Interaction](resources/timed-invoke-interaction.jpg) @@ -121,7 +121,7 @@ Just like a Timed Write Transaction, a Timed Invoke Transaction consists of the Untimed and timed Invoke Transactions differ in the same way that untimed and timed Write Transactions differ, both in their actions and restrictions on unicast or multicast. -## The Subscription Interaction +## Subscription Interaction ![Diagram of a Subscription Interaction](resources/subscription-interaction.jpg) diff --git a/docs/silabs/general/FUNDAMENTALS_INTRO.md b/docs/silabs/general/FUNDAMENTALS_INTRO.md index 264310fc76180f..a2a1e408ec7a52 100644 --- a/docs/silabs/general/FUNDAMENTALS_INTRO.md +++ b/docs/silabs/general/FUNDAMENTALS_INTRO.md @@ -40,7 +40,7 @@ Regardless of the Network topology being used, Matter has a concept of Fabrics. | Vendor | 16 bit number that uniquely identifies a particular product manufacturer, vendor, or group thereof. | | Product | 16 bit number that uniquely identifies the product from a specific vendor. | | Group | 16 bit number ID set of nodes across a Matter Fabric | -| Universal Group | 16 bit subrange of the Group ID reserved for groups across Matter Standard. Specifically a UID for all nodes, all non-sleepy nodes, and all proxies. | +| Universal Group | 16 bit subrange of the Group ID reserved for groups across Matter Standard. Specifically a UID for all nodes, all non-ICD nodes, and all proxies. | | Operational Node | 64 bit number that uniquely identifies an individual node on the fabric | | PAKE Key Identifiers | This is a subrange of Node ID used to assign an Access Control subject to a particular PAKE key. This creates an ACL (Access Control List) entry to provide admin access via a PASE session. | diff --git a/docs/silabs/general/GATT.md b/docs/silabs/general/GATT.md index 4ce820f7aef273..925def91ae43b4 100644 --- a/docs/silabs/general/GATT.md +++ b/docs/silabs/general/GATT.md @@ -1,6 +1,6 @@ # Using Simplicity Studio's GATT Configurator with Matter -The Simplicity Studio Bluetooth GATT Configurator is an Advanced Configurator +The Simplicity Studio Bluetooth LE (BLE) GATT Configurator is an Advanced Configurator within the Simplicity Studio Project Configuration suite. For more information on using the [Simplicity Studio Project Configurator in Matter refer to this guide](./PINTOOL.md). diff --git a/docs/silabs/general/HARDWARE_REQUIREMENTS.md b/docs/silabs/general/HARDWARE_REQUIREMENTS.md index 490bdbdfab0868..73f99c41779b39 100644 --- a/docs/silabs/general/HARDWARE_REQUIREMENTS.md +++ b/docs/silabs/general/HARDWARE_REQUIREMENTS.md @@ -102,17 +102,17 @@ Matter Accessory Devices for Matter over Thread on the following platforms: - [SLWRB4170A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4170a-efr32mg12-radio-board) -## Matter over Wi-Fi Accessory Device Requirements for NCP mode +## Matter Over Wi-Fi Accessory Device Requirements + +### Matter Over Wi-Fi Accessory Device Requirements for NCP Mode The Silicon Labs Matter over Wi-Fi NCP mode demo and development requires two boards: the Silicon Labs EFR32 Radio board to run the Matter code and either the RS9116, SiWx917 or WF200 to run the Wi-Fi protocol stack. -Pre-built images for the EFR32 are provided on the [Matter Artifacts page](./ARTIFACTS.md). Pre-built images for SiWx917 or RS9116 connectivity -firmware are available as per the instructions on the [Software Requirements Page](./SOFTWARE_REQUIREMENTS.md). +Pre-built images for the EFR32 are provided on the [Matter Artifacts page](./ARTIFACTS.md). Pre-built images for SiWx917 or RS9116 connectivity firmware are also provided on the [Matter Artifacts page](./ARTIFACTS.md). > **Note:** > 1. The EFR32MG24 is the preferred starting point for Matter MCUs. It provides Secure Vault and can use the internal flash of the device to store an upgrade image. -> 2. The WF200 connectivity firmware image is included in the EFR32MG12 or EFR32MG24 images on the [Matter Artifacts page](./ARTIFACTS.md) for running with the WF200 in NCP mode. The -Matter application downloads the connectivity firmware onto the WF200 on first-time startup. +> 2. The WF200 connectivity firmware image is included in the EFR32MG24 images on the [Matter Artifacts page](./ARTIFACTS.md) for running with the WF200 in NCP mode. The Matter application downloads the connectivity firmware onto the WF200 on first-time startup. The following boards are supported for the Matter over Wi-Fi demos and development: @@ -125,20 +125,6 @@ The following boards are supported for the Matter over Wi-Fi demos and developme - [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board) - MG24 with WSTK : [xG24-PK6010A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-20-dbm?tab=overview) -- **MG12 boards:** - - [EFR32MG12 Development Kit](https://www.silabs.com/development-tools/wireless/zigbee/efr32mg12-dual-band-starter-kit) - - BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board) - - BRD4162A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@10dBm - - [SLWRB4162A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4162a-efr32mg12-radio-board) - - BRD4163A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4163A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4163a-efr32mg12-radio-board) - - BRD4164A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4164A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4164a-efr32mg12-radio-board) - - BRD4170A / SLWSTK6000B / Multiband Wireless Starter Kit / 2.4GHz@19dBm, 915MHz@19dBm - - [SLWRB4170A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4170a-efr32mg12-radio-board) - - - **Wi-Fi NCP Dev Kits & boards** - RS9116 @@ -149,49 +135,47 @@ The following boards are supported for the Matter over Wi-Fi demos and developme - DB-EVK1 / Dual Band Wi-Fi Development Kit / 2.4GHz & 5GHz - [RS9116X-DB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-db-evk-development-kit) > **Note:** Matter only supported over 2.4GHz on this Dev kit. - - Interconnect board (included in the Wi-Fi kits) - - SPI Cable (included in the RS9116 kit) - - Jumper Cables (included in the RS9116 kit) - SiWx917 - SiWx917 NCP Mode / Wi-Fi Expansion Board / 2.4GHz - - BRD8036A (A0 Expansion v1.0) - - BRD8036A (A0 Expansion v1.1) + - BRD4346A - WF200 - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) - WFM200S / Single Band Wi-Fi Expansion Board / 2.4GHz - [SLEXP8023A](https://www.silabs.com/development-tools/wireless/wi-fi/wfm200-wifi-expansion-kit) + - Interconnect board (included in the Wi-Fi kits) + - SPI Cable (included in the RS9116 kit) + - Jumper Cables (included in the RS9116 kit) - -## Matter over Wi-Fi Accessory Device Requirements for SoC mode +### Matter over Wi-Fi Accessory Device Requirements for SoC mode The Silicon Labs Matter over Wi-Fi demo and development for SoC mode requires the SiWx917 SoC board that supports Matter over Wi-Fi in a single-chip package - the integrated M4 processor is dedicated for peripheral and application-related processing (Matter), while the ThreadArch® runs the wireless and networking protocol stacks. -Pre-built images for the SiWx917 connectivity firmware are available as per the instructions on the [Software Requirements Page](./SOFTWARE_REQUIREMENTS.md). The following boards are supported for the Matter over Wi-Fi demos and development: +Pre-built images for the SiWx917 connectivity firmware are available as per the instructions on the [Matter Artifacts page](./ARTIFACTS.md). The following boards are supported for the Matter over Wi-Fi demos and development: - **Wi-Fi SoC boards:** -- SiWx917 / BRD4002A / Wireless Starter Kit -- SiWx917 SoC Mode - - SiWx917 SoC / Dual Flash Radio Board / 2.4GHz - - BRD4325B - A0 dual flash 1.1 - - BRD4325B - A0 dual flash 1.2 - - SiWx917 SoC / Common Flash Radio Board / 2.4GHz - - BRD4325C - B0 common flash v1.2 - - BRD4325G - B0 Stacked Flash + External PSRAM v1.2 - - BRD4338A - B0 common flash v2.0 +- SiWx917 / BRD4002A / Wireless Starter Kit +- SiWx917 SoC Mode + - SiWx917 SoC / Common Flash Radio Board / 2.4GHz + - BRD4338A - B0 common flash v2.0 **Note:** Refer [SiWx917 SoC](https://www.silabs.com/wireless/wi-fi/siwx917-wireless-socs) for more details -## Additional Matter over Wi-Fi Hardware Requirements +### Additional Matter over Wi-Fi Hardware Requirements In addition to your Matter over Wi-Fi Accessory Device you will need the following for both running the demo and for development: +- Windows/Linux/MacOS computer with a USB port +- USB cable for connecting WSTK Board to Computer +- Raspberry Pi with a >32 GB SD Card - Access point with Internet access -- microSD card (>=32GB) (if using Raspberry Pi) - **[Optional]** Android Mobile phone (If using the chip-tool on Android) +- Interconnect board (included in the RS9116 kit) +- SPI Cable (included in the RS9116 kit) +- Jumper Cables (included in the RS9116 kit) diff --git a/docs/silabs/general/MATTER_ICD.md b/docs/silabs/general/MATTER_ICD.md index 0e3de180db0e47..40ca2ce4aa0f91 100644 --- a/docs/silabs/general/MATTER_ICD.md +++ b/docs/silabs/general/MATTER_ICD.md @@ -4,28 +4,28 @@ Matter introduces the concept of Intermittently Connected Devices (ICD) in the S An Intermittently Connected Device is the Matter representation of a device that is not always reachable. This covers battery-powered devices that disable their underlying hardware when in a low-power mode or devices that can be disconnected from the network, like a phone app. -This page focuses on features designed to improve the performance and reliability of battery-powered devices. +This page focuses on features designed to improve the performance and reliability of battery-powered devices. By default Matter ICD functionality is enabled. ## ICD Device Types -Matter introduces two types of Intermittently Connected Device. +Matter introduces two types of ICDs. -* Short Idle Time ICDs -* Long Idle Time ICDs +- Short Idle Time ICDs +- Long Idle Time ICDs ### Short Idle Time ICDs Short Idle Time ICDs are battery powered devices that can always be reached by clients. -This means that their polling intervals are small enough to garantee that a message sent from client will be able to reach the ICD without any synchronization. -A door lock, for example, is typicaly a SIT ICD because it needs to be able to receive commands from clients at any given time. +This means that their polling intervals are small enough to guarantee that a message sent from a client will be able to reach the ICD without any synchronization. +A door lock, for example, is typicaly a short idle time ICD because it needs to be able to receive commands from clients at any given time. These devices are usually not the initiators in the communication flow. ### Long Idle ICDs Long Idle Time ICDs are battery powered devices that require synchronization between the client and the ICD for communication to succeed. -A sensor device is an example of a device that are typicaly LIT ICDs. +A sensor device is an example of a device that are typicaly long idle time ICDs. -Long Idle Time ICDs are provisionnal with the Matter 1.2 release. +Long Idle Time ICDs are provisional with the Matter 1.3 alpha release. ## ICD Management Cluster @@ -48,25 +48,21 @@ They can be changed by using the following build configuration. sl_idle_mode_interval_ms = 600000 //10min Idle Mode Interval sl_active_mode_interval_ms = 1000 //1s Active Mode Interval sl_active_mode_threshold_ms = 500 //500ms Active Mode Threshold -``` - +``` To change them within a build command ```shell ./scripts/examples/gn_silabs_example.sh ./examples/light-switch-app/silabs ./out/light-switch-app_ICD BRD4187C --icd sl_idle_mode_interval_ms=600000 sl_active_mode_interval_ms=1000 sl_active_mode_threshold_ms= 500 ``` - -These options can also be change by setting them to a default value in the projects `openthread.gni` file. -See `examples/lock-app/silabs/openthread.gni` for an example on how they can be configured. +These options can also be change by setting them to a default value in the projects openthread.gni file. See examples/lock-app/silabs/openthread.gni for an example on how they can be configured. ```cpp // ICD Matter Configuration flags sl_idle_mode_interval_s = 600 //10min Idle Mode Interval sl_active_mode_interval_ms = 10000 //10s Active Mode Interval sl_active_mode_threshold_ms = 1000 //1s Active Mode Threshold ``` +The second way of changing the configuration is to set these defines in the projects ChipProjectConfig.h. -The second way of changing the configuration is to set these defines in the projects `ChipProjectConfig.h`. ```cpp - /** * @def CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL_SEC * @@ -89,8 +85,7 @@ The second way of changing the configuration is to set these defines in the proj */ #define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD_MS 300 ``` - -Using the build arguments either in the build command or in the `openthread.gni` file is the preffered method. +Using the build arguments either in the build command or in the openthread.gni file is the preferred method. ## Subscription Maximum Interval @@ -98,8 +93,7 @@ Using the build arguments either in the build command or in the `openthread.gni` The subscription mechanism is used by ecosystems and controllers to receive attribute change updates and liveness checks. The maximum interval of a subscription request is what defines the frequency at which a device will send a liveness check if there are no attribute changes. -Within the subscription request / response model, a device has the opportunity to decide the maximum interval at which it will send its liveness check (Empty Report Update). -The device can set a maximum interval within this range if and only if it is an ICD: +Within the subscription request / response model, a device has the opportunity to decide the maximum interval at which it will send its liveness check (Empty Report Update). The device can set a maximum interval within this range if and only if it is an ICD: ```shell MinIntervalRequested ≤ MaxInterval ≤ MAX(IdleModeInterval, MaxIntervalRequested) @@ -114,7 +108,7 @@ The following table shows the subscribe response fields. ### Maximum Interval Negotiation The Matter SDK provides a default implementation that allows an ICD to negotiate its MaxInterval. -The goal of the algorithme is to set the MaxInterval to the IdleModeInterval. +The goal of the algorithm is to set the MaxInterval to the IdleModeInterval. ```cpp #if CHIP_CONFIG_ENABLE_ICD_SERVER @@ -217,6 +211,7 @@ public: ``` The second step is registering the callback object to the Interaction Model Engine. + ```cpp // Register ICD subscription callback to match subscription max intervals to its idle time interval chip::app::InteractionModelEngine::GetInstance()->RegisterReadHandlerAppCallback(&mICDSubscriptionHandler); @@ -227,26 +222,22 @@ chip::app::InteractionModelEngine::GetInstance()->RegisterReadHandlerAppCallback Persistent subscriptions were added to Matter as a means to ensure that an ICD can re-establish its subscription and by extension its secure session to a subscriber in the event of a power cycle. When a device accepts a subscription request, it will persist the subscription. When the device reboots, it will try to re-establish its subscription with the subscriber. -If the subscription is torn down during normal operations or if the re-establishement fails, +If the subscription is torn down during normal operations or if the re-establishment fails, the subscription will be deleted. -Persistent subscriptions are enable by default on all Silabs sample apps. -```bash -chip_persist_subscriptions = true -``` +Persistent subscriptions are enabled by default on all Silicon Labs sample applications. -Matter also provides a retry mecanishme for devices to try to re-establish a lost subscription with a client. -This feature is desable by default on the door-lock and light-switch example. -This feature should not be used a ICD since it can significantly reduce battery life. -```bash -chip_subscription_timeout_resumption = false -``` +### Subscription Timeout Resumption -## Subscription synchronisation +Matter also provides a retry mechanism for devices to try to re-establish a lost subscription with a client. This feature should not be used on an ICD since it can significantly reduce battery life. This functionality can be disabled by adding -To avoid forcing an ICD to become active multiple times, the Matter SDK allows an ICD to synchronize its subscription reporting and send all the reports at the same time. -The mecansim syncrhonizes the maximum interval of the all subscription to only require the ICD to become active one. -```bash -sl_use_subscription_synching = true -``` -This feature is enabled by default on the door-lock sample app and the light-switch simple app. \ No newline at end of file +`chip_subscription_timeout_resumption = false` + +## Subscription Synchronization + +To avoid forcing an ICD to become active multiple times, the Matter SDK allows an ICD to synchronize its subscription reporting and send all the reports at the same time. The mecansim syncrhonizes the maximum interval of the all subscription to only require the ICD to become active one. This functionality can be enabled by adding + +`sl_use_subscription_synching = true` + +For further details on Matter ICD's operating on OpenThread, visit [Matter Intermittently Connected Devices over OpenThread](../thread/OT_SLEEPY_END_DEVICE.md). +And for Matter ICD's operating via WiFi, visit [Matter Intermittently Connected Devices over WiFi](../wifi/WIFI_SLEEPY_END_DEVICE.md). diff --git a/docs/silabs/general/OTA_BOOTLOADER.md b/docs/silabs/general/OTA_BOOTLOADER.md index f84730a006dd99..f26f2ec6d01ba2 100644 --- a/docs/silabs/general/OTA_BOOTLOADER.md +++ b/docs/silabs/general/OTA_BOOTLOADER.md @@ -35,10 +35,10 @@ Bootloader Storage Slot component (it should be already installed) configure Slot 0's Start Address and Slot size. - For external storage bootloaders the Start Address should be 0 and Slot size - should be 1048576 -- both values are set by default + should be 1048576 -- both values are set by default - For internal storage bootloaders see the "Internal Bootloader: Image Size, - Selecting Storage Slot Address and Size" section below In the Common Storage - component leave the "Start address of bootload info" at 0. + Selecting Storage Slot Address and Size" section below In the Common Storage + component leave the "Start address of bootload info" at 0. ### Configuring Other Components @@ -125,10 +125,9 @@ by using the Simplicity Commander tool: beginning of the second or third available block to account for potential growth of the application image -- this way the bootloader won't have to be reconfigured for every increase in the image size. The storage slot must - still be able to accommodate the GBL image for the update. Another way to + still be able to accommodate the GBL image for the update. Another way to calculate the Storage Slot parameters is by examining the application's .map file: - - Build the running image for the Matter application - In the application .map file find the highest address preceding the .data section, round it up to align on the 8K page boundary (e.g. @@ -143,39 +142,42 @@ by using the Simplicity Commander tool: This example is for an internal storage bootloader for the Matter lighting app on BRD4186C. -- Build the application disabling all optional features - +- Build the application disabling all optional features + ```shell $ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs out lighting-app BRD4186A chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true ``` -- Build the GBL file for the update image and note its size +- Build the GBL file for the update image and note its size ```shell $ commander gbl create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37 ``` ```shell - $ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl 451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl + $ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl + 451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl ``` - Flash the application image, bootloader (pre-built BRD4186C bootloader binary from the [Matter Artifacts page](./ARTIFACTS.md). Erase the flash. -![Erase Flash](./images/ApplicationUploadEraseFlash.png) + ![Erase Flash](./images/ApplicationUploadEraseFlash.png) - In Simplicity Commander display the flash map - ![Flash Map](./images/CommanderFlashMap.png) + + ![Flash Map](./images/CommanderFlashMap.png) - The address of the first available page is 0x080b8000, the end address of - the last available block is 0x08172000. This means you can set the Slot - Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = - 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file - (451176 bytes) + the last available block is 0x08172000. This means you can set the Slot + Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = + 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file + (451176 bytes) - Create a project base on the "Bootloader - SoC Internal Storage (single - image on 512kB device)" example. Configure the Bootloader Storage Slot - component and set Slot Address and Slot Size. - ![StudioProject](./images/StudioProject.png) + image on 512kB device)" example. Configure the Bootloader Storage Slot + component and set Slot Address and Slot Size. + + ![StudioProject](./images/StudioProject.png) - Enable the "GBL Compression (LZMA)" component. - Build the project diff --git a/docs/silabs/general/OTA_SOFTWARE_UPDATE.md b/docs/silabs/general/OTA_SOFTWARE_UPDATE.md index d3cd94265bd4b4..35eeb88f42ce40 100644 --- a/docs/silabs/general/OTA_SOFTWARE_UPDATE.md +++ b/docs/silabs/general/OTA_SOFTWARE_UPDATE.md @@ -1,8 +1,10 @@ -# Matter Software Update with EFR32 Example Applications +# Matter Software Update with Silicon Labs Example Applications -The Over The Air (OTA) Software Update functionality is enabled by default for -all of the EFR32 example applications. Its inclusion in an application is -controlled by the `chip_enable_ota_requestor` compile flag. +This page outlines the steps for a scenario that demonstrates the Over +The Air (OTA) Software Update functionality of Matter. + +Over The Air (OTA) Software Update functionality is enabled by default for +all Silicon Labs example applications. ## Hardware Requirements - To run matter ota on Silicon Labs Platform, refer to: [Hardware Requirements](../general/HARDWARE_REQUIREMENTS.md) @@ -11,13 +13,17 @@ controlled by the `chip_enable_ota_requestor` compile flag. - To run matter ota on Silicon Labs Platform, refer to: [Software Requirements](../general/SOFTWARE_REQUIREMENTS.md) ## Setting up OTA Environment -- To execute OTA on Silicon Labs Platform Wi-Fi Boards, we need to build two different applications below: - - **OTA-A** is a normal application with default or older software version. It acts as **ota-requestor** where it needs to update the latest software version. - - **OTA-B** is a normal application with an updated software version. - - **Chip-tool** is a controller for sending commands to the ota-requestor to update the software version and receiving commands from device. - - **OTA-Provider** is the server that has the latest software version and from which ota-requestor will download the updated software. -### Setting up Chip-tool Controller +- **OTA-A**, the running image: a regular application built with the default/older software version value. This application will be updated to the one with a higher software version. In the OTA Software Update process it acts as the OTA Requestor. +- **OTA-B**, the update image: a regular application built with a higher software version value. +- **Chip-tool**: the controller that announces the OTA-Provider's address to the application thus triggering the OTA Software Update. +- **OTA-Provider**: the server that carries the update image and from which the OTA Requestor will download the updated software. +- **Bootloader**: Silicon Labs Gecko Bootloader image that supports OTA; supports the external (SPI-flash) or the internal storage option. + + +### Setting up Chip-tool + +The chip-tool binary is a part of the Silicon Labs' Matter Hub Raspberry Pi Image available as a part of the Release Artifacts page. If you are planning to run chip-tool on the Matter Hub you may skip the rest of this section. If you have not downloaded or cloned this repository, you can run the following commands on a Linux terminal running on either Linux machine, WSL or Virtual @@ -40,10 +46,8 @@ application images. $ mkdir out ``` -In order to control the Wi-Fi Matter Accessory Device, you will have to compile -and run the chip-tool on either a Linux, Mac or Raspberry Pi. The chip-tool builds -faster on the Mac and Linux machines, so that is recommended, but if you have -access to a Raspberry Pi that will work as well. + To control the Matter application you will have to compile and run the chip-tool on either a Linux, Mac, or Raspberry Pi. The chip-tool builds faster on the Mac and Linux machines so that is recommended, but if you have access to a Raspberry Pi that will work as well. + 3. Build the chip-tool @@ -55,7 +59,11 @@ This will build chip-tool in `out/standalone`. ### Setting up OTA-Provider + +The chip-ota-provider-app binary for a Raspberry Pi is a part of the Artifacts package available with the Matter Extension release. If you are planning to run the OTA-Provider on a Raspberry Pi there is no need to build it. + - To Build OTA-Provider app for Linux Platform, run below command in the matter repository. + ```shell scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false ``` @@ -76,6 +84,15 @@ For RS9116: For WF200 ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/wf200_lighting_A BRD41xxx chip_build_libshell=false --wifi wf200 + +For SiWx917 NCP + +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_lighting BRD41xxx disable_lcd=true use_external_flash=false --wifi SiWx917 + +For SiWx917 SOC + +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/SiWx917_lighting BRD4388A + ``` **Note:** Matter OTA-A application will be having software version as 1 by default in **third_party/silabs/BUILD.gn** file. @@ -89,39 +106,59 @@ For WF200 ``` For RS9116: -./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting_B BRD41xxx disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting_B BRD41xxx use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 For WF200 ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/wf200_lighting_B BRD41xxx chip_build_libshell=false --wifi wf200 + +For SiWx917 NCP + +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_lighting BRD41xxx disable_lcd=true use_external_flash=false --wifi SiWx917 + +For SiWx917 SOC + +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/SiWx917_lighting BRD4388A + ``` -## Executing OTA Scenario +## Running the OTA Download Scenario -### Generating the OTA image -1. Locate Simplicity Commander Path via **Command Prompt Terminal**. -2. Create a bootable image file by running below command in commander terminal(using the Lighting application as an -example): -```shell +- Create a bootable image file (using the Lighting application image as an + example): + + ```shell commander gbl create chip-efr32-lighting-example.gbl --compress lzma --app chip-efr32-lighting-example.s37 -``` + ``` **Note**:- Using LZMA compression when building the .gbl file ( passing `--compress lzma` parameter to the `commander gbl create` command) further reduces the downloaded image size. -3. Create the Matter OTA file by running below command in **${WORKSPACE_DIR}/matter** path: -```shell - ./src/app/ota_image_tool.py create -v 0xFFF1 -p 0x8005 -vn 2 -vs "2.0" -da sha256 chip-efr32-lighting-example.gbl chip-efr32-lighting-example.ota -``` -**Note**: Modify **-vn** to **sl_matter_version** as per OTA-B application Building step [Build OTA B](#build-ota-b-application) +- Create the Matter OTA file from the bootable image file: + + ```shell + $ commander ota create --type matter --input chip-efr32-lighting-example.gbl --vendorid 0xFFF1 --productid 0x8005 --swstring "2.0" --swversion 2 --digest sha256 -o chip-efr32-lighting-example.ota + ``` ### Running OTA Provider + - Locate **ota-provider** terminal and start the Provider app passing to it the path to the Matter OTA file created in the previous step: -```shell - rm -rf /tmp/chip_* - ./out/debug/chip-ota-provider-app -f chip-efr32-lighting-example.ota -``` + +- In a terminal start the Provider app and pass to it the path to the Matter + OTA file created in the previous step: + + ```shell + $ rm -r /tmp/chip_kvs_provider + ``` + + ```shell + ./out/chip-ota-provider-app --KVS /tmp/chip_kvs_provider -f chip-efr32-lighting-example.ota + ``` + ### Setting up OTA-Requestor + - Before running **ota-requestor** app flash the bootloader binary images for Silicon Labs Devices. + #### Flash Bootloader Images + - Bootloader binaries will be flashed using Simplicity Commander only. It will support EFR32 NCP Boards only. - Silicon Labs Devices will supports below Bootloader variants for EFR32 Boards. - Internal Storage Bootloader @@ -129,21 +166,43 @@ example): - To Flash the Bootloader Binary along with the application for Silicon Labs Device, refer [Flashing Binaries](../general/FLASHING_USING_COMMANDER.md) ### Running OTA-Requestor -1. In a separate terminal, locate the chip-tool and ota-requestor and run the chip-tool commands to provision the Provider: -```shell - ./out/chip-tool pairing onnetwork 1 20202021 - ./out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 -``` -2. If the application device had been previously commissioned hold Button 0 for six seconds to factory-reset the device. -3. In the chip-tool terminal, commission the Device by passing below command: -```shell - ./out/chip-tool pairing ble-wifi "node_id" "SSID" "PSK" 20202021 3840 -``` -where SSID and PSK are AP username and password. +- In a separate terminal run the chip-tool commands to provision the Provider: -4. Once the commissioning process completes in the same terminal, run below requestor command to start downloading the image: -```shell - ./out/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0 -``` + ```shell + $ ./out/chip-tool pairing onnetwork 1 20202021 + ``` + + ```shell + $ ./out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 + ``` +- For Matter over OpenThread, bring up the OpenThread Border Router and get its operational + dataset, for Matter over WiFi bring up the AP. + +- If the application device had been previously commissioned, hold Button 0 + for six seconds to factory-reset the device. + +- Commission the device. + For Matter over OpenThread: + + ```shell + $ ./out/chip-tool pairing ble-thread 2 hex: 20202021 3840 + ``` + where operationalDataset is obtained from the OpenThread Border Router. + + For Matter over WiFi: + ```shell + ./out/chip-tool pairing ble-wifi "node_id" "SSID" "PSK" 20202021 3840 + ``` + +- Once the commissioning process completes enter: + + ```shell + $ ./out/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0 + ``` - The application device will connect to the Provider and start the image download. Once the image is downloaded the device will reboot into the downloaded image. + +## Additional Info + +Developers can find more resources on +[Silicon Labs Matter Community Page](https://community.silabs.com/s/article/connected-home-over-ip-chip-faq?language=en_US). diff --git a/docs/silabs/general/PINTOOL.md b/docs/silabs/general/PINTOOL.md index a5a1d8a6993b7c..33b2088d0223ee 100644 --- a/docs/silabs/general/PINTOOL.md +++ b/docs/silabs/general/PINTOOL.md @@ -4,7 +4,7 @@ At some point during product development you may need to move your project over you will likely need to change the pinout and hardware configuration in the example project to reflect your own custom project. You can do this with Simplicity Studio's Pintool starting from a blank C++ project. -## 1. Locating the board support files in the Matter repo +## 1. Locate the board support files in the Matter repo The pin and peripheral configuration for your example application is stored within the Silicon Labs Matter support directory. For all the examples used in diff --git a/docs/silabs/general/SECURITY.md b/docs/silabs/general/SECURITY.md index f1c12ef622c9f9..3b77ed0e8c46a2 100644 --- a/docs/silabs/general/SECURITY.md +++ b/docs/silabs/general/SECURITY.md @@ -1,69 +1,302 @@ -# Security +# Matter Security -## General +Matter raises the bar on security to a new level beyond simply guaranteeing the communication pipe is secure. Now, the end device must be proven to be authentic. The Matter Node Security will likely raise over time. As threats evolve, the SHOULDs will become SHALLs. Creating Secure Identities and injecting them securely in your manufacturing process is not trivial and can be costly. Silicon Labs has the hardware, software, and services to get your secure Matter products to market quickly and cost effectively. + +Register at [Silicon Labs Tech Talks](https://www.silabs.com/about-us/events/tech-talks-wireless-technology-training/matter) to watch a detailed on-demand discussion of Matter Security, along with other tech talks as part of the Interactive Matter Training Series. + +>Note: All graphics were extracted from the Tech Talk, *Future-Proofing Matter Security with Secure Vault*, created by the Connectivity Standards Alliance (CSA) and used with permission. + +## Principles + +The following are the guiding principles for the Matter security design: + +1. **No anonymous joining**: Always requires “proof of ownership” (that is, a device-specific passcode). +2. **Device Attestation**: Every device has unique identity that is authenticated by the manufacturer and verified through the CSA as a certified device. +3. **Operational Credentials**: When commissioned onto a Matter network, every device is given unique operational credentials after verifying their manufacturer credentials. +4. **Network Credentials**: The Wi-Fi network key or Thread Master key are not given until the device’s certificate is verified and authenticated properly. +5. **Open standard**: The open-source software is open to third parties vetting the claims by examining the standard and auditing the source code. + +## Security Tenants Promoted by the Connectivity Standards Alliance (CSA) + +1. Easy, secure, and flexible device commissioning +2. Validation that each device is authentic and certified +3. Up-to-date information via Distributed Compliance Ledger +4. Strong device identity so only your devices can join +5. Secured communications protecting confidentiality, etc. +6. Even group communications secured +7. Multiple administrators and controllers, maximizing choice +8. Verified access controls to prevent unauthorized actions +9. Secured, standard software updates +10. Remote monitoring of software integrity + +## Matter Security Relevant Nomenclature + +![Matter Network Example](resources/matter-network-example.png) + +- **Node**: An independently addressable entity on a Matter network, which must be running an approved protocol (eg, Wi-Fi and Thread). +- **Device**: Anything that you take out of a box, such as a thermostat. Devices can have multiple nodes. +- **Router**: A standard router found in homes. +- **Controller**: Controls multiple nodes on a network. +- **Commissioner**: Can commission multiple nodes on a network in three ways: + + - BLE (most common) + - Wi-Fi AP protocol + - Ethernet + +Once commissioned, devices can start communicating on the Matter network via an approved protocol, usually Wi-Fi. + +A **Bridge** bridges to other protocols, such as Zigbee or ZWave to allow other devices communicate in the network. + +A **Border Router** is intended to perform the communication protocol translation between approved protocols. It does not bridge between other protocols. + +**Device Identity** starts with an identity within the device called a device attestation certificate (DAC). Any device that needs to be commissioned needs a DAC. If the device is inherently trusted within the ecosystem that it's trying to join, it does not need a DAC. If not, it does need a DAC. + +End devices are what need to be trusted. + +## Matter Security Provisioning + +### Certificates and Process Overview Each Matter device gets two certificates. The first, the **device certificate**, is programmed by the manufacturer before the device is shipped. This will be used later for device attestation when trying to join the network. The other, the **operational certificate**, is assigned by the commissioner in the commissioning stage. Certificates natively use a CHIP TLV format but can convert to/from X.509 format. All devices are given an operational certificate to prove their authorization on the Matter network (fabric) and securely identify them. Communication between Matter devices is protected with different keys in different stages. At the commissioning stage, the key is a result of the Password Authenticated Session Establishment (**PASE**) process over the commissioning channel using the passcode from the device's QR code as the input. During this initial setup, verification of possession of the passcode by both commissioner and joining device is confirmed. At the operational stage, the key is a result of the Certificate Authenticated Session Establishment (**CASE**) process over the operational channel using the operational certificate as the input. These sessions are used during normal operation between controller and device to validate that both are part of the Matter network. -### Principles +### Message Protection + +Various cryptographic algorithms are used to ensure communication security and integrity. These include: + +- **Hashing Algorithm**: SHA\-256 + +- **Message Authentication**: HMAC-SHA\-256 + +- **Public Key**: ECC Curve NIST P\-256 + +- **Message Encryption**: AES\-CCM (128 bit keys) + +![Payload Encryption](resources/payloadencryption.png) + +**Confidentiality**: Message payload is encrypted by the encryption key (AES) + +![Address Encryption](resources/addressencryption.png) + +**Privacy**: Addresses are encrypted by the privacy key + +### Onboarding Payload + +The Onboarding Payload is the information used by the Commissioner to ensure interoperability between commissioners and devices. It can be encoded in different formats: + +- Human-readable (numeric string) +- Machine-readable (QR code and NFC tag) + +![Matter Onboarding Payload](resources/matter-onboarding-payload.png) + +:::custom-table{width=25%,75%} +| Onboarding Payload Element | Description | +|-------------------------------------------|-------------| +| Version | Provides versioning of the payload. | +| Vendor ID | Assigned by CSA. Allows a way to identify the maker of the device. | +| Product ID | Vendor specified. Unique for each certified product within a Vendor ID. | +| Custom Flow | :para[Indicates to the Commissioner the steps needed before commissioning can take place.] :list[Standard commissioning flow: A device, when uncommissioned, always enters commissioning mode upon power-up. \n User-intent commissioning flow: Device requires user action (pressing a button, for example) to enter commissioning mode. \n Custom commissioning flow: Interaction with a service provided by the manufacturer is required for initial device setup.] {type=unordered} | +| Discovery Capabilities Bitmask | :para[Indicate device’s available technologies for device discovery:] :list[Soft-AP \n BLE \n On IP Network (device is already on the IP network)] {type=unordered} | +| Discriminator | Helps to further identify potential devices during the setup process. | +| Passcode | Establishes proof of possession and is also used as the shared secret for the initial secure channel before further onboarding steps. | +| TLV Data | :para[(Optional) TLV (Tag-length-value) data.] :para[Indicates manufacturer-specific information elements and/or elements common to Matter. For instance, kTag_NumberOfDevices: Number of devices that are expected to be onboarded using this payload when using the Enhanced Commissioning Method.] | +::: + +## Commissioning Steps + +There are four steps involved in commissioning devices to start communicating on a Matter network: + +1. Device Discovery +2. Secure Channel (PASE) +3. Device Attestation +4. Configuration + +### 1. Device Discovery + +The focus of this phase is getting the onboarding payload. The steps are: + +1. The Device announces its availability for commissioning over initial network. +2. The Commissioner finds the Device. +3. The Commissioner connects to the Device, using: -The following are guiding principles for the Matter security design: + - Discriminator + - Vendor ID (optional) + - Product ID (optional) -1. **No anonymous joining** - Always requires “proof of ownership” (that is, a device-specific passcode) +### 2. Secure Channel (PASE) -2. **Device Attestation** - Every device has unique identity that is authenticated by the manufacturer and verified through the CSA as a certified device +The focus of this phase is establishing a secure link. The steps are: -3. **Operational Credentials** - When commissioned onto a Matter network every device is given unique operational credentials after verifying their manufacturer credentials +1. The Commissioner establishes a secure unicast channel to the Device. +2. Protocol PASE = Password Authenticated Session Establishment +3. Based on SPAKE2+ protocol +4. Uses: -4. **Network credentials are given only *after* device authentication** - Wi-Fi network key or Thread Master Key are not given until device’s certificate is verified + - Passcode + - Verifier -5. **Open standard and open-source software** - Open to third parties vetting the claims by examining the standard and auditing the source code +Several key constructs are important to understand prior to understanding Device Attestation. -## Message Protection +#### Public Key Infrastructure (PKI) -Various cryptographic algorithms are used to ensure communication security and integrity. These include: +A PKI is a set of roles, policies, and procedures used to create, manage, distribute, and revoke digital certificates and manage public-key encryption. The Matter Certificate Policy defines the rules and +methods by which the Matter PKI Policy Authority (PKI-PA) is governed. -- **Hashing Algorithm** - SHA\-256 +The Matter PKI for Device Attestation is comprised of: -- **Message Authentication** - HMAC-SHA\-256 +- Certificate authorities: -- **Public Key** - ECC Curve NIST P\-256 + - PAA (Product Attestation Authority) + - PAI (Product Attestation Intermediate) -- **Message Encryption** - AES\-CCM (128 bit keys) +- Authorized entities: -![Payload Encryption](./images/PayloadEncryption.png) + - DAC (Device Attestation Certificate) + + ![Public Key Infrastructure example](resources/matter-paa-pai-example.png) -**Confidentiality** - Message payload is encrypted by the encryption key (AES) +#### Certification Declaration -![Address Encryption](./images/AddressEncryption.png) +Another data construct that is necessary for Device Attestation is the Certification Declaration (CD), which is cryptographically signed by CSA and contains the Vender and Device information as well as the PAA of the device. The CD must be put into the Device during manufacturing to be used during the Device Attestation process. The Commissioner will ask for the stored CD during the commissioning of the Node. -**Privacy** - Addresses are encrypted by the privacy key +![Certification Declaration](resources/matter-certification-declaration-example.png) -## Device Attestation +#### Distributed Compliance Ledger -Every device has a unique certificate that is signed by the manufacturer. There is no single root CA across all devices. During commissioning the device is challenged to prove possession of the associated private key. The certificate can be validated against the Distributed Compliance Ledger (**DCL**) to verify device certification status +The Distributed Compliance Ledger (DCL) is the immutable single source of truth. It is a private blockchain-based distributed ledger of data records. Reading from the DCL is open to public, but writing to the DCL is restricted to various parties/roles. These roles typically include CSA certification, test house, and vendor roles. -![Certificate Authentication](./images/CertificateAuthentication.png) +![DCL Overview](resources/dcl-overview.png) + +It contains records about all certified devices, such as: + +- Certification status +- Vendor ID (VID) +- Product ID (PID) +- Product name +- Part number and version +- Software and firmware versions +- Special commissioning instructions +- URLs to product pages and user manual + +It also contains the Root PAA certificate for that Device, which is needed to complete the Device certificate chain verification. The DCL also contains the Certification Declaration ID number that will be compared with the CD pulled from the Device. + +![Distributed Compliance Ledger diagram](resources/matter-dcl-example.png) + +### 3. Device Attestation + +Every device has a unique certificate that is signed by the manufacturer. There is no single root CA across all devices. During commissioning, the device is challenged to prove possession of the associated private key. The certificate can be validated against the Distributed Compliance Ledger (**DCL**) to verify device certification status. The hierarchy allows for a 3-level tier: -- The first level is the Product Attestation Authority (**PAA**) -- The PAA will be used to sign the Product Attestation Intermediate (**PAI**) -- The PAI will be used to sign the Device Attestation Certificate (**DAC**). The DAC will be transferred to the commissioner and verified against the DCL. +- The first level is the Product Attestation Authority (PAA). +- The PAA will be used to sign the Product Attestation Intermediate (PAI). +- The PAI will be used to sign the Device Attestation Certificate (DAC). The DAC will be transferred to the commissioner and verified against the DCL. + +![Certificate Authentication](resources/certificateauthentication.png) + +The focus of this phase is to verify the authenticity of the Device. The high-level steps are: + +1. The Commissioner verifies the Device’s: + - VID + - PID + - Certification status +2. To do so, it uses: + - Device Attestation Credentials + - Distributed Compliance Ledger (DCL) or + - Certification Declaration (CD) -![Attestation Overview](./images/AttestationOverview.png) +![Attestation Overview](resources/attestation-overview.png) DAC is retrieved and verified before the device joins the Thread or Wi-Fi network. The Commissioner issues a challenge to the device to prove it possesses the associated Private Key. -## Distributed Compliance Ledger +First, the Commissioner asks the Node for the CD, the PAI Certificate, and the DAC. It then pulls the Certificate ID, the PAA Certificate, and the Device VID/PID from the immutable root of trust DCL. At that point, it has all the information needed to perform the device attestation. The Commissioner then runs a certification chain check from the DAC to the PAI, and all certificates should chain together correctly. If that check is passed, the Commissioner takes the certification ID from the DCL and checks it against the CD ID that it pulled from the device itself to make sure the device is a genuine CSA certified device. The final step is to verify that the public key in the DAC pulled from the Matter device mathematically matches the private key inserted in the device during manufacture. This is done by sending a message to the device during this final step of Device Attestation, and having the message signed by the device and then the signature verified using the public key from the DAC. -![DCL Overview](./images/DCL_Overview.png) +#### Node Operational Credentials -DCL is a database of all certified products which includes: +The Node Operational Credentials enable a Node to identify itself within a Fabric. A Node receives its initial set of Node Operational Credentials when it is commissioned to a Fabric by a Commissioner. -- Certification status -- Product name / description / firmware URL -- Product certificates +![Fabric diagram](resources/matter-fabric-diagram.png) + +The Node Operational Credentials include the following items: + +- Node Operational Key Pair +- Node Operational Certificate (NOC) +- Intermediate Certificate Authority (ICA) Certificate (optional) +- Trusted Root Certificate Authority (CA) Certificate(s) + +>Note: The Node Operational Credentials are distinct from the Device Attestation credentials. + +#### Commissioning Process + +The Commissioning process uses the DAC to establish that the Commissioner is talking to a certified Matter Device and then loads operational identities for each ecosystem that it joins. + +![Commissioning Process diagram](resources/matter-commissioning-process-diagram.png) + +### 4. Configuration + +The Commissioner configures the Device by: + +- Loading Node Operational Credentials per ecosystem: + + - Fabric ID + - Node ID + - Trusted Root Certificate + - ICA Cert + - Operational Cert + - Node Operational Key Pair + - Access Control List (ACL) + - Operational Network + - Time (optional) + +- Establishing communication with other Nodes using CASE + +This completes all the commissioning steps and now on the Matter Network. + +## Matter Security Requirements + +### Matter Security as Specified by CSA + +**Manufacturing**: Matter Devices must be injected with a unique DAC certificate/private key, Onboarding Payload (QR code delivered), Certification Declaration (CD), and other static/dynamic data during manufacturing. (SHALL) + +**Commissioning**: DAC with VID/PID must be checked against the DCL and CD verified to ensure only authentic and certified Matter Devices are commissioned. (SHALL) + +**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) + +### Other Security Specifications + +- Authentication and encryption keys must be generated by a “Deterministic Random Bit Generator” seeded by NIST 800-90B TRNG. (SHALL) +- Debug interfaces and access to secure boot trust anchors should be disabled to only allow authorized access (fusing). (SHOULD) +- DACs and operational private key confidentiality should be protected from remote attacks. (SHOULD) +- Vendors should have a public policy and mechanism to identify and rectify security vulnerabilities in a timely manner. (SHOULD) +- The software should be encrypted *at rest* to prevent unauthorized access to core IP. (MAY) +- Some devices should be protected against *physical* attacks to prevent tampering, side-channel, or debug glitching attacks. (MAY) + +### Matter Compliant Security Solution + +- Secure Vault Mid or High supports all Matter security functionalities now (Shall) and future (Should, May) +- Uncrackable keys are generated by the True Random Number Generator (TRNG) +For DAC, secure boot, secure debug, OTA, software image and communication encryption +- The Crypto Engine assists with special algorithms like SPAKE2+ and CASE with side channel protection +- Secure key storage at PSA/SESIP Level 2 (Mid) and Level 3 (High); Private keys are stored with a TEE/TZ (SV Mid) or PUF Wrapped (SV +High) +- Secure Matter Identities (DACs) securely programmed at our factory +- Secure Boot with RTSL ensures code running on the device is trusted. +- Secure OTA firmware updates in conjunction with Secure +- Boot prevents the installation of malicious software and allows for vulnerability patching +- Glitch Mitigated Secure Debug Lock/Unlock only allow authorized access with security tokens that can be revoked +- Anti-Tamper protects from physical attacks (SV High) + + ![Secure Vault diagram](resources/matter-secure-vault-diagram.png) + +## Matter Secure Manufacturing + +The following diagram describes the high-level process of what needs to happen before secure programming. + +![What Needs to Happen Before Secure Programming diagram](resources/matter-before-secure-programming-diagram.png) + +The following diagram describes the high-levels steps as part of secure programming. -Reading from the DCL is open to public, but writing to the DCL is restricted to various parties/roles. These roles typically include CSA certification, test house, and vendor roles. +![Secure Programming diagram](resources/matter-secure-programming-diagram.png) \ No newline at end of file diff --git a/docs/silabs/general/SOFTWARE_REQUIREMENTS.md b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md index bef92d06adca61..4040ab8f934ead 100644 --- a/docs/silabs/general/SOFTWARE_REQUIREMENTS.md +++ b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md @@ -143,21 +143,27 @@ $ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev libglib2. ## Wi-Fi Specific Requirements: -Before you run the demo or development on the Wi-Fi, please be sure that you update the NCP firmware to the latest version. +### Software Packages Required for Wi-Fi EFR32 NCP Devices -Pre-Built firmware images are available in the github repository under `third_party/silabs/wiseconnect-wifi-bt-sdk/firmware` +1. Gecko SDK package. +2. WiseConnect SDK v2.x for RS9116 NCP. +3. Wiseconnect SDK v3.x for SiWx917 NCP. +4. [Firmware for RS9116 NCP](../general/ARTIFACTS.md#rs9116-firmware) +5. [Firmware for SiWx917 NCP](../general/ARTIFACTS.md#siwx917-firmware-for-siwx917-ncp) -1. [Setting up TeraTerm](https://docs.silabs.com/rs9116/wiseconnect/2.0/tera-term-setup) -2. [Updating the RS9116 Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/update-evk-firmware) +### Software Packages Required for Wi-Fi SiWx917 SoC Devices +1. GeckoSDK package. +2. WiSeConnect SDK v3.x. +3. [Firmware for SoC](../general/ARTIFACTS.md#siwx917-firmware-for-siwx917-soc) -## Wi-Fi SiWx917 Specific Requirements: +**Note:** +Before you run the demo or development on the Wi-Fi, please be sure that you update the NCP or SiWx917 firmware to the latest version. -Before you run the demo or development on the SiWx917, please be sure that you update the SiWx917 firmware to the latest version. - -Pre-Built SiWx917 firmware images are available in the github repository under `third_party/silabs/wifi-sdk/connectivity_firmware` +Pre-Built firmware images are available in the following path of github repository: + 1. For RS9116 NCP images: under `third_party/silabs/wiseconnect-wifi-bt-sdk/firmware` + 2. For SiWx917 NCP & SoC images: under `third_party/silabs/wifi-sdk/connectivity_firmware` 1. [Setting up TeraTerm](https://docs.silabs.com/SiWx917/wiseconnect/2.0/tera-term-setup) -2. For updating the SiWx917 NCP Firmware, refer [Updating the RS9116 Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/update-evk-firmware). -Instructions are the same for both SiWx917 and RS9116. -3. For updating the SiWx917 SoC Firmware, refer [Updating the SiWx917 SOC Firmware Using Simplicity Commander](../wifi/RUN_DEMO_SiWx917_SoC.md#steps-to-update-the-firmware-on-siwx917-soc-radio-board-using-simplicity-commander) +2. [Updating the RS9116 or SiWx917 NCP Firmware](../wifi/RUN_DEMO.md#steps-to-update-the-firmware-on-ncp-boards-using-tera-term) +3. [Updating the SiWx917 SOC Firmware Using Simplicity Commander](../wifi/RUN_DEMO_SiWx917_SoC.md#steps-to-update-the-firmware-on-siwx917-soc-radio-board-using-simplicity-commander) diff --git a/docs/silabs/general/ZAP.md b/docs/silabs/general/ZAP.md index 4aa15761de7433..a40d5a607c4085 100644 --- a/docs/silabs/general/ZAP.md +++ b/docs/silabs/general/ZAP.md @@ -4,7 +4,7 @@ EFR32 example applications provide a baseline demonstration of a lock device, built using the Matter SDK and the Silicon Labs GeckoSDK. It can be controlled -by a CHIP controller over Openthread network. +by a CHIP controller over OpenThread network. The EFR32 device can be commissioned over Bluetooth Low Energy (BLE) where the device and the CHIP controller will exchange security information with the @@ -20,32 +20,26 @@ CHIP, and a template for creating real products on the Silicon Labs platform. Each Matter application consists of the following layers: -- Matter SDK: Source code necessary to communicate through the Matter network - over Thread or Wi-Fi -- Data model layer in the form of clusters. There are two types of clusters: - - Utility Clusters: - - They represent common management and diagnostic features of a Matter +- Matter SDK: Source code necessary to communicate through the Matter network over Thread or Wi-Fi +- Data model layer in the form of clusters. There are two types of clusters: + - Utility Clusters: + - They represent common management and diagnostic features of a Matter endpoint - - Identify cluster is an example of a Utility Cluster. Given a Node - ID, it can be used to Blink LED0 to the corresponding Silicon Labs - WSTK - - Application Clusters: - - These clusters represent functionalities specific to a given + - Identify cluster is an example of a Utility Cluster. Given a Node + ID, it can be used to Blink LED0 to the corresponding Silicon Labs WSTK + - Application Clusters: + - These clusters represent functionalities specific to a given application - - Door Lock Cluster is an example of an Application specific cluster. - This cluster contains commands to lock and unlock a door(door-lock - is represented by an LED), with options to set passwords and lock - schedules - -
+ - Door Lock Cluster is an example of an Application specific cluster. + This cluster contains commands to lock and unlock a door(door-lock is represented by an LED), with options to set passwords and lock schedules ## Clusters Every Matter Application uses multiple clusters leveraged from the Zigbee -Cluster Library(ZCL). A cluster can be seen as a building block for the Data +Cluster Library (ZCL). A cluster can be seen as a building block for the Data Model of a Matter application. Clusters contains attributes, commands, and events. Attributes are customizable variables specified by the Zigbee Advanced -Platform(ZAP) tool. Commands are sent to the application, which may respond with +Platform (ZAP) tool. Commands are sent to the application, which may respond with data, LED flickering, lock actuation, etc. Events are notifications sent out by the server. @@ -58,11 +52,10 @@ Some applications have callbacks that are left to be implemented by the device manufacturer. For example, the storage and management of users and credentials in the lock-app is left up to the application developer. - ## ZAP Tool The ZAP tool is built and maintained by Silicon Labs and developers in the ZAP -opensource community. It inherits its name and features from the Zigbee Cluster +open source community. It inherits its name and features from the Zigbee Cluster Library, which was the starting point for the Matter data model. ZAP is used for generating code for Matter applications based on the Zigbee Cluster Library and associated Matter code templates. @@ -73,32 +66,32 @@ repo and build the ZAP binary from scratch. ZAP binaries can be downloaded from the latest ZAP release here: -> `https://github.com/project-chip/zap/releases/latest` +`https://github.com/project-chip/zap/releases/latest` Optionally, the ZAP tool can be cloned using the following git command. This will create a root level zap folder in your current directory. -> `$ git clone https://github.com/project-chip/zap.git` +`$ git clone https://github.com/project-chip/zap.git` The ZAP tool can be invoked using the `run_zaptool.sh` script located in the Matter repo at `./scripts/tools/zap/run_zaptool.sh`. Before you run this script you have to provide the location of the ZAP instance to be run. This is either the binary that you downloaded or the binary that you built from scratch in the ZAP repo. You can do this by setting the `ZAP_INSTALL_PATH` environment variable like this: -> `$ export ZAP_INSTALL_PATH=(path to your instance of the ZAP binary)` +`$ export ZAP_INSTALL_PATH=(path to your instance of the ZAP binary)` The `run_zaptool.sh` script can be invoked without arguments, or, you can provide the path to a ZAP file to be opened upon launch. In the following examples, the ZAP file for the lock-app has been chosen. -> `$ ./scripts/tools/zap/run_zaptool.sh ($PATH_TO_ZAP_FILE)` +`$ ./scripts/tools/zap/run_zaptool.sh ($PATH_TO_ZAP_FILE)` ZAP files for the various sample applications are included in the sample applications `data_model` directory such as -`./examples/lighting-app/silabs/data_model/lighting-thread-app.zap`. +`./examples/lighting-app/silabs/efr32/data_model/lighting-thread-app.zap`. -This shows the output of the run_zaptool script with no arguments. To load a new +This shows the output of the `run_zaptool` script with no arguments. To load a new zap file, click the application menu for Electron (Upper left corner of the screen for macs), then click "Open File". Then navigate to the desired .zap file. @@ -110,17 +103,17 @@ argument, or after a .zap file has been opened in the ZAP UI. An Electron application will open, pre-loaded with the information from the .zap file provided as a command line argument. -![ZAP Endpoint](./images/zap_endpoint.png) +![ZAP Endpoint](./images/endpoint-0.png) -The Out of the box(OOB) example lock application has 2 endpoints. Endpoint 0 is +The Out of the box (OOB) example lock application has 2 endpoints. Endpoint 0 is called the root node. It contains all Service and Device management clusters. In general, any cluster or feature that is not specific to a device type belongs in Endpoint 0. Examples of clusters one might find in Endpoint 0: Device Descriptor cluster, Network Diagnostics cluster. Endpoint 1 contains information specific to the device type. Conveniently, the -ZAP tool offers a Door lock cluster, which contains Commands(lock, unlock, set -credential, etc..) and Attributes(Lock state, Require PIN) that a standard door +ZAP tool offers a Door lock cluster, which contains Commands (lock, unlock, set +credential, and so on) and Attributes (Lock state, Require PIN) that a standard door lock application might use. More endpoints can be added. Each endpoint acts like a port on a network @@ -135,9 +128,7 @@ Client side of the same cluster. Click on Endpoint 1 on the left hand side of the application. The door lock cluster should already be enabled as "Server". -![ZAP Endpoint 1](./images/zap_endpoint_1.png) - -
+![ZAP Endpoint 1](./images/endpoint-1.png) ## Attributes @@ -154,9 +145,7 @@ Each attribute can be provided with a default starting value value. Click the settings wheel to enable/disable, choose a storage option, and choose a default value for attributes, commands and events for Endpoint 1. -![ZAP Attributes](./images/zap_attributes.png) - -
+![ZAP Attributes](./images/door-lock-attributes.png) ## Commands @@ -167,13 +156,11 @@ the application to define. In the EFR32 lock example, the set/get user and credential functions are customizable as each implementation of a lock might store these differently. -![ZAP Commands](./images/zap_commands.png) - -
+![ZAP Commands](./images/door-lock-commands.png) ## Generation of Code Once you have chosen the cluster options, save the current ZAP configuration using the application menu in the upper left corner. Before v1.1.0-1.1 you needed to click the Generate button to generate code. Now, code is generated automatically in the save function. You will be prompted to choose a save location for the generated ZAP code. In the Silicon Labs Matter repository, the lock-app generated files belong in -matter/zzz_generated/lock-app/zap-generated . +matter/zzz_generated/lock-app/zap-generated. \ No newline at end of file diff --git a/docs/silabs/general/images/door-lock-attributes.png b/docs/silabs/general/images/door-lock-attributes.png new file mode 100644 index 00000000000000..dc49b4d31633ae Binary files /dev/null and b/docs/silabs/general/images/door-lock-attributes.png differ diff --git a/docs/silabs/general/images/door-lock-commands.png b/docs/silabs/general/images/door-lock-commands.png new file mode 100644 index 00000000000000..0fc3a7922d60ee Binary files /dev/null and b/docs/silabs/general/images/door-lock-commands.png differ diff --git a/docs/silabs/general/images/edit-endpoint.png b/docs/silabs/general/images/edit-endpoint.png new file mode 100644 index 00000000000000..0b4447a6a69cae Binary files /dev/null and b/docs/silabs/general/images/edit-endpoint.png differ diff --git a/docs/silabs/general/images/endpoint-0.png b/docs/silabs/general/images/endpoint-0.png new file mode 100644 index 00000000000000..daf4b98a6fa8b6 Binary files /dev/null and b/docs/silabs/general/images/endpoint-0.png differ diff --git a/docs/silabs/general/images/endpoint-1.png b/docs/silabs/general/images/endpoint-1.png new file mode 100644 index 00000000000000..68bd389f15bd08 Binary files /dev/null and b/docs/silabs/general/images/endpoint-1.png differ diff --git a/docs/silabs/general/images/multiple-endpoints.png b/docs/silabs/general/images/multiple-endpoints.png new file mode 100644 index 00000000000000..5ec5a9029908a5 Binary files /dev/null and b/docs/silabs/general/images/multiple-endpoints.png differ diff --git a/docs/silabs/general/images/tutorial1.png b/docs/silabs/general/images/tutorial1.png new file mode 100644 index 00000000000000..8ccf9963b5ce65 Binary files /dev/null and b/docs/silabs/general/images/tutorial1.png differ diff --git a/docs/silabs/general/images/tutorial2.png b/docs/silabs/general/images/tutorial2.png new file mode 100644 index 00000000000000..f72d89cb8fc4ba Binary files /dev/null and b/docs/silabs/general/images/tutorial2.png differ diff --git a/docs/silabs/general/images/zap_attributes.png b/docs/silabs/general/images/zap_attributes.png deleted file mode 100644 index 07d1f9ed0c1c98..00000000000000 Binary files a/docs/silabs/general/images/zap_attributes.png and /dev/null differ diff --git a/docs/silabs/general/images/zap_commands.png b/docs/silabs/general/images/zap_commands.png deleted file mode 100644 index 6e7e959758a9ef..00000000000000 Binary files a/docs/silabs/general/images/zap_commands.png and /dev/null differ diff --git a/docs/silabs/general/images/zap_endpoint.png b/docs/silabs/general/images/zap_endpoint.png deleted file mode 100644 index 9f46e85883a2ad..00000000000000 Binary files a/docs/silabs/general/images/zap_endpoint.png and /dev/null differ diff --git a/docs/silabs/general/images/zap_endpoint_1.png b/docs/silabs/general/images/zap_endpoint_1.png deleted file mode 100644 index 56d55137f09e72..00000000000000 Binary files a/docs/silabs/general/images/zap_endpoint_1.png and /dev/null differ diff --git a/docs/silabs/general/resources/addressencryption.png b/docs/silabs/general/resources/addressencryption.png new file mode 100644 index 00000000000000..6f1f6633246d98 Binary files /dev/null and b/docs/silabs/general/resources/addressencryption.png differ diff --git a/docs/silabs/general/resources/attestation-overview.png b/docs/silabs/general/resources/attestation-overview.png new file mode 100644 index 00000000000000..a0b069c59ea493 Binary files /dev/null and b/docs/silabs/general/resources/attestation-overview.png differ diff --git a/docs/silabs/general/resources/certificateauthentication.png b/docs/silabs/general/resources/certificateauthentication.png new file mode 100644 index 00000000000000..680ddd6b90fcc9 Binary files /dev/null and b/docs/silabs/general/resources/certificateauthentication.png differ diff --git a/docs/silabs/general/resources/dcl-overview.png b/docs/silabs/general/resources/dcl-overview.png new file mode 100644 index 00000000000000..05989dc714ddbc Binary files /dev/null and b/docs/silabs/general/resources/dcl-overview.png differ diff --git a/docs/silabs/general/resources/matter-before-secure-programming-diagram.png b/docs/silabs/general/resources/matter-before-secure-programming-diagram.png new file mode 100644 index 00000000000000..d164e4530c5f98 Binary files /dev/null and b/docs/silabs/general/resources/matter-before-secure-programming-diagram.png differ diff --git a/docs/silabs/general/resources/matter-certification-declaration-example.png b/docs/silabs/general/resources/matter-certification-declaration-example.png new file mode 100644 index 00000000000000..c3945f0bf3d269 Binary files /dev/null and b/docs/silabs/general/resources/matter-certification-declaration-example.png differ diff --git a/docs/silabs/general/resources/matter-commissioning-process-diagram.png b/docs/silabs/general/resources/matter-commissioning-process-diagram.png new file mode 100644 index 00000000000000..2014ecf14d5f1d Binary files /dev/null and b/docs/silabs/general/resources/matter-commissioning-process-diagram.png differ diff --git a/docs/silabs/general/resources/matter-dcl-example.png b/docs/silabs/general/resources/matter-dcl-example.png new file mode 100644 index 00000000000000..c9b924105d2b36 Binary files /dev/null and b/docs/silabs/general/resources/matter-dcl-example.png differ diff --git a/docs/silabs/general/resources/matter-fabric-diagram.png b/docs/silabs/general/resources/matter-fabric-diagram.png new file mode 100644 index 00000000000000..1c9bc527926230 Binary files /dev/null and b/docs/silabs/general/resources/matter-fabric-diagram.png differ diff --git a/docs/silabs/general/resources/matter-network-example.png b/docs/silabs/general/resources/matter-network-example.png new file mode 100644 index 00000000000000..7aa02abef6b3ab Binary files /dev/null and b/docs/silabs/general/resources/matter-network-example.png differ diff --git a/docs/silabs/general/resources/matter-onboarding-payload.png b/docs/silabs/general/resources/matter-onboarding-payload.png new file mode 100644 index 00000000000000..d526a8895e3d21 Binary files /dev/null and b/docs/silabs/general/resources/matter-onboarding-payload.png differ diff --git a/docs/silabs/general/resources/matter-paa-pai-example.png b/docs/silabs/general/resources/matter-paa-pai-example.png new file mode 100644 index 00000000000000..ec8caed3a80b16 Binary files /dev/null and b/docs/silabs/general/resources/matter-paa-pai-example.png differ diff --git a/docs/silabs/general/resources/matter-secure-programming-diagram.png b/docs/silabs/general/resources/matter-secure-programming-diagram.png new file mode 100644 index 00000000000000..5cb13c6f25de74 Binary files /dev/null and b/docs/silabs/general/resources/matter-secure-programming-diagram.png differ diff --git a/docs/silabs/general/resources/matter-secure-vault-diagram.png b/docs/silabs/general/resources/matter-secure-vault-diagram.png new file mode 100644 index 00000000000000..f053dfe840b616 Binary files /dev/null and b/docs/silabs/general/resources/matter-secure-vault-diagram.png differ diff --git a/docs/silabs/general/resources/payloadencryption.png b/docs/silabs/general/resources/payloadencryption.png new file mode 100644 index 00000000000000..fc5900c05dc394 Binary files /dev/null and b/docs/silabs/general/resources/payloadencryption.png differ diff --git a/docs/silabs/index.rst b/docs/silabs/index.rst index cd7f06b1550224..fc2d0c1604c820 100644 --- a/docs/silabs/index.rst +++ b/docs/silabs/index.rst @@ -16,6 +16,7 @@ Welcome to Silicon Labs' Matter documentation! ./nav_2_prereq ./nav_4_thread ./nav_5_wifi + ./nav_7_prod_guide ./unify/index ./nav_3_general ./nav_6_faq diff --git a/docs/silabs/nav_1_overview.rst b/docs/silabs/nav_1_overview.rst index a16abe63088f34..7e338db7381df1 100644 --- a/docs/silabs/nav_1_overview.rst +++ b/docs/silabs/nav_1_overview.rst @@ -12,7 +12,7 @@ Matter Overview ./general/FUNDAMENTALS_DATA_MODEL.md ./general/FUNDAMENTALS_INTERACTION_MODEL.md ./general/COMMISSIONING.md - ./general/OT_SLEEPY_END_DEVICE.md + ./general/SECURITY.md + ./general/MATTER_ICD.md ./general/OTA_BOOTLOADER.md ./general/OTA_SOFTWARE_UPDATE.md - ./general/SECURITY.md diff --git a/docs/silabs/nav_3_general.rst b/docs/silabs/nav_3_general.rst index 0094d3b56813a2..9afd2ab51e5c59 100644 --- a/docs/silabs/nav_3_general.rst +++ b/docs/silabs/nav_3_general.rst @@ -11,7 +11,6 @@ Developer Reference Flashing Using Simplicity Commander <./general/FLASHING_USING_COMMANDER.md> Flash an EFR32 Device <./general/FLASH_SILABS_DEVICE.md> Flash a 917SoC Device <./general/FLASH_SILABS_SiWx917_SOC_DEVICE.md> - Matter ICDs <./general/MATTER_ICD.md> Using ZAP <./general/ZAP.md> Using Wireshark <./general/WIRESHARK.md> Using Energy Profiler <./general/EP.md> diff --git a/docs/silabs/nav_4_thread.rst b/docs/silabs/nav_4_thread.rst index d1c3376318c7f3..8c7744f17c2a63 100644 --- a/docs/silabs/nav_4_thread.rst +++ b/docs/silabs/nav_4_thread.rst @@ -10,3 +10,4 @@ Matter Over Thread Setting up the RCP <./thread/RCP.md> Build, Flash Matter Device <./thread/BUILD_FLASH_MAD.md> Using the Matter Hub <./thread/CHIP_TOOL.md> + Intermittently Connected Devices over OpenThread <./thread/OT_SLEEPY_END_DEVICE.md> diff --git a/docs/silabs/nav_5_wifi.rst b/docs/silabs/nav_5_wifi.rst index 4b4058a18dcabd..d84d7edd01c495 100644 --- a/docs/silabs/nav_5_wifi.rst +++ b/docs/silabs/nav_5_wifi.rst @@ -9,6 +9,7 @@ Matter Over Wi-Fi Build Chip Tool on Raspi <./wifi/BUILD_PI_ENV.md> Matter Demo on EFR32 NCP <./wifi/RUN_DEMO.md> Matter Demo on 917 SoC <./wifi/RUN_DEMO_SiWx917_SoC.md> + Matter 917 SoC JLink RTT Debugger <./wifi/JLINK_GUIDE_917.md> Enablement of Ozone for 917 SOC <./wifi/SiWx917_Enablement_For_Ozone.md> nav_5_wifi_dic Wi-Fi Intermittently Connected Devices (ICD) <./wifi/WIFI_SLEEPY_END_DEVICE.md> diff --git a/docs/silabs/nav_7_prod_guide.rst b/docs/silabs/nav_7_prod_guide.rst new file mode 100644 index 00000000000000..fe70336897f844 --- /dev/null +++ b/docs/silabs/nav_7_prod_guide.rst @@ -0,0 +1,10 @@ +Matter Production Guide +=============================================== + +.. toctree:: + :maxdepth: 2 + + Device Development Prerequisites <./production/CPMS_PREREQS.md> + Using Custom Part Manufacturing Services (CPMS) <./production/USING_CPMS.md> + Matter Device Attestation <./production/CPMS_ATTESTATION.md> + Matter, CPMS, and Kudelski <./production/KUDELSKI.md> diff --git a/docs/silabs/production/CPMS_ATTESTATION.md b/docs/silabs/production/CPMS_ATTESTATION.md new file mode 100644 index 00000000000000..7d83b8f4494946 --- /dev/null +++ b/docs/silabs/production/CPMS_ATTESTATION.md @@ -0,0 +1,67 @@ +# Matter Device Attestation + +## Matter Certificate Overview + +For Matter devices to be commissioned into a Matter network, a Matter commissioner must verify that the devices are certified by the Connectivity Standards Alliance, this step in the Commissioning process is called Device Attestation. Each certified device must be configured with a unique Device Attestation Certificate (DAC) and its corresponding DAC private key, which will be checked by a commissioner to add this device to its Matter fabric. For a more conceptual overview of the Matter Certificates and Device Attestation Procedure, refer to [Matter Security](../general/SECURITY.md). + +## Device Attestation Public Key Infrastructure and Certification Declaration + +Device Attestation Certificates or DACs must be included in all commissionable Matter products and must be unique in each product. DACs are immutable, so they must be installed in-factory and must be issued by a Product Attestation Intermediate (PAI) which chains directly to a Product Attestation Authority (PAA), issued by specified root Certification Authorities (CAs). These root CAs are entities that have been approved by the CSA to issue digital Matter Certificates. Therefore, if you decide not to apply to become a Certification Authority, you will need to request the generation of the Matter Certificate Chain which is a Public Key Infrastructure. To request these certificates, you must meet the following requirements: + +- Certify your Matter Product. CSA will issue a CD with a corresponding VID and PID. + +- Select a Certification Authority where you will request your DACs. At Silicon Labs, we have partnered with Kudelski to offer the [Custom Manufacturing Service](./USING_CPMS.md) to facilitate this process. + +The PAA are root certificates (certificates of a Root Certificate Authority) and are used to sign PAIs (intermediate certificates). For the attestation process to succeed, the certificate chain must start from a trusted Root Certificate; for this purpose, Matter has a database, called [Distributed Compliance Ledger (DCL)](https://webui.dcl.csa-iot.org/), where the PAAs will reside. + +>Note: PAAs are not stored on the target devices. + +The PAIs are intermediate certificates, signed by the PAA's private key, and are used to sign the DACs (device certificates). The PAI is stored on the target device and is sent to the Commissioner during the attestation process. + +The DAC is the certificate that uniquely identifies the device itself. It is signed by the PAI, and like the PAI itself, it is sent to the Commissioner during the attestation process. The DAC public-key must match the device's private-key, which should be stored in the most secure location possible and is used to sign outgoing messages during commissioning. + +The CD (Certification Declaration) is a file issued by CSA upon the firmware's certification process. It contains the Vendor ID (VID), and a list of Product IDs (PIDs), which should match the VID, and PID stored in the Subject field of both the PID, and DAC certificates. Along with the PID and DAC, the CD is stored on the device and sent to the Commissioner during the commissioning process. + +## Certification Authorities and Recommended Certificate Use + +The Certification Authority's certificate chain is used to validate any certificate said authority has signed and confirm the Matter Device Identity. A Root Certification Authority is a CA whose certificates are self-signed. They are the root of trust. These are the most trusted and secured CAs, and their private keys are expected to be the most highly secured keys. Root CAs can generate the whole Certificate Chain (PAA > PAI > DAC). Intermediate Certificate Authorities are CAs whose certificates have been signed by a higher-level CA from which you can generate DACs that will be signed by these Intermediate CAs and saved on Matter Devices. These CAs will generate (PAI-DAC). A compromise in the private key of the Root CA would jeopardize not only their issued Root Certificates, but also all the certificates in that chain including PAIs and DACs. + +![Certification Authorities](resources/certification-authorities.png) + +While the information in the certificate location is public, write access to the certificate location should be restricted. Usually the certificates are installed in-factory, but the exact procedure depends on the CAs involved, and the mechanisms available to secure the DAC private-key, and the certificate files. Ideally: + +1. The device must run a small application in privilege mode that generates the key-pair in a secured environment. This procedure should run on-device. + +2. The device issues a CSR, signed with its new private key, that is sent to the CA. + +3. The CA issues the new certificate from the certificate Chain and signs it using its own PAI private key. + +4. The newly created DAC is returned to the device. + +5. The device stores the new DAC in a read-only section of non-volatile memory. + +6. The device boots into normal operation mode, thus forbidding any further modification of either the DAC key-pair, and the DAC. + +7. From this point on, the DAC private-key value should never be exposed, and the DAC should never be modified, unless it is compromised. + +However, in some environments, the key-pair is generated outside the device. A CA may generate the DAC private keys on behalf of the device and use the keys to generate the DAC too. In this case, both the DAC key-pair, and the DAC are stored into the device on secured locations, and any external copy of the DAC private-key must be destroyed. + +## Device Attestation Procedure + +When commissioning a device, the Commissioner must execute this procedure to validate if the device is indeed Matter certified and compliant, and if it has been produced by a certified manufacturer. The procedure is as follows: + +1. The commissioner generates a random 32-byte nonce meant for attestation. +2. The commissioner sends the generated nonce to the commissionee (Matter Device being attested) and makes an Attestation Request. +3. The commissionee responds with an Attestation Response including an Attestation Information message signed with the DAC private key. This Attestation Information must be validated by the commissioner to accept the Matter Device into its Matter Fabric (Network). +4. The commissioner will retrieve the Matter Certificate Chain in order to attest the Matter Device. + +Attestation Information to validate: + +- The commissioner validates the PAA retrieved is trusted. Generally, the trusted PAA certificates are included in the Distributed Compliance Ledger (DCL). +- The device presents a valid CD, PAI, and DAC. This is determined by verifying the Certificate Chain. +- The VIDs and PIDs on the CD, PAI, and DAC must match. If the VID is included in the PAA, it must also match the other certificates. +- DAC must be valid, and signed by the PAI. +- The PAI must be valid, and signed by a trusted PAA. +- The Discriminator stored on the device must match the one searched by the Commissioner. +- The Passcode provided by the Commissioner must match the one stored on the device. +- The Attestation nonce from the device must match the Commissioners provided nonce. diff --git a/docs/silabs/production/CPMS_PREREQS.md b/docs/silabs/production/CPMS_PREREQS.md new file mode 100644 index 00000000000000..0e73b794977365 --- /dev/null +++ b/docs/silabs/production/CPMS_PREREQS.md @@ -0,0 +1,79 @@ +# Matter Device Development Prerequisites + +If you plan to develop a Matter end product, this page lists the prerequisites and next steps to facilitate your production journey through Matter. + +## Become a CSA Member + +Your organization must be an associate member or better to get your product certified by a CSA-approved testing facility. As a member, your organization will receive membership perks: + +- Official resources to assist you in developing Matter products. + +- Authorization to contribute to the [Matter Github repository](https://github.com/project-chip/connectedhomeip). + +- Once approved, CSA will reserve a unique Vendor ID (VID) chosen by your organization. This VID will be needed to provision your device. + + - Your unique VID will be added to the [CSA Distributed Compliance Ledger](https://webui.dcl.csa-iot.org/) (DCL). + +- [Matter Certification tool access](https://csa-iot.org/certification/tools/certification-tool/) + + - Allows you to evaluate your product for certification before the official certification process. + +Become a member at [CSA Membership](https://csa-iot.org/become-member/). You can see a list of the different memberships offered at CSA. + +## Develop Your Matter Application + +Creating a Matter Application is an exciting journey. To start your journey, you need to understand the [Matter Fundamentals - Silabs](../general/FUNDAMENTALS_INTRO.md). We also provide two development paths that you can choose from (OpenThread/WiFi) + +Once you are ready to develop your Matter Application, you should review the [Matter over WiFi](../nav_5_wifi.rst) or [Matter over WiFi](../nav_4_thread.rst), which provides detailed background and instructions for Matter developers working in either the Thread or Wi-Fi models. The Developer's Guide contains a deeper dive into development. + +Additionally, Silicon Labs recommends that you become familiar with the Matter Specification documents: + +- Matter Core Specification + +- Matter Device Library Specification + +- Matter Application Cluster Specification + +These specifications can be downloaded from the [CSA's Specifications Download Request](https://csa-iot.org/developer-resource/specifications-download-request/) website. + +## CSA Certification + +Once a device/product is ready for production, you must have your product certified by a CSA-approved testing facility to certify compliance with the Matter Standard. Review the [CSA Certification Process](https://csa-iot.org/certification/why-certify/) to ensure a smooth and prompt Matter product certification. + +By becoming a member of the CSA, access to their [Matter Certification Tool](https://csa-iot.org/certification/tools/certification-tool/) is granted. The Matter Certification Tool facilitates applying to certify your Matter product, after which you can create your application and upload your images and required documents. For additional resources on the certification process, refer to the [Certifying your Matter Product, an Overview](https://community.silabs.com/s/article/Certifying-your-Matter-Product-an-Overview?language=en_US) KBA. This KBA provides information on: + +- Overview of Matter Certification Steps and milestones + +- Thread Certification + +- Matter Test Harness Guide + +- Important Matter CSA Resources and a Q&A + +Once your device is approved, your organization will be issued an official Certification Declaration (CD). This CD is a cryptographic document issued by CSA that confirms that your device has been certified. The CD is included in the attestation process sent by the Commissionee during device attestation. To view a list of authorized test facilities, check out the [CSA Authorized Testing Providers](https://csa-iot.org/certification/testing-providers/) summary. This CD is required to be injected during the manufacturing process if you are using the Silicon Labs CPMS process. This certification process can take some time to complete. You should ensure that this time is accounted for during your development lifecycle to keep your product on schedule. + +### Helpful CSA Links + +- [CSA Membership](https://csa-iot.org/become-member/) + +- [CSA Specifications Download Request page](https://csa-iot.org/developer-resource/specifications-download-request/) + +- [CSA Pre-Certification Tool](https://csa-iot.org/certification/tools/certification-tool/) + +- [CSA Authorized Testing Providers](https://csa-iot.org/certification/testing-providers/) + +- [CSA Distributed Compliance Ledger (DCL)](https://webui.dcl.csa-iot.org/) + +- [CSA Test Distributed Compliance Ledger (DCL)](https://testnet.iotledger.io/) + +- [PAA Providers](https://csa-iot.org/certification/paa/) + +## Standards Development Organizations (SDO) Membership + +Matter is an application layer that works on top of other proven network technologies. Your organization may also be required to be a member of an SDO and be able to pass the certification processes that these organizations require. Examples of these SDOs are Bluetooth, WiFi, Thread, and others. Be sure to take these organizational requirements into account when planning your products. Refer to the [Certifying your Matter Product, an Overview](https://community.silabs.com/s/article/Certifying-your-Matter-Product-an-Overview?language=en_US) KBA. + +## Ready for Production + +Silicon Labs is the only IoT embedded solution provider offering a Custom Part Manufacturing Service (CPMS) to device makers. This secure provisioning service allows IoT device makers to order customized hardware straight from the factory via the [CPMS web portal](https://cpms.silabs.com/login). CPMS removes the numerous complexities, time, and expense of custom provisioning Matter devices at scale. To provide this solution, Silicon Labs has partnered with Kudelski Security to provide scalable access to Device Attestation Certificates (DACs) for Matter Devices. + +When moving to production, if you decide to provision your devices at scale using CPMS and would like to learn more about Kudelski, refer to their [Matter-compliant certificate service](https://www.kudelski-iot.com/services-and-systems/matter-paa-pai). To use the Silicon Labs CPMS solution, contact [Kudelski](https://www.kudelski-iot.com/services-and-systems/matter-paa-pai) to create an account. When creating a Kudelski account and using CPMS for production, you will need to specify Silicon Labs as a requestor and recipient of DACs for any PAIs that will be programmed in the Silicon Labs manufacturing facilities. diff --git a/docs/silabs/production/KUDELSKI.md b/docs/silabs/production/KUDELSKI.md new file mode 100644 index 00000000000000..03567eab7506ea --- /dev/null +++ b/docs/silabs/production/KUDELSKI.md @@ -0,0 +1,43 @@ +# Matter, CPMS, and Kudelski + +## Kudelski PKI Infrastructure + +Silicon Labs has partnered with Kudelski Security to generate Matter Device Attestation Certificates (DAC) for our Custom Part Manufacturing Service (CPMS). "Kudelski IoT’s Matter Product Attestation Certificate Service enables companies to get scalable access to Device Attestation Certificates, allowing each device to join the Matter ecosystem with confidence and ease". Kudelski is a certified CSA certificate authority that forms the root Product Attestation Authority (PAA) certificate in the CPMS Matter certificate chain. Each PAA owns a public and private key along with their self-signed PAA certificate which will be used to sign PAI certificates. Kudelski also manages the Product Attestation Intermediate (PAI) keys for CPMS used to sign the unique Device Attestation Certificates (DAC). PAIs are submitted in the form of a CSR request to the PAA to be signed. These three items, the PAA, PAI, and DAC as well as a Certification Declaration form the basis for a device to attest to the Matter network. + +## What is Required of My Organization with the Silicon Labs/Kudelski Security Partnership? + +To have DACs generated by Kudelski, your organization will need to have an account created with Kudelski Security. Start at [Kudelski](https://www.kudelski-iot.com/services-and-systems/matter-paa-pai) to begin the process of creating this account. + +After creating your account, your organization will want to create a Product Attestation Intermediary (PAI) certificate with Kudelski. This will be used to sign the DACs that will end up in your devices at manufacturing. If you use CPMS, you will need to specify Silicon Labs as a requestor and recipient of DACs for any PAIs that will be programmed in the Silicon Labs manufacturing facilities. This will allow CPMS Secure Vault Services to request those DACs on your behalf when you are ready to manufacture those products. Depending on your own internal processes, this may require reviews from within your own organization. Be sure to allow enough lead time for yourself when planning your Matter devices to account for this. + +## Why Not Just Do This Myself? + +Kudelski IoT has done the heavy lifting for you. Kudelski is a well-established Public Key Infrastructure (PKI) provider that offers Matter certificates that allow you to be a part of the Matter ecosystem. Kudelski IoT uses its keySTREAM PKI-as-a-Service application to help manage your Matter PKI artifacts. + +- Kudelski has done the heavy lifting of becoming a Connectivity Standards Alliance (CSA) authorized PAA for you. + +- Kudelski has been creating device credentials for more than 30 years and is a trusted leader in PKI-as-a-Service. + +- Cloud setup of your vendor-specific Product Attestation Intermediate (PAI) + +- Managed generation and secure delivery of Matter Device Attestation Certificates (DAC) + +- Kudelski and Silicon Labs have created an ultra-secure integration straight from the root CA to the factory. + +- Spare yourself time, and get to market sooner with CPMS. CPMS already handles this for you! + +Becoming your own PAA and issuing your own signed attestation certificates for Matter is no small undertaking. CSA requires very strict requirements for becoming a trusted certificate authority, as well as rigorous security and privacy requirements, hardware, infrastructure, governance, and much more. This is a costly endeavor that may include specialized hardware, such as on and offline Hardware Security Modules (HSM), specialized facility and operational needs, and much more that can quickly be out of reach of all but the largest of organizations, not to mention the time required to put these processes in place. In most cases, partnering with an established provider is far more economical for vendors and will get you up and running as quickly as possible. + +## What Should I Expect When I Create an Account with Kudelski? + +There are a few processes in place to get you set up and working quickly to start receiving signed DACs from Kudelski: + +1. Account Setup - If you are already a CSA member, you can start the setup of your account (fees may apply) on Kudelski's cloud application. If you are not a CSA member yet, review the CSA requirements. Per CSA requirements, Kudelski will conduct some manual background checks. Your organization will also need to sign the Kudelski Requestor Agreement Document (RAD) document before any PAIs are created. + +2. New Product Family Setup - Once your Product Family is successfully certified by CSA, Kudelski can create your vendor-specific Product Attestation Intermediate (PAI) on keySTREAM for that Product Family. + +3. Certificate Request - Once a PAI is created, you can request a batch of certificates for your devices. For the CPMS workflow, you will need to agree (with Kudelski) to allow Silicon Labs to be a requestor and receiver of DACs in order for the CPMS integrations to successfully request and receive those DACs during manufacturing. + +4. Certificate Delivery - In the CPMS workflow, Silicon Labs will receive delivery of these DACs through secure services with Kudelski, which can then be programmed into your devices on the manufacturing line. + +5. DACs are billed after your devices are manufactured and shipped. diff --git a/docs/silabs/production/USING_CPMS.md b/docs/silabs/production/USING_CPMS.md new file mode 100644 index 00000000000000..619c7e2141b0c6 --- /dev/null +++ b/docs/silabs/production/USING_CPMS.md @@ -0,0 +1,131 @@ +# Using Custom Part Manufacturing Services (CPMS) + +Silicon Labs offers Matter support through our Custom Part Manufacturing Services (CPMS). Your organization can order your Matter devices directly from Silicon Labs or a third-party vendor utilizing our CPMS services. Silicon Labs is one of the few providers that can program your information directly to silicon through secure automation with our partner, Kudelski Security. + +## What is CPMS? + +CPMS allows you to customize Silicon Labs hardware – wireless SoCs, modules, MCUs – at the factory. The CPMS self-service web portal guides you through the customization process and its various customizable features and settings. You can place orders for customized test and production units to our factories securely via the CPMS portal. + +Unlike traditional flash programming, CPMS is a secure provisioning service that enables you to customize your chips with highly advanced features. These include secure boot, secure debug, encrypted OTA, public, private, and secret keys, secure identity certificates, and more. The custom features, identities, and certificates are injected into the hardware securely, quickly, and cost efficiently through Silicon Lab's own factories. + +## Why CPMS? + +Securing an IoT device is a highly complicated and costly process. You must generate public and private keys for secure boot and secure debug, sign code with a private key, store all the private keys in a Hardware Security Module (HSM), place the public keys for secure boot and secure debug in one-time-programmable (OTP) memory, flip OTP bits for secure boot and secure debug, and flash the encrypted code and identity certificates within the hardware. CPMS streamlines the programming part of this process for you. Even the most advanced security features, certificates, and identities can be programmed in a secure, fast, and cost-efficient way in Silicon Lab's factories. + +## How Does Matter Fit into the CPMS Equation? + +Silicon Labs is the only IoT-embedded solution provider at this time offering a secure provisioning service for Matter devices at scale. Silicon Labs has partnered with [Kudelski Security](./KUDELSKI.md) to provide scalable access to Device Attestation Certificates (DACs) for your Matter devices. Kudelski has "30+ years of experience securely provisioning more than 500 million devices". Rest assured that your secrets are stored in HSMs both on and offline to provide maximum security for your secret key material. Learn more about [Security](https://www.kudelski-iot.com/services-and-systems/matter-paa-pai). + +CPMS allows you to configure your device and receive production samples for a minimal cost before making a full production order. To configure your Matter settings, there are two ways to accomplish this with Silicon Labs tooling. + +If your organization uses [Simplicity Studio](https://www.silabs.com/developers/simplicity-studio), Silicon Lab's IoT IDE, we have provided a built-in utility that will output a JSON formatted data file that can be uploaded directly into CPMS. This data file will fill out the necessary Matter information for you. This is the preferred method as it reduces the potential for errors and/or typos. + +The second method is to simply provide the required information through the CPMS web forms. This is a minimal process that includes important attestation information such as your Vendor ID (VID), Product ID (PID), Certification Declaration, and other inputs required to generate the Matter certificate chain. + +CPMS has automated integrations with Kudelski to obtain the unique DACs for each device at the time of manufacturing. All data remains encrypted throughout the entire process through secure channels between Kudelski and Silicon Labs. + +## I'm Ready to Get my Product to Market. What is Needed by CPMS? + +CPMS will ask for various attributes about your device, but these are the primary elements that will be needed for proper certificate generation. + +- Vendor ID (VID) - Your unique VID will be required by CPMS to properly generate the necessary PKI infrastructure to allow your device on the Matter network. + +- Product ID (PID) - Your organization will need to provide a unique PID that will be used to identify this product on the network. + +- Certification Declaration (CD) - This is a cryptographic document that is issued to you by CSA after your device has been successfully certified by a CSA-approved testing facility. + +## Pre-Production Checklist + +1. Choose a Matter-capable part to develop your Matter application on. + +2. Become a [CSA member](https://csa-iot.org/become-member/) if your organization is not already a member. An associate-level membership or higher is required to obtain membership perks, certification, and a Vendor ID. See [Device Development Prerequisites](../nav_2_prereq.rst). If you have not been through these steps, please ensure ample time to get this step done before you are ready to go to production. + +3. If you are already a CSA member, make sure that you have been supplied a VID from CSA. If not, contact CSA to obtain a VID. The VID should also have been added to the [CSA Distributed Compliance Ledger (DCL)](https://webui.dcl.csa-iot.org/). + +4. Confirm that your VID has been added to the [DCL](https://webui.dcl.csa-iot.org/). + +5. As a device maker and CSA member, you should add information about your device to the ledger before shipping your device to the market. If this is not available at the time of release, your devices will not attest properly. + +6. Your application has been developed and is ready for certification. + +7. Using the [CSA Pre-certification tool](https://csa-iot.org/certification/tools/certification-tool/), you can test your application for completeness before submitting your application for certification. Save your organization time and money by pre-certifying your application before submitting it for certification. + +8. Submit your application for certification to a [CSA-approved testing facility](https://csa-iot.org/certification/testing-providers/) for your product type. Once certified, you will be issued a **Certification Declaration (CD)**. This is a cryptographic document stating that your device has successfully been certified and is used in conjunction with the Matter certificate chain to attest to the Matter network. This file should be in a .der format. + +9. Begin the process of setting up an account with Kudelski Security as a provider of DACs. Note: Kudelski provides DACs on the Test DCL for no charge. [Learn more about our partnership](./KUDELSKI.md) with Kudelski Security for Matter devices. + +10. Ensure that you have the CD in hand. This will need to be uploaded to CPMS. + +11. You're ready to order samples with [CPMS](https://cpms.silabs.com/)! + +## Choosing the Test DCL or Production DCL + +There are two public ledgers available to developers known as the Matter Distributed Compliance Ledger (DCL). The DCL is a cryptographically secure ledger based on blockchain technology. This ledger preserves an immutable record that stores public information that can be retrieved by DCL clients. For more details, see the [CSA Matter DCL whitepaper](https://csa-iot.org/developer-resource/white-paper-distributed-compliance-ledger/). Each DCL contains five schemas that can be accessed by a client to retrieve information about a device. + +- Vendor Info Schema - this schema provides public information about the device vendor such as the VID, Vendor Name, and Company Legal Name. + +- Device Model Schema - this schema provides public information about the actual device such as the Product Name, PID, VID, and more. + +- Device Software Version Model Schema - this schema provides public information about software-specific data about the device such as Release Notes URL, OTA software image URL, and more. + +- Compliance Schema - this schema provides public information about the certification of a device such as the VID, PID, Software Version, CD Certificate ID, and more. + +- PAA Schema - this schema provides information about valid Product Attestation Authority certificates for approved PAAs. + +The **Test DCL**, as the name suggests, is a public Matter ledger that will allow vendors to test their devices in a test environment. Entries into the Test DCL are less rigorous than the Production DCL and can be used to test devices using test certificates provided by Matter or other valid vendors. These test certificates cannot be used on the production DCL. For the production case, you have to ensure that you have the proper certificate chain in place. For CPMS, Kudelski provides Test DCL DACs at **no additional charge**. Your organization needs to ensure that an account has been created with Kudelski to order these DACs through CPMS. [Learn more here](./KUDELSKI.md). + +If you are ready to take your device to production, you have the option to select the **Production DCL**. This is the primary [Matter DCL](https://webui.dcl.csa-iot.org/) for production devices. For your device to properly commission onto the Matter fabric, the commissioner needs to be able to verify that a valid certificate chain is in place. The information needed must be publicly available in the production DCL. The device needs to have a valid DAC signed by an approved PAI provider, and a root PAA provider. Your device also must contain a valid certification of the device, all available in the DCL. Silicon Labs partners with Kudelski Security as a PAA provider of choice. Kudelski also signs the Product Attestation Intermediate (PAI) certificate for our customers using CPMS. Each PAI is specific to our customer's products and is created when you set up a new product on your account with Kudelski. Production DCL samples must be approved even if you have already approved Test DCL samples before going to production. + +## CPMS Workflow + +You've completed all of the items in the pre-production checklist and are ready to create samples. With CPMS, you get the benefit of receiving several actual samples of your product for your approval. This allows you to test the actual device before placing a large production run. Once you approve the sample, you have an Orderable Part Number (OPN) that can be used with Silicon Labs or other third-party distributors. The workflow involves the following steps: + +1. To access CPMS, you need to register for an account with Silicon Labs. If you are using Simplicity Studio or other Silicon Labs tools, you probably already have this. If not, [register for a Silicon Labs account](https://community.silabs.com/SL_CommunitiesSelfReg). + +2. [Login to CPMS](https://cpms.silabs.com/login). + +3. Create a new Custom Part. + +4. Select the part on which you have built your Matter application. You will be asked a couple of questions about your future order. This helps Silicon Labs prepare for your eventual order and ensure that the factories are ready to go in the timeframe expected. + + ![screenshot](resources/image1.png) + +5. Click **Customize** to start configuring your device. With CPMS, you have a wide range of options to work with to customize your device. Matter is only one component of this. You have full control over other features of the part itself such as debug lock/unlock, secure boot, and many other security features depending on the part selected. + +6. The Matter-specific configurations can be found in the Ecosystem Identities toggle. Select the toggle to view the available ecosystems supported by your device. + + ![screenshot](resources/image2.png) + +7. Add the Matter Ecosystem to your part and you will be presented with the required Matter inputs to help secure the proper PAA/PAI/DAC certificates from Kudelski. + +8. Upload your Certification Declaration. This is the file in .der format that you should have received after successful certification from a CSA-approved testing facility. + + ![screenshot](resources/image3.png) + +9. (optional) If you used Simplicity Studio, use the Provisioning Tool to output your Matter information directly from the application. This tool outputs a cpms.json file that can be uploaded to help you quickly fill out this information. + + ![screenshot](resources/image4.png) + +10. Fill out the required Matter fields. This includes the VID, PID, and several additional inputs to help Silicon Labs generate the necessary Matter certificate chain. If you use the cpms.json file that is generated through the Silicon Labs Matter provisioning tool, these will be automatically filled in for you. + + ![screenshot](resources/image5.png) + +11. (optional) Fill out the Matter Optional Fields. These fields will also be automatically filled out for you if you use the cpms.json file referenced above. + + ![screenshot](resources/image6.png) + +12. Once you have satisfied all of the required fields, you will be prompted to **Proceed to Review** to review the selections in your order. + + ![screenshot](resources/image7.png) + +13. Review your customizations and pricing information. You may also be asked for the shipping information if this is not on file with us already. The sample orders will be shipped to this address. + +14. Submit for evaluation. + +15. For Matter-specific parts, Silicon Labs works with Kudelski IoT to secure the DACs for your sample parts. These DACs are signed with the proper PAA/PAI certificate chains and delivered via Secure Vault Services integrations directly with Kudelski. + +16. Once the DACs are available, the order will go into Silicon Labs manufacturing to be programmed and shipped to your address once the samples are complete. + +17. You can then Approve or Reject the samples once your organization is able to test the sample parts. Silicon Labs recommends at this time that you test these samples with your device commissioner to ensure that the samples can properly attest to the Matter network. + +18. Once approved, you will be able to order these parts, based on the OPN for that part. You can do this through Silicon Labs or through a third-party distributor. You may also opt to work with a Silicon Labs Field Application Engineer to help get this order executed. diff --git a/docs/silabs/production/resources/certification-authorities.png b/docs/silabs/production/resources/certification-authorities.png new file mode 100644 index 00000000000000..232acde944e94a Binary files /dev/null and b/docs/silabs/production/resources/certification-authorities.png differ diff --git a/docs/silabs/production/resources/image1.png b/docs/silabs/production/resources/image1.png new file mode 100644 index 00000000000000..aa1a077d2af17c Binary files /dev/null and b/docs/silabs/production/resources/image1.png differ diff --git a/docs/silabs/production/resources/image2.png b/docs/silabs/production/resources/image2.png new file mode 100644 index 00000000000000..1b287afd6fa0cf Binary files /dev/null and b/docs/silabs/production/resources/image2.png differ diff --git a/docs/silabs/production/resources/image3.png b/docs/silabs/production/resources/image3.png new file mode 100644 index 00000000000000..21864bee2af427 Binary files /dev/null and b/docs/silabs/production/resources/image3.png differ diff --git a/docs/silabs/production/resources/image4.png b/docs/silabs/production/resources/image4.png new file mode 100644 index 00000000000000..59ca06ca2d9fbe Binary files /dev/null and b/docs/silabs/production/resources/image4.png differ diff --git a/docs/silabs/production/resources/image5.png b/docs/silabs/production/resources/image5.png new file mode 100644 index 00000000000000..6404096b229ff9 Binary files /dev/null and b/docs/silabs/production/resources/image5.png differ diff --git a/docs/silabs/production/resources/image6.png b/docs/silabs/production/resources/image6.png new file mode 100644 index 00000000000000..18a5b5044ed406 Binary files /dev/null and b/docs/silabs/production/resources/image6.png differ diff --git a/docs/silabs/production/resources/image7.png b/docs/silabs/production/resources/image7.png new file mode 100644 index 00000000000000..fa643f4abdec52 Binary files /dev/null and b/docs/silabs/production/resources/image7.png differ diff --git a/docs/silabs/thread/BUILD_FLASH_MAD.md b/docs/silabs/thread/BUILD_FLASH_MAD.md index 7c0aafbb4c5b9d..e6e92c6ef8d08a 100644 --- a/docs/silabs/thread/BUILD_FLASH_MAD.md +++ b/docs/silabs/thread/BUILD_FLASH_MAD.md @@ -32,12 +32,13 @@ use one of the following options: > Matter 15.4 development is included on the > [Matter Software Requirements](../general/SOFTWARE_REQUIREMENTS.md) page. > Be sure that you have satisfied these requirements before proceeding. + > Users may need to run the various commands as the root user or with certain privilges enabled. The Matter Accessory Device (lighting-app) can be built out of this repo. Documentation on how to build and use the lighting-app Matter Accessory Device is provided in this - [README.md](https://github.com/SiliconLabs/matter/blob/latest/examples/lighting-app/silabs/efr32/README.md) + [README.md](https://github.com/SiliconLabs/matter/blob/latest/examples/lighting-app/silabs/README.md) Please note that you only need to build a single device for the demo such as the lighting-app. If you wish to build other examples such as the sleepy end diff --git a/docs/silabs/general/OT_SLEEPY_END_DEVICE.md b/docs/silabs/thread/OT_SLEEPY_END_DEVICE.md similarity index 92% rename from docs/silabs/general/OT_SLEEPY_END_DEVICE.md rename to docs/silabs/thread/OT_SLEEPY_END_DEVICE.md index 02471f2f446441..227044961044a7 100644 --- a/docs/silabs/general/OT_SLEEPY_END_DEVICE.md +++ b/docs/silabs/thread/OT_SLEEPY_END_DEVICE.md @@ -8,7 +8,7 @@ Matter provides an Intermittently Connected Device (ICD) operating mode to exten The Matter ICD manager leverages subscription report synchronization and OpenThread functionalities to allow devices to sleep for set periods without disrupting their Matter sessions. -Currently, in Matter v1.2 only ICD with Short Idle Time (SIT) is supported. ICD SIT are devices that SHOULD be configured with a Slow Polling Interval shorter than or equal to 15 seconds. For example, in a typical scenario for door locks and window coverings, commands need to be sent to the ICD with a use-case imposed latency requirement. Typically, devices that are Short Idle Time ICDs are not initiators in the communication flow. +In Matter v1.2, only ICD's with Short Idle Time (SIT) are supported. Matter 1.3 alpha provides provisional support for Long Idle Time (LIT) ICD's. A SIT ICD are devices that SHOULD be configured with a Slow Polling Interval shorter than or equal to 15 seconds. For example, in a typical scenario for door locks and window coverings, commands need to be sent to the ICD with a use-case imposed latency requirement. Typically, devices that are Short Idle Time ICDs are not initiators in the communication flow. ## Operating Modes @@ -48,7 +48,7 @@ Matter exposes some defines to configure the polling intervals of the openthread | SlowPollInterval | CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL | Interval, in milliseconds, at which the thread radio will poll its network in idle mode. | 15000 ms | <= IdleModeInterval | | FastPollInterval | CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL | Interval, in milliseconds, at which the thread radio will poll its network in active mode. | 200 ms | < ActiveModeInterval | -For Matter configuration, see the [Matter ICD](./MATTER_ICD.md) documentation. +For Matter configuration, see the [Matter ICD](../general/MATTER_ICD.md) documentation. ### Usage diff --git a/docs/silabs/wifi/BUILD_PI_ENV.md b/docs/silabs/wifi/BUILD_PI_ENV.md index c8258af8b079cd..d7c0ca737962a9 100644 --- a/docs/silabs/wifi/BUILD_PI_ENV.md +++ b/docs/silabs/wifi/BUILD_PI_ENV.md @@ -62,7 +62,7 @@ Follow the instructions in in the section "Installing prerequisites on Raspberry Pi 4". -2. To build enviorment follow the `Software setup` and `Compiling chip-tool` steps given in [Software setup](./SW_SETUP.md), +2. To build enviorment follow the `Software setup` and `Compiling chip-tool` steps given in [Software setup](./SW_SETUP.md). ## Bluetooth Setup diff --git a/docs/silabs/wifi/DEMO_OVERVIEW.md b/docs/silabs/wifi/DEMO_OVERVIEW.md index 24adfcddc998da..300c051e043023 100644 --- a/docs/silabs/wifi/DEMO_OVERVIEW.md +++ b/docs/silabs/wifi/DEMO_OVERVIEW.md @@ -22,7 +22,7 @@ of two platforms, either Linux/Mac or Raspberry Pi. ## Step 3: Building the Matter Accessory Device (MAD) for Wi-Fi -To build a Matter of Wi-Fi Accessory Device, follow the steps in the [Software Setup](SW_SETUP.md) +To build a Matter Wi-Fi Accessory Device, follow the steps in the [Software Setup](SW_SETUP.md) Build commands are provided for the EFR32MG24 host processor, with the RS9116, SiWx917 and WF200 network co-processors. diff --git a/docs/silabs/wifi/DIC_Wi-Fi.md b/docs/silabs/wifi/DIC_Wi-Fi.md index bb921dc76714a2..bacc38db7a8a99 100644 --- a/docs/silabs/wifi/DIC_Wi-Fi.md +++ b/docs/silabs/wifi/DIC_Wi-Fi.md @@ -36,6 +36,7 @@ To set up and configure AWS or Mosquitto for DIC support please see the followin ### Building Matter DIC Application 1. To Build DIC Application, refer [Building of DIC](./BUILD_DIC.md) 2. Commission the Matter Device and confirm DIC connection is done from Device side logs. + ## End-to-End Test of DIC Application - **Sharing status of device to cloud** @@ -44,7 +45,7 @@ To set up and configure AWS or Mosquitto for DIC support please see the followin ![Silicon Labs - DIC design](./images/dic-status-sharing.png) **Note**: For reference, Lighting App commands given in the above image. Similarly other application commands also can be passed. - - End-to-end command to be executed from chip-tool, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md#demo-execution---commissioning-a-wi-fi-device-using-chip-tool-for-linux) + - End-to-end command to be executed from chip-tool, refer [Running the Matter Demo](RUN_DEMO.md#demo-execution---commissioning-a-wi-fi-device-using-chip-tool-for-linux) - Below is the application specific attribute/s information or state shared to the cloud through Direct Internet Connectivity Solution - For Lighting App, On/Off Attributes - For Lock App, lock/unlock Attributes @@ -62,7 +63,7 @@ To set up and configure AWS or Mosquitto for DIC support please see the followin **Note**: For reference, Lighting App commands given in the above image. Similarly other application commands also can be passed. -- Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md#demo-execution---commissioning-a-wi-fi-device-using-chip-tool-for-linux) +- Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo](RUN_DEMO.md#demo-execution---commissioning-a-wi-fi-device-using-chip-tool-for-linux) - For Controlling the device, set topic name and the commands to be executed in the mqtt_explorer for below applications. - Lighting App @@ -102,7 +103,7 @@ To set up and configure AWS or Mosquitto for DIC support please see the followin ![Silicon Labs - DIC design](./images/dic-aws-ota.png) - Build DIC with AWS OTA , refer [Building DIC AWS OTA](./BUILD_DIC.md#build-command-with-dic-aws-ota) - - Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md) + - Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo on EFR Hosts](RUN_DEMO.md) or [Running the Matter Demo on SiWx917 SoC Hosts](RUN_DEMO_SiWx917_SoC.md) - Make sure device is connected to MQTT Server successfully. - Then Create a AWS OTA Job in the AWS Website, refer [How to create AWS OTA JOB](AWS_CONFIGURATION_REGISTRATION.md) - Trigger OTA Command through MQTT Explorer like below. diff --git a/docs/silabs/wifi/ECOSYSTEM_SETUP.md b/docs/silabs/wifi/ECOSYSTEM_SETUP.md index 5e863b011a67dc..ea7c44ec1988a0 100644 --- a/docs/silabs/wifi/ECOSYSTEM_SETUP.md +++ b/docs/silabs/wifi/ECOSYSTEM_SETUP.md @@ -31,12 +31,7 @@ - **Wi-Fi SoC Dev kits and boards** - SiWx917 / BRD4002A / Wireless Starter Kit - - SiWx917 SoC / Dual Flash Radio Board / 2.4GHz - - BRD4325B - A0 dual flash 1.1 - - BRD4325B - A0 dual flash 1.2 - SiWx917 SoC / Common Flash Radio Board / 2.4GHz - - BRD4325C - B0 common flash v1.2 - - BRD4325G - B0 Stacked Flash + External PSRAM v1.2 - BRD4338A - B0 common flash v2.0 - **Wi-Fi NCP Dev kits and boards** @@ -47,39 +42,27 @@ - BRD4187C / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm - [XG24-RB4187C](https://www.silabs.com/development-tools/wireless/xg24-rb4187c-efr32xg24-wireless-gecko-radio-board) - MG24 with WSTK : [xG24-PK6010A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-20-dbm?tab=overview) - - **MG12 boards:** - - [EFR32MG12 Development Kit](https://www.silabs.com/development-tools/wireless/zigbee/efr32mg12-dual-band-starter-kit) - - BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4161A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4161a-efr32mg12-radio-board) - - BRD4162A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@10dBm - - [SLWRB4162A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4162a-efr32mg12-radio-board) - - BRD4163A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4163A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4163a-efr32mg12-radio-board) - - BRD4164A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - [SLWRB4164A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4164a-efr32mg12-radio-board) - - BRD4170A / SLWSTK6000B / Multiband Wireless Starter Kit / 2.4GHz@19dBm, 915MHz@19dBm - - [SLWRB4170A](https://www.silabs.com/development-tools/wireless/zigbee/slwrb4170a-efr32mg12-radio-board) - **Wi-Fi Dev Kits & boards** - RS9116 - SB-EVK1 / Single Band Wi-Fi Development Kit / 2.4GHz - [RS9116X-SB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk-development-kit) - - SB-EVK2 / Single Band Wi-Fi Development Kit / 2.4GHz - - [RS9116X-SB-EVK2](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk2-development-kit) - - DB-EVK1 / Dual Band Wi-Fi Development Kit / 2.4GHz & 5GHz - - [RS9116X-DB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-db-evk-development-kit) + - SB-EVK2 / Single Band Wi-Fi Development Kit / 2.4GHz + - [RS9116X-SB-EVK2](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-sb-evk2-development-kit) + - DB-EVK1 / Dual Band Wi-Fi Development Kit / 2.4GHz & 5GHz + - [RS9116X-DB-EVK1](https://www.silabs.com/development-tools/wireless/wi-fi/rs9116x-db-evk-development-kit) **Note:** Matter only supported over 2.4GHz on this Dev kit. - - Interconnect board (included in the Wi-Fi kits) - - SPI Cable (included in the RS9116 kit) - - Jumper Cables (included in the RS9116 kit) + - Interconnect board (included in the Wi-Fi kits) + - SPI Cable (included in the RS9116 kit) + - Jumper Cables (included in the RS9116 kit) - SiWx917 - SiWx917 NCP Mode / Wi-Fi Expansion Board / 2.4GHz - - BRD8036A (A0 Expansion v1.1) + - BRD4346A - WF200 - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz - - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) - - WFM200S / Single Band Wi-Fi Expansion Board / 2.4GHz - - [SLEXP8023A](https://www.silabs.com/development-tools/wireless/wi-fi/wfm200-wifi-expansion-kit) + - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) + - WFM200S / Single Band Wi-Fi Expansion Board / 2.4GHz + - [SLEXP8023A](https://www.silabs.com/development-tools/wireless/wi-fi/wfm200-wifi-expansion-kit) - Windows/Linux/MacOS computer with a USB port - USB cable for connecting WSTK Board to Computer diff --git a/docs/silabs/wifi/JLINK_GUIDE_917.md b/docs/silabs/wifi/JLINK_GUIDE_917.md new file mode 100644 index 00000000000000..f7dc6e1a262c72 --- /dev/null +++ b/docs/silabs/wifi/JLINK_GUIDE_917.md @@ -0,0 +1,20 @@ +# JLink RTT Environment Setup for a SiWx917 SoC Device + +- For 917 SOC Common Flash Boards, Ozone debugging support is not enabled. To get the logs for 917 SOC, the **JLink RTT** tool will be used. +- Auto detection of SiWx917 SoC device in **JLink RTT** is not enabled. +- Follow the steps to configure the SiWx917 SoC with Latest **JLink RTT Logging** tool. + +## Steps to Configure the SiWx917 SoC on the JLink-RTT Logging + +1. Update the **JlinkDevices.xml** and **.elf** files found on the [Matter Artifacts Page](../general/ARTIFACTS.md). + - Download the JLinkDevices.xml file and copy it in your **JLink RTT** installation path shown in this [JlinkDevices Folder](https://wiki.segger.com/J-Link_Device_Support_Kit#JLinkDevices_folder). If there is no JLinkDevices Folder, create a `JLinkDevices` folder and copy the `JlinkDevices.xml` file into it. + - In the `JLinkDevices` folder, create a `Devices` folder and then create a sub-folder named `SiliconLabs`. + - Download the **.elf** file (Flash driver) and copy it in the created `SiliconLabs` folder. + +2. Launch **JLink RTT**. The SiWx917 Common Flash SoC device should be visible in the Device field’s selection list. + + ![Search SOC](./images/search-soc-jlink.png) + +3. Select **SI917COMMONFLASH** and, click **OK**. + + ![Select SOC](./images/select-common-flash-soc.png) \ No newline at end of file diff --git a/docs/silabs/wifi/MATTER_SHELL.md b/docs/silabs/wifi/MATTER_SHELL.md index 1b18ea3f380f91..a8deb2b562e438 100644 --- a/docs/silabs/wifi/MATTER_SHELL.md +++ b/docs/silabs/wifi/MATTER_SHELL.md @@ -17,11 +17,17 @@ For WF200:- ./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/wf200_lock BRD41xxx chip_build_libshell=true --wifi wf200 For RS9116:- -./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/rs911x_lock BRD41xxx disable_lcd=true use_external_flash=false chip_build_libshell=true chip_enable_ble_rs911x=true --wifi rs9116 +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/rs911x_lock BRD41xxx disable_lcd=true use_external_flash=false chip_build_libshell=true --wifi rs9116 + +For SiWx917 NCP:- +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/siwx917_lock BRD41xxx disable_lcd=true use_external_flash=false chip_build_libshell=true --wifi SiWx917 + +For SiWx917 SoC:- +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/SiWx917_lock BRD4338A chip_build_libshell=true ``` 3. Connect Matter Device to the machine. - + 4. Flash the Builded binary to the board by following, [Flashing the Silabs Device](../general/FLASH_SILABS_DEVICE.md) document. 5. After successful flashing commission the device , refer [Commission Matter Platform](../wifi/RUN_DEMO.md#demo-execution---commissioning-a-wi-fi-device-using-chip-tool-for-linux) diff --git a/docs/silabs/wifi/RUN_DEMO.md b/docs/silabs/wifi/RUN_DEMO.md index d09653e746ee8d..100a7ad1e00775 100644 --- a/docs/silabs/wifi/RUN_DEMO.md +++ b/docs/silabs/wifi/RUN_DEMO.md @@ -43,17 +43,52 @@ To install above software tools , refer [Software Installation](../general/SOFTW ### Steps to update the firmware on NCP boards using Tera Term - SiWx917 NCP or RS9116 EVK connectivity firmware can be upgraded using tera-term or kermit. -1. Make sure that the switches on the expansion board are towards UART side. - ![Switch Position before firmware flash](./images/si917-board.png) +#### Firmware Upgrade On RS9116 -2. Refer [Updating the Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/update-evk-firmware) +1. Connect the EVK to PC using the USB interface labeled UART as identified below. -**Note**:Instructions are the same for both SiWx917 NCP and RS9116 EVK. + ![Switch Position before firmware flash](images/rs916-board.png) -3. Once firmware flashing is done make sure to make switches back to Expansion mode, while using it with the host platform. +2. If this is the first time connecting the EVK to your PC, verfy that it is properly detected by the PC. The EVK will appear to the PC as a COM port labeled USB Serial Port (COMx) - ![Switch Position after firmware flash](./images/mg21-si917-board.jpg) +3. Configure your terminal application with the following settings: + + - Configure the serial port settings to 115200 baud / 8-bit data / No parity / 1 stop bit + - Enable local echo + - Set receive and transmit new-line characters to CR+LF + +4. Refer to [Setup Tera Term and Updating the Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/tera-term-setup). + + ```shell + Instructions are the same for both SiWx917 NCP and RS9116 EVK. + ``` + +5. Once firmware flashing is done The console displays **Loading...** followed by **Loading Done**. + +#### Firmware Upgrade On SIWx917 NCP + +1. Connect USB-UART Cable to Machine and WPK board as well with SOC Mounted on it. + + ![Connect NCP Board](./images/ncp-board-connect.png) + +2. Connect USB-UART Cable 2(Yellow) to F9 and 3(Green) to F8 on WPK Board shown below. + + ![Connect Port Wires](./images/connect-board-port.png) + +3. Configure your terminal application with the following settings: + + - Configure the serial port settings to 115200 baud / 8-bit data / No parity / 1 stop bit + - Enable local echo + - Set receive and transmit new-line characters to CR+LF + +4. Refer to [Setup Tera Term and Updating the Firmware](https://docs.silabs.com/rs9116/wiseconnect/2.0/tera-term-setup). + + ```shell + Instructions are the same for both SiWx917 NCP and RS9116 EVK. + ``` + +5. Once firmware flashing is done The console displays **Loading...** followed by **Loading Done**. ### Troubleshoot NCP Firmware Update Failure If the firmware update fails, try the following: diff --git a/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md b/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md index 7a0074ba0fb86e..4ff821b122bdb8 100644 --- a/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md +++ b/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md @@ -1,35 +1,39 @@ # Getting Started with SoC Mode + This guide describes how to get started developing an application for the SiWx91x in System-on-chip (SoC) mode, where both the application and the networking stack run on the SiWx917 chipset. -## Hardware Requirements -The following hardware devices are required for executing Matter over Wi-Fi for SOC Mode: +## Check Prerequisites + +In order to run Matter over Wi-Fi, check for the following prerequisites: + +### Hardware Requirements + +The following hardware devices are required for executing Matter over Wi-Fi: - Refer, [Hardware Requirements](../general/HARDWARE_REQUIREMENTS.md#matter-over-wi-fi-accessory-device-requirements-for-soc-mode) - - Additional hardwares required for SOC Boards: - - Windows/Linux/MacOS computer with a USB port - - USB cable for connecting WSTK Board to Computer - - Raspberry Pi with a >32 GB SD Card - - Access Point with Internet Access - -## Software Requirements -Below are the software tools, packages and images required for executing Matter over Wi-Fi for SOC Mode: - -### Software Tools Requirements - - Simplicity Commander for flashing firmware and binary on SOC Boards - - Putty for controlling SOC hardware using chip-tool controller - - Ozone Debugger for logging and debugging (Optional) - - JLink RTT for logging only (Optional) -To install above software tools , refer [Software Installation](../general/SOFTWARE_REQUIREMENTS.md) - -## Connect the Boards to a Computer +- Silicon Labs Wireless starter/development kit (WSTK) +- SiWx917 SoC development kit +- Wi-Fi Dev Kit + - SiWx917 + - SoC mode: + - BRD4388A (B0 2.0 common flash) + SiWx917 +- Windows/Linux/MacOS computer with a USB port +- USB cable for connecting WSTK Board to Computer +- Raspberry Pi with a >32 GB SD Card +- Access Point with Internet Access + +### Software Requirements + +Refer to [Software Requirements & Installation ](../general/SOFTWARE_REQUIREMENTS.md) + +## Connect SiWx917 SOC to Computer + 1. Mount the SiWx917 radio board on the SiWx917 WSTK board. ![Silicon Labs - design](./images/mount-soc.png) 2. Connect your SiWx917 Wireless Starter Kit (WSTK) board to your computer using a USB cable. -## Updating SiWx917 SoC Connectivity Firmware -- Download the recommended version of firmware before you start with the update process from the [Matter Artifacts page](../general/ARTIFACTS.md#siwx917-firmware-for-siwx917-soc) - ### Steps to update the firmware on SiWx917 SoC radio board using Simplicity Commander 1. Open Simplicity Commander application. @@ -74,18 +78,15 @@ If the firmware update fails, try the following: 1. SiWx917 SoC device support is available in the latest Simplicity Commander(version 1v15p3). To flash the TA Firmware/Matter application on SiWx917 SoC, - Convert the .s37 file into .rps file using the below command, - commander rps create .rps --app .s37 - Flash to the device using, - commander rps load .rps - -2. Official support for SiWx917 SoC for Common Flash Board is not yet available in the Ozone Debugger, but can be configured for dual flash board - [Ozone Environment Setup for SiWx917 SoC](SiWx917_Enablement_For_Ozone.md). + commander rps load .rps + +2. Official support for SiWx917 SoC for Common Flash Board is not yet available in the Ozone Debugger, but can be configured - [Ozone Environment Setup for SiWx917 SoC](SiWx917_Enablement_For_Ozone.md). -3. 917 SoC switch positions for Dual Flash Boards: Left switch should be on the **OFF/LOW**, and right switch should be on the **NORMAL** side. - -4. After creating rps file flash the binary to board by using Simplicity Commander, refer [Flashing SiWx917 SOC Using Simplicity Commander](../general/FLASHING_USING_COMMANDER.md#flashing-the-siwx917-soc-matter-pre-built-binary-using-simplicity-commander) +3. After creating the rps file flash the binary to the board by using Simplicity Commander, refer [Flashing SiWx917 SOC Using Simplicity Commander](../general/FLASHING_USING_COMMANDER.md#flashing-the-siwx917-soc-matter-pre-built-binary-using-simplicity-commander) -5. Flashing the Matter application using Ozone Debugger +4. Flashing the Matter application using Ozone Debugger - Download the Pre-built images for SiWx917 SoC Matter Application (.out file) from [Matter Artifacts page](../general/ARTIFACTS.md) - Refer [Flashing MATTER Application Using Ozone debugger](./SiWx917_Enablement_For_Ozone.md) diff --git a/docs/silabs/wifi/SW_SETUP.md b/docs/silabs/wifi/SW_SETUP.md index 5e451d4e0b9531..a58a08f4ec73ee 100644 --- a/docs/silabs/wifi/SW_SETUP.md +++ b/docs/silabs/wifi/SW_SETUP.md @@ -5,7 +5,7 @@ If you have not downloaded or cloned this repository, you can run the following commands on a Linux terminal running on either Linux machine, WSL or Virtual Machine to clone the repository and run bootstrap to prepare to build the sample -application images. +application images. Users may need to run the various commands as the root user or with certain privilges enabled. 1. To download the [SiliconLabs Matter codebase](https://github.com/SiliconLabs/matter.git) run @@ -47,9 +47,6 @@ Matter Accessory Device images from scratch, you can download the MAD images for Wi-Fi from this software release on the [Matter Artifacts Page](../general/ARTIFACTS.md) -> **Note:** A pre-built image is not available for SiWx917 in SoC mode. It must be built from scratch in this release. -> Pre-built images will be provided in the next release. - Once you have downloaded the image you require for your device, you can skip forward to the instructions for running the demo. @@ -104,22 +101,15 @@ Build command for EFR32MG24 + WF200: $ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/wf200_lighting BRD41xxx chip_build_libshell=false --wifi wf200 |& tee out/wf200_lighting.log ``` -Build command for SiWx917 SoC processor(dual flash): - -```shell -./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/SiWx917_lighting BRD4325B |& tee out/soc_lighting.out -``` - Build command for SiWx917 SoC processor(common flash): ```shell -./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/SiWx917_lighting BRD4325x is_debug=false |& tee out/soc_lighting.out +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/SiWx917_lighting BRD4338A |& tee out/soc_lighting.out ``` > **Note:** > 1. LED and button features are enabled for SiWx917 SoC. -> 2. LCD and QR code features are not enabled for SiWx917 SoC. -> 3. Before building for SiWx917 SoC, you must first obtain the WiseMCU Combo SDK package and install it. See the [Software Requirements page](../general/SOFTWARE_REQUIREMENTS.md). +> 2. Before building for SiWx917 SoC, you must first obtain the WiseMCU Combo SDK package and install it. See the [Software Requirements page](../general/SOFTWARE_REQUIREMENTS.md). A complete list of hardware supported is included on the [Hardware Requirements page](../general/HARDWARE_REQUIREMENTS.md). @@ -163,3 +153,10 @@ Navigate to `examples/platform/silabs/efr32/FreeRTOSConfig.h`. Find the macro: \``configMINIMAL_STACK_SIZE`\`, and change the macro value from `140` to **`320`**. + + ### Troubleshooting + +If having issues building the above examples, users may need to run the following commands: + + git submodule update --init --checkout + pip install --upgrade prompt-toolkit diff --git a/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md b/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md index e8d3d2518ea930..af4c94b10b362e 100644 --- a/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md +++ b/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md @@ -1,9 +1,9 @@ -# Matter Intermittently Connected Devices (ICD) (Formerly Sleepy End Devices) +# Matter Intermittently Connected Devices over WiFi This page explains how Matter Wi-Fi Intermittently Connected Devices (ICDs) work and how to configure a Matter Wi-Fi ICD example. ## Overview -Matter provides an Intermittently Connected Device (ICD) operating mode to extend the battery life of a power-limited devices. This operating mode leverages native Wi-Fi functionality to enhance the power management features provided within the Matter protocol. +Matter provides the Intermittently Connected Device (ICD) operating mode to extend the battery life of power-limited devices. This operating mode leverages native Wi-Fi functionality to enhance the power management features provided within the Matter protocol. Wi-Fi module power saving is achieved by the Wi-Fi Station notifying the Access Point (AP) that it is entering its power save (PS) mode. Afterwards, the Wi-Fi station will shut down its RF and Wi-Fi SoC blocks to enter power saving mode. @@ -11,15 +11,16 @@ The Access Point (AP) buffers the frames destined to a Wi-Fi station while it is During association, the Wi-Fi Station uses the Delivery Traffic Information Map (DTIM) parameter to get from the Access Point (AP) how many beacon intervals it shall spend in sleep mode before it needs to retrieve the queued frames from the Access Point (AP). -Wi-Fi module sleep is implemented by using the PS-Poll Legacy Power Save (DTIM based) method. EFR sleep is implemented by using the power manager component (EM2). +Wi-Fi module sleep is implemented by using the PS-Poll Legacy Power Save (DTIM based) method. EFR sleep is implemented by using the power manager (EM2). -> **Note**: Wi-Fi module sleep is enabled after successful commissioning and EFR sleep is enabled after system bootup. +**Note**: Wi-Fi module sleep is enabled after successful commissioning and EFR sleep is enabled after system bootup. -> **Note**: Wi-Fi is implemented with DTIM-based sleep, since the operational discovery packet is a broadcast packet that will not be buffered by the Wi-Fi router. +**Note**: Wi-Fi is implemented with DTIM-based sleep, since the operational discovery packet is a broadcast packet that will not be buffered by the Wi-Fi router. ## Power Save Methods ### Deep Sleep Power Save Mode for EFR32 + The EFR32 will go into deep sleep (EM2) power save mode by using the power manager module. The power manager is used to transition the system to a power mode when the application is the Idle Task. In EM2 energy mode, all high frequency clock sources are shut down. Peripherals that require a high frequency clock are unavailable or have limited functionality. @@ -27,7 +28,7 @@ In EM2 energy mode, all high frequency clock sources are shut down. Peripherals ### PS-Poll Legacy Power Save for Wi-Fi Module The PS-Poll Legacy power save mode leverages the PS-Poll frame to retrieve the buffered frames from the Access Point (AP). The PS-Poll frame is a short Control Frame containing the Association Identifier (AID) value of the Wi-Fi station. -In the Legacy power save mode, when the Wi-Fi station receives a beacon with its Association Identifier (AID) in the TIM element, it initiates the buffered frame delivery by transmitting a PS-POLL control frame to the Access Point (AP). +In the Legacy power save mode, when the Wi-Fi station receives a beacon with its Association Identifier (AID) in the TIM element, it initiates the buffered frame delivery by transmitting a PS-POLL control frame to the Access Point (AP). The AP acknowledges the PS-Poll frame and responds with a single buffered frame. In this mode, the Wi-Fi station stays active and retrieves a single buffered frame at a time. The AP also indicates that there are more buffered frames for the station using the More Data subfield. @@ -44,9 +45,9 @@ A Wi-Fi station in DTIM Power Save mode can wake at any time to transmit uplink In order to inform the Wi-Fi station in Power Save mode that the access point has buffered downlink traffic, the access point uses the Traffic Indication Map element present in the beacon frames. The Wi-Fi station in Power Save mode wakes up to receive the DTIM beacon and checks the status of the TIM element. This element indicates whether any frames need to be retrieved from the Access Point (AP). -> **Note**: The DTIM parameter can be configured on the access point settings. +**Note**: The DTIM parameter can be configured on the access point settings. -## Building +## Building with ICD Functionality ### Enabling ICD Functionalities @@ -65,8 +66,10 @@ Here is an example to build the lock-app as an ICD for the EFR32MG24 + WF200. ```bash ./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/wf200_lock_sleep BRD41xxx chip_enable_icd_server=true chip_build_libshell=false --wifi wf200 ``` - -> **Note**: The power save feature is not enabled for the RS917 SoC. +Here is an example to build the lock-app as an ICD for the SiWx917 SoC +```bash +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/SiWx917_lock_sleep BRD4338A chip_enable_icd_server=true +``` ### Minimal Power Consumption @@ -80,5 +83,9 @@ The following set of features increase power consumption. To achieve the most power-efficient build, add these build arguments to the build command to disable all power-consuming features. ```bash -./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/SiWx917/lock_sleep BRD41xxx chip_enable_icd_server=true disable_lcd=true show_qr_code=false use_external_flash=false chip_build_libshell=false chip_enable_ble_rs911x=true --wifi SiWx917 -`````` \ No newline at end of file +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/SiWx917/lock_sleep BRD4338A chip_enable_icd_server=true --low_power +``` + +# Power Measurement + +Refer to [ Power Measurement ](./WIFI_Sleepy_Device_Power_Measurement.md) \ No newline at end of file diff --git a/docs/silabs/wifi/images/connect-board-port.png b/docs/silabs/wifi/images/connect-board-port.png new file mode 100644 index 00000000000000..bdd19080f40a9f Binary files /dev/null and b/docs/silabs/wifi/images/connect-board-port.png differ diff --git a/docs/silabs/wifi/images/mg21-si917-board.jpg b/docs/silabs/wifi/images/mg21-si917-board.jpg deleted file mode 100644 index c5967b6db05ac8..00000000000000 Binary files a/docs/silabs/wifi/images/mg21-si917-board.jpg and /dev/null differ diff --git a/docs/silabs/wifi/images/ncp-board-connect.png b/docs/silabs/wifi/images/ncp-board-connect.png new file mode 100644 index 00000000000000..1e69c42b09070a Binary files /dev/null and b/docs/silabs/wifi/images/ncp-board-connect.png differ diff --git a/docs/silabs/wifi/images/rs916-board.png b/docs/silabs/wifi/images/rs916-board.png new file mode 100644 index 00000000000000..39b7ecf3d9a68a Binary files /dev/null and b/docs/silabs/wifi/images/rs916-board.png differ diff --git a/docs/silabs/wifi/images/search-soc-jlink.png b/docs/silabs/wifi/images/search-soc-jlink.png new file mode 100644 index 00000000000000..d370bed11e864b Binary files /dev/null and b/docs/silabs/wifi/images/search-soc-jlink.png differ diff --git a/docs/silabs/wifi/images/select-common-flash-soc.png b/docs/silabs/wifi/images/select-common-flash-soc.png new file mode 100644 index 00000000000000..4aaa648214f793 Binary files /dev/null and b/docs/silabs/wifi/images/select-common-flash-soc.png differ diff --git a/docs/silabs/wifi/images/si917-board.png b/docs/silabs/wifi/images/si917-board.png deleted file mode 100644 index db7520843617c4..00000000000000 Binary files a/docs/silabs/wifi/images/si917-board.png and /dev/null differ