diff --git a/README.md b/README.md index f776fa672934cb..c10f29a1804e95 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.1.0-1.1/thread/DEMO_OVERVIEW.html) + [Matter Thread](https://siliconlabs.github.io/matter/2.2.0-1.2-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.1.0-1.1/wifi/DEMO_OVERVIEW.html) + [Matter Wi-Fi](https://siliconlabs.github.io/matter/2.2.0-1.2-alpha.1/wifi/DEMO_OVERVIEW.html) The full documentation set starts here: -[Silicon Labs Matter GitHub Documentation](https://siliconlabs.github.io/matter/2.1.0-1.1) +[Silicon Labs Matter GitHub Documentation](https://siliconlabs.github.io/matter/2.2.0-1.2-alpha.1) --- diff --git a/docs/silabs/NEW_FEATURES.md b/docs/silabs/NEW_FEATURES.md index f7b5d1ef730a32..4c9c9fdd8411a5 100644 --- a/docs/silabs/NEW_FEATURES.md +++ b/docs/silabs/NEW_FEATURES.md @@ -1,5 +1,35 @@ # Silicon Labs Matter New Features +## New Features for v2.2.0-1.2-alpha.1 + +### Support for Intermittently Connected Devices (ICD) + +- Full support for ICD Short idle time (SIT) Devices in support of the Matter 1.2 specification. + - In this release Silicon Labs has provided full support for Short Idle Time intermittently connected devices. + - These are ICDs (formerly called Sleepy End Devices) which must remain responsive to user input such as Door Locks and Window Coverings. +- ICD Management cluster server implementation + - Silicon Labs has provided an implementation of the ICD cluster server and the configuration of the ICD +- ICD Manager and ICD Event manager has been implemented to manage the Idle and Active mode of the ICD +- NEW DNS advertisement Text Key SAI: indicates the SLEEPY_ACTIVE_INTERVAL (default to 4000 ms when ICD is not enabled) +- NEW Matter ICD configuration defines: + - CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL set value for the ICD IdleInterval attribute + - CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL set value for the ICD ActiveInterval attribute + - CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD set value for the ICD ActiveThreshold attribute + - CHIP_CONFIG_ICD_CLIENTS_SUPPORTED_PER_FABRIC set value for the ICD ClientsSupportedPerFabric attribute + - All of these defines can be configured by our following build arguments (default values listed here) + - 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` + - sl_icd_supported_clients_per_fabric = 2 `# 2 registration slots per fabric` + - The OpenThread polling rates used in either ICD mode can be configured with (default value listed here) + - sl_ot_idle_interval_ms = 15000 `# 15s Idle Intervals` + - sl_ot_active_interval_ms = 200 `# 200ms Active Intervals` + +- CHANGES: + - Optimized the subscription reports by synchronizing all client’s subscriptions with the ICD idle mode interval. This ensures the minimal amount of wake ups possible due to subscription reports + - The previous `--sed` build preset has been replaced by `--icd`. This goes in line with previous sleepy end device behavior being deprecated and replaced by the ICD behavior. + - Silicon Labs' Light Switch and Door Lock apps support the ICD implementation and have the ICD cluster enabled. To build those apps as ICDs, use the aforementioned prefix `--icd` in your usual build command. + - e.g.: `./scripts/examples/gn_silabs_example.sh ./examples/light-switch-app/silabs/efr32/ ./out/light-switch-app_ICD BRD4187C --icd` ## New Features for v2.1.0-1.1 - ### Update to GSDK Version 4.2.3 @@ -7,37 +37,37 @@ ## New Features for v2.0.0-1.1 -## Matter Intermittently Connected Devices (ICD / Sleepy) Improvements -- ### Expose the API for a device to change the max interval in a subscription request +### Matter Intermittently Connected Devices (ICD / Sleepy) Improvements +- #### Expose the API for a device to change the max interval in a subscription request A device can, when accepting a subscription request, change the maximum reporting interval for it to match with its idle time instead of accepting the requested intervals. When not using this API, the ICDs idle time interval could functionally be shortened by a controller without the ICD being able to refuse the subscription. For more details see the [Matter Intermittently Connected Devices](./general/MATTER_ICD.md) section. -- ### Persistent Subscription +- #### Persistent Subscription The device will persist a subscription to be able to recover its subscription with a subscriber in case of a reboot. For more details see the [Matter Intermittently Connected Devices](./general/MATTER_ICD.md) section. -- ### During the commissioning flow, the device will not be able to go to idle mode until the commissioning is complete. +- #### During the commissioning flow, the device will not be able to go to idle mode until the commissioning is complete. Before, the thread devices would go to idle mode right after completing its srp registration but before the sigma1 message was received. With 1.1, devices will remain in Active Mode until the commissioning is complete. -- ### Adding the Active Mode Threshold feature. +- #### Adding the Active Mode Threshold feature. When a thread ICD goes from Idle Mode to Active Mode, the ICD will stay in Active Mode for a defined amount before going back to Idle Mode. 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. -## Matter Sleepy End Devices over Wi-Fi +### Matter Sleepy End Devices over Wi-Fi - A Matter Sleepy End Device is a device where the EFR32 along with the Wi-Fi coprocessor go into sleep mode during idle time resulting in less power consumption. This helps devices running on limited power sources like battery powered devices. The EFR32 goes into sleep mode whenever the device is idle. The Wi-Fi coprocessor goes into Power Save (PS) Poll legacy power save mode where it wakes for every Delivery Traffic Information Map (DTIM) interval to check for any packets. For more details see the [Wi-Fi Sleepy End Device](wifi/WIFI_SLEEPY_END_DEVICE.md) section. -## Added support for CMPS (Custom Part Manufacturing Service) +### Added support for CMPS (Custom Part Manufacturing Service) - The new provisioning script allows easy setup of factory data in Matter devices. This tool provides a common architecture for use both in development and production environments, which allows easy deployment of the developed products. @@ -45,7 +75,7 @@ The EFR32 goes into sleep mode whenever the device is idle. The Wi-Fi coprocesso The provision/provision.py tool supersedes the silabs_example/credentials/creds.py script. -## Matter Wi-Fi Direct Internet Connectivity +### Matter Wi-Fi Direct Internet Connectivity - The Matter Wi-Fi Direct Internet Connectivity (DIC) solution connects to proprietary cloud solutions for direct access to software downloads, to device controls, or to aggregate statistics on where and how the device is being used. diff --git a/docs/silabs/README.md b/docs/silabs/README.md index 42177318db9619..43a74ac9f6600c 100644 --- a/docs/silabs/README.md +++ b/docs/silabs/README.md @@ -21,12 +21,10 @@ 1. [Matter Wi-Fi Demo Overview](wifi/DEMO_OVERVIEW.md) 2. [Building a Matter Wi-Fi End Device](wifi/SW_SETUP.md) 3. [Running the Matter Demo on EFR32 hosts](wifi/RUN_DEMO.md) - 4. [Ozone Environment Setup for the SiWx917 SoC](wifi/SiWx917_Enablement_For_Ozone.md) - 5. [Flashing the SiWx917 SoC](general/FLASH_SILABS_SiWx917_SOC_DEVICE.md) - 6. [Running the Matter Demo on SiWx917 SoC](wifi/RUN_DEMO_SiWx917_SoC.md) - 7. [Matter Wi-Fi Sleepy End Devices](wifi/WIFI_SLEEPY_END_DEVICE.md) - 8. [Matter Wi-Fi Sleepy End Device Power Measurement](wifi/WIFI_Sleepy_Device_Power_Measurement.md) - 9. [Matter Wi-Fi Direct Internet Connectivity(DIC)](wifi/DIC_Wi-Fi.md) + 4. [Running the Matter Demo on SiWx917 SoC](wifi/RUN_DEMO_SiWx917_SoC.md) + 5. [Matter Wi-Fi Sleepy End Devices](wifi/WIFI_SLEEPY_END_DEVICE.md) + 6. [Matter Wi-Fi Sleepy End Device Power Measurement](wifi/WIFI_Sleepy_Device_Power_Measurement.md) + 7. [Matter Wi-Fi Direct Internet Connectivity(DIC)](wifi/DIC_Wi-Fi.md) 6. Matter Bridging to Zigbee/Z-Wave diff --git a/docs/silabs/conf.py b/docs/silabs/conf.py index 706dbd24a48529..e26cb2c43a1f84 100644 --- a/docs/silabs/conf.py +++ b/docs/silabs/conf.py @@ -9,8 +9,8 @@ project = 'Matter' copyright = 'Copyright © 2023 Silicon Laboratories. All rights reserved.' author = 'Silicon Labs' -release = '2.1.0-1.1' -version = '2.1.0-1.1' +release = '2.2.0-1.2-alpha.1' +version = '2.2.0-1.2-alpha.1' # -- General configuration --------------------------------------------------- diff --git a/docs/silabs/general/ARTIFACTS.md b/docs/silabs/general/ARTIFACTS.md index bf8b03d9206741..e5a60f8387eecf 100644 --- a/docs/silabs/general/ARTIFACTS.md +++ b/docs/silabs/general/ARTIFACTS.md @@ -11,7 +11,7 @@ Matter chip-tool. Note the image is ~10GB in size so depending on your internet connection this download may take some time. Start the Matter Hub Raspberry Pi image download here: -https://www.silabs.com/documents/public/software/SilabsMatterPi_2.0.0-1.1.zip +https://www.silabs.com/documents/public/software/SilabsMatterPi_2.2.0-1.2-alpha.1.zip ## Radio Co-Processor (RCP) Images @@ -20,7 +20,7 @@ used with a Raspberry Pi to allow the Raspberry Pi's Open Thread Border Router to access the Thread network. Radio Co-Processor (RCP) images are available in the Assets section of this page: -https://github.com/SiliconLabs/matter/releases/tag/v2.1.0-1.1 +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 ## Matter Accessory Device Images @@ -28,7 +28,7 @@ The Matter Accessory Device Images are used to turn an EFR into a Matter device. These are pre-built binary images for the Matter Demo. Matter Accessory Device Images are located in the Assets section of this page: -https://github.com/SiliconLabs/matter/releases/tag/v2.1.0-1.1 +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 For Matter over Thread, 3 different types of images are provided: @@ -43,21 +43,40 @@ EFR32MG2x device, you will need to flash a bootloader binary on your device alon with the application image. Bootloader binaries for all of the Matter supported devices are available here: -https://github.com/SiliconLabs/matter/releases/tag/v2.1.0-1.1 +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 ## RS9116 Firmware -The RS9116 firmware is used to update the RS9116 - it can be found in the -repository you have cloned, at the following relative path from the `/matter` -directory, `./third_party/silabs/wiseconnect-wifi-bt-sdk/firmware` +The RS9116 firmware (rs9116_firmware_files_with_rev.zip) is used to update the RS9116 which can be found in the Assets section of this page: -## SiWx917 Firmware +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 -> **Note**: SiWx917 firmware is only available to Alpha customers. Contact Silicon Labs support to obtain the WiseMCU SDK and install it as per the instructions on the [Software Requirements page](./SOFTWARE_REQUIREMENTS.md). +**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` -The SiWx917 firmware is used to update the SiWx917 device connectivity firmware. It can be found in the -repository you have cloned, at the following relative path from the `/matter` -directory, `./third_party/silabs/wisemcu-wifi-bt-sdk/connectivity_firmware` +## SiWx917 Firmware for SiWx917 NCP + +The SiWx917 firmware(SiWx917NCP_firmware_files.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/tag/v2.2.0-1.2-alpha.1 + +**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` + + +## 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 in the Assets section of this page: + +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 + +**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.2) board` +- `SiWG917-B.2.9.X.X.X.rps - This firmware image is valid for BRD4325C(B0 common flash v1.2) board` ## SiWx917 SoC Configuration Files for Flashing the Matter Application @@ -67,4 +86,4 @@ be configured for the SiWx917 SoC device by following the instructions on the [O The **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/tag/v2.1.0-1.1 +https://github.com/SiliconLabs/matter/releases/tag/v2.2.0-1.2-alpha.1 diff --git a/docs/silabs/general/COMMISSIONING.md b/docs/silabs/general/COMMISSIONING.md index 7957193d7ab9f1..e0706eb37330c8 100644 --- a/docs/silabs/general/COMMISSIONING.md +++ b/docs/silabs/general/COMMISSIONING.md @@ -1,4 +1,4 @@ -# Commissioning +# Matter Commissioning ## Overview diff --git a/docs/silabs/general/COMMIT_HASHES.md b/docs/silabs/general/COMMIT_HASHES.md index b4d74c41017598..e46ea587f3aa15 100644 --- a/docs/silabs/general/COMMIT_HASHES.md +++ b/docs/silabs/general/COMMIT_HASHES.md @@ -7,19 +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 | 1813352247aa60fb8993773918f1e5b4af6f3b79 | +| https://github.com/SiliconLabs/ot-br-posix | main | bb565ca0164981f58a2659222c30917399703a9b | ## Radio Co-Processor (RCP) | Repo | Branch | Commit Hash | | --------------------------------------- | ------ | ---------------------------------------- | -| https://github.com/SiliconLabs/ot-efr32 | main | 7a567da02a078546eb34136c1c44170c8832dd55 | +| https://github.com/SiliconLabs/ot-efr32 | main | 3528d4bba47743a5367a822e350aaccb04698542 | ## Connectivity Standards Alliance (CSA) connectedhomeip (Matter) | Repo | Branch | Commit Hash | | ----------------------------------------------- | ------ | ---------------------------------------- | -| https://github.com/project-chip/connectedhomeip | v1.1-branch | 8f66f4215bc0708efc8cc73bda80620e67d8955f | +| https://github.com/project-chip/connectedhomeip | master | 684b9d6246e5e5ef33db589af61a30e224d61ee3 | ## Matter chip-tool diff --git a/docs/silabs/general/FUNDAMENTALS_DATA_MODEL.md b/docs/silabs/general/FUNDAMENTALS_DATA_MODEL.md new file mode 100644 index 00000000000000..4c26f4f850ce3c --- /dev/null +++ b/docs/silabs/general/FUNDAMENTALS_DATA_MODEL.md @@ -0,0 +1,87 @@ +# The Matter Data Model + +The Data Model in Matter describes a hierarchical encapsulation of data elements in the Matter network, including, but not limited to, nodes, endpoints, clusters, and device types, where the node is the highest level data element. + +A single physical Matter device, such as a light, switch, or door lock, can be represented by one or more nodes. An environment where multiple Matter nodes interoperate is referred to as a Matter fabric. These nodes share a common root of trust. On each separate fabric, a physical Matter device is represented by a node. Every node has a unique network address (Operational Node ID) that makes it uniquely identifiable in the fabric it is on. For example, in the following figure a Matter Lighting device on an Apple HomePod fabric (blue) has an operational node ID unique to the HomePod fabric and a Matter Switch device on a separate Samsung SmartThings Station fabric (red) in the same home has an operational node ID unique to the SmartThings fabric. These IDs may be the same or different; they are independent of each other because they are on two different fabrics. + +A Matter device may also be part of more than one fabric and thus is represented on each different fabric by a different node. In following figure, a Matter Door Lock device is on both the HomePod and SmartThings fabrics. Thus, the Door Lock is represented by two different nodes; one for the HomePod fabric and another for the SmartThings fabric. The operational node IDs for the two nodes representing the device may be the same or different; the IDs are independent of each other because the nodes are on two different fabrics. + +![Devices and their fabrics](resources/devices-fabrics.jpg) + +The following section describes the Matter data model, including Nodes and Device Types. + +## Nodes + +In the following figure, the hierarchical structure of endpoint, cluster, attributes/commands/events is shown from left to right. + +![Matter Node Overview](resources/node-overview.jpg) + +Each node contains the complete application functionality for its device on a single stack. Because of this, nodes can communicate directly with other nodes on the network without the need for an intermediary. + +Nodes have a set of related behaviors, known as a role. There are a few main node roles: + +- **Commissioner** - Commissions/adds new devices to a Matter network +- **Controller** - Controls one or more nodes +- **Controlee** - Can be controlled by one or more nodes +- **Over the Air (OTA) Provider** - Provides OTA software updates to the OTA Requestor +- **OTA Requestor** - Requests OTA software updates from the OTA Provider + +### Endpoints + +Endpoints enclose one component of a node’s complete functionality; together, they encapsulate all the node’s capabilities needed for functional wholeness. A smart thermostat, for example, could have two endpoints where one would implement the temperature control functionalities and another would implement the temperature monitoring functionalities. + +Each of these endpoints are known as a feature set, which is made of clusters that define the attributes, events, and commands of a single endpoint's functionality. There are two distinct types of endpoints in Matter: leaf endpoints and composed endpoints. + +- Leaf endpoints, such as Endpoints 0, 10, and 11 in the following figure, do not require other endpoints to function. +- Composed endpoints, such as Endpoint 1 in the following figure, require other endpoints to function. Connector lines indicate the endpoints that a certain endpoint has access to. + +![Leaf and Composed Endpoints](resources/endpoint-types.jpg) + +Nodes have numbered endpoints starting from 0 that contain their own feature set. Endpoints with the same number but on different nodes may enclose different feature sets. The exception is Endpoint 0, which is reserved exclusively for Utility Clusters. These special clusters are specifically used for enclosing a node’s servicing functionality: the discovery process, addressing, diagnostics, and software updates. + +Endpoints are individually addressable to easily modify feature sets separately. + +### Clusters + +Clusters are collections of data that group the attributes, events, and commands of a specific functionality, representing a single feature in an endpoint’s feature set. A cluster may be thought of as an interface, service, or object class and is the lowest independent functional element in the device data model. Endpoints have multiple clusters to create individual instances of the same functionality for easier unit control. For example, each light on a light strip may have its own designated cluster for independent access. + +Attributes, events, and commands make up clusters: + +- **Attributes** represent the current state, configuration, or capability of a node, for example whether a light is on or off, or if a switch is up or down. + + - Fabric-scoped attributes are only accessible to devices in the same fabric. + - Attributes can be of uint8, string, array, etc. data types. + +- **Commands** are actions that a cluster can perform, analogous to verbs in the English language. + + - Commands always have a direction, either from client to server or vice versa. + - The target can reply to the command in one of two ways: + + - **Request** - such as toggling the ON/OFF attribute of a server cluster representing a light. + - **Response** - such as sending a success status, or an error/unsupported status. + +- **Events** are a record of past transitions between states of the node. + + - Events include data for a timestamp and priority of each change, as well as a monotonically increasing counter to track the number of state changes. + - They are useful in capturing state transitions and modeling past data that attributes do not store. + +Clusters have two main types: + +- **Server cluster** - Stateful, holds the data for the attributes, events, and commands. +- **Client cluster** - Stateless, interacts with other server clusters by reading and writing attributes, reading remote events, and/or invoking methods. + +Any cluster can be a server or a client, giving nodes the ability to both store information and horizontally communicate with other nodes. For a light and switch example, a client cluster in the light would send a command to a server cluster in the light to toggle the on/off feature of the light. The following figure illustrates examples of cluster communication. On the top is a light and switch example and on the bottom is an app controlling a door lock. + +![Examples of cluster communication](resources/communication-examples.jpg) + +## Device Types + +Device types are a collection of clusters on their respective endpoints that define top-level attributes of the physical device they represent. Device types can require other types for operational purposes; these are known as composed device types and require composed endpoints. + +A device can be made up of any combination of clusters. Therefore, to ensure the interoperability of devices from different manufacturers on a single network, Matter defined sets of requirements for official device types in the Matter Device Library for users to implement and extend. Every definition contains the device type ID, type revision number, and mandatory cluster(s) with their minimum revision number. Device Types are constantly updating, with each iteration tracked using the revision number starting from 1. However, changes to a device type's definition do not change its functionality, but only serve to improve operation. It is also important to note that newer versions of a device will continue to interoperate with older revision levels. + +The device types that Matter supports are an unyielding requirement for Matter nodes. Nodes that implement certain device types are required to include feature sets of clusters on one or more endpoints for the said device type. A node cannot implement a device type if it does not have all the required feature sets. Official documentation lists the application device types that Matter supports in the Device Library Specification, while the respective supported application clusters are defined in the Application Cluster Library. These two documents, along with Chapter 7: Data Model Specification of the Matter specification document, can be found on the website for CSA members: [Specifications Download Request - CSA-IOT](https://csa-iot.org/developer-resource/specifications-download-request/). + +## Relating Matter to Zigbee + +Ultimately, Matter serves to extend existing protocol stacks to maintain and bolster their architecture for future use. Thus, the Data Model originates from and resembles the Dotdot Architecture Model found here: [https://groups.csa-iot.org/wg/matter-tsg/document/18649](https://groups.csa-iot.org/wg/matter-tsg/document/18649) and Chapter 2 of the Zigbee Cluster Library Specification found here: [https://groups.csa-iot.org/wg/members-all/document/23019](https://groups.csa-iot.org/wg/members-all/document/23019). The Matter Data Model better defines the architecture in the Zigbee Cluster Library while keeping the certifiable cluster specifications. diff --git a/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md b/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md new file mode 100644 index 00000000000000..14b2dbf56a93f7 --- /dev/null +++ b/docs/silabs/general/FUNDAMENTALS_INTERACTION_MODEL.md @@ -0,0 +1,173 @@ +# The Matter Interaction Model + +The Matter Device Interaction Model (IM) defines the methods of communication between nodes, and serves as the common language for node-to-node information transmission. + +Nodes communicate with each other through interactions. Interactions are a sequence of transaction(s), which in turn are a sequence of actions. + +For example, in a Read Interaction, a client cluster can initiate a Read Transaction, where the client can request to read an attribute and a server cluster can respond by reporting the attribute. Both the client request and the server response are separate actions, but they are part of the same Read Transaction, which the Read Interaction encompasses. + +![Interaction structure overview](resources/interaction-structure.jpg) + +The Interaction Model supports four types of interactions: + +- **Read** +- **Write** +- **Invoke** +- **Subscribe** + +All interaction types except Subscribe consist of one transaction. The Interaction Model supports five types of transactions: + +- **Read** - Get attributes and/or events from a server. +- **Write** - Modify attribute values. +- **Invoke** - Invoke cluster commands. +- **Subscribe** - Create subscription for clients to receive periodic updates from servers automatically. +- **Report** - Maintain the subscription for the Subscribe Interaction. + +The following concepts are important for understanding transactions. + +- **Initiators and Targets** - Interactions happen between an initiator node and target node(s). The initiator starts the transaction, and the target responds to the initiator's action. More specifically, the transaction is usually between a client cluster on the initiator node and a server cluster on the target node. +- **Transaction ID** - The transaction ID field must be present in all actions that are part of a transaction to indicate the logical grouping of the actions as part of one transaction. All actions that are part of the same transaction must have the same transaction ID. +- **Groups** - Groups of devices allow an initiator to send an action to multiple targets. This group-level communication is known as a groupcast, which leverages Ipv6 multicast messages. +- **Paths** - Paths are the location of the attribute, event, or command an interaction seeks to access. Examples of path assembly: + + - ` = ` + - ` = ` + + When groupcasting, a path may include the group or a wildcard operator to address several nodes simultaneously, decreasing the number of actions required and thus decreasing the response time of an interaction. Without groupcasting, humans may perceive latency between multiple devices reacting to an interaction. For example, when turning off a strip of lights, a path would include the group containing all the lights instead of turning off each light individually. + +The following sections review each of the four interaction types and their constituent transactions and actions. + +## The Read Interaction + +![Diagram of a Read Interaction](resources/read-interaction.jpg) + +An initiator starts a Read Interaction when it wants to determine the value of one or more of a target node's attributes or events. The following steps occur: + +1. **Read Request Action** - Requests a list of the target’s attributes and/or events, along with paths to each +2. **Report Data Action** - Generated in response to the Read Request Action. Target sends back the requested list of attributes and/or events, a suppress response, and a subscription ID. + + 1. Suppress response: Flag that indicates whether the status response should be sent or withheld. + 2. Subscription ID: Integer that identifies the subscription transaction, only included if the report is part of a Subscription Transaction. + +3. **Status Response Action** (OPTIONAL) - Generates a Status Response by default; however, not sent if the suppress response flag is set. Ends transaction once the initiator sends the Status Response or receives a Report Data with the suppress flag set. + +Read Transactions are restricted to unicast only. This means that the Read Request and Report Data actions cannot target groups of nodes, whereas the Status Response Action cannot be generated as a response to a groupcast. + +## The Write Interaction + +![Diagram of Timed Write Interaction](resources/timed-write-interaction.jpg) + +An initiator modifies a target’s attributes through a Write Interaction, which consists of either a Timed or Untimed Write Transaction. + +An untimed transaction remains open to the receiver for an indefinite period, whereas a timed transaction establishes a maximum period (usually a few seconds) to receive a return action. + +### Timed Transactions and Security + +Timed transactions are mainly used for devices such as doors or locks because they protect assets and thus are a greater target for intercept attacks. To understand why timed transactions are effective it is important to understand the nature of intercept attacks: + +1. The initiator node sends an initial message directed to the target node. +2. An attacker intercepts the message and holds it, preventing the message from reaching the target. +3. Since the initiator did not receive a message back from the target, the initiator sends another message. +4. The attacker intercepts this second message and sends the first message to the target, keeping the second message for later use. +5. The target receives the first message as if it were arriving from the initiator node, sending a confirmation response to the initiator node and, unknowingly, the attacker. + +The problem lies in the second message; since the target never received the second message, the attacker now has a valid message to use at its convenience. The message may elicit a response from the target node such as “unlock” or “open door,” which means that the network now has a breach in security. By establishing a maximum period to receive a message back, a timed transaction effectively guards against intercept attacks. The attacker can no longer hold a message to use at its convenience, as the message will expire after a set time. + +Although timed transactions are important in guarding against attacks, they increase the complexity of a network since they need more actions. Therefore, they are only recommended for use on transactions that give access to valuable information. + +### Timed Write Transactions + +A Timed Write Transaction consists of the following sequence of actions: + +1. **Timed Request Action** - Sets the time interval to send a Write Request Action. +2. **Status Response Action** - Confirms the transaction and time interval. +3. **Write Request Action** - Requests three items: + + 1. List of tuples (each tuple is called a write request) containing the path and data to be modified. + 2. Timed request flag indicating if the transaction is timed. + 3. Suppress response flag. + + If the transaction is timed and a timed request flag is set, the initiator must also send a timeout: the number of milliseconds the transaction remains open, during which the next action to be received is still valid. +4. **Write Response Action (OPTIONAL)** - A list of paths or error codes for every write request. Like a Read Transaction Status Response, a Write Response is not sent if the suppress response flag is set. + +### Untimed Write Transactions + +An Untimed Write Transaction requires only the Write Request Action and the Write Response Action Timed Write Transaction since there is no time interval that needs to be set or confirmed. + +### Write Transaction Restrictions + +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 + +![Diagram of a Timed Invoke Interaction](resources/timed-invoke-interaction.jpg) + +An initiator invokes command(s) on a target’s cluster(s) through Invoke Interactions. An Invoke Interaction consists of either a Timed or Untimed Invoke Transaction, just like a Write Interaction consists of a Timed or Untimed Write Transaction. + +Just like a Timed Write Transaction, a Timed Invoke Transaction consists of the following steps: + +1. **Timed Request Action** - Sets the time interval to send a Write Request Action. +2. **Status Response Action** - Confirms the transaction and time interval. +3. **Invoke Request Action** - Requests four items: + + 1. List of paths to cluster commands (each item in the list is an invoke command which may optionally contain argument(s) for the command). + 2. Timed request flag. + 3. Suppress response flag. + 4. Interaction ID: Integer to match the Invoke Request to its corresponding Invoke Response. + + An Invoke Request initiating a timed Invoke Transaction must also send a timeout just like a timed Write Transaction. + +4. **Invoke Response (OPTIONAL)** - Target responds by sending back the interaction ID and a list of invoke responses: command responses and statuses for each invoke request. Like a Write Response, an Invoke Response is not sent if the suppress response flag is set + +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 + +![Diagram of a Subscription Interaction](resources/subscription-interaction.jpg) + +An initiator uses a Subscription Interaction to automatically receive periodic Report Data Transactions from the target. This creates a relationship between the initiator and target, which are referred to respectively as the subscriber and publisher after the subscription has been made. + +Subscription Interactions include two transactions types: A Subscribe Transaction and Report Transaction. + +### Subscribe Transaction + +The Subscribe Transaction is as follows: + +1. **Subscribe Request Action** - Requests three items: + + 1. Min interval floor (minimum interval between Data Reports). + 2. Max interval ceiling (maximum interval between Data Reports). + 3. Request for attributes and/or events to be reported. + +2. **Subscribe Request Action** - A Report Data Action containing the first batch of data, known as the Primed Published Data. +3. **Status Response Action** - Acknowledges the Report Data Action. +4. **Subscribe Response Action** - Finalizes the subscription ID (an integer that acts as an identifier for the subscription) and the min interval floor and max interval ceiling. Indicates a successful subscription between the subscriber and publisher. + +### Report Transaction + +After a successful subscription, Report Transactions are sent to the subscriber. There are two types of Report Transactions: non-empty and empty. + +1. **Non-empty** + + 1. Report Data Action - Reports data and/or events with the SuppressResponse flag set to FALSE + 2. Status Response - Indicates a successful report or an error, the latter of which ends the interaction + +2. **Empty** + + 1. Report Data Action - A report that has no data or events with the SuppressResponse flag set to TRUE, meaning no Status Response. + +### Subscription Interaction Restrictions + +Subscription Interactions have a few restrictions. + +- First, the Subscribe Request and Subscribe Response actions are unicast-only, meaning an initiator cannot subscribe to more than one target simultaneously. +- Second, Report Data Actions in the same Subscription Interaction must have the same subscription ID. +- Third, a subscription may be ended if the subscriber responds to a Report Data Action with an “INACTIVE_SUBSCRIPTION” status or if the subscriber does not receive a Report Data Action within the max interval ceiling. The latter connotes that the publisher may end a subscription by not sending Report Data Actions. + +## Relating Matter to Zigbee + +The Matter Interaction Model originates from Chapter 2 in the Zigbee Cluster Library found here: [https://groups.csa-iot.org/wg/members-all/document/23019](https://groups.csa-iot.org/wg/members-all/document/23019); the Interaction model extends this by abstracting interactions from other layers (security, transport, message format, encoding). The Interaction Model fills in gaps in the Zigbee Cluster Library identified by the Matter Data Model Tiger Team, adding Multi-Element Message support, Synchronized Reporting, reduce message types in commands and actions, complex data type support in all messages, Events, and interception attack. + +## Matter Specifications + +More information on the Matter Interaction Model can be found in Chapter 8 of Matter Core Specifications [Specifications Download Request - CSA-IOT](https://csa-iot.org/developer-resource/specifications-download-request/). diff --git a/docs/silabs/general/FUNDAMENTALS_INTRO.md b/docs/silabs/general/FUNDAMENTALS_INTRO.md new file mode 100644 index 00000000000000..264310fc76180f --- /dev/null +++ b/docs/silabs/general/FUNDAMENTALS_INTRO.md @@ -0,0 +1,73 @@ +# Introduction to Matter + +## Why Matter? + +The Connectivity Standards Alliance (CSA) seeks to enable smart home devices to be secure, reliable, and interoperable with other Internet of Things (IoT) devices, regardless of manufacturer. One of the biggest pain points of smart home devices is the various application-layer implementations that limit the compatibility of different smart home devices. Therefore, Matter was adopted so that matter-enabled devices, under the same standard, provide a better experience for both the manufacturers and users. + +While Matter was created to make the IoT seamless and effortless for users, it is important to acknowledge the complexity involved under the surface. Matter leverages a range of tools to enable seamless and secure connectivity within an IoT system. Understanding these tools is crucial for a comprehensive overview of this technology. + +## Matter Enablement + +Matter implements the Application Layer of the Open Systems Interconnection (OSI) model. It builds on the lower layers, such as the transport and network layers, to enable reliable communication between nodes. + +Matter may sit on top of two prominent connectivity technologies: Thread and Wi-Fi. Thread is a low-power wireless mesh networking protocol that facilitates reliable communication between nodes. It enables extended coverage and reliable connections to improve the overall performance of IoT ecosystems. + +Matter is an IPv6-based protocol that utilizes transport layer protocols like TCP/UDP to facilitate network addressing and reliable transmission of data packets, respectively. Due to this, Matter is compatible with multiple connectivity options (such as Thread and Wi-Fi). This flexibility allows Matter-enabled devices to communicate over various network protocols, ensuring broad compatibility and integration with different networking technologies. + +The true power of Matter lies in its commitment to interoperability. Industry leaders such as Google, Apple, Amazon, and Samsung Smart Things have implemented Matter in their IoT devices, fostering wider adoption from other manufacturers. Matter also supports bridging from other existing technologies, such as Zigbee, Bluetooth® Mesh and Z-Wave. This allows already existing IoT technology to be integrated into an interoperable environment. The compatibility and seamless integration across brands create a unified ecosystem where your smart devices work harmoniously. + +![The Matter Ecosystem](resources/ecosystem.jpg) + +## Matter Network Architecture + +In theory, Matter can sit on top of any IPv6-bearing network. However in practice, the Matter specifications solely focus on three link layer technologies, enabling Matter to run on Ethernet, Wi-Fi, and Thread 802.15.4 networks. As mentioned above, one of the great benefits of Matter is its flexibility, especially when it comes to network configuration. The Matter protocol can operate without a globally-routable IPv6 infrastructure and allows the flexibility of having multiple Matter networks run over the same set of constituent IP Networks. + +Two common underlying network topologies are commonly used in Matter. The first is known as a Single Network topology, where Matter runs solely over one Network. This means the Matter Network could run over one 802.15.4 Thread network or over a Wi-Fi network. In this scenario all Matter devices are connected to the same single logical network. + +![Single network topology](resources/single-network-topology.png) + +The other, more common, network topology is the star network, which consists of multiple peripheral networks joined together by a central hub network. If a peripheral network is used it must be directly joined to a hub via one or more border routers. A border router (or an edge router) is a special router that can provide routing services between two IP Subnets, effectively acting as a bridge between the two different networks. This enables a lot of flexibility and interoperability between various home networks that can all be interconnected. + +![Star network topology](resources/star-network-topology.png) + +Regardless of the Network topology being used, Matter has a concept of Fabrics. A Matter Fabric is a security domain that contains a collection of nodes. These nodes can be identified and can communicate with each other within the context of that security domain. Each Matter Fabric has a unique Node ID for each node within the fabric and has a unique Fabric ID. Any Matter device can be a part of multiple Matter fabrics, and in turn will have multiple associated Node IDs / Fabric IDs depending on the fabric it is communicating with. + + Below is a table of some basic Identifiers that are commonly used in Matter to identify and communicate with nodes on the fabric. + +| **Identifiers** | **Definition** | +|-----------------|----------------| +| Fabric | 64 bit number that uniquely identifies the Matter fabric. | +| 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. | +| 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. | + +## Matter Layered Architecture + +Matter is split up into a layered architecture to help separate the different responsibilities and encapsulate various pieces of the protocol stack. The following diagram shows the various interactions between the Matter application stack layers as defined by the Matter CSA specification. For implementation purposes the last four layers are handled as a Messaging Layer and a Transport layer. + +![Stack layer interactions](resources/stack-layer-interactions.png) + +- The **Application Layer** of the Matter stack is the highest layer, and corresponds to the high-level logic of the device. The user application is built on the unified data model, which helps improve interoperability. +- The **Data Model** layer corresponds to how the data and action elements support the functionality of the application, such as the defines of the elements, namespaces for endpoints, clusters, and attributes in the application. +- The **Interaction Model** handles, as the name suggests, the interactions between the nodes and is responsible for how data is transferred between nodes. Both the Data Model and Interaction Model are inherited from the well-known dotdot standard used by Zigbee. +- The **Action Framing** layer is where the interactions are transformed into a message payload. +- The **Security Layer** takes the payload and encrypts and appends the packet with a MAC (Message authentication code). +- From the security layer, the packet transfers down to the Transport layer to what the CSA refers to as the **Message Framing and Routing** layer. This updates the payload with the necessary routing information such as fabric and Node ID. +- Finally the packet is sent to the **Transport and IP Framing** layer, from which the payload is sent through the IP network either through TCP (which is not yet currently supported) or Matter's Message Reliability Protocol, a software layer on top of UDP, for IP management of the data. Note that the IP Framing in Matter is handled by the Networking Protocol stack to handle this. + +Once the data is received on a peer device, it travels up the Matter Protocol stack in reverse and delivers the message to the **Application** layer. + +## Matter Security + +As mentioned before, one of the main benefits of using Matter is the enhanced security that it offers. Matter offers security at many layers throughout the network. Many security features are integrated into commissioning a Matter device onto an existing network. Matter requires all devices to have a device-specific passcode that delivers "proof of ownership" to commissioning devices and requires all devices to have immutable credentials that can be cryptographically verified to indicate that the joining devices are Matter-certified devices. In fact, the network credentials are only given to the Matter device after the device has been authenticated and verified. This helps keep the Matter network secure from foreign and unsecure devices, significantly improving the overall network security. Furthermore, Matter enables encryption and authentication to all unicast messages, as well as providing relay protection. Below is a list of commonly-used Matter security terms. + +| **Concepts** | **Definition** | +|--------------|----------------| +| **DAC (Device Attestation Certificate)** | This is an immutable certificate of credentials that can be cryptographically verified to confirm that the device is a certified Matter device. | +| **PASE (Passcode Authentication Session Establishment)** | This process at the Commissioning stage uses a passcode provided out-of-band (like a device's QR code) to commission a Matter device on the network. | +| **CASE (Certificate Authentication Session Establishment)** | This process at the Operational stage establishes and provides an authentication key exchanged between two devices. | + +More detailed information on Matter security can be found in [Matter Security Documentation](./SECURITY.md) and [Matter Commissioning Documentation](COMMISSIONING.md). diff --git a/docs/silabs/general/HARDWARE_REQUIREMENTS.md b/docs/silabs/general/HARDWARE_REQUIREMENTS.md index 1dece8d9f14fb9..281395b3b88186 100644 --- a/docs/silabs/general/HARDWARE_REQUIREMENTS.md +++ b/docs/silabs/general/HARDWARE_REQUIREMENTS.md @@ -139,6 +139,9 @@ The following boards are supported for the Matter over Wi-Fi demos and developme - 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) - WF200 - WF200 / Single Band Wi-Fi Expansion Board / 2.4GHz - [SLEXP8022A](https://www.silabs.com/development-tools/wireless/wi-fi/wf200-wifi-expansion-kit) @@ -149,16 +152,25 @@ The following boards are supported for the Matter over Wi-Fi demos and developme ## 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 MCU is dedicated -for peripheral and application-related processing (Matter), while the ThreadArch® runs the +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 Wireless processor 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: -- **Wi-Fi SoC boards** +- **Wi-Fi SoC boards:** - - SiWx917 / SLWSTK6006A / Wireless Starter Kit - - [SiWx917](https://www.silabs.com/wireless/wi-fi/siwx917-wireless-socs) +- 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 + + **Note:** + Refer [SiWx917 SoC](https://www.silabs.com/wireless/wi-fi/siwx917-wireless-socs) for more details ## Additional Matter over Wi-Fi Hardware Requirements diff --git a/docs/silabs/general/OT_SLEEPY_END_DEVICE.md b/docs/silabs/general/OT_SLEEPY_END_DEVICE.md index 680f8c39d97dd6..5e2009b76f3c7b 100644 --- a/docs/silabs/general/OT_SLEEPY_END_DEVICE.md +++ b/docs/silabs/general/OT_SLEEPY_END_DEVICE.md @@ -1,86 +1,99 @@ -# Matter Sleepy End Devices over OpenThread +# Matter Intermittently Connected Devices over OpenThread -This page explains how Matter OpenThread Sleepy End devices (SEDs) work and how to configure an SED example. +This page explains how Matter OpenThread Intermittently Connected Devices (ICDs) work and how to configure an ICD example. ## Overview -Matter provides a Sleepy End Device (SED) operating mode to extend the battery life of a power-limited devices. -This operating mode leverages OpenThread functionalities to enhance the provided Matter features. -Matter Sleepy functionalities currently focus on allowing an application to define the interval of time where a device is asleep. +Matter provides an Intermittently Connected Device (ICD) operating mode to extend the battery life of power-limited devices. +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. ## Operating Modes -SEDs have two operating modes, Idle and Active. +ICDs have two operating modes, Idle and Active. An ICD alternates normally between the Idle mode and Active mode based on the `IdleModeInterval` and `ActiveModeInterval` respectively -- _Active Mode_ sets the SED into a fast-polling interval for maximum responsiveness when the Node is engaged in ongoing communication, such as an active exchange. -The SLEEPY_ACTIVE_INTERVAL parameter communicates the maximum sleep interval of a node in active mode. +When the device is in _Active Mode_, the ICD is set into a fast-polling interval for maximum responsiveness. +The `CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL` parameter communicates the maximum sleep interval of a node in active mode. -- _Idle mode_, or slow-polling, sets the maximum time an SED will sleep before polling. -This parameter affects both the minimum power consumption and maximum latency. The SLEEPY_IDLE_INTERVAL parameter communicates the maximum sleep interval of a node in idle mode. +Any of the following device states will start or keep the ICD in _Active Mode_: + - A commissioning window is open + - An exchange context is awaiting a response or ack + - The fail-safe is armed. + +Any of the following events can trigger the start of the _Active Mode_ interval or extend it by one `ActiveModeThreshold`: + - A Message needs to be Sent. + - A Message was received. + - An implemented User action occurred. -A device determines if it is in Active or Idle mode based on whether it has at least one open exchange in the message layer. -As long as the device has one open exchanges, it will remain in Active mode and poll its associated OpenThread router at the fast-polling interval. -Once all exchanges are closed, the device will switch operating modes to Idle Mode. +Once the active mode is triggered, the ICD stays in this mode for a minimum duration of `ActiveModeInterval` +When the active interval has elapsed and none of the aforementioned states are active, the device will switch its operating mode to the Idle Mode. -When a device is in _Idle mode_, it will poll its associated router at its slow-polling interval to see if another device has tried to communicate with it while it was sleeping. -If the OpenThread router has an outstanding message for the SED, the SED will enter its Active polling mode to process the message. +In _Idle mode_, the ICD will poll its associated router at its slow-polling interval to see if another device has tried to communicate with it while it was sleeping. +If no event occurs, the ICD stays in its idle mode for the entirety of the `IdleModeInterval`. +The `CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL` parameter communicates the slow-polling interval and therefore the maximum sleep interval of the node in idle mode. This parameter affects both the minimum power consumption and maximum latency. ## Thread Communication -To receive message that were sent while the SED was sleeping, SED relies on its associated Thread router to buffer any incoming messages. -The Thread router will send all buffered messages to the SED when the SED polls the router at the end of its slow-polling interval. +In order to receive messages that were sent while the ICD was sleeping, the ICD relies on its associated Thread router which buffers any incoming messages. +The Thread router will send all buffered messages to the ICD when it polls the router at the end of its slow-polling interval. ## Configuration -Matter exposes three defines that can be set to configure the SLEEPY_ACTIVE_INTERVAL, SLEEPY_IDLE_INTERVAL and SLEEPY_ACTIVE_THRESHOLD parameters. +Matter exposes some defines to configure the ICD mode intervals and the polling intervals of the openthread stack in both Idle and Active modes. | Parameter Name | Define | Description | Default Value | Maximum allowed Value | | - | - | - | - | - | -| SLEEPY_IDLE_INTERVAL | CHIP_DEVICE_CONFIG_SED_IDLE_INTERVAL | Maximum node sleep interval when in idle mode. | 30000 ms | <= 1 hour| -| SLEEPY_ACTIVE_INTERVAL | CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL | Maximum node sleep interval when in active mode. | 200 ms | <= 1 hour| -| SLEEPY_ACTIVE_THRESHOLD | CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD | Minimum amount the node SHOULD stay awake after network activity. | 1000 ms | NA | +| IdleModeInterval | CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL | Maximum interval in seconds the server can stay in idle mode. | 600 s | 64800 s | +| ActiveModeInterval | CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL | Minimum interval in milliseconds the server typically will stay in active mode | 1000 ms | NA | +| ActiveModeThreshold | CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD | Minimum amount of time in milliseconds the server typically will stay active after network activity when in active mode. | 500 ms | NA | +| 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 | ### Usage -The default values for the these defines for the Silabs platform are located in `src/platform/silabs/CHIPDevicePlatformConfig.h`. +The default values for these defines for the Silabs platform is split in two files: + +In `src/platform/silabs/CHIPPlatformConfig.h` you will find the ICD cluster related default defines; ```c++ -/** - * CHIP_DEVICE_CONFIG_SED_IDLE_INTERVAL - * - * The maximum amount of time in milliseconds that the sleepy end device will use as an idle interval. - * This interval is used by the device to periodically wake up and poll the data in the idle mode. - */ -#ifndef CHIP_DEVICE_CONFIG_SED_IDLE_INTERVAL -#define CHIP_DEVICE_CONFIG_SED_IDLE_INTERVAL chip::System::Clock::Milliseconds32(SL_OT_IDLE_INTERVAL) +#ifndef CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL +#define CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL SL_IDLE_MODE_INTERVAL +#endif // CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL + +#ifndef CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL +#define CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL SL_ACTIVE_MODE_INTERVAL +#endif // CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL + +#ifndef CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD +#define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD SL_ACTIVE_MODE_THRESHOLD +#endif // CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD +``` + +and `src/platform/silabs/CHIPDevicePlatformConfig.h` is where the openthread polling intervals default are set. + +```c++ +#ifndef CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL +#define CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL chip::System::Clock::Milliseconds32(SL_OT_IDLE_INTERVAL) #endif // CHIP_DEVICE_CONFIG_SED_IDLE_INTERVAL -/** - * CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL - * - * The minimum amount of time in milliseconds that the sleepy end device will use as an active interval. - * This interval is used by the device to periodically wake up and poll the data in the active mode. - */ -#ifndef CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL -#define CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL chip::System::Clock::Milliseconds32(SL_OT_ACTIVE_INTERVAL) +#ifndef CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL +#define CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL chip::System::Clock::Milliseconds32(SL_OT_ACTIVE_INTERVAL) #endif // CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL - -/** - * CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD - * - * The minimum amount of time Minimum amount the sleepy end device will stay awake after network activity. - */ -#ifndef CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD -#define CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD chip::System::Clock::Milliseconds32(SL_ACTIVE_MODE_THRESHOLD) -#endif // CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD ``` + The default values for the defines previously shown are located `third_party/silabs/efr32_sdk.gni`. ```bash - # ICD Configuration flags - sl_ot_idle_interval_ms = 30000 # 30s Idle Intervals - sl_ot_active_interval_ms = 200 # 500ms Active Intervals - sl_active_mode_threshold = 1000 # 1s Active mode threshold + # ICD Openthread Configuration flags + sl_ot_idle_interval_ms = 15000 # 15s Idle Intervals + sl_ot_active_interval_ms = 200 # 200ms Active Intervals + + # ICD Matter Configuration flags + 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 ``` There are two methods with which you can change these defaults values. @@ -89,14 +102,16 @@ The first method is by adding these defines to `CHIPProjectConfig.h` file of you For the lighting-app, the file is `examples/lighting-app/silabs/efr32/include/CHIPProjectConfig.h`. ```c++ -#define CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD -#define CHIP_DEVICE_CONFIG_SED_ACTIVE_INTERVAL -#define CHIP_DEVICE_CONFIG_SED_ACTIVE_THRESHOLD +#define CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL chip::System::Clock::Milliseconds32() +#define CHIP_DEVICE_CONFIG_ICD_SLOW_POLL_INTERVAL chip::System::Clock::Milliseconds32() +#define CHIP_CONFIG_ICD_IDLE_MODE_INTERVAL +#define CHIP_CONFIG_ICD_ACTIVE_MODE_INTERVAL +#define CHIP_CONFIG_ICD_ACTIVE_MODE_THRESHOLD ``` The second method is by adding arguments to the build command. Here is an example building the EFR32MG24 BRD4186C with different values. ```bash -./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32 out/lighting-app BRD41686C sl_ot_idle_interval_ms=1000 sl_ot_active_interval_ms=200 sl_active_mode_threshold=5000 --sed +./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32 out/lighting-app BRD41686C sl_ot_idle_interval_ms=10000 sl_ot_active_interval_ms=200 sl_idle_mode_interval_ms = 300000 sl_active_mode_interval_ms=5000 sl_active_mode_threshold_ms=1000 --icd ``` If both methods of changing the default values are used, the defines added to the `CHIPProjectConfig.h` take precedence on the build arguments. @@ -105,17 +120,23 @@ If both methods of changing the default values are used, the defines added to th ### Enabling Sleepy Functionalities -To build an OpenThread SED example, two conditions must be met: 1) The following macro must be defined : `CHIP_DEVICE_CONFIG_ENABLE_SED` and 2) the example must use the MTD OpenThread libraries to be able to leverage OpenThread Sleepy functionalities. +To build an OpenThread ICD example, three conditions must be met: + 1) The Intermittently Connected Device cluster must be enabled as a server on the end device application. + 2) The following macro must be defined : `CHIP_CONFIG_ENABLE_ICD_SERVER`. + *This can be set with gn build argument `chip_enable_icd_server=true`* + 3) The example must use the MTD OpenThread libraries to be able to leverage OpenThread Sleepy functionalities. + +Adding the preset `--icd` to your build command will ensure that conditions 2 and 3 are met to enable icd functionalities. This of course only works on sample apps that respect the first condition. The Lock and Light-switch sample applications are configured with the ICD cluster enabled. -The `--sed` macro can be added to the build command to enable sleepy functionalities. Here is an example to build the light-switch-app as a SED for the EFR32MG24 BRD4186C. +Here is an example to build the light-switch-app as an ICD for the EFR32MG24 BRD4186C. ```bash -./scripts/examples/gn_efr32_example.sh ./examples/light-switch-app/efr32/ ./out/light-switch-app_SED BRD4186C --sed +./scripts/examples/gn_efr32_example.sh ./examples/light-switch-app/efr32/ ./out/light-switch-app_SED BRD4186C --icd ``` ### Minimal Power Consumption -Simply enabling Sleepy functionalities does not give the application the best power consumption. +Simply enabling ICD functionalities does not give the application the best power consumption. By default, several features that increase power consumption are enabled in the example applications. The following set of features increase power consumption. @@ -123,8 +144,8 @@ The following set of features increase power consumption. - OpenThread CLI - LCD and Qr Code -To achieve the most power-efficient build, add these build arguments to the build command to disable all power-consuming features. +To achieve the most power-efficient build, add the following build arguments to the build command to disable all power-consuming features. ```bash -./scripts/examples/gn_efr32_example.sh ./examples/light-switch-app/efr32/ ./out/light-switch-app_SED BRD4186C --sed --low-power +./scripts/examples/gn_efr32_example.sh ./examples/light-switch-app/efr32/ ./out/light-switch-app_ICD BRD4186C --icd --low-power ``` \ No newline at end of file diff --git a/docs/silabs/general/SOFTWARE_REQUIREMENTS.md b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md index df85b717d3cc12..60adf01f7797f9 100644 --- a/docs/silabs/general/SOFTWARE_REQUIREMENTS.md +++ b/docs/silabs/general/SOFTWARE_REQUIREMENTS.md @@ -150,13 +150,7 @@ Pre-Built RS9116 firmware is available in the github repository under `third_par Before you run the demo or development on the SiWx917 please be sure that you update the SiWx917 firmware. -The WiseMCU Combo SDK package is only available to Alpha customers. Please contact Silicon Labs support. - -The WiseMCU Combo SDK package version used in this release is **A.1.0.0.0.23**. - -On obtaining the package, extract it, rename the folder as `wisemcu-wifi-bt-sdk` and copy it in the github repository under `third_party/silabs`. - -Pre-Built SiWx917 firmware is available under `third_party/silabs/wisemcu-wifi-bt-sdk/connectivity_firmware` +Pre-Built SiWx917 firmware is available 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. diff --git a/docs/silabs/general/resources/communication-examples.jpg b/docs/silabs/general/resources/communication-examples.jpg new file mode 100644 index 00000000000000..c8cc2bf6616486 Binary files /dev/null and b/docs/silabs/general/resources/communication-examples.jpg differ diff --git a/docs/silabs/general/resources/devices-fabrics.jpg b/docs/silabs/general/resources/devices-fabrics.jpg new file mode 100644 index 00000000000000..51a43bc1133af8 Binary files /dev/null and b/docs/silabs/general/resources/devices-fabrics.jpg differ diff --git a/docs/silabs/general/resources/ecosystem.jpg b/docs/silabs/general/resources/ecosystem.jpg new file mode 100644 index 00000000000000..e4e4f76d5b1d04 Binary files /dev/null and b/docs/silabs/general/resources/ecosystem.jpg differ diff --git a/docs/silabs/general/resources/endpoint-types.jpg b/docs/silabs/general/resources/endpoint-types.jpg new file mode 100644 index 00000000000000..73f5ea19d22649 Binary files /dev/null and b/docs/silabs/general/resources/endpoint-types.jpg differ diff --git a/docs/silabs/general/resources/interaction-structure.jpg b/docs/silabs/general/resources/interaction-structure.jpg new file mode 100644 index 00000000000000..26b379b425afa3 Binary files /dev/null and b/docs/silabs/general/resources/interaction-structure.jpg differ diff --git a/docs/silabs/general/resources/matter-layers.jpg b/docs/silabs/general/resources/matter-layers.jpg new file mode 100644 index 00000000000000..e4e4f76d5b1d04 Binary files /dev/null and b/docs/silabs/general/resources/matter-layers.jpg differ diff --git a/docs/silabs/general/resources/node-overview.jpg b/docs/silabs/general/resources/node-overview.jpg new file mode 100644 index 00000000000000..8ceea07239c9c4 Binary files /dev/null and b/docs/silabs/general/resources/node-overview.jpg differ diff --git a/docs/silabs/general/resources/read-interaction.jpg b/docs/silabs/general/resources/read-interaction.jpg new file mode 100644 index 00000000000000..fb9250bf927a5e Binary files /dev/null and b/docs/silabs/general/resources/read-interaction.jpg differ diff --git a/docs/silabs/general/resources/single-network-topology.png b/docs/silabs/general/resources/single-network-topology.png new file mode 100644 index 00000000000000..d2920f6d550b81 Binary files /dev/null and b/docs/silabs/general/resources/single-network-topology.png differ diff --git a/docs/silabs/general/resources/stack-layer-interactions.png b/docs/silabs/general/resources/stack-layer-interactions.png new file mode 100644 index 00000000000000..bc069b9552cd12 Binary files /dev/null and b/docs/silabs/general/resources/stack-layer-interactions.png differ diff --git a/docs/silabs/general/resources/star-network-topology.png b/docs/silabs/general/resources/star-network-topology.png new file mode 100644 index 00000000000000..e53a2ee3b89733 Binary files /dev/null and b/docs/silabs/general/resources/star-network-topology.png differ diff --git a/docs/silabs/general/resources/subscription-interaction.jpg b/docs/silabs/general/resources/subscription-interaction.jpg new file mode 100644 index 00000000000000..af8cd1df93d13b Binary files /dev/null and b/docs/silabs/general/resources/subscription-interaction.jpg differ diff --git a/docs/silabs/general/resources/timed-invoke-interaction.jpg b/docs/silabs/general/resources/timed-invoke-interaction.jpg new file mode 100644 index 00000000000000..0094105181a9df Binary files /dev/null and b/docs/silabs/general/resources/timed-invoke-interaction.jpg differ diff --git a/docs/silabs/general/resources/timed-write-interaction.jpg b/docs/silabs/general/resources/timed-write-interaction.jpg new file mode 100644 index 00000000000000..24929d12f498b2 Binary files /dev/null and b/docs/silabs/general/resources/timed-write-interaction.jpg differ diff --git a/docs/silabs/index.rst b/docs/silabs/index.rst index f2caae736bcf56..cd7f06b1550224 100644 --- a/docs/silabs/index.rst +++ b/docs/silabs/index.rst @@ -10,13 +10,12 @@ Welcome to Silicon Labs' Matter documentation! :maxdepth: 1 :caption: Contents: - ./OVERVIEW.md - ./NEW_FEATURES.md + User's Guide Overview <./OVERVIEW.md> + Matter New Features <./NEW_FEATURES.md> ./nav_1_overview ./nav_2_prereq ./nav_4_thread ./nav_5_wifi ./unify/index - ./dev/vscode/index ./nav_3_general ./nav_6_faq diff --git a/docs/silabs/nav_1_overview.rst b/docs/silabs/nav_1_overview.rst index e64731a8ff9063..a16abe63088f34 100644 --- a/docs/silabs/nav_1_overview.rst +++ b/docs/silabs/nav_1_overview.rst @@ -8,6 +8,9 @@ Matter Overview .. toctree:: + ./general/FUNDAMENTALS_INTRO.md + ./general/FUNDAMENTALS_DATA_MODEL.md + ./general/FUNDAMENTALS_INTERACTION_MODEL.md ./general/COMMISSIONING.md ./general/OT_SLEEPY_END_DEVICE.md ./general/OTA_BOOTLOADER.md diff --git a/docs/silabs/nav_3_general.rst b/docs/silabs/nav_3_general.rst index 58a60c84628e07..c0b8df4a705eed 100644 --- a/docs/silabs/nav_3_general.rst +++ b/docs/silabs/nav_3_general.rst @@ -4,15 +4,17 @@ Developer Reference .. toctree:: :maxdepth: 2 - ./general/CODE_SIZE_SAVINGS.md - ./general/COMMIT_HASHES.md - ./general/CUSTOM_MATTER_DEVICE.md - ./general/FIND_RASPI.md - ./general/FLASH_SILABS_DEVICE.md - ./general/FLASH_SILABS_SiWx917_SOC_DEVICE.md - ./general/MATTER_ICD.md - ./general/ZAP.md - ./general/WIRESHARK.md - ./general/EP.md - ./general/GATT.md - ./general/PINTOOL.md + Code Savings Guide <./general/CODE_SIZE_SAVINGS.md> + Commit Hash Reference <./general/COMMIT_HASHES.md> + Custom Matter Device <./general/CUSTOM_MATTER_DEVICE.md> + Find Your Raspberry Pi <./general/FIND_RASPI.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> + BLE GATT Configuration <./general/GATT.md> + Hardware Pin Configuration <./general/PINTOOL.md> + ./dev/vscode/index + \ No newline at end of file diff --git a/docs/silabs/nav_4_thread.rst b/docs/silabs/nav_4_thread.rst index 466cdc4ed6c0e4..d1c3376318c7f3 100644 --- a/docs/silabs/nav_4_thread.rst +++ b/docs/silabs/nav_4_thread.rst @@ -4,9 +4,9 @@ Matter Over Thread .. toctree:: :maxdepth: 2 - ./thread/THREAD.md - ./thread/DEMO_OVERVIEW.md - ./thread/RASPI_IMG.md - ./thread/RCP.md - ./thread/BUILD_FLASH_MAD.md - ./thread/CHIP_TOOL.md + Introduction <./thread/THREAD.md> + Demo Overview <./thread/DEMO_OVERVIEW.md> + Setting up the Matter Hub <./thread/RASPI_IMG.md> + Setting up the RCP <./thread/RCP.md> + Build, Flash Matter Device <./thread/BUILD_FLASH_MAD.md> + Using the Matter Hub <./thread/CHIP_TOOL.md> diff --git a/docs/silabs/nav_5_wifi.rst b/docs/silabs/nav_5_wifi.rst index 0a6c869d6d97e3..7cd236847eb744 100644 --- a/docs/silabs/nav_5_wifi.rst +++ b/docs/silabs/nav_5_wifi.rst @@ -4,22 +4,12 @@ Matter Over Wi-Fi .. toctree:: :maxdepth: 2 - ./wifi/DEMO_OVERVIEW.md - ./wifi/RUN_DEMO.md - ./wifi/RUN_DEMO_SiWx917_SoC.md - ./wifi/SiWx917_Enablement_For_Ozone.md - ./wifi/SiWx917_SoC_FWUpdate.md - ./wifi/SiWx917SoC_Factory_Reset.md - ./wifi/using_917_NCP_with_the_Google_Ecosystem_SETUP.md - ./wifi/SW_SETUP.md - ./wifi/WIFI_SLEEPY_END_DEVICE.md - ./wifi/OPENSSL_CERTIFICATE_CREATION.md - ./wifi/MOSQUITTO_SETUP.md - ./wifi/MQTT_EXPLORER_SETUP.md - ./wifi/DIC_Wi-Fi.md - ./wifi/BUILD_DIC.md - ./wifi/BUILD_CHIP_ENV.md - ./wifi/BUILD_PI_ENV.md - ./wifi/AWS_CONFIGURATION_REGISTRATION.md - ./wifi/WIFI_Sleepy_Device_Power_Measurement.md - ./wifi/WIFI_ANDROID.md + Demo Overview <./wifi/DEMO_OVERVIEW.md> + Demo on EFR32 NCP <./wifi/RUN_DEMO.md> + Demo on 917 SoC <./wifi/RUN_DEMO_SiWx917_SoC.md> + Wi-Fi GitHub Development <./wifi/SW_SETUP.md> + nav_5_wifi_917 + nav_5_wifi_dic + Wi-Fi Intermittently Connected Devices (ICD) <./wifi/WIFI_SLEEPY_END_DEVICE.md> + Wi-Fi ICD Power Measurement <./wifi/WIFI_Sleepy_Device_Power_Measurement.md> + Build Chip Tool on Raspi <./wifi/BUILD_PI_ENV.md> diff --git a/docs/silabs/nav_5_wifi_917.rst b/docs/silabs/nav_5_wifi_917.rst new file mode 100644 index 00000000000000..ca5ee248ca2a96 --- /dev/null +++ b/docs/silabs/nav_5_wifi_917.rst @@ -0,0 +1,10 @@ +917 SoC Development +=============================================== + +.. toctree:: + :maxdepth: 2 + + Using Ozone with 917 SoC <./wifi/SiWx917_Enablement_For_Ozone.md> + 917 SoC Firmware Update <./wifi/SiWx917_SoC_FWUpdate.md> + 917 SoC Factory Reset <./wifi/SiWx917SoC_Factory_Reset.md> + 917 SoC with Google Ecosystem <./wifi/using_917_NCP_with_the_Google_Ecosystem_SETUP.md> diff --git a/docs/silabs/nav_5_wifi_dic.rst b/docs/silabs/nav_5_wifi_dic.rst new file mode 100644 index 00000000000000..bc9ea2039870fa --- /dev/null +++ b/docs/silabs/nav_5_wifi_dic.rst @@ -0,0 +1,12 @@ +Wi-Fi Direct Internet Connectivity +=============================================== + +.. toctree:: + :maxdepth: 2 + + What is DIC? <./wifi/DIC_Wi-Fi.md> + How to Build DIC <./wifi/BUILD_DIC.md> + MQTT Server with Mosquitto <./wifi/MOSQUITTO_SETUP.md> + MQTT Server with AWS <./wifi/AWS_CONFIGURATION_REGISTRATION.md> + MQTT Explorer <./wifi/MQTT_EXPLORER_SETUP.md> + Open SSL for MQTT <./wifi/OPENSSL_CERTIFICATE_CREATION.md> diff --git a/docs/silabs/nav_6_faq.rst b/docs/silabs/nav_6_faq.rst index 759e7ddd494335..a7e49ece5e51ed 100644 --- a/docs/silabs/nav_6_faq.rst +++ b/docs/silabs/nav_6_faq.rst @@ -4,5 +4,5 @@ FAQ .. toctree:: :maxdepth: 2 - ./thread/FAQ.md - ./wifi/FAQ.md + Thread FAQ <./thread/FAQ.md> + Wi-Fi FAQ <./wifi/FAQ.md> diff --git a/docs/silabs/thread/CHIP_TOOL.md b/docs/silabs/thread/CHIP_TOOL.md index d14e7e6db621cc..2e8b0c40d86389 100644 --- a/docs/silabs/thread/CHIP_TOOL.md +++ b/docs/silabs/thread/CHIP_TOOL.md @@ -1,4 +1,4 @@ -# Using the Mattertool (chip-tool) +# Using the Matter Hub and the Mattertool (chip-tool) The following commands show how to start a new Thread network from the local OTBR, commission an EFR32 Matter End Device (Matter Accessory Device), and then diff --git a/docs/silabs/thread/RASPI_IMG.md b/docs/silabs/thread/RASPI_IMG.md index b68b00ec9ee970..1ed5a1950d992f 100644 --- a/docs/silabs/thread/RASPI_IMG.md +++ b/docs/silabs/thread/RASPI_IMG.md @@ -68,7 +68,9 @@ for instructions on how to connect your Raspberry Pi to a Wi-Fi network. Once you have connected your Raspberry Pi to the network, you need to connect to your Raspberry Pi over SSH. This requires the IP address of your Raspberry Pi. See [Finding Your Raspberry Pi](../general/FIND_RASPI.md) for more information -on finding the IP address and connecting to the Raspberry Pi by SSH. . +on finding the IP address and connecting to the Raspberry Pi by SSH. + +> Please note that if you are using Wi-Fi to connect to your Raspberry Pi over 2.4 GHz you may have difficulty with commissioning your device. The workaround for this issue is to use either Ethernet or 5GHz to connect to your device in order to reserve the 2.4GHz channel for the Matter commissioning. #### Raspberry Pi Login Credentials diff --git a/docs/silabs/wifi/AWS_CONFIGURATION_REGISTRATION.md b/docs/silabs/wifi/AWS_CONFIGURATION_REGISTRATION.md index feab5d810b6e6d..81c6335eae07f0 100644 --- a/docs/silabs/wifi/AWS_CONFIGURATION_REGISTRATION.md +++ b/docs/silabs/wifi/AWS_CONFIGURATION_REGISTRATION.md @@ -39,3 +39,26 @@ Once done, select `Create`. - Thing name must be unique as it will be used as CLIENT ID. 8. Copy the contents of [AWS_CA CERT](https://www.amazontrust.com/repository/AmazonRootCA1.pem) and create a .pem file to use as a SERVER CERTIFICATE in MQTT Explorer. + +## How to create AWS OTA JOB + +1. Go to AWS Amazon link https://aws.amazon.com/ +2. Login with Amazon Credentials. +3. Click on Services and select `IOT Core`. +4. On Side Bar Menu in Manage Section click on `Remote Actions` and click on `jobs`. +5. Click on Create Job and select Job type as a `Create FreeRTOS OTA update job`. +6. Enter a unique Job name without spaces. +7. In `Devices to update` dropdown select your Certificates which is configured above. for example:- SQA_DIC_C2, SQA_DIC_C3, DIC_2 +8. Select `MQTT` as the protocol for file transfer. +9. In File Section select `New/Previously/Custom` signed gbl file. + - If gbl file is newly created then select `Sign a new file for me` + - If gbl file is already uploaded to AWS then select `Choose a previously signed file` + - If gbl file is modified customly then select `Use my custome signed file` +10. In `Existing code signing profile` select `dic_ota_codesign` . Refer [AWS Code Signing Certificate Creation](https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert.html) +11. For uploading gbl file follow above step `9`. +12. In File upload location in S3 select S3 URL as `ota_demo`. Refer [AWS S3 bucket Creation](https://docs.aws.amazon.com/freertos/latest/userguide/dg-ota-bucket.html) +13. In `Path name of file on device` give any file name (file.txt). +14. Select `ota_demo` as `IAM role` and click on Next. +15. Click on `create job`. + +Note: For more details, Refer [AWS OTA prerequisites](https://docs.aws.amazon.com/freertos/latest/userguide/ota-prereqs.html) \ No newline at end of file diff --git a/docs/silabs/wifi/BUILD_CHIP_ENV.md b/docs/silabs/wifi/BUILD_CHIP_ENV.md deleted file mode 100644 index cf578db3be3f02..00000000000000 --- a/docs/silabs/wifi/BUILD_CHIP_ENV.md +++ /dev/null @@ -1,38 +0,0 @@ -# Building Your Wi-Fi Matter End Device and the chip-tool - -# Build Environment for Linux - -This section will go through the steps required to build the chip-tool for Linux. - -> **Do not execute any commands on this page as ROOT (no _su_ required), unless -> specified** - -
- -## Prepare Linux Packages - -Update the latest packages by typing following commands in terminal: - -```shell -$ sudo apt update -$ sudo apt install -``` -
- -## Prerequisites for Matter (CHIP) project on Linux - -### 1. Installing packages on Ubuntu Laptop/PC - -- Open the Linux terminal from Start menu -- Install required packages on Ubuntu Laptop/PC using the following commands: - - ```shell - $ sudo apt install git gcc g++ pkg-config libssl-dev libdbus-1-dev - libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev - ``` -
-### 2. Building Enviorment - -- To build enviorment follow the `Software setup` and `Compiling chip-tool` steps given in [SW_SETUP](./SW_SETUP.md), - -
diff --git a/docs/silabs/wifi/BUILD_DIC.md b/docs/silabs/wifi/BUILD_DIC.md index 6b35e5c426ba76..6ae8502eeb84c2 100644 --- a/docs/silabs/wifi/BUILD_DIC.md +++ b/docs/silabs/wifi/BUILD_DIC.md @@ -4,31 +4,52 @@ To enable DIC functionality use the `enable_dic=true` flag. ### Here is an example to build the lighting-app with DIC feature for the EFR32MG24 + 9116 ```shell -./scripts/examples/gn_efr32_example.sh silabs_examples/Direct_Internet_lighting-app/efr32 out/rs9116_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true chip_enable_ble_rs911x=true --wifi rs9116 +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs9116_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true chip_enable_ble_rs911x=true --wifi rs9116 ``` ### Here is an example to build the lighting-app with DIC feature for the EFR32MG24 + WF200 ```shell -./scripts/examples/gn_efr32_example.sh silabs_examples/Direct_Internet_lighting-app/efr32/ out/wf200_DIC_light BRD418XX chip_build_libshell=false chip_enable_wifi_ipv4=true enable_dic=true --wifi wf200 +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/wf200_DIC_light BRD418XX chip_build_libshell=false chip_enable_wifi_ipv4=true enable_dic=true --wifi wf200 ``` ### Here is an example to build the lighting-app with DIC for the EFR32MG24 + 917 NCP ```shell -./scripts/examples/gn_efr32_example.sh silabs_examples/Direct_Internet_lighting-app/efr32 out/siwx917_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true chip_enable_ble_rs911x=true --wifi SiWx917 +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true chip_enable_ble_rs911x=true --wifi SiWx917 ``` ### Here is an example to build the lighting-app with DIC for the SiWx917 SoC ```shell -./scripts/examples/gn_efr32_example.sh silabs_examples/Direct_Internet_lighting-app/SiWx917/ out/siwx917_DIC_light BRD4325B enable_dic=true chip_enable_wifi_ipv4=true +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_DIC_light BRD4325B enable_dic=true chip_enable_wifi_ipv4=true ``` + +## Build command with DIC AWS OTA +To enable DIC AWS OTA functionality use the `aws_sdk_ota=true` flag. + +### Here is an example to build the lighting-app with DIC feature for the EFR32MG24 + 9116 + ```shell +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs9116_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true aws_sdk_ota=true chip_enable_ble_rs911x=true --wifi rs9116 + ``` +### Here is an example to build the lighting-app with DIC feature for the EFR32MG24 + WF200 + ```shell +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/wf200_DIC_light BRD418XX chip_build_libshell=false chip_enable_wifi_ipv4=true enable_dic=true aws_sdk_ota=true --wifi wf200 +``` +### Here is an example to build the lighting-app with DIC for the EFR32MG24 + 917 NCP + + ```shell +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_DIC_light BRD418XX disable_lcd=true use_external_flash=false chip_enable_wifi_ipv4=true enable_dic=true aws_sdk_ota=true chip_enable_ble_rs911x=true --wifi SiWx917 + ``` + ## Compile using new/different certificates - Two devices should not use the same Client ID. To use a different Client ID for your second connection do the following: - - If using AWS, Change the following file `examples/platform/silabs/DIC/matter_abs_interface/include/dic_config.h` under `#if USE_AWS` - * Replace `DIC_CLIENT_ID` macro value with your Client ID - * Replace device_certificate and device_key with your device cert and device key. (There is no need to change the CA certificate.) + - If using AWS, Change the following file `examples/platform/silabs/DIC/matter_abs_interface/src/dic_nvm_cert.cpp` under `#if USE_AWS` + * provide device_certificate and device_key with your device cert and device key. (There is no need to change the CA certificate.), Refer [Openssl Certificate Creation](./OPENSSL_CERTIFICATE_CREATION.md) + * provide `DIC_SERVER_HOST` with your hostname + * provide `DIC_CLIENT_ID` macro value with your Client ID in `examples/platform/silabs/DIC/matter_abs_interface/include/dic_config.h` file - The preferred certificate type to use in the application is ECDSA. - - If using mosquitto, change the following file `matter/examples/platform/silabs/DIC/matter_abs_interface/include/dic_config.h` enable `USE_MOSQUITTO` and disable `USE_AWS`. + - If using mosquitto, change the following files `matter/examples/platform/silabs/DIC/matter_abs_interface/src/dic_nvm_cert.cpp` and `examples/platform/silabs/DIC/matter_abs_interface/include/dic_config.h` enable `USE_MOSQUITTO` and disable `USE_AWS`. - Under `#if USE_MOSQUITTO` - * Replace DIC_CLIENT_ID macro value with your Client ID - * Replace ca_certficate, device_certificate and device_key with your ca_certficate, device cert and device key. + * provide DIC_CLIENT_ID macro value with your Client ID + * provide `DIC_SERVER_HOST` with your hostname + * provide ca_certficate, device_certificate and device_key with your ca_certficate, device cert and device key. Refer [Openssl Certificate Creation](./OPENSSL_CERTIFICATE_CREATION.md) + * provide mosquitto client user in `DIC_CLIENT_USER` and password im `DIC_CLIENT_PASS` in `examples/platform/silabs/DIC/matter_abs_interface/include/dic_config.h` file. - The preferred certificate type to use in the application is ECDSA. diff --git a/docs/silabs/wifi/BUILD_PI_ENV.md b/docs/silabs/wifi/BUILD_PI_ENV.md index 5b468f2c950524..c8258af8b079cd 100644 --- a/docs/silabs/wifi/BUILD_PI_ENV.md +++ b/docs/silabs/wifi/BUILD_PI_ENV.md @@ -1,9 +1,4 @@ -# Using the Pre-Built Rasberry Pi "Matter Hub" Image - -When using a Raspberry Pi as a controller in your Matter network you have two -options - -# Building Environment using Raspberry Pi 4 +# Building the Chip-Tool using Raspberry Pi 4 ## To flash the Ubuntu OS onto the SD card: diff --git a/docs/silabs/wifi/DEMO_OVERVIEW.md b/docs/silabs/wifi/DEMO_OVERVIEW.md index 1444f5a07abe68..24adfcddc998da 100644 --- a/docs/silabs/wifi/DEMO_OVERVIEW.md +++ b/docs/silabs/wifi/DEMO_OVERVIEW.md @@ -1,6 +1,6 @@ # Matter over Wi-Fi Demo Overview -This document walks through the steps to build the Matter 1.1 applications, such as lighting, light Switch, window covering, thermostat, door lock and On/Off Plug for +This document walks through the steps to build the Matter 1.1 and 1.2 applications, such as Lighting, Light Switch, Window Covering, Thermostat, Door Lock and On/Off Plug for both the NCP and SoC examples on the EFR32MG24 and SiWx917 SoC boards. A complete list of hardware supported for Wi-Fi is included on the [Hardware Requirements page](../general/HARDWARE_REQUIREMENTS.md). ## Step 1: Matter Wi-Fi Prerequisites @@ -13,20 +13,20 @@ use case. ## Step 2: Building the chip-tool for Wi-Fi -In order to run the Matter Wi-Fi demo you will need to run the chip-tool on one +In order to run the Matter over Wi-Fi demo you will need to run the chip-tool on one of two platforms, either Linux/Mac or Raspberry Pi. -1. [Build Linux Environment](BUILD_CHIP_ENV.md) +1. [Build Linux Environment](SW_SETUP.md) 2. [Build Raspberry-Pi Environment](BUILD_PI_ENV.md) ## Step 3: Building the Matter Accessory Device (MAD) for Wi-Fi -Follow the steps in [Software Setup](SW_SETUP.md) +To build a Matter of 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. -Build command is provided for the SiWx917 SoC processor. +Build commands are also provided for the SiWx917 SoC processor. ## Step 4: Running the Demo @@ -34,6 +34,6 @@ Build command is provided for the SiWx917 SoC processor. [Running the Matter Demo on SiWx917 SoC](RUN_DEMO_SiWx917_SoC.md) -This contains instructions to run the Matter Wi-Fi demo using chip-tool +This contains instructions to run the Matter Wi-Fi demo using the chip-tool running on a Linux Machine (either Laptop or Raspberry Pi) - follow this after successfully executing the above steps. diff --git a/docs/silabs/wifi/DIC_Wi-Fi.md b/docs/silabs/wifi/DIC_Wi-Fi.md index 26fc44dd3258b2..652ba5aa48ebc9 100644 --- a/docs/silabs/wifi/DIC_Wi-Fi.md +++ b/docs/silabs/wifi/DIC_Wi-Fi.md @@ -1,7 +1,7 @@ # Matter Wi-Fi Direct Internet Connectivity - Direct Internet Connectivity (DIC) is a silabs only feature to connect matter devices to proprietary cloud solutions(AWS,GCP,APPLE ...) 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 notifiction on the attribute status. +- Remote user can install the cloud specific application to get the notification on the attribute status. ## Feature Design ![Silicon Labs - DIC design](./images/END_to_END_FLOW.png) @@ -28,9 +28,43 @@ To set up and configure AWS or Mosquitto for DIC support please see the followin ## End-to-End Test of DIC Light Application -- User Setup (MQTT Explorer) - - For executing with efr32, refer to the following: [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md) - - For executing with SiWx917 SoC, refer to the following: [Running the Matter Demo on SiWx917 SoC](RUN_DEMO_SiWx917_SoC.md) -- In MQTT explorer under light/state topic, state of the light will be updated. Below is the screenshot for reference + - Sharing status of device to cloud + - End-to-end command to be executed from chip-tool, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md) + - 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 + - Application status would be updated on the mqtt_explorer UI, as shown in below image. ![DIC STATUS UPDATE](./images/mqtt_explorer_4.png) + + - Control of the device through cloud interface + - Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.md) + - 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 + - Then click `publish` button to execute the command. + ![Silicon Labs - DIC design](./images/control-device-through-cloud.png) + + - Download AWS OTA Image through cloud interface + - Make sure matter device is up and commissioned successfully, refer [Running the Matter Demo on EFR32 hosts](RUN_DEMO.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. + - Then click `publish` button to execute the AWS OTA command. + ![Silicon Labs - DIC design](./images/download-aws-ota-through-cloud.png) \ No newline at end of file diff --git a/docs/silabs/wifi/MQTT_EXPLORER_SETUP.md b/docs/silabs/wifi/MQTT_EXPLORER_SETUP.md index 04a2164fec31af..89b429b7e4ddb1 100644 --- a/docs/silabs/wifi/MQTT_EXPLORER_SETUP.md +++ b/docs/silabs/wifi/MQTT_EXPLORER_SETUP.md @@ -12,7 +12,10 @@ ![Silicon Labs - DIC design](./images/mqtt_explorer_2.png) - - Add topics as shown (#, light/*, test_publish ) + - Add application specific topics as shown below + - For Lighting app, topic to be added (light/*) + - For onoff plug app, topic to be added (light/*) + - For Lock app, topic to be added (lock/*) - 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) @@ -30,7 +33,10 @@ ![Silicon Labs - DIC design](./images/mqtt_explorer_2.png) - - Add topics as shown (#, light/*, test_publish ) + - Add application specific topics as shown below + - For Lighting app, topic to be added (light/*) + - For onoff plug app, topic to be added (light/*) + - For Lock app, topic to be added (lock/*) - MQTT Client ID depends on the certificate set that you will use. - Add the Certificate, following step 5 in [openssl certificate create](./OPENSSL_CERTIFICATE_CREATION.md) diff --git a/docs/silabs/wifi/RUN_DEMO.md b/docs/silabs/wifi/RUN_DEMO.md index 587fe3e01c96a0..b3a2b8fc8af324 100644 --- a/docs/silabs/wifi/RUN_DEMO.md +++ b/docs/silabs/wifi/RUN_DEMO.md @@ -1,9 +1,9 @@ -# Running the Matter Demo over Wi-Fi on EFR32 device +# Running the Matter Demo over Wi-Fi on an EFR32 device ## Flashing Images/Binaries on EFR32MG24 Platform using Ozone, Simplicity Studio, or Simplicity Commander > Note: If you are coming from Simplicity Studio, you may have already installed -> the demo image in Simplicity Studio, in which case you can skip to the +> the demo image using Simplicity Studio, in which case you can skip to the > next step. 1. Plug the WSTK and EFR into the laptop. @@ -11,11 +11,14 @@ 2. Based on the Application being built, make sure to flash proper [bootloader](../general/ARTIFACTS.md) internal or external binaries. 3. Launch Ozone, Simplicity Studio or Simplicity Commander Standalone - this - will display a GUI. If you are not using Ozone, you can follow the - instructions to - [Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md) + will display a GUI. + + If you are using Simplicity Studio or Simplicity Commander, you can follow the general instructions for flashing a Silicon Labs device. + [Flash a Silicon Labs Device](../general/FLASH_SILABS_DEVICE.md). If you are using Ozone, you can follow the instructions below. -4. In 'New Project Wizard': +## Directions for Flashing using Ozone + +1. In 'New Project Wizard': 1. Click the three-dots on the 'Device' tab and select 'Manufacturer' as '`Silicon Labs`' @@ -25,7 +28,7 @@ 4. The 'Register set' tab will get filled automatically 5. 'Peripherals' tab need not be changed as it is optional -5. Click 'Next' - the window that is displayed will contain: +2. Click 'Next' - the window that is displayed will contain: - Serial Number: Read from device - Target Interface: JTAG @@ -34,9 +37,9 @@ - There will be one product in the 'Emulators connected via USB' tab - select this and click 'Next' -6. Click on the 'Silicon Labs device' detected, and then click 'Next' +3. Click on the 'Silicon Labs device' detected, and then click 'Next' -7. You will be asked to select the image/binary to be loaded: click the +4. You will be asked to select the image/binary to be loaded: click the three-dots on that tab and navigate to '`out/rs911x_lighting/BRD41xxx`' through 'Browse', select the file named `chip-efr32-lighting-example.out` and click 'Next'. This is the image built in previous step. @@ -45,22 +48,22 @@ > BRD4186C or BRD4187C, in which case your image will be in a directory > corresponding to that board identifier. -8. Make sure the next screen has 'Initial PC' selected as 'ELF Entry Point' - +5. Make sure the next screen has 'Initial PC' selected as 'ELF Entry Point' - click 'Finish' > Ignore Diagnostics warning about 'FreeRTOS' detected - click 'Continue' -9. Select 'Download and Reset Program' in the dropdown next to the Power button +6. Select 'Download and Reset Program' in the dropdown next to the Power button on the top left of the page > The Silabs chip, EFR32MG24, will be erased and programmed -10. Run the image by clicking the 'Play' button on the top left (or press the F5 +7. Run the image by clicking the 'Play' button on the top left (or press the F5 key) > The output of the EFR32 can be viewed on the console of the Ozone GUI -11. **[Optional]** This step is for when the device has already been flashed and +8. **[Optional]** This step is for when the device has already been flashed and is being used for testing/debug purposes: > If you are restarting the device and do not need to re-flash the EFR diff --git a/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md b/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md index 338f5ca7c5f181..b2c6578fc49f2f 100644 --- a/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md +++ b/docs/silabs/wifi/RUN_DEMO_SiWx917_SoC.md @@ -3,7 +3,7 @@ ## Flashing Images/Binaries on the SiWx917 SoC platform using Ozone or Simplicity Studio and Simplicity Commander > **Note:** -> 1. SiWx917 SoC device support is available in the latest Simplicity Studio and Simplicity Commander(versions 1v14p5 and above). To flash the TA Firmware/Matter application on SiWx917 SoC, +> 1.SiWx917 SoC device support is available in the latest Simplicity Studio and 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` @@ -14,54 +14,41 @@ > 2. Official support for SiWx917 SoC device 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: Left switch should be on the **OFF/LOW**, and right switch should be on the **NORMAL** side. -1. Plug the WSTK and SiWx917 radio board into the laptop. +## Flashing Images/Binaries on the SiWx917 SoC platform using Simplicity Studio + +1. SiWx917 SoC boards supported: + - `BRD4325B - Dual Flash Boards` + - `BRD4325C & BRD4325G - common flash boards` + +2. Plug the WSTK and SiWx917 radio board into the laptop. ![SiWx917 soc Device](./images/SiWx917_Radio_WSTK.png) + +3. For updating SiWx917 SoC Firmware, Refer [Firmware Update](./SiWx917_SoC_FWUpdate.md). -2. Launch the Ozone Debugger. - -3. In the **New Project Wizard**: +3. Go to *Demo Execution - Commissioning a SiWx917 SoC Device using chip-tool for Linux* section, to run the demo with SiWx917 SoC - - Click the three dots (`...`) on the **Device** tab and select the **Manufacturer** as `Silicon Labs`. - - Select the **Device** as `Si917DualFlash`. - - Click **OK**. - - The **Register set** tab is populated automatically. +## Alternate flashing methods for SiWx917 SoC without Simplicity Studio -> **Note:** Entering data in the **Peripherals** tab is optional. - -4. Click **Next**. A window will be displayed showing the following: +1. Flashing the Matter application using commander tool - - Serial Number: Read from device - - Target Interface: JTAG - - Speed: 4MHz - - Host Interface: USB - - One Product in the **Emulators connected via USB** tab - -5. Select the Product shown in the **Emulators connected via USB** tab and click **Next**. - -6. Click the detected **Silicon Labs device** that gets displayed and click **Next**. - -7. Click the three dots (`...`) on that tab, select **Browse** and choose the `*.out` image you wish to flash and run. Click **Next**. + - Download the Pre-built images for SiWx917 SoC Matter Application (_isp.bin/.rps file) from [Matter Artifacts page](../general/ARTIFACTS.md). -> **Note**: The image you select will be the one built using the instructions on the [Building a Matter Wi-Fi End Device page](./SW_SETUP.md). - -8. Make sure the next screen has **Initial PC** selected as `Read from Base Address Vector Table` and click **Finish**. - -9. A Diagnostics Warning may be displayed about FreeRTOS being detected. Click **Continue**. - -10. Select **Download and Reset Program** in the dropdown next to the **Power** button on the top-left hand corner of the page. - -11. The SiWx917 SoC device will be erased and programmed. - -12. Click **Reset Program to main (F4)** next to the **Play/Pause** button on the top-left hand corner of the page. + - Refer [Flashing MATTER Application Using Commander](../general/FLASH_SILABS_DEVICE.md) + + - Go to *Demo Execution - Commissioning a SiWx917 SoC Device using chip-tool for Linux* section, to run the demo with SiWx917 SoC -> **Note**: This will reset the MCU after flashing the application. - -13. Run the image by clicking the **Resume/Halt** button on the top-left hand corner of the page (or press the **F5** key). +2. 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) + + - Go to *Demo Execution - Commissioning a SiWx917 SoC Device using chip-tool for Linux* section, to run the demo with SiWx917 SoC > **Note:** -> 1. The output of the SiWX917 SoC application will be displayed on the Ozone terminal or J-Link RTT Client. -> 2. The RTT Client is provided with Ozone and does not have to be downloaded separately. +1. SiWx917 SoC Common flash boards are not supported by Ozone. +2. To enable RTT logs, download **JlinkDevices.xml** file from the [Matter Artifacts page](../general/ARTIFACTS.md) and install in the Jlink installation path. ## Demo Execution - Commissioning a SiWx917 SoC Device using chip-tool for Linux @@ -85,12 +72,12 @@ > **Note:** > 1. The Node ID used here is `1122`. This will be used in future commands. > 2. The below given steps (3, 4, 5) are for Lighting-app, use app specific commands if you are using any other application. - + 3. To turn **on** the LED on the SiWx917: ```shell $ out/standalone/chip-tool onoff on 1122 1 ``` - + 4. To turn **off** the LED on the SiWx917: ```shell $ out/standalone/chip-tool onoff off 1122 1 @@ -100,7 +87,7 @@ ```shell $ out/standalone/chip-tool onoff read on-off 1122 1 ``` - + If you are having difficulty getting the chip-tool to commission the device successfully, refer to the troubleshooting information on the [Running the Matter Demos over Wi-Fi on EFR32 hosts page](./RUN_DEMO.md). diff --git a/docs/silabs/wifi/SW_SETUP.md b/docs/silabs/wifi/SW_SETUP.md index 37f84833dd2a12..0c2383c6bdbf94 100644 --- a/docs/silabs/wifi/SW_SETUP.md +++ b/docs/silabs/wifi/SW_SETUP.md @@ -1,4 +1,4 @@ -# Software Setup and Preliminaries +# Building a Wi-Fi End Device for Matter in GitHub ## Software Setup @@ -71,8 +71,7 @@ you are using, select the appropriate command to build. > **Note:** > 1. The build commands given below are for the following applications: `lighting-app`, `lock-app`, `light-switch-app`, `window-app` -> 2. In order to build applications other than those mentioned in # 1, (such as `thermostat-app`), substitute the appropriate application name & -substitute `/silabs/efr32/` with `/efr32/` after the application name. +> 2. In order to build applications other than those mentioned in # 1, (such as `thermostat-app`), substitute the appropriate application name after the application name. > 3. Additional examples (such as `onoff-plug-app`) are provided in the [/examples](https://github.com/SiliconLabs/matter/blob/latest/examples/) or [/silabs_examples](https://github.com/SiliconLabs/matter/blob/latest/silabs_examples/) directory. > 4. In order to build applications from [/silabs_examples](https://github.com/SiliconLabs/matter/blob/latest/silabs_examples/) (such as `onoff-plug-app`), substitute `examples` with `silabs_examples`. > 5. To build for EFR32MG24 host processors, substitute `BRD41xxx` in the build command with the appropriate MG24 board number @@ -90,26 +89,33 @@ $ Build command for EFR32MG24 + RS9116: ```shell -$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32 out/rs911x_lighting BRD41xxx disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 |& tee out/rs911x_lighting.log +$ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting BRD41xxx disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 |& tee out/rs911x_lighting.log ``` Build command for EFR32MG24 + SiWx917: ```shell -$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32 out/siwx917_lighting BRD41xxx disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi SiWx917 |& tee out/siwx917_lighting.log +$ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/siwx917_lighting BRD41xxx disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi SiWx917 |& tee out/siwx917_lighting.log ``` Build command for EFR32MG24 + WF200: ```shell -$ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32 out/wf200_lighting BRD41xxx chip_build_libshell=false --wifi wf200 |& tee out/wf200_lighting.log +$ ./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: +Build command for SiWx917 SoC processor(dual flash): ```shell -./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/SiWx917 out/SiWx917_lighting BRD4325B |& tee out/soc_lighting.out +./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 +``` + > **Note:** > 1. LED and button features are enabled for SiWx917 SoC. > 2. LCD and QR code features are not enabled for SiWx917 SoC. @@ -122,7 +128,7 @@ Enable or disable the lighting application's features using the following flags. 1. `rs91x_wpa3_only` : Use this flag while building to enable wpa3 mode in rs91x wifi chip. ```shell - $ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32/ out/rs911x_lighting BRD41xxx rs91x_wpa3_only=true --wifi rs9116 |& tee out/rs911x_lighting.log + $ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting BRD41xxx rs91x_wpa3_only=true --wifi rs9116 |& tee out/rs911x_lighting.log ``` > **Note:** @@ -132,12 +138,12 @@ Enable or disable the lighting application's features using the following flags. 2. `segger_rtt_buffer_size_up` : Flag to get the complete logs without truncation. ```shell - $ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32/ out/rs911x_lighting BRD41xxx segger_rtt_buffer_size_up=2068 --wifi rs9116 |& tee out/rs911x_lighting.log + $ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting BRD41xxx segger_rtt_buffer_size_up=2068 --wifi rs9116 |& tee out/rs911x_lighting.log ``` 3. `show_qr_code=false` : Use this flag while building to disable QR code. ```shell - $ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32/ out/rs911x_lighting BRD41xxx show_qr_code=false --wifi rs9116 |& tee out/rs911x_lighting.log + $ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting BRD41xxx show_qr_code=false --wifi rs9116 |& tee out/rs911x_lighting.log ``` > **Note:** > 1. QR code is enabled by default for all except MG24 @@ -146,7 +152,7 @@ Enable or disable the lighting application's features using the following flags. 4. `chip_enable_wifi_ipv4` : Use this flag while building to enable IPV4 (disabled by default). ```shell - ./scripts/examples/gn_efr32_example.sh examples/lighting-app/silabs/efr32/ out/rs911x_lighting BRD41xxx chip_enable_wifi_ipv4=true --wifi rs9116 |& tee out/rs911x_lighting.log + ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/rs911x_lighting BRD41xxx chip_enable_wifi_ipv4=true --wifi rs9116 |& tee out/rs911x_lighting.log ``` The generated software can be found in diff --git a/docs/silabs/wifi/SiWx917SoC_Factory_Reset.md b/docs/silabs/wifi/SiWx917SoC_Factory_Reset.md index 977d8ec6fbdd4e..8b49dc02bba5ec 100644 --- a/docs/silabs/wifi/SiWx917SoC_Factory_Reset.md +++ b/docs/silabs/wifi/SiWx917SoC_Factory_Reset.md @@ -1,9 +1,13 @@ # SiWx917 SoC Factory Reset -1. Press the BTN0 on WSTK for about 6-7 seconds. The LED0 will flash 5 times. +## SiWx917 SoC Factory Reset without Ozone -2. You will get "Target Connection Lost" pop-up on Ozone, click **YES**. +1. Press the BTN0 on WSTK for about 6-7 seconds. The LED0 will flash 5 times and board will reboot. + +## SiWx917 SoC Factory Reset with Ozone + +1. You will get "Target Connection Lost" pop-up on Ozone, click **YES**. ![Silicon Labs - SiWx917 SoC Ozone Target Connection Lost](./images/SiWx917_SoC_TargetConnectionLost.png) -3. Select **Attach to Running Program** in the dropdown next to the **Power** button on the top-left hand corner of the page. +2. Select **Attach to Running Program** in the dropdown next to the **Power** button on the top-left hand corner of the page. ![Silicon Labs - SiWx917 SoC Ozone Target Connection Lost](./images/SiWx917SoC_AttachToRunningProgram.png) diff --git a/docs/silabs/wifi/SiWx917_Enablement_For_Ozone.md b/docs/silabs/wifi/SiWx917_Enablement_For_Ozone.md index f77b8d47593e99..c77e3420391948 100644 --- a/docs/silabs/wifi/SiWx917_Enablement_For_Ozone.md +++ b/docs/silabs/wifi/SiWx917_Enablement_For_Ozone.md @@ -1,5 +1,7 @@ # Ozone Environment Setup for a SiWx917 SoC Device +**Note:** +- Ozone debugging support is enabled for SiWx917 Dual flash boards only - Auto detection of SiWx917 SoC device in Ozone is not enabled. - Follow the steps to manually configure the SiWx917 SoC with Latest Ozone Debugger. @@ -17,6 +19,44 @@ ![Silicon Labs - SiWx917 SoC](./images/SiWx917_Target_Ozone.png) -3. If the above steps are successful, you can download and flash the Matter application - - - [Flashing the Application with Ozone](./RUN_DEMO_SiWx917_SoC.md) +3. In the **New Project Wizard**: + + - Click the three dots (`...`) on the **Device** tab and select the **Manufacturer** as `Silicon Labs`. + - Select the **Device** as `Si917DualFlash`. + - Click **OK**. + - The **Register set** tab is populated automatically. + +**Note:** Entering data in the **Peripherals** tab is optional. + +4. Click **Next**. A window will be displayed showing the following: + + - Serial Number: Read from device + - Target Interface: JTAG + - Speed: 4MHz + - Host Interface: USB + - One Product in the **Emulators connected via USB** tab + +5. Select the Product shown in the **Emulators connected via USB** tab and click **Next**. + +6. Click the detected **Silicon Labs device** that gets displayed and click **Next**. + +7. Click the three dots (`...`) on that tab, select **Browse** and choose the `*.out` image you wish to flash and run. Click **Next**. + +8. Make sure the next screen has **Initial PC** selected as `Read from Base Address Vector Table` and click **Finish**. + +9. A Diagnostics Warning may be displayed about FreeRTOS being detected. Click **Continue**. + +10. Select **Download and Reset Program** in the dropdown next to the **Power** button on the top-left hand corner of the page. + +11. The SiWx917 SoC device will be erased and programmed. + +12. Click **Reset Program to main (F4)** next to the **Play/Pause** button on the top-left hand corner of the page. + +**Note**: This will reset the MCU after flashing the application. + +13. Run the image by clicking the **Resume/Halt** button on the top-left hand corner of the page (or press the **F5** key). + +**Note:** +1. The output of the SiWX917 SoC application will be displayed on the Ozone terminal or J-Link RTT Client. +2. The RTT Client is provided with Ozone and does not have to be downloaded separately. + diff --git a/docs/silabs/wifi/SiWx917_SoC_FWUpdate.md b/docs/silabs/wifi/SiWx917_SoC_FWUpdate.md index f3f4221cfd82fe..e7afd38281d3da 100644 --- a/docs/silabs/wifi/SiWx917_SoC_FWUpdate.md +++ b/docs/silabs/wifi/SiWx917_SoC_FWUpdate.md @@ -1,9 +1,16 @@ -# Updating SiWx917 SoC Firmware using Tera Term +# Updating SiWx917 SoC Connectivity Firmware -> Please note that the method of updating the SiWx917 SoC firmware listed below is considered a legacy mode of operation. You may also update the SiWx917 SoC firmware using Simplicity Commander. For instructions on how to do this please consider [Running Demo on the SiWx917SoC](./RUN_DEMO_SiWx917_SoC.md) +Download the recommended version of firmware before you start with the update process from the [Matter Artifacts page](../general/ARTIFACTS.md) -## Steps to update the firmware on SiWx917 SoC radio board +## Steps to update the firmware on SiWx917 SoC radio board using Simplicity Studio +1. Refer to the Simplicity Studio documentation on flashing a device [Upgrading SiWx917 Connectivity firmware](http://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-building-and-flashing/flashing) + + +## Steps to update the firmware on SiWx917 SoC radio board using Simplicity Commander +1. Refer to the Simplicity Commander documentation on flashing a device [Upgrading SiWx917 Connectivity firmware with Simplicity Commander](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf) + +## Steps to update the firmware on SiWx917 SoC radio board using Tera Term 1. Connect power cable to radio board. 2. Jumper should be connected. @@ -26,6 +33,4 @@ 8. Once the image transfer is complete, type "c" to continue to check the upgrade sequence, once the upgrade is successful , Enter "1" for the Enter next command , once text "Loading..." appears type (Ctrl + \ + c) to exit from Kermit and "q" to quit and return to the terminal. -9. Reset both the buttons to Off/Low state. - -10. Flash and run the application - [Running the Matter Demo on SiWx917 SoC](RUN_DEMO_SiWx917_SoC.md). +9. Reset 917 SoC switch positions: Left switch should be on the **OFF/LOW**, and right switch should be on the **NORMAL** side diff --git a/docs/silabs/wifi/WIFI_ANDROID.md b/docs/silabs/wifi/WIFI_ANDROID.md deleted file mode 100644 index f9ad4dcec08072..00000000000000 --- a/docs/silabs/wifi/WIFI_ANDROID.md +++ /dev/null @@ -1,34 +0,0 @@ -# Commissioning Wi-Fi Device using Android - -Commissioning can be done using an Android Phone through the following steps. - -Download pre-built application from the -[Matter Artifacts page](../general/ARTIFACTS.md). - -1. Open the .apk that is installed in the Android mobile. -1. Connect the Android phone to the Wi-Fi Access Point that is going to be used. -1. Run the installed CHIP app. -1. Click 'Provision Chip device with Wi-Fi'. -1. The app will bring up the camera: - - Hold the camera to the LCD on the WSTK board - - Scan the QR Code displayed on LCD screen of EFR32 MG12 Platform -1. Input the SSID/Passphrase of the Wi-Fi Access Point on the next screen. You will see messages (Toasts) pop up - saying that the App is 'Scanning', then 'Pairing', followed by 'Commissioning Done' -1. Once commissioning is completed, the app will go back to the original/home - screen -1. Click on 'Light ON/OFF & Level Cluster' -1. You can then bring up the On/Off Cluster and send On/Off Commands (Toggle - does not work as required currently) - this will cause LED 1 on the WSTK to - change states - -If the Commissioning is not successful, try rebooting your mobile and try -again. - -Once commissioning is completed, if you want to repeat the test, follow these -steps: - -- Disconnect the system (EFR32MG12 + RS9116) from power. -- Power up the system again - this should cause the LCD to turn on and the QR - code to show up -- Press the BTN0 button and keep it pressed for about 1 min - this should - cause LED0 and LED1 to turns ON and OFF for 3 times. You can then release - the button diff --git a/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md b/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md index 5c297d5ae0d47c..e8d3d2518ea930 100644 --- a/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md +++ b/docs/silabs/wifi/WIFI_SLEEPY_END_DEVICE.md @@ -1,10 +1,9 @@ -# Matter Sleepy End Devices over Wi-Fi - -This page explains how Matter Wi-Fi Sleepy End devices (SEDs) work and how to configure a Matter Wi-Fi SED example. +# Matter Intermittently Connected Devices (ICD) (Formerly Sleepy End Devices) +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 a Sleepy End Device (SED) 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 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. 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. @@ -32,7 +31,7 @@ In the Legacy power save mode, when the Wi-Fi station receives a beacon with its 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. -The Wi-Fi station continues to retrieve buffered frames using the PS-Poll frame until there are no more buffered frames and the More Data subfield is set to 0. The Wi-Fi station goes back into the sleep aterwards. +The Wi-Fi station continues to retrieve buffered frames using the PS-Poll frame until there are no more buffered frames and the More Data subfield is set to 0. The Wi-Fi station goes back into the sleep afterwards. A Wi-Fi station can enter sleep mode after sending a Null frame to the AP with the power management (PM) bit set. From then on, the AP will store all packets destined to the Wi-Fi station in a per-device queue and sets the TIM field in the beacon frame to indicate that packets destined for the Wi-Fi station have been queued. @@ -49,22 +48,22 @@ The Wi-Fi station in Power Save mode wakes up to receive the DTIM beacon and che ## Building -### Enabling Sleepy Functionalities +### Enabling ICD Functionalities -To enable sleepy functionality, the `enable_sleepy_device` build argument needs to be set to true. It will enable the following macro: `CHIP_DEVICE_CONFIG_ENABLE_SED` +To enable ICD functionality, the `chip_enable_icd_server` build argument needs to be set to true. It will enable the following macro: `CHIP_CONFIG_ENABLE_ICD_SERVER` -Here is an example to build the lock-app as an SED for the EFR32MG24 + RS9116. +Here is an example to build the lock-app as an ICD for the EFR32MG24 + RS9116. ```bash -./scripts/examples/gn_efr32_example.sh examples/lock-app/silabs/efr32/ out/rs9116/lock_sleep BRD41xxx enable_sleepy_device=true disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/rs9116/lock_sleep BRD41xxx chip_enable_icd_server=true disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 ``` -Here is an example to build the lock-app as an SED for the EFR32MG24 + RS917 (NCP). +Here is an example to build the lock-app as an ICD for the EFR32MG24 + RS917 (NCP). ```bash -./scripts/examples/gn_efr32_example.sh examples/lock-app/silabs/efr32/ out/SiWx917/lock_sleep BRD41xxx enable_sleepy_device=true disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi SiWx917 +./scripts/examples/gn_silabs_example.sh examples/lock-app/silabs/ out/SiWx917/lock_sleep BRD41xxx chip_enable_icd_server=true disable_lcd=true use_external_flash=false chip_enable_ble_rs911x=true --wifi SiWx917 ``` -Here is an example to build the lock-app as an SED for the EFR32MG24 + WF200. +Here is an example to build the lock-app as an ICD for the EFR32MG24 + WF200. ```bash -./scripts/examples/gn_efr32_example.sh examples/lock-app/silabs/efr32/ out/wf200_lock_sleep BRD41xxx enable_sleepy_device=true chip_build_libshell=false --wifi wf200 +./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. @@ -81,5 +80,5 @@ 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_efr32_example.sh examples/lock-app/silabs/efr32/ out/SiWx917/lock_sleep BRD41xxx enable_sleepy_device=true disable_lcd=true show_qr_code=false use_external_flash=false chip_build_libshell=false chip_enable_ble_rs911x=true --wifi SiWx917 +./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 diff --git a/docs/silabs/wifi/images/control-device-through-cloud.png b/docs/silabs/wifi/images/control-device-through-cloud.png new file mode 100644 index 00000000000000..346e903ec69d7c Binary files /dev/null and b/docs/silabs/wifi/images/control-device-through-cloud.png differ diff --git a/docs/silabs/wifi/images/download-aws-ota-through-cloud.png b/docs/silabs/wifi/images/download-aws-ota-through-cloud.png new file mode 100644 index 00000000000000..ccc13db4d4bef1 Binary files /dev/null and b/docs/silabs/wifi/images/download-aws-ota-through-cloud.png differ diff --git a/provision/README.md b/provision/README.md index 5b58097435a53b..4c1c4ed94da5e6 100644 --- a/provision/README.md +++ b/provision/README.md @@ -6,18 +6,18 @@ parameters. To facilitate the transition between development and production, thi [Custom Part Manufacturing Service](https://www.silabs.com/services/custom-part-manufacturing-service). Most of the parameters are stored once during the manufacturing process, and shall not change during the lifetime of the device. During runtime, two interfaces are used to pull the authentication data from permanent storage: -* [CommissionableDataProvider](https://github.com/project-chip/connectedhomeip/blob/master/src/include/platform/CommissionableDataProvider.h), implemented as [EFR32DeviceDataProvider](https://github.com/project-chip/connectedhomeip/blob/master/examples/platform/silabs/efr32/EFR32DeviceDataProvider.cpp) -* [DeviceAttestationCredsProvider](https://github.com/project-chip/connectedhomeip/blob/master/src/credentials/DeviceAttestationCredsProvider.h), implemented as [SilabsDeviceAttestationCreds](https://github.com/project-chip/connectedhomeip/blob/master/examples/platform/silabs/SilabsDeviceAttestationCreds.h) +* [CommissionableDataProvider](../src/include/platform/CommissionableDataProvider.h), implemented as [SilabsDeviceDataProvider](../examples/platform/silabs/SilabsDeviceDataProvider.cpp) +* [DeviceAttestationCredsProvider](../src/credentials/DeviceAttestationCredsProvider.h), implemented as [SilabsDeviceAttestationCreds](../examples/platform/silabs/SilabsDeviceAttestationCreds.h) The provisioning script on this folder now supercedes the following tools: -* [Credentials Example](https://stash.silabs.com/projects/WMN_TOOLS/repos/matter/browse/silabs_examples/credentials) -* [Factory Data Provider](https://github.com/project-chip/connectedhomeip/tree/master/scripts/tools/silabs) +* [Credentials Example](https://github.com/SiliconLabs/matter/tree/release_1.1.0-1.1/silabs_examples/credentials) +* [Factory Data Provider](../scripts/tools/silabs/README.md) ## Provisioned Data The Commissionable Data includes Serial Number, Vendor Id, Product Id, and the Setup Payload (typicallty displayed in the QR), while the Attestation Credentials includes the Certificate Declaration (CD), the Product Attestation Intermediate (PAI) certificate, and the DAC (Device Attestation Certificate). -During commissioning, Matter devices perform a Password Authenticated Key Exchange using the SPAKE2+ protocol. The SPAKE2+ verifier is pre-calculated [using an external tool](https://github.com/project-chip/connectedhomeip/tree/master/src/tools/spake2p). +During commissioning, Matter devices perform a Password Authenticated Key Exchange using the SPAKE2+ protocol. The SPAKE2+ verifier is pre-calculated [using an external tool](../src/tools/spake2p/README.md). The passcode is used to derive a QR code, typically printed on the label, or displayed by the device itself. The QR code contains the pre-computed setup payload, which allows the commissioner to establish a session with the device. The parameters required to generate and validate the session keys are static and stored in NVM3. @@ -54,7 +54,7 @@ The directory structure is as follows: The `provision.py` file is the main script used to load all the required data on the Matter device. This script requires: * [Simplicity Commander](https://community.silabs.com/s/article/simplicity-commander?language=en_US) * [SEGGER J-Link](https://www.segger.com/downloads/jlink/) -* [SPAKE2+ generator](https://github.com/project-chip/connectedhomeip/tree/master/src/tools/spake2p) +* [SPAKE2+ generator](../src/tools/spake2p/README.md) * [PyLink](https://pylink.readthedocs.io/en/latest/index.html) sudo pip3 install ecdsa @@ -201,7 +201,7 @@ python ./provision.py -c config/develop.json ## Attestation Files The `--generate` option instructs the `provider.py` script to generate test attestation files with the given Vendor ID, and Product ID. -These files are generated using [the chip-cert tool](https://github.com/project-chip/connectedhomeip/tree/master/src/tools/chip-cert), +These files are generated using [the chip-cert tool](../src/tools/chip-cert/README.md), and stored under the `provision/temp` folder. To generate the certificates manually: @@ -216,7 +216,7 @@ To generate the certificates manually: ``` NOTE: The commissioning fails if the commissioner do not recognize the root certificate (PAA). -When using [chip-tool](https://github.com/project-chip/connectedhomeip/tree/master/examples/chip-tool), +When using [chip-tool](../examples/chip-tool), you can use the `--paa-trust-store-path` to enabled the PAA certificates for testing purposes. ## Example