diff --git a/sld388-matter-new-features/index.md b/sld388-matter-new-features/index.md index b94970e..4ff0cf2 100644 --- a/sld388-matter-new-features/index.md +++ b/sld388-matter-new-features/index.md @@ -1,5 +1,9 @@ # New Features +## New Features for v2.9.0-1.6 + +- Matter + AWS dual-stack support for 917 NCP boards. + ## New Features for v2.8.1-1.5 - PSRAM board support in Matter now uses WiseConnect components. To place specific code/data in PSRAM, enable the corresponding WiseConnect component for the section or region you want to relocate. diff --git a/sld962-matter-aws-feature/aws-configuration-registration.md b/sld962-matter-aws-feature/aws-configuration-registration.md index 7d276af..6144de1 100644 --- a/sld962-matter-aws-feature/aws-configuration-registration.md +++ b/sld962-matter-aws-feature/aws-configuration-registration.md @@ -32,24 +32,39 @@ AWS IoT Core provides secure, bi-directional communication for Internet-connecte 7. Complete the following steps to create a thing and generate certificates for your Matter application to use in the `MatterAwsNvmCert.cpp` source file: - - Go to **All Devices > Things** and select **Create Things**. + - Go to **All Devices > Things** and select **Create Things**. ![Create Thing](./images/device-create-things.png) - - Select **Create Single Thing** and click **Next**. - - Under **Specific thing properties > Thing properties**, specify the thing name (this will be the `MATTER_AWS_CLIENT_ID` in `MatterAwsConfig.h`), then click **Next**. + - Select **Create Single Thing** and click **Next**. + - Under **Specific thing properties > Thing properties**, specify the thing name (this will be the `MATTER_AWS_CLIENT_ID` in `MatterAwsConfig.h`), then click **Next**. ![Add Thing Name](./images/aws-add-thing-name.png) - - Under **Configure device certificate > Device Certificate**, select **Upload CSR**. - - In **Certificate signing request > Choose file** (Choose Client CSR generated by Openssl Certificate Creation in Step 6. e.g., `device.csr`). Click **Next**. + - Under **Configure device certificate** > **Device Certificate**. + + - For 917 NCP Dual Stack: + - Select **Auto-generate a new certificate**. + ![Auto-generate a new certificate](./images/thing-auto-gen-aws-certs.png) + - Download the Amazon Root CA1. + - Download the Public and Private keys. + - Skip **Certificate signing request** step for 917 NCP Dual Stack. + + - For 917 NCP and 917 SoC: + - Select **Upload CSR**. + - Under**Certificate signing request**, click **Choose File**. (Choose Client CSR generated by Openssl Certificate Creation in Step 6. e.g., `device.csr`). + - Click **Next**. ![Upload CSR](./images/thing-upload-csr.png) - - Select the policy (e.g., `MATTER_AWS_POLICY`) created at Step 4. + + - Select the policy (e.g., `MATTER_AWS_POLICY`) created at Step 4. ![Attach Policy](./images/thing-attach-policy.png) - - Once the thing is successfully created, click **View certificate**. + - Once the thing is successfully created, click **View certificate**. ![View Certificate](./images/thing-view-certificate.png) - - Next: - - Activate the certificate. - - Download the certificate. + - Next: + - Activate the certificate. + - Download the certificate. ![Activate and Download Certificate](./images/thing-activate-download-certificate.png) -8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA3.pem) (We are using Amazon Root CA3) and add it as CA certificate in `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp`. +8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA3.pem) and add it as CA certificate in `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp`. + +> **Note**: In this example, Amazon Root CA3 is used for 917 NCP and 917 Soc, and Amazon Root CA1 is used for 917 Dual Stack. + All the certificate should be added in below format: ```cpp diff --git a/sld962-matter-aws-feature/build-matter-aws-dual-stack.md b/sld962-matter-aws-feature/build-matter-aws-dual-stack.md new file mode 100644 index 0000000..92f8984 --- /dev/null +++ b/sld962-matter-aws-feature/build-matter-aws-dual-stack.md @@ -0,0 +1,110 @@ +# Build Procedure for Matter + AWS Dual Stack + +This procedure details how to enable the dual-stack flavor of Matter + AWS in a 917 NCP project. This configuration uses IPv6 on the EFR32 host for Matter and IPv4 on the SiWx917 NWP for AWS cloud connectivity. + +For an architectural overview and flavor comparison, see [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md). + +For the standard Matter + AWS build (917 SoC or standard 917 NCP with host LwIP transport), see [Build Procedure for Matter + AWS](./build-matter-aws.md). + +> **Note:** Dual-stack Matter + AWS is currently supported on 917 NCP boards only (BRD4186C, BRD4187C, BRD4120A). + +## Prerequisites + +- A **917 NCP** Matter project or the reference example `matter_wifi_917_ncp_lock_app_dual_stack_freertos`. +- Matter Extension **2.9.0** or later, and WiseConnect SDK **4.1.0** or later installed in Simplicity Studio. +- AWS cloud configured according to [AWS installation](./aws-configuration-registration.md). +- Hardware and software requirements are met as described in [Matter + AWS Prerequisites](./index.md#prerequisites). + +## Add the AWS Server, Client ID, and Certificate Details + +AWS server, client ID, and Certificates are the same as the standard Matter + AWS flavor. Perform the steps in [Adding the AWS Server, Client ID, and Cluster Details](./build-matter-aws.md#adding-the-aws-server-client-id-and-cluster-details) in the standard build guide and refresh the Matter extension in Simplicity Studio. + +## Get started + +In Simplicity Studio, from the reference example, create a project using `matter_wifi_917_ncp_lock_app_dual_stack_freertos` (917 NCP Lock Dual Stack). + +## Add Dual-Stack Matter + AWS Components + +Configure the project using the Simplicity Studio Project Configurator. Following steps specifically describe about dual-stack, which is different from the [standard Matter + AWS build procedure](./build-matter-aws.md#adding-the-matter--aws-component). + + +### 1. Install Matter AWS with NWP Transport + +1. In the **Software Components** section, enter `aws` in the search box, and then click the search icon. + Search result displays the "AWS for Matter Wi-Fi" component. +2. Select the **AWS for Matter Wi-Fi** component (`matter_aws`) and then click on install. + +3. When prompted for the AWS transport dependency, select **Matter AWS NWP Transport (Si91x)** (`matter_aws_transport_nwp`). Do **not** select Matter AWS LwIP Transport.![Matter AWS NWP Transport Component](images/matter-aws-dependency-3.png) + +4. Select the dependencies for the Matter AWS component as shown in the images. The order of the dependencies can vary, in each case select the option with "+ AWS". + +![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) + +![X.509 Create certificates for Matter + AWS](images/matter-aws-dependency-5.png) + +![X.509 Use certificates for Matter + AWS](images/matter-aws-dependency-4.png) + +### 2. Install TLS 1.2 PRF (917 NCP Requirement) + +In **Software Components**, search for `TLS 1.2 PRF` and install the **TLS 1.2 PRF** component (`psa_crypto_tls12_prf`). + +This step is required for all 917 NCP Matter + AWS builds, including dual-stack. + +![TLS 1.2 PRF Component](images/tls-prf-component-install.png) + +## Build and Flash the Application + +1. Build the dual-stack Matter + AWS application in Simplicity Studio. + For 917 NCP flash and boot procedures, refer to the [917 NCP getting started documentation](/matter/{build-docspace-version}/matter-wifi-getting-started-example/getting-started-siwx917-rcp). +2. Flash the EFR32 host application and the SiWx917 NCP connectivity firmware as required for your board. + +## Verify the Build + +1. Confirm AWS connectivity from the device logs. + The `[MATTER_AWS]` messages displayed after device bootup: + ```console + [00:00:23.400][info ][SVR] [MATTER_AWS] connection callback started + [00:00:23.690][info ][SVR] [MATTER_AWS] MQTT connection status: 0 + [00:00:23.995][info ][SVR] [MATTER_AWS] MQTT sub request callback: 0 + ``` + +2. After subscribing to a topic in AWS IoT, publish logs appears in the device console and in the AWS IoT console. + +![Device Logs AWS](./images/aws-device-logs-thermostat-app.png) + +![AWS IoT App Data](./images/matter-aws-iot-app-data.png) + +3. Commission the device over **EFR32 BLE** and verify Matter control with chip-tool. +4. For end-to-end Matter and cloud testing steps, refer to [End-to-End Test of Matter + AWS Application](./index.md#end-to-end-test-of-matter--aws-application) and [Running the Matter Demo Over Wi-Fi](/matter/{build-docspace-version}/matter-wifi-run-demo). + +## Compile Using New Thing for Different Certificates + +Do not use the same client ID for multiple devices. + +To use AWS, update the following information: + +1. Add your AWS certificates in the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp` file. + - Provide the AWS Root CA key (https://www.amazontrust.com/repository/AmazonRootCA1.pem). + - Provide `device_certificate` and `device_key` with your device certificate and device key. For more details, refer to [OpenSSL Device Certificate Creation](./openssl-certificate-creation.md). + +2. Add your AWS server and client ID information to the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsConfig.h` file. + + - Provide `MATTER_AWS_SERVER_HOST` with your AWS Server name. + - Provide `MATTER_AWS_CLIENT_ID` with your device/thing ID. + +> **Note:** +> - The supported certificate type for the 917 NCP matter dual stack is RSA keys. +> - AWS Root CA used for the 917 NCP matter dual stack https://www.amazontrust.com/repository/AmazonRootCA1.pem + +## Troubleshooting + +- **Matter commissioning or IPv6 connectivity issues** + Ensure that `SLI_SI91X_ENABLE_IPV6=1` is defined and your network supports IPv6 SLAAC. See the IPv6 troubleshooting section in [Matter Wi-Fi FAQ](/matter/{build-docspace-version}/matter-faq/wifi-faq). + +- **AWS MQTT connection failures** + Ensure that IPv4 is enabled on the Matter Wi-Fi component, and AWS server details and credentials in `MatterAwsConfig.h` and `MatterAwsNvmCert.cpp` are correct. + +- **Build errors about conflicting transport** + Remove `matter_aws_transport_lwip` if exists; only one AWS transport component can be installed. + +For architectural context and supported board list, see [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md). diff --git a/sld962-matter-aws-feature/build-matter-aws.md b/sld962-matter-aws-feature/build-matter-aws.md index b03ce57..c78835c 100644 --- a/sld962-matter-aws-feature/build-matter-aws.md +++ b/sld962-matter-aws-feature/build-matter-aws.md @@ -13,20 +13,17 @@ Follow the steps below to set the AWS configuration in the Matter SDK. - Update the AWS server name at `#define MATTER_AWS_SERVER_HOST ""`. - Update the client ID at `#define MATTER_AWS_CLIENT_ID ""`. - - Update the cluster server information as shown in the table below, based on your app: - - | Application Type | Cluster Definition | - |------------------|--------------------| - | Thermostat | `#define ZCL_USING_THERMOSTAT_CLUSTER_SERVER` | - | Lighting | `#define ZCL_USING_ON_OFF_CLUSTER_SERVER` | - | Lock | `#define ZCL_USING_DOOR_LOCK_CLUSTER_SERVER` | - | Window Covering | `#define ZCL_USING_WINDOW_COVERING_CLUSTER_SERVER` | **MatterAwsConfig.h File:** ![MatterAwsConfig.h File](./images/matter-aws-config.png) -4. After making the above changes, refresh the `matter-extension` in Simplicity Studio. +4. Add your AWS certificates in the `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.cpp` file. + + - Provide the AWS Root CA key. + - Provide `device_certificate` and `device_key` with your device certificate and device key. For key generation details, refer to [AWS Thing Certificate Creation](./aws-configuration-registration.md). + +5. After making the above changes, refresh the `matter-extension` in Simplicity Studio. - In the **Home** tab, from the left panel, select **Settings**. ![Select Settings](images/aws-build-settings.jpg) - Click **SDKs**, ensure the correct version of the SDK is selected, and then click **Refresh** in the right side menu. @@ -51,10 +48,15 @@ To enable the component in Simplicity Studio, add the following components. 3. Next, select the dependencies for the Matter AWS component. > Note: The order can vary, but in every case select the option with "+ AWS". + When prompted for the AWS transport dependency, select **Matter AWS LWIP Transport** (`matter_aws_transport_lwip`). Do **not** select Matter AWS NWP Transport. + +![Matter AWS NWP Transport Component](images/matter-aws-dependency-2.png) + +![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) - ![Default Entropy Source for Matter + AWS](images/matter-aws-dependency-1.png) +![X.509 Create certificates for Matter + AWS](images/matter-aws-dependency-5.png) - ![Public-Key Abstaction Layer for Matter + AWS](images/matter-aws-dependency-2.png) +![X.509 Use certificates for Matter + AWS](images/matter-aws-dependency-4.png) ### Additional Step Needed Only For 917 NCP @@ -100,4 +102,3 @@ Two devices should not use the same client ID. Use a different client ID for you - Provide `MATTER_AWS_SERVER_HOST` with your AWS Server name. - Provide `MATTER_AWS_CLIENT_ID` with your device/thing ID. - - Update `ZCL_USING_ON_OFF_CLUSTER_SERVER` with the cluster server details based on your app. diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-2.png b/sld962-matter-aws-feature/images/matter-aws-dependency-2.png index 001ec76..d353eab 100644 Binary files a/sld962-matter-aws-feature/images/matter-aws-dependency-2.png and b/sld962-matter-aws-feature/images/matter-aws-dependency-2.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-3.png b/sld962-matter-aws-feature/images/matter-aws-dependency-3.png new file mode 100644 index 0000000..28bbebf Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-3.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-4.png b/sld962-matter-aws-feature/images/matter-aws-dependency-4.png new file mode 100644 index 0000000..fb5c5f5 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-4.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dependency-5.png b/sld962-matter-aws-feature/images/matter-aws-dependency-5.png new file mode 100644 index 0000000..e4c7048 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dependency-5.png differ diff --git a/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png b/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png new file mode 100644 index 0000000..a89c556 Binary files /dev/null and b/sld962-matter-aws-feature/images/matter-aws-dual-stack-architecture.png differ diff --git a/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png b/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png new file mode 100644 index 0000000..f59c884 Binary files /dev/null and b/sld962-matter-aws-feature/images/thing-auto-gen-aws-certs.png differ diff --git a/sld962-matter-aws-feature/index.md b/sld962-matter-aws-feature/index.md index c313ddc..6de5b16 100644 --- a/sld962-matter-aws-feature/index.md +++ b/sld962-matter-aws-feature/index.md @@ -9,6 +9,13 @@ - Remote users can install a cloud-specific application to receive notifications about the attribute status. +## Matter + AWS Flavors + +Matter + AWS is available in two build flavors: + +- **Standard flavor** — For **917 SoC** and **standard 917 NCP** boards. Uses the host LwIP stack for both Matter (IPv6) and AWS (IPv4) with `matter_lwip` and `matter_aws_transport_lwip`. See [Build Procedure for Matter + AWS](./build-matter-aws.md). +- **Dual-stack flavor (917 NCP)** — For **917 NCP** boards only. Uses a split-stack architecture: Matter over **IPv6** on the EFR32 host LwIP stack and AWS over **IPv4** on the SiWx917 NWP offload stack with `matter_dual_stack` and `matter_aws_transport_nwp`. See [Matter + AWS Dual Stack Overview](./matter-aws-dual-stack-overview.md) and [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md). + ## Matter + AWS Feature Diagram The following diagram shows end-to-end flow for Direct Internet Connectivity. @@ -24,7 +31,7 @@ official [Silicon Labs Matter hardware requirements](/matter/{build-docspace-version}/matter-prerequisites/hardware-requirements) documentation. -> **Note:** This is supported for 917 SoC and NCP boards only. +> **Note:** The standard flavor is supported for 917 SoC and NCP boards. The dual-stack flavor is supported for **917 NCP boards only** (EFR32 host + BRD4346A). ### Software Requirements @@ -55,7 +62,9 @@ Remote users are used to check the state of Matter devices. In this context, MQT ### Building Matter + AWS Application using Simplicity Studio -Follow the instructions in [Build Procedure for Matter + AWS](./build-matter-aws.md) to enable the MATTER + AWS feature in your application code. +Follow the steps in [Build Procedure for Matter + AWS](./build-matter-aws.md) to enable the Matter + AWS feature for the **standard flavor** (917 SoC and standard 917 NCP). + +For the **dual-stack flavor** on 917 NCP boards, follow [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md). ## End-to-End Test of Matter + AWS Application diff --git a/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md b/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md new file mode 100644 index 0000000..9ffb02d --- /dev/null +++ b/sld962-matter-aws-feature/matter-aws-dual-stack-overview.md @@ -0,0 +1,99 @@ +# Matter + AWS Dual Stack Overview + +The dual-stack flavor of Matter + AWS is a Silicon Labs–specific configuration for 917 NCP (Network Co-Processor) designs. It enables Matter devices to connect locally to the Matter fabric over IPv6 through the EFR32 host and to AWS over IPv4 through the SiWx917 network wireless processor (NWP). + +> **Note:** Dual-stack here is not classic single-stack IPv4+IPv6 on one TCP/IP stack. It is a split-stack NCP architecture with separate network stacks on the host and the NWP. + +## When to Use the Dual-Stack Flavor + +Use the dual-stack flavor when all of the following apply: + +- Your design uses a 917 NCP board (EFR32 host + SiWx917 co-processor over SPI). +- You need Matter + AWS (Direct Internet Connectivity) on that NCP platform. +- Matter traffic must remain on IPv6 on the EFR32 host LwIP stack. +- AWS MQTT/TLS traffic must run over IPv4 on the SiWx917 NWP offload stack. + +For **917 SoC** or **standard 917 NCP** builds that use a single host LwIP stack for both Matter and AWS, use the [standard Matter + AWS build procedure](./build-matter-aws.md) instead. + +## Dual-Stack Architecture + +The following diagram shows how traffic is divided between the EFR32 host and the SiWx917 NWP. + +![Matter + AWS dual-stack architecture](./images/matter-aws-dual-stack-architecture.png) + +| Traffic path | Processor | Network stack | Protocol | +|--------------|-----------|---------------|----------| +| Matter fabric, mDNS, CASE | EFR32 host | Host LwIP | IPv6 | +| Wi-Fi radio association | SiWx917 NWP | Offload stack | — | +| AWS MQTT/TLS | SiWx917 NWP | `sl_si91x_socket` (NWP offload) | IPv4 | + +The EFR32 host and SiWx917 NWP communicate over the SPI NCP interface. The **Matter Dual Stack** component (`matter_dual_stack`) replaces the standard **Matter LwIP** component (`matter_lwip`) and defines the build macro `SL_MATTER_ENABLE_DUAL_STACK=1`. + +## Flavor Comparison + +| Setting | 917 SoC Matter + AWS | Standard 917 NCP Matter + AWS | 917 NCP Dual-Stack Matter + AWS | +|---------|----------------------|-------------------------------|----------------------------------| +| Network provider | `matter_lwip` | `matter_lwip` | **`matter_dual_stack`** | +| AWS transport | `matter_aws_transport_lwip` | `matter_aws_transport_lwip` | **`matter_aws_transport_nwp`** | +| MQTT/TLS path | Host LwIP altcp | Host LwIP altcp | NWP `sl_si91x_socket` | +| Matter protocol | IPv6 (host LwIP) | IPv6 (host LwIP) | IPv6 (host LwIP) | +| AWS/cloud protocol | IPv4 (host LwIP) | IPv4 (host LwIP) | IPv4 (NWP offload) | +| BLE for commissioning | SoC BLE | `matter_wifi_ble` (917) | **`matter_ble`** (EFR32 host) | +| IPv6 project define | via `matter_lwip` | via `matter_lwip` | **`SLI_SI91X_ENABLE_IPV6=1`** | +| Dual-stack build macro | — | — | **`SL_MATTER_ENABLE_DUAL_STACK=1`** | + +The AWS transport components **`matter_aws_transport_lwip`** and **`matter_aws_transport_nwp`** are mutually exclusive. Install exactly one transport with the **Matter AWS** component. + +## Component and Macro Checklist + +When building a dual-stack Matter + AWS application, verify the following: + +| Item | Dual-stack value | +|------|------------------| +| Network stack provider | `matter_dual_stack` (not `matter_lwip`) | +| AWS transport | `matter_aws_transport_nwp` (not `matter_aws_transport_lwip`) | +| BLE component | `matter_ble` (not `matter_wifi_ble`) | +| Matter Wi-Fi IPv4 setting | Enable `CHIP_DEVICE_CONFIG_ENABLE_IPV4` | +| Project define | `SLI_SI91X_ENABLE_IPV6=1` | +| Build macro (automatic) | `SL_MATTER_ENABLE_DUAL_STACK=1` (set by `matter_dual_stack`) | +| AWS dependencies | `mbedtls_x509_use_aws`, `mbedtls_x509_create_aws`, `mbedtls_entropy_default_aws` | +| 917 NCP TLS | `psa_crypto_tls12_prf` (TLS 1.2 PRF) | + +## Supported Hardware and Software + +### Hardware + +Dual-stack Matter + AWS is supported on **917 NCP Radio boards only(BRD4346A)**: + +- BRD4186C +- BRD4187C +- BRD4120A + +Standard Matter + AWS on 917 SoC and standard 917 NCP boards is documented separately. See [Prerequisites](./index.md#prerequisites) on the Matter + AWS index page. + +### Software + +- Matter Extension **2.9.0** or later +- WiseConnect SDK **4.1.0** or later +- Correct SiWx917 NCP connectivity firmware supporting dual network stack mode + +## Reference Example + +The Matter Extension provides a reference door lock application for dual-stack builds: + +- **Project:** `matter_wifi_917_ncp_lock_app_dual_stack_freertos` +- **Description:** Matter over Wi-Fi door lock with BLE on the EFR32 host (IPv6 on EFR32, IPv4 on SiWx917) + +This is currently the only Matter example project configured for the dual-stack flavor. + +## Limitations + +- **917 NCP only** — not supported on 917 SoC or standard single-stack 917 NCP AWS builds. +- **Single reference app** — only the lock app example is provided for dual-stack today. +- **Transport exclusivity** — do not install both `matter_aws_transport_lwip` and `matter_aws_transport_nwp` in the same project. + +## Next Steps + +- [Build Procedure for Matter + AWS Dual Stack](./build-matter-aws-dual-stack.md): For component installation and project configuration. +- [Build Procedure for Matter + AWS (standard flavor)](./build-matter-aws.md): For 917 SoC and standard 917 NCP. +- [Matter + AWS index](./index.md): For AWS cloud setup, end-to-end testing, and shared configuration.