-
Notifications
You must be signed in to change notification settings - Fork 31
[SL-ONLY] Add Matter+AWS documentation #581
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
sabollim-silabs
wants to merge
5
commits into
release_2.7-1.4
Choose a base branch
from
docs/matter_aws_documentation
base: release_2.7-1.4
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
3b04a8e
Adding Matter+AWS Documentation
sabollim-silabs 1ee4fa1
Apply suggestions from code review
sabollim-silabs 2257ede
Addressing PR comments
sabollim-silabs 4170cb4
PR comments
sabollim-silabs c93cba1
Restyled by prettier-markdown
restyled-commits File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Binary file added
BIN
+84.4 KB
docs/platforms/silabs/images/matter_aws_cloud_control_mqtt_explorer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+116 KB
docs/platforms/silabs/images/matter_aws_device_csr_certificate_generation.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # Build Procedure For Matter AWS | ||
|
|
||
| ## Build command with Matter AWS | ||
|
|
||
| - To enable Matter AWS functionality use the `enable_matter_aws=true` flag. | ||
|
|
||
| ```` | ||
|
|
||
| ### Here is an example to build the lighting-app with Matter AWS for the SiWx917 SoC | ||
|
|
||
| ```shell | ||
| ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/debug BRD4338A enable_matter_aws=true chip_enable_wifi_ipv4=true | ||
| ```` | ||
|
|
||
| ## 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](#matter--aws-device-openssl-keys-generation) | ||
| - 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 | ||
| - 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 | ||
|
|
||
| ## Matter + AWS device openssl keys generation | ||
|
|
||
| ## 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. | ||
|  | ||
|
|
||
| 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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # Matter Wi-Fi + 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. | ||
|
|
||
|  | ||
|
|
||
| ## 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 | ||
|
|
||
| ### Building Matter Matter + AWS Application | ||
|
|
||
| 1. To Build Matter + AWS Application, refer | ||
| [Building of Matter + AWS](./silabs_matter_aws_build_guide.md) | ||
| 2. Commission the Matter Device and confirm Matter + AWS connection is done from | ||
| Device side logs. | ||
|
|
||
| ## End-to-End Test of Matter + AWS Application | ||
|
|
||
| - **Sharing status of device to cloud** | ||
|
|
||
| - Below diagram gives end-to-end flow for sharing status from matter | ||
| device to cloud | ||
|
|
||
|  | ||
|
|
||
| **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](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 - For On/off Plug App, On/Off | ||
| Attributes - For Windows App, lift/tilt Attributes - For Thermostat App, | ||
| SystemMode/CurrentTemp/LocalTemperature/OccupiedCoolingSetpoint/OccupiedHeatingSetpoint | ||
| Attributes - Application status would be updated on the mqtt_explorer UI, as | ||
| shown in below image. | ||
|
|
||
|  | ||
|
|
||
| - **Control of the device through cloud interface** | ||
| - Below diagram gives end-to-end flow for Control of the matter device | ||
| through cloud interface | ||
|  | ||
|
|
||
| **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](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 | ||
| - 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 ex: | ||
| Lift/2500) | ||
| - Tilt/value(value need to provide in range 1000 to 10000 ex: | ||
| Tilt/2500) | ||
| - Then click `publish` button to execute the command. | ||
|
|
||
|  | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
mqtt instance will be available over IPv6 at least locally as I recollect. Do we want to mention that ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lets not mention it as its not tested