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 (ex: MATTER_AWS_POLICY_) and, 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 client CSR certificate, and a client key using the [Openssl Certificate Creation](./openssl-certificate-creation.md) documentation.
+
+6. 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**.
+    - Specify thing properties in **Info > Give the thing a name** (Note: Client ID) and click **Next**.
+    - Configure the device certificate (optional) in **Info > Upload CSR**.
+    - In **Certificate > Choose file** (Choose Client CSR generated in Openssl Certificate Creation ex: `device.csr`). Click **Next**. 
+    - Use the policy (ex: MATTER_AWS_POLICY_) created in AWS Certificate creation.
+    - Upon successful creation, Activate the Certificate 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 to use in MQTT Explorer using the certificate created for MQTT explorer (from Openssl Certificate Creation ex: `explorer.csr`). create a .pem file from CA certificate in step 8 to use as a SERVER CERTIFICATE in MQTT Explorer.
+
+    **Note**: Thing name must be unique as it will be used as 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 app specific .slcp file.
+
+## How to Add the Matter + AWS Component
+
+To add the Matter + AWS component, modify the corresponding app specific .slcp file.
+
+```shell
+  - id: matter_aws
+    from: matter
+```
+To add component in Simplicity Studio, add below components.
+
+- Go to Software components, search for Matter_Wifi. Click on Settings symbol beside Matter Wifi 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)
+
+- Go to Software Components, search for aws and install matter aws component.
+
+- Next select the dependencies for 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.
+
+- Add the Server ID, CLient Id and Cluster Info in `MatterAwsConfig.h`.
+    - update AWS server name at #define MATTER_AWS_SERVER_HOST ""
+    - update client ID at #define MATTER_AWS_CLIENT_ID ""
+    - update intrested cluster at #define ZCL_USING_THERMOSTAT_CLUSTER_SERVER
+
+
+## Building Matter + AWS Application
+
+- After modification in the **.slcp** Project file as above step, refresh the **matter-extension** in Simplicity Studio.
+
+- Select **Preferences** in the **Launcher** tab.
+
+ ![Select Preferences](images/select-preferences.png)
+
+- Expand Simplicity Studio section and click on **SDKs** Tab.
+
+ ![Select SDK](images/select-studio-sdk-option.png)
+
+- Expand **Simplicity SDK** and click the **Refresh** button from side menu.
+
+ ![Select Refresh](images/select-refresh-option.png)
+
+- Build the Matter + AWS application using Simplicity Studio
+  - [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, Change the following:
+    -   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 cert and
+            device key. Refer
+            [Openssl Device Certificate Creation] (./openssl-certificate-creation.md)
+    -   Add your AWS server and Client ID in file
+        `examples/platform/silabs/matter_aws/matter_aws_interface/include/MatterAwsConfig.h`
+        -   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 silabs only feature to connect matter devices to
+    proprietary cloud solutions(AWS) directly. 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 controller and the
+    respective status of the attribute modified will be published to the cloud.
+-   Remote user can install the cloud specific application to get the
+    notification on the attribute status.
+
+## Matter + AWS Feature Diagram
+
+1. Below diagram gives end-to-end flow about Direct Internet Connectivity.
+
+![Silicon Labs - Matter + AWS design](./images/matter-aws-flow.png)
+
+## Prerequisites
+
+### Hardware Requirements
+
+For the list of hardware requirements for Matter + AWS feature , see the
+official
+[Silicon Labs Matter HW requirements](https://siliconlabs.github.io/matter/latest/general/HARDWARE_REQUIREMENTS.html)
+documentation.
+
+### Software Requirements
+
+For the list of software requirements for 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. Refer https://mqtt.org/ for
+    more details
+
+### 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)
+
+A remote user is used to check the state of a Matter device. In this context, MQTT explorer is used as a remote user. See [MQTT explorer setup and configuration](./mqtt-explorer-setup.md).
+
+### Building Matter + AWS Application using Simplicity Studio
+
+1. Follow instructions in [Build MATTER + AWS](./build-matter-aws.md) to enable the MATTER + AWS feature in 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, Lighting App commands are given in the above image. 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).
+- Below are the application-specific attributes or states 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
+  - Application status would be updated on the mqtt_explorer UI, as shown in below image.
+
+      ![Matter + AWS status update](images/mqtt-explorer-4.png)
+
+- Control of the device through cloud interface
+  - The diagram below 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, Lighting App commands are shown in the above image. Similarly, other application commands also can be passed.
+
+  - Make sure the Matter device is up and commissioned successfully. Refer to [Running the Matter Demo Over Wi-Fi](/matter/{build-docspace-version}/matter-wifi-run-demo).
+  - For controlling the device, set 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,25 @@
+# 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) - `sudo apt install openssl`
+
+## Certificates Creation
+
+The following commands are used to generate certificates:
+
+1. To generate Client key:
+    - `openssl ecparam -name prime256v1 -genkey -noout -out device.key`
+2. To generate Client certificate (ex: `device.crt` and `device.key`) using CA
+   certficate:
+    - `openssl req -new -out device.csr -key device.key`
+3. While creating AWS thing , use Upload CSR option in configure device
+   certificate step. once uploaded the CSR generated in step 2. AWS will
+   generate AWS CA authenticated device.crt.
+   ![AWS CSR Upload ](./images/matter_aws_device_csr_certificate_generation.png)
+
+Repeat step 1 and 2 to create an additional set of certificate to use in MQTT
+explorer (ex: `explorer.crt` and `explorer.key`). (Create with different name
+for Identification)