MATTER AWS Documentation

sld297-matter-aws-feature/aws-configuration-registration.md

@@ -0,0 +1,43 @@
+# Amazon Web Services (AWS)
+
+Amazon Web Services offers reliable, scalable, and inexpensive cloud computing services. Refer to [AWS Documentation](https://aws.amazon.com/what-is-aws/) for more details.
+
+## AWS CA Certificate Registration
+
+1. Open [AWS](https://aws.amazon.com/).
+2. Log in using your AWS credentials.
+
+3. Go to **Security > Policies** and select **Create Policy**. Enter the policy name (e.g., `MATTER_AWS_POLICY_`). In the policy statements, select **JSON** and replace the contents with the JSON provided below:
+
+    ```shell
+     {
+       "Version": "2012-10-17",
+       "Statement": [
+        {
+          "Effect": "Allow",
+          "Action": "*",
+          "Resource": "*"
+        }
+      ]
+     }
+    ```
+
+4. Once done, select **Create**.
+
+5. Create a client CSR certificate and a client key by following the steps in the [OpenSSL Certificate Creation](./openssl-certificate-creation.md) documentation.
+
+6. 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**.
+    - Select **Create Single Thing** and click **Next**.
+    - Under **Info > Give the thing a name**, specify the thing name (this will be the client ID), then click **Next**.
+    - (Optional) Configure the device certificate under  **Info > Upload CSR**.
+    - In **Certificate > Choose file** (Choose Client CSR generated in Openssl Certificate Creation ex: `device.csr`). Click **Next**. 
+    - Use the policy (e.g., `MATTER_AWS_POLICY_`) created in AWS Certificate creation.
+    - Once the thing is successfully created, activate and download the certificate.
+
+8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA3.pem) and add it as CA certificate in `MatterAwsNvmCert.cpp`. 
+
+9. Repeat Step 5 to create a new thing for use in MQTT Explorer, using the certificate generated for MQTT Explorer during OpenSLL certificate creation (e.g., `explorer.csr`). Create a `.pem` file from the CA certificate in step 8 and use it as the server certificate in MQTT Explorer.
+
+    **Note**: The thing name must be unique as it will be used as the client ID.

sld297-matter-aws-feature/build-matter-aws.md

@@ -0,0 +1,72 @@
+# Build Procedure For Matter + AWS
+
+The following components are common for all apps and should be modified in the corresponding application-specific `.slcp` file.
+
+## How to Add the Matter + AWS Component
+
+To add the Matter + AWS component, modify the corresponding application-specific `.slcp` file.
+
+```shell
+  - id: matter_aws
+    from: matter
+```
+To enable the component in Simplicity Studio, add the following components.
+
+- Go to **Software** components, search for `Matter_Wifi`. Click on **Settings** symbol beside Matter Wi-fi component in the left panel and enable IPV4 configuration.
+    ![IPV4 Component](images/matter_aws_ipv4_enable_1.png)
+    ![IPV4 Settings Enable](images/matter_aws_ipv4_enable_2.png)
+
+- In **Software Components**, search for `aws` and install the Matter AWS component.
+
+- Next, select the dependencies for the Matter AWS component.
+ ![Default Entropy Source for Matter + AWS](images/matter_aws_dependency_1.png)
+ ![Public-Key Abstaction Layer for Matter + AWS](images/matter_aws_dependency_2.png)
+
+## How to Add the Matter + AWS Server, Client, Cluster Details.
+
+- Update the definitions for the server ID, client ID and cluster in `MatterAwsConfig.h`:    
+    - Update the AWS server name at `#define MATTER_AWS_SERVER_HOST ""`.
+    - Update the client ID at `#define MATTER_AWS_CLIENT_ID ""`.
+    - Update the cluster information at `#define ZCL_USING_THERMOSTAT_CLUSTER_SERVER`.
+
+
+## Building Matter + AWS Application
+
+- After you finish modifying the **.slcp** project file as described above, refresh the `matter-extension` in Simplicity Studio.
+
+-  On the **Launcher** tab, select **Preferences**.
+
+ ![Select Preferences](images/select-preferences.png)
+
+- Expand the **Simplicity Studio** section, and click the **SDKs** tab.
+
+ ![Select SDK](images/select-studio-sdk-option.png)
+
+- Expand **Simplicity SDK**, and click **Refresh** in the side menu.
+
+ ![Select Refresh](images/select-refresh-option.png)
+
+- Build the Matter + AWS application using Simplicity Studio as described in
+  - [Build SOC Application Using Studio](/matter/{build-docspace-version}/matter-wifi-run-demo/build-soc-application-using-studio).
+
+## Compile using new/different certificates
+
+-   Two devices should not use the same client ID. Use a different client ID for
+    your second connection.
+-   While using AWS, update the following information:
+    -   Add your AWS certificates in file
+        `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsNvmCert.h`
+        -   Provide the AWS Root CA key
+            (https://www.amazontrust.com/repository/AmazonRootCA3.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)
+    -   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.
+        -   Provide  `ZCL_USING_THERMOSTAT_CLUSTER_SERVER` with the cluster details.
+-   The preferred certificate type to use in the application is ECDSA.
+-   AWS RootCA used in this PoC is
+    https://www.amazontrust.com/repository/AmazonRootCA3.pem
+

sld297-matter-aws-feature/index.md

@@ -0,0 +1,124 @@
+# Matter + AWS Component
+
+-   Matter + AWS is a Silicon Labs–specific feature that enables Matter devices to connect directly to 
+    proprietary cloud solutions, such as AWS Cloud.  As such, a Matter Wi-Fi device
+    must support connecting locally on the Matter Fabric via IPv6 and
+    connecting to the Internet via IPv4.
+-   Matter devices can be controlled by chip-tool or a controller. The
+    status of the modified attributes will be published to the cloud.
+-   Remote users can install a cloud-specific application to receive
+    notifications about the attribute status.
+
+## Matter + AWS Feature Diagram
+
+The following diagram shows end-to-end flow for Direct Internet Connectivity.
+
+![Silicon Labs - Matter + AWS design](./images/matter-aws-flow.png)
+
+## Prerequisites
+
+### Hardware Requirements
+
+For a list of hardware requirements for the Matter + AWS feature, see the
+official
+[Silicon Labs Matter hardware requirements](https://siliconlabs.github.io/matter/latest/general/HARDWARE_REQUIREMENTS.html)
+documentation.
+
+### Software Requirements
+
+For a list of software requirements for the Matter + AWS feature, see the
+official
+[Silicon Labs Matter Software requirements](https://siliconlabs.github.io/matter/latest/general/SOFTWARE_REQUIREMENTS.html)
+documentation.
+
+## End-to-End Set-up bring up
+
+### Message Queuing Telemetry Transport (MQTT)
+
+MQTT is an OASIS standard messaging protocol for the Internet of Things
+    (IoT). It is designed as an extremely lightweight publish/subscribe
+    messaging transport that is ideal for connecting remote devices with a small
+    code footprint and minimal network bandwidth. 
+    For more details, visit https://mqtt.org/.
+
+### Configuring the MQTT server
+
+To set up and configure AWS for Matter + AWS support, see the following documentation:
+
+- [AWS installation](./aws-configuration-registration.md)
+
+### Remote User Setup (MQTT Explorer) (optional)
+
+Remote users are used to check the state of Matter devices. In this context, MQTT Explorer acts as a remote user. For more information, see [MQTT Explorer Setup and Configuration](./mqtt-explorer-setup.md).
+
+### Building Matter + AWS Application using Simplicity Studio
+
+Follow the instructions in [Build MATTER + AWS](./build-matter-aws.md) to enable the MATTER + AWS feature in your application code.
+
+
+## End-to-End Test of Matter + AWS Application
+
+User Setup (MQTT Explorer):
+
+- Sharing status of device to cloud
+  - The following diagram shows the end-to-end flow for sharing status from a Matter device to the cloud.
+
+![Silicon Labs - Matter + AWS design](images/dic-status-sharing.png)
+
+  **Note**: For reference, the diagram shows Lighting App commands. Other application commands also can be passed.
+
+- For the end-to-end commands to be executed from chip-tool, refer to [Running the Matter Demo Over Wi-Fi](/matter/{build-docspace-version}/matter-wifi-run-demo).
+- The following application-specific attributes or states are shared to the cloud:
+  - For Lighting App, On/Off Attributes
+  - For Lock App, lock/unlock Attributes
+  - For Windows App, lift/tilt Attributes
+  - For Thermostat App, SystemMode/CurrentTemp/LocalTemperature/OccupiedCoolingSetpoint/OccupiedHeatingSetpoint Attributes
+  - For On/off Plug App, On/Off Attributes
+  - The MQTT Explorer UI updates the application status as shown in following image.
+
+      ![Matter + AWS status update](images/mqtt-explorer-4.png)
+
+- Control of the device through cloud interface
+  - The following diagram shows the end-to-end flow for control of the Matter device through a cloud interface.
+
+      ![Silicon Labs - Matter + AWS design](images/dic-control-part.png)
+
+    **Note**: For reference, the diagram shows Lighting App commands. Other application commands also can be passed.
+
+  - Ensure that the Matter device is running and successfully commissioned. For detailed steps, refer to [Running the Matter Demo Over Wi-Fi](/matter/{build-docspace-version}/matter-wifi-run-demo).
+  - To control the device, set the topic name and the commands to be executed in the MQTT Explorer for the following applications.
+
+```shell
+    - Lighting App
+      - Topic: command
+        - Commands:
+           - toggle
+           - on
+           - off
+    - Onoff-plug App
+      - Topic: command
+        - Commands:
+          - toggle
+          - on
+          - off
+    - Lock App
+      - Topic: command
+        - Commands:
+          - lock
+          - unlock
+    - Thermostat App
+      - Topic: command
+        - Commands:
+          - SetMode/value(value need to provide 1,2,3,4 ex:SetMode/1)
+          - Heating/value(value need to provide 2500,2600 ex:HeatingSetPoint/2500)
+          - Cooling/value(value need to provide 2500,2600 ex:CoolingSetPoint/2500)
+    - Window App
+      - Topic: command
+        - Commands:
+          - Lift/value(value need to provide in range 1000 to 10000)
+          - Tilt/value(value need to provide in range 1000 to 10000)
+```
+
+- Click **Publish** to execute the command.
+
+![Silicon Labs - Matter + AWS design](images/control-device-through-cloud.png)

sld297-matter-wifi-dic/mqtt-explorer-setup.md → sld297-matter-aws-feature/mqtt-explorer-setup.md

@@ -13,7 +13,7 @@ Download and install the MQTT Explorer from https://mqtt-explorer.com/.
 - Make sure you enable **Validate Certificate and Encryption**
 - Click **Advanced Settings**
 
-![Silicon Labs - DIC design](./images/mqtt-explorer-2.png)
+![Silicon Labs - MATTER + AWS design](./images/mqtt-explorer-2.png)
 
 - Add application specific topics as shown below
   - For Lighting app, topic to be added (light/*)
@@ -30,11 +30,11 @@ Download and install the MQTT Explorer from https://mqtt-explorer.com/.
 - MQTT Client ID depends on the certificate set that you will use.
 - Add the Certificate, following step 7 in [AWS installation](./aws-configuration-registration.md).
 
-![Silicon Labs - DIC design](./images/mqtt-explorer-5.png)
+![Silicon Labs - MATTER + AWS design](./images/mqtt-explorer-5.png)
 
 - Once the above steps are done, try connecting to AWS.
 
-![Silicon Labs - DIC design](./images/mqtt-explorer-3.png)
+![Silicon Labs - MATTER + AWS design](./images/mqtt-explorer-3.png)
 
 ### Connecting to Mosquitto Connection
 
@@ -43,7 +43,7 @@ Download and install the MQTT Explorer from https://mqtt-explorer.com/.
 - Make sure you enable Validate Certificate and Encryption
 - Click **Advanced Settings**
 
-![Silicon Labs - DIC design](./images/mqtt-explorer-2.png)
+![Silicon Labs - MATTER + AWS design](./images/mqtt-explorer-2.png)
 
 - Add application specific topics as shown below
   - For Lighting app, topic to be added (light/*)
@@ -60,4 +60,4 @@ Download and install the MQTT Explorer from https://mqtt-explorer.com/.
   - MQTT Client ID depends on the certificate set that you will use.
   - Add the Certificate, following step 5 in [Openssl Certificate Creation](./openssl-certificate-creation.md).
 
-![Silicon Labs - DIC design](./images/mqtt-explorer-5.png)
+![Silicon Labs - MATTER + AWS design](./images/mqtt-explorer-5.png)

sld297-matter-aws-feature/openssl-certificate-creation.md

@@ -0,0 +1,24 @@
+# OpenSSL Certificate Creation
+
+An SSL certificate is an important way to secure user information and protect against hackers.
+
+## Openssl Installation (In ubuntu 22.04)
+
+1. To install OpenSSL (v 3.0.2), issue the following command:  `sudo apt install openssl`
+
+## Certificates Creation
+
+Use the following commands to generate certificates:
+
+1. **Generate the client key:**
+    - `openssl ecparam -name prime256v1 -genkey -noout -out device.key`
+2. **Generate the client certificate** (e.g., `device.crt` and `device.key`) using a CA
+   certficate:
+    - `openssl req -new -out device.csr -key device.key`
+3. **Upload CSR to AWS**: While creating the AWS IoT thing, use the **Upload CSR** option in the configure device
+   certificate step. Once the CSR generated in step 2 is uploaded, AWS will
+   generate an AWS CA-authenticated `device.crt`.
+   ![AWS CSR Upload ](./images/matter_aws_device_csr_certificate_generation.png)
+
+To use MQTT Explorer, repeat steps 1 and 2 to create an additional set of certificates 
+(e.g., `explorer.crt` and `explorer.key`). Use a different name to uniquely identify the certificates.