diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 07f3df6b7a9822..a6d2183cfd5ea1 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -17,6 +17,7 @@ ables AccessControl AccessControlEntry accessor +Accessors AccountLogin acdbc ack @@ -31,7 +32,9 @@ AddNOC AddOrUpdateThreadNetwork AddOrUpdateWiFiNetwork addr +AddResponse AddThreadNetwork +AddStatus adk AdministratorCommissioning adoc @@ -97,6 +100,7 @@ att attId attr attrib +AttributeAccessInterface attributeValue attrListName attrMask @@ -256,6 +260,7 @@ clusterAttrs clusterId clusterList clusterListName +ClusterName ClusterObjectTests ClusterRevision ClusterTestGeneration @@ -276,6 +281,8 @@ codelabs ColorControl Comcast Commandline +CommandHandlerInterface +CommandName Commissionable CommissionableDataProvider commissionables @@ -289,6 +296,7 @@ configs configTOTAL ConfigurationManager ConfigurationManagerImpl +conformant connectedhomeip ConnectionData ConnectIP @@ -490,8 +498,11 @@ eg EjQ elftools elock +emberAf emberAfExternalAttributeReadCallback emberAfExternalAttributeWriteCallback +EmberAfInitializeAttributes +emberAfSetDynamicEndpoint EnableNetwork EnableWiFiNetwork endian @@ -521,6 +532,7 @@ EvalCodeWithName EvalFrameDefault EV EVB +EventLogging evk EVSE exceptfds @@ -594,6 +606,7 @@ GetDeviceInfo GetDns GetIP getManualTests +GetSafeAttributePersistenceProvider getstarted getTests GH @@ -629,6 +642,7 @@ Gv gz gzbf HaloaceticAcidsConcentrationMeasurement +HandleCommand hardcoded hardknott hardwarever @@ -700,6 +714,7 @@ installDebug instantiation integrations IntelliSense +InteractionModelEngine InteractionModelVersion Interoperable introvideos @@ -804,6 +819,7 @@ localhost LocalizationConfiguration localstatedir LockingState +LogEvent loopback LowPower LPC @@ -832,6 +848,7 @@ matterc MatterCustomTrace matterd MatterLock +MatterReportingAttributeChangeCallback matterSdkSourceBuild matterSourceBuildAbiFilters matterUTestLib @@ -1065,6 +1082,7 @@ plaintext PlatformManager PlatformManagerImpl plt +PluginServerCallback png Podman PollControl @@ -1152,6 +1170,8 @@ recommand recommanded recurse regen +registerAttributeAccessOverride +RegisterCommandHandler RelativeHumidityMeasurement RemainAfterExit remoteDeviceId @@ -1161,6 +1181,7 @@ RendezvousParameters RendezVousTest REPL repo +repos req Requestor Requestor's diff --git a/build/chip/esp32/esp32_codegen.cmake b/build/chip/esp32/esp32_codegen.cmake index 75cd1f42587469..af943e39fbff30 100644 --- a/build/chip/esp32/esp32_codegen.cmake +++ b/build/chip/esp32/esp32_codegen.cmake @@ -33,6 +33,7 @@ macro(chip_app_component_codegen IDL_NAME) OUTPUTS "app/PluginApplicationCallbacks.h" "app/callback-stub.cpp" + "app/cluster-init-callback.cpp" OUTPUT_PATH APP_GEN_DIR OUTPUT_FILES APP_GEN_FILES ) diff --git a/docs/ERROR_CODES.md b/docs/ERROR_CODES.md index 35dcd05d5bff07..8cd4a4c80940e3 100644 --- a/docs/ERROR_CODES.md +++ b/docs/ERROR_CODES.md @@ -44,6 +44,7 @@ This file was **AUTOMATICALLY** generated by | 26 | 0x1A | `CHIP_ERROR_DUPLICATE_KEY_ID` | | 27 | 0x1B | `CHIP_ERROR_WRONG_KEY_TYPE` | | 28 | 0x1C | `CHIP_ERROR_UNINITIALIZED` | +| 29 | 0x1D | `CHIP_ERROR_INVALID_IPK` | | 30 | 0x1E | `CHIP_ERROR_INVALID_STRING_LENGTH` | | 31 | 0x1F | `CHIP_ERROR_INVALID_LIST_LENGTH` | | 33 | 0x21 | `CHIP_ERROR_END_OF_TLV` | diff --git a/docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md b/docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md new file mode 100644 index 00000000000000..9e34e961ae6d87 --- /dev/null +++ b/docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md @@ -0,0 +1,251 @@ +# New Clusters & Device Types + +The goal of new cluster and device type development is to + +1. write the cluster implementations +2. write the code and supporting material that will allow zap to generate the + appropriate ember layers +3. write the unit tests, test plans and automation scripts that prove the code + correctness and allow these new features to be certified + +Unit tests, test plans and certification tests are covered in the testing +section. This document will concentrate on implementing clusters and device +types in the SDK. + +- Cluster Definition + - XML + - Describes the structures, enums, attributes, commands, events etc. + - Direct translation of the spec into code + - src/app/zap-templates/zcl/data-model/chip/ +- Cluster Implementation + + - Client side - codegen, you write the glue + - Server side - cpp implementation through Ember and / or + AttributeAccessInterface & CommandHandlerInterface + - src/app/clusters/ + - build file: src/app/chip_data_model.gni + - build file uses data from the codegen to auto-populate the cluster + list. + - Follow examples in there to get your code building into the image + when selected in zap + +- Device Type Definitions + - XML defines conformance + - src/app/zap-templates/zcl/data-model/chip/matter-devices.xml + +The following wiki page has a detailed description of how and where to add +cluster and device type definitions so they are picked up properly by ZAP/ember +and the SDK. + +[https://groups.csa-iot.org/wg/matter-tsg/wiki/howto-add-a-new-device-type](https://groups.csa-iot.org/wg/matter-tsg/wiki/howto-add-a-new-device-type) + +Note that the output should also be verified against the spec using the +[.matter parser tools](https://project-chip.github.io/connectedhomeip-doc/guides/matter_idl_tooling.html). + +## ZAP, Ember and Overrides + +- Goal: get zap to understand the new cluster so it can be used on devices + (XML and glue) + +![](../getting_started/img/zap_compiler.png) + +### Cluster definitions and ZAP + +Please see [ZAP](../getting_started/zap.md) for an introduction to ZAP. + +After implementing the changes outlined in the wiki article, your cluster and +device type should show up in zap. you can check this by running zaptool with +any zap file. + +./scripts/tools/zap/run_zaptool.sh + +To ensure the cluster and device type are correctly implemented for ZAP, open +the endpoint configuration and ensure the device type appears in the device type +list. + +![](../getting_started/img/zap3.png) + +Next, check your cluster. The "domain" parameter in the XML controls which group +the cluster is in. It should have all the expected attributes, commands and +events. + +![](../getting_started/img/zap4.png) + +Last, ensure that your attributes have the storage option set appropriately. + +![](../getting_started/img/zap5.png) + +### Cluster implementation - Ember and overrides + +- Ember: layer used to setup/access the endpoints / attributes / commands etc. + on the device + + - The build generates the Ember function signatures and defaults + - The Cluster server code implements callbacks for initialization, + commands, attribute access and event generation + - Interaction Model layer will call ember functions when it receives + incoming interactions for your cluster + +- Overrides + - Ember layer is _generated_ at compile time whereas overrides are + _installed_ at run time + - Overrides are called before the ember layer for attribute access or + command handling + - AttributeAccessInterface & CommandHandlerInterface + - Allow significantly more control, but are more complex + - **UNIT TESTABLE** + - Both allow fall through to the ember layer (if setup in zap) + +#### Cluster Server Initialization + +The following diagram shows the flow of messages coming into the Matter core and +ending in the cluster initialization code. + +![](img/cluster_initialization.png) + +EmberAfInitializeAttributes - ember attribute storage - for all attributes +marked as “RAM” in the zap, sets defaults in the storage +MatterPluginServerCallback - .h is a generated file, .cpp impl is done +in the server cluster code. Use this to setup the cluster and do attribute +overrides registerAttributeAccessOverride - use this if you want to handle +attribute reads and writes externally + +Blue sections can be overridden. + +#### Cluster Server Attributes + +**Two mechanisms** + +- Ember layer +- Override + +**ZAP files and implementation** + +- For attributes marked as **“RAM”** storage in the zap file + - Storage allocated automatically, Ember handles read/write + - Generated “Get” and “Set” functions for each attribute in Accessors.h + (generated file) + - You _CAN_ register an override on the cluster. If you don’t try to + encode the attribute in the override, it will fall through to the + storage. + - If you _DO_ always encode the attribute in the access override + function, you’re wasting space. +- For attributes marked as **“External”** storage in the zap file + - NO storage is allocated, no fall through to ember storage + - NEED to register an access override for these to work + +##### Cluster Server Attributes via Override (read) + +![](img/cluster_attribute_read.png) + +[AttributeAccessInterface::Read()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#L424) + +``` +CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, + AttributeValueEncoder & aEncoder) +{ + // Parse aPath to determine the requested attribute + switch (aPath.mAttributeId) + { + case SomeAttribute::Id: + // Just encode the value + aEncoder.Encode(mSomeValue); + break; + } + // Beware of lists - the need to use EncodeList to have + // chunking handled properly + return CHIP_NO_ERROR; +``` + +#### Cluster Server Attributes via override (write) + +Write are handled using the same path as read, but land in the “Write” function +of the AttributeAccessInterface. + +[AttributeAccessInterface::Write()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#444) + +The attribute handler is responsible for constraint checking and Attribute +persistence + +##### Attribute Persistence + +- When using AttributeAccessInterface, you need to manage any Attributes that + require Persistence. +- This can be done by using GetSafeAttributePersistenceProvider() +- This provides a useful API for Reading & Writing values of any type to the + default Persistence Store + - [src/app/SafeAttributePersistenceProvider.h](https://github.com/project-chip/connectedhomeip/blob/master/src/app/SafeAttributePersistenceProvider.h) + +#### Ember layer read / write + +In the ember layer functions, the ember layer handles the encode and decode. +This can work for simple attributes, but is can be challenging for complex +attribute interactions. The ember layer is also VERY difficult to unit test. + +The ember layer provides callbacks for attribute changes so you can handle them + +``` +void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, + uint8_t type, uint16_t size, uint8_t * value) + +``` + +Take care when using this that the callbacks are implemented in a way that can +be used across examples + +#### Cluster Server Commands + +- As with Attributes, there is an ember layer option, and an override option +- **Override** + - Registered at runtime + - InteractionModelEngine::RegisterCommandHandler + - Implement CommandHandlerInterface +- **Ember** + - static + - emberAfCallback + +![](img/cluster_commands.png) + +##### Command Handler Code + +- CommandHandlerInterface + - Can use HandleCommand function for convenience (sets handled) + - If not, need to set whether the command was handled + - if no, falls through to ember by default + - If entirely handled by this interface, add to + src/app/common/templates/config-data.yaml to disable ember +- Ember interface + - Return true if the command was handled, false to have an invalid command + response returned +- For both + - Need to handle the return to the caller using either AddResponse or + AddStatus in the command handler + - Need to handle constraints checking and return the appropriate status or + response per the spec + +The +[config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml) +file is used to turn off ember command callback generation for clusters with +pure CommandHandlerInterface implementations. + +#### Events and Attribute Subscriptions + +- **Attribute** change reporting + - If you go through the ember storage layer (generated Get/Set functions + on the attribute), this is handled for you + - If you are using an AttributeAccessInterface, you need to tell the + reporting engine that the attribute has changed + - **MatterReportingAttributeChangeCallback** +- **Events** + - No direct ember support + - Call LogEvent function in EventLogging.h + +#### A note on Dynamic Endpoints + +- Dynamic endpoint registration + - ZAP configs are static at compile time + - Can also use dynamic endpoint registration at runtime + - common for bridges + - **emberAfSetDynamicEndpoint** + - If you have your own storage for attributes etc, need to account for + dynamic endpoints as well as static diff --git a/docs/cluster_and_device_type_dev/img/cluster_attribute_read.png b/docs/cluster_and_device_type_dev/img/cluster_attribute_read.png new file mode 100644 index 00000000000000..5f073aca8067a6 Binary files /dev/null and b/docs/cluster_and_device_type_dev/img/cluster_attribute_read.png differ diff --git a/docs/cluster_and_device_type_dev/img/cluster_commands.png b/docs/cluster_and_device_type_dev/img/cluster_commands.png new file mode 100644 index 00000000000000..959774e071b717 Binary files /dev/null and b/docs/cluster_and_device_type_dev/img/cluster_commands.png differ diff --git a/docs/cluster_and_device_type_dev/img/cluster_initialization.png b/docs/cluster_and_device_type_dev/img/cluster_initialization.png new file mode 100644 index 00000000000000..9cf980e3f727fb Binary files /dev/null and b/docs/cluster_and_device_type_dev/img/cluster_initialization.png differ diff --git a/docs/cluster_and_device_type_dev/index.md b/docs/cluster_and_device_type_dev/index.md new file mode 100644 index 00000000000000..6d5cf71edfef1c --- /dev/null +++ b/docs/cluster_and_device_type_dev/index.md @@ -0,0 +1,15 @@ +# Cluster and Device Type development + +The following docs present a guide on how to develop new clusters and device +types in the SDK. + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* + +``` + +- [Cluster and device type development](./cluster_and_device_type_dev.md) diff --git a/docs/getting_started/SDKBasics.md b/docs/getting_started/SDKBasics.md new file mode 100644 index 00000000000000..fee03ae7cd484d --- /dev/null +++ b/docs/getting_started/SDKBasics.md @@ -0,0 +1,99 @@ +# SDK Basics + +## Getting Started + +- SDK Location: + [https://github\.com/project\-chip/connectedhomeip](https://github.com/project-chip/connectedhomeip)\_ +- email _[help@csa\-iot\.org](mailto:help@csa-iot.org)_ to get access to the + other repos and to be added to project\-chip org + +## Basic SDK Architecture + +![](img/SDK_layers.png) + +### Platform Layer + +Platform layer implements the connection to the network stack and the base OS. +Messages flow off the wire into the platform layer, where they are routed into +the platform API for processing by the Matter stack. + +### Platform API + +The platform API defines a common layer to interact with the core. + +### Core + +Core encompasses a huge part of the spec, including all of the the underlying +communication protocols. The goal of the core code is to deliver valid messages +to the ember layer indicating the cluster request and associated endpoint +information. + +### Ember + +The ember layer is a generated layer that implements the composition of ONE +SPECIFIC device. It looks at each message and determines if the device has +implemented the selected attribute or command on the cluster on the selected +endpoint, and then blocks or routes accordingly, based on the implementation and +the access control. + +Valid requests are forwarded on to the cluster implementations to handle and +invalid requests get sent back with an error. Ember layer is the piece that +makes your device your device. Most are generated statically using zap. + +### Cluster implementations + +The cluster implementations are the logic that back the cluster. The cluster +implementation code receives messages from the ember layer to request data model +operations on the cluster (reads / writes / command invokes). They are also +responsible for event generation and attribute change reporting. Simple cluster +logic can be written in the ember callback functions, but more complex cluster +logic is handled in the run-time installed interface layers. + +## SDK Organization (some key bits) + +- docs + - [docs/guides/BUILDING\.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md) - + follow this first + - [docs/guides/chip_tool_guide.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/chip_tool_guide.md) +- examples + - [examples/chip-tool](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool) - + main controller example + - [examples/all-clusters-app](https://github.com/project-chip/connectedhomeip/blob/master/examples/all-cluster-app) - + QA app + - [examples/\](https://github.com/project-chip/connectedhomeip/blob/master/examples) - + Specific Device examples +- scripts + - [bootstrap.sh](https://github.com/project-chip/connectedhomeip/blob/master/scripts/bootstrap.sh) + & + [activate.sh](https://github.com/project-chip/connectedhomeip/blob/master/scripts/activate.sh) - + environment setup + - [build/build_examples.py](https://github.com/project-chip/connectedhomeip/blob/master/scripts/build/build_examples.py) - + build example code + - [tools/zap/run_zaptool.sh](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap/run_zaptool.sh) - + start zap tool + - [tools/zap_regen_all.py](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap_regen_all.py) - + .zap -> .matter +- src + - [controller](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/) - + client side code including python implementation + - [app](https://github.com/project-chip/connectedhomeip/blob/master/src/app) - + base server side code + - [app/clusters](https://github.com/project-chip/connectedhomeip/blob/master/src/app/clusters) - + cluster implementations (.cpp) + - [app/zap-templates/zcl/data-model/chip/](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/) - + cluster definitions (.xml) + - [app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification) - + yaml cert test automation scripts + - [lib/support/](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/) - + Embedded versions of common utilities + - [platform](https://github.com/project-chip/connectedhomeip/blob/master/src/platform) - + platform delegate APIs / implementations + - [include/platform](https://github.com/project-chip/connectedhomeip/blob/master/src/include/platform) - + platform delegate APIs / implementations + - [python_testing](https://github.com/project-chip/connectedhomeip/blob/master/src/python_testing) - + python cert test automation scripts +- zzz_generated/app-common/app-common/zap-generated/\* + - all the generated cluster logic / namespaces +- data_model + - These files are generated and are used to check conformance against the + spec. They should not be manually changed. diff --git a/docs/getting_started/discovery_from_a_host_computer.md b/docs/getting_started/discovery_from_a_host_computer.md new file mode 100644 index 00000000000000..5b02524460ff80 --- /dev/null +++ b/docs/getting_started/discovery_from_a_host_computer.md @@ -0,0 +1,14 @@ +# Device discovery from a Host computer (mDNS Scanning) + +Device discovery for commissioning over the operational network happens over +DNS-SD. DNS-SD is handled over mDNS on WiFi and using an SRP server on a boarder +router for thread. On a computer, you can use the built-in mDNS applications to +discover devices for the purposes of testing. Avahi is the standard mDNS program +for linux, dns-sd is used on macs. + +- Scanning for commissionable devices + - avahi-browse -d local \_matterc.\_udp --resolve + - dns-sd -B \_matterc.\_udp +- Scanning for commissioned devices + - avahi-browse -d local \_matter.\_tcp --resolve + - dns-sd -B \_matter.\_tcp diff --git a/docs/getting_started/img/SDK_layers.png b/docs/getting_started/img/SDK_layers.png new file mode 100644 index 00000000000000..84ecda72153507 Binary files /dev/null and b/docs/getting_started/img/SDK_layers.png differ diff --git a/docs/getting_started/img/ci_raw_logs.png b/docs/getting_started/img/ci_raw_logs.png new file mode 100644 index 00000000000000..84465ab7d19592 Binary files /dev/null and b/docs/getting_started/img/ci_raw_logs.png differ diff --git a/docs/getting_started/img/zap1.png b/docs/getting_started/img/zap1.png new file mode 100644 index 00000000000000..4356cda98e85e5 Binary files /dev/null and b/docs/getting_started/img/zap1.png differ diff --git a/docs/getting_started/img/zap2.png b/docs/getting_started/img/zap2.png new file mode 100644 index 00000000000000..cd73e0417c25ad Binary files /dev/null and b/docs/getting_started/img/zap2.png differ diff --git a/docs/getting_started/img/zap3.png b/docs/getting_started/img/zap3.png new file mode 100644 index 00000000000000..018778c7dceeb4 Binary files /dev/null and b/docs/getting_started/img/zap3.png differ diff --git a/docs/getting_started/img/zap4.png b/docs/getting_started/img/zap4.png new file mode 100644 index 00000000000000..92ab5cce5186b4 Binary files /dev/null and b/docs/getting_started/img/zap4.png differ diff --git a/docs/getting_started/img/zap5.png b/docs/getting_started/img/zap5.png new file mode 100644 index 00000000000000..5ca6908144704b Binary files /dev/null and b/docs/getting_started/img/zap5.png differ diff --git a/docs/getting_started/img/zap6.png b/docs/getting_started/img/zap6.png new file mode 100644 index 00000000000000..0901e225fbff46 Binary files /dev/null and b/docs/getting_started/img/zap6.png differ diff --git a/docs/getting_started/img/zap_compiler.png b/docs/getting_started/img/zap_compiler.png new file mode 100644 index 00000000000000..68c1e09395a069 Binary files /dev/null and b/docs/getting_started/img/zap_compiler.png differ diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md new file mode 100644 index 00000000000000..b961701cc98bc8 --- /dev/null +++ b/docs/getting_started/index.md @@ -0,0 +1,16 @@ +# Getting Started + +The following docs are a brief introduction to SDK development. + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* + +``` + +- [SDK Basics](./SDKBasics.md) +- [ZAP](./zap.md) +- [Discover from a host computer](./discovery_from_a_host_computer.md) diff --git a/docs/getting_started/zap.md b/docs/getting_started/zap.md new file mode 100644 index 00000000000000..0177aa8ba4f3a7 --- /dev/null +++ b/docs/getting_started/zap.md @@ -0,0 +1,92 @@ +# ZAP + +The ZAP tool is a GUI tool that is used to generate a .zap file that describes +the endpoint composition of a device. This includes the endpoints on the device, +the clusters and device types on each endpoint, as well as the cluster features, +attributes, commands and events. The .zap file is used by the ZAP compiler along +with the cluster definitions files to generate an ember layer. This happens +automatically as part of the build process, and the ember layer is compiled into +the firmware. + +.matter files are a human-readable version of the .zap that can be used for +review + +![](img/zap_compiler.png) + +## A quick tour + +Run ./scripts/tools/zap/run_zaptool.sh \ to open a file in zap. +Select the Matter format. + +The left hand side shows the endpoint configuration. + +![](img/zap1.png) + +Select the edit button (pencil) on an endpoint to edit it. + +![](img/zap2.png) + +This will open a dialog where you can edit the device types and revisions of +your endpoint. Do not edit the profile ID or network. The profile ID identifies +the zap endpoint as being a matter endpoint, network is a property that only +applies to zigbee products. + +![](img/zap3.png) + +To edit the clusters on an endpoint, select the endpoint. To enable a cluster on +an endpoint, set the "enable" drop down to "server" and click the gear to edit +the cluster + +![](img/zap4.png) + +### Cluster setup + +#### Attributes + +The zap file will list all the available attributes in the cluster. The column +settings are as follows: + +- Enabled - turn this on to enable the attribute on the device. +- Attribute ID - Attribute ID of the attribute from the spec +- Attribute - Attribute name from the spec +- Required - This is set to yes if the attribute is mandatory. Note that some + attributes become mandatory when features or other attributes are enabled. + This will NOT be reflected in the UI. It is up to the device manufacture to + ensure the device is conformant with the specification. Conformance can be + checked using the conformance checker test + [TC_DeviceConformance.py](https://github.com/project-chip/connectedhomeip/blob/master/src/python_testing/TC_DeviceConformance.py) + +- Client/Server - For Matter, all attributes will be server +- Mfg code - applies only to manufacturer specific attributes +- Storage option - determines whether ember allocates storage for the + attribute. The correct value for this field is determined by the cluster + implementation. Clusters that use the ember layer directly will be RAM, + clusters that use the override layer and implement their own storage are + external. Files in the Matter SDK will set these values as appropriate based + on the the cluster implementations and as described in the Matter zap config + document. It is best to leave these values as-is unless you have a specific + reason to override them. + +[//]: + # + "NOTE: Insert a link to the override specification documentation once that is up" + +- Type - type from the spec +- Default - this is different than the "default" set in the spec, and + represents the desired starting value for an attribute IF it is implemented + in the ember layer (RAM storage) + +![](img/zap5.png) + +#### Attribute Reporting + +This does not apply to Matter and is unused. + +#### Commands + +Check off the commands you wish to support. Response commands are required if +the corresponding Request command is supported. ![](img/zap6.png) + +#### Events + +This does not apply to Matter and is unused. diff --git a/docs/index.md b/docs/index.md index f6575ed88a5d7c..12218445600743 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,8 @@ VSCODE_DEVELOPMENT api/index ci-cd/index discussion/index +getting_started/index +cluster_and_device_type_dev/index guides/index style/index examples/index diff --git a/examples/all-clusters-app/esp32/main/CMakeLists.txt b/examples/all-clusters-app/esp32/main/CMakeLists.txt index 623e2ded547abe..f2f432a60d615a 100644 --- a/examples/all-clusters-app/esp32/main/CMakeLists.txt +++ b/examples/all-clusters-app/esp32/main/CMakeLists.txt @@ -28,6 +28,8 @@ set(SRC_DIRS_LIST "${CMAKE_CURRENT_LIST_DIR}" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/zzz_generated/app-common/app-common/zap-generated/attributes" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/zzz_generated/app-common/app-common/zap-generated" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/all-clusters-app/all-clusters-common/src" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/energy-management-app/energy-management-common/src" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/providers" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/platform/esp32/ota" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/platform/esp32/common" @@ -38,9 +40,11 @@ set(SRC_DIRS_LIST "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/util" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/reporting" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/administrator-commissioning-server" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/air-quality-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/test-cluster-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/boolean-state-configuration-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/descriptor" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/energy-evse-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/fault-injection-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/fan-control-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/fixed-label-server" @@ -56,6 +60,7 @@ set(SRC_DIRS_LIST "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/groups-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/color-control-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/operational-credentials-server" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/operational-state-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/mode-select-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/mode-base-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/low-power-server" @@ -90,9 +95,8 @@ set(SRC_DIRS_LIST "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/time-synchronization-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/valve-configuration-and-control-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/dishwasher-alarm-server" - "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/laundry-washer-controls-server" + "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/laundry-washer-controls-server" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/laundry-dryer-controls-server" - "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/examples/all-clusters-app/all-clusters-common/src" "${CMAKE_SOURCE_DIR}/third_party/connectedhomeip/src/app/clusters/electrical-energy-measurement-server" ) diff --git a/examples/android/CHIPTool/app/src/main/java/com/google/chip/chiptool/SelectActionFragment.kt b/examples/android/CHIPTool/app/src/main/java/com/google/chip/chiptool/SelectActionFragment.kt index a597bd934514e7..f935ab37926927 100644 --- a/examples/android/CHIPTool/app/src/main/java/com/google/chip/chiptool/SelectActionFragment.kt +++ b/examples/android/CHIPTool/app/src/main/java/com/google/chip/chiptool/SelectActionFragment.kt @@ -172,7 +172,7 @@ class SelectActionFragment : Fragment() { /** Notifies listener of Scan QR code button click. */ private fun handleScanQrCodeClicked() { - showFragment(BarcodeFragment.newInstance(), false) + showFragment(BarcodeFragment.newInstance()) } /** Notifies listener of Light On/Off & Level Cluster button click. */ @@ -221,24 +221,24 @@ class SelectActionFragment : Fragment() { } private fun handleOTAProviderClicked() { - showFragment(OtaProviderClientFragment.newInstance(), false) + showFragment(OtaProviderClientFragment.newInstance()) } /** Notifies listener of provision-WiFi-credentials button click. */ private fun handleProvisionWiFiCredentialsClicked() { getCallback()?.SetNetworkType(ProvisionNetworkType.WIFI) - showFragment(BarcodeFragment.newInstance(), false) + showFragment(BarcodeFragment.newInstance()) } /** Notifies listener of provision-Thread-credentials button click. */ private fun handleProvisionThreadCredentialsClicked() { getCallback()?.SetNetworkType(ProvisionNetworkType.THREAD) - showFragment(BarcodeFragment.newInstance(), false) + showFragment(BarcodeFragment.newInstance()) } /** Notifies listener of provision-custom-flow button click. */ private fun handleProvisionCustomFlowClicked() { - showFragment(BarcodeFragment.newInstance(), false) + showFragment(BarcodeFragment.newInstance()) } private fun handleGroupSettingClicked() { diff --git a/examples/common/pigweed/rpc_console/py/BUILD.gn b/examples/common/pigweed/rpc_console/py/BUILD.gn index d250129dca13c5..5c74b7b2599544 100644 --- a/examples/common/pigweed/rpc_console/py/BUILD.gn +++ b/examples/common/pigweed/rpc_console/py/BUILD.gn @@ -37,6 +37,7 @@ pw_python_package("chip_rpc") { "$dir_pw_log_tokenized/py", "$dir_pw_protobuf_compiler/py", "$dir_pw_rpc/py", + "$dir_pw_system/py", "$dir_pw_tokenizer/py", "${chip_root}/examples/common/pigweed:attributes_service.python", "${chip_root}/examples/common/pigweed:button_service.python", diff --git a/examples/common/pigweed/rpc_console/py/chip_rpc/console.py b/examples/common/pigweed/rpc_console/py/chip_rpc/console.py index 7880d579fccf52..6d2b06fd73208f 100644 --- a/examples/common/pigweed/rpc_console/py/chip_rpc/console.py +++ b/examples/common/pigweed/rpc_console/py/chip_rpc/console.py @@ -29,35 +29,20 @@ rpcs - used to invoke RPCs device - the serial device used for communication - client - the pw_rpc.Client + client - the HDLC rpc client protos - protocol buffer messages indexed by proto package An example RPC command: - rpcs.chip.rpc.DeviceCommon.GetDeviceInfo() + rpcs.chip.rpc.Device.GetDeviceInfo() + device.rpcs.chip.rpc.Device.GetDeviceInfo() """ - import argparse -import logging -import re import sys -import threading -from collections import namedtuple -from concurrent.futures import ThreadPoolExecutor -from inspect import cleandoc -from typing import Any, BinaryIO, Callable, Collection +from pathlib import Path +from typing import Any, Collection -import pw_cli.log -from chip_rpc.plugins.device_toolbar import DeviceToolbar -from chip_rpc.plugins.helper_scripts import HelperScripts -from pw_console import PwConsoleEmbed, socket_client -from pw_console.__main__ import create_temp_log_file -from pw_console.pyserial_wrapper import SerialWithLogging -from pw_hdlc.rpc import HdlcRpcClient, SelectableReader, SerialReader, default_channels -from pw_rpc import callback_client -from pw_rpc.console_tools.console import ClientInfo, flattened_rpc_completions -from pw_tokenizer import tokens -from pw_tokenizer.database import LoadTokenDatabases -from pw_tokenizer.detokenize import Detokenizer +import pw_system.console +from pw_hdlc import rpc # Protos # isort: off @@ -72,24 +57,6 @@ from thread_service import thread_service_pb2 from wifi_service import wifi_service_pb2 -_LOG = logging.getLogger(__name__) -_DEVICE_LOG = logging.getLogger('rpc_device') - -PW_RPC_MAX_PACKET_SIZE = 256 -SOCKET_SERVER = 'localhost' -SOCKET_PORT = 33000 - -PROTOS = [attributes_service_pb2, - button_service_pb2, - descriptor_service_pb2, - device_service_pb2, - echo_pb2, - lighting_service_pb2, - locking_service_pb2, - ot_cli_service_pb2, - thread_service_pb2, - wifi_service_pb2] - def _parse_args(): """Parses and returns the command line arguments.""" @@ -116,7 +83,7 @@ def _parse_args(): parser.add_argument("--token-databases", metavar='elf_or_token_database', nargs="+", - action=LoadTokenDatabases, + type=Path, help="Path to tokenizer database csv file(s).") group.add_argument('-s', '--socket-addr', @@ -126,227 +93,55 @@ def _parse_args(): return parser.parse_args() -def _start_ipython_raw_terminal() -> None: - """Starts an interactive IPython terminal with preset variables. This raw - terminal does not use HDLC and provides no RPC functionality, this is - just a serial log viewer.""" - local_variables = dict( - LOG=_DEVICE_LOG, - ) - - welcome_message = cleandoc(""" - Welcome to the CHIP Console! - - This has been started in raw serial mode, - and all RPC functionality is disabled. - - Press F1 for help. - """) - - interactive_console = PwConsoleEmbed( - global_vars=local_variables, - local_vars=None, - loggers={ - 'Device Logs': [_DEVICE_LOG], - 'Host Logs': [logging.getLogger()], - 'Serial Debug': [logging.getLogger('pw_console.serial_debug_logger')], - }, - repl_startup_message=welcome_message, - help_text=__doc__, - app_title="CHIP Console", - ) - - interactive_console.hide_windows('Host Logs') - interactive_console.hide_windows('Serial Debug') - interactive_console.hide_windows('Python Repl') - - # Setup Python logger propagation - interactive_console.setup_python_logging() - # Don't send device logs to the root logger. - _DEVICE_LOG.propagate = False - interactive_console.embed() - - -def _start_ipython_hdlc_terminal(client: HdlcRpcClient) -> None: - """Starts an interactive IPython terminal with preset variables.""" - local_variables = dict( - client=client, - channel_client=client.client.channel(1), - rpcs=client.client.channel(1).rpcs, - scripts=HelperScripts(client.client.channel(1).rpcs), - protos=client.protos.packages, - # Include the active pane logger for creating logs in the repl. - LOG=_DEVICE_LOG, - ) - - client_info = ClientInfo('channel_client', - client.client.channel(1).rpcs, client.client) - completions = flattened_rpc_completions([client_info]) - - welcome_message = cleandoc(""" - Welcome to the CHIP RPC Console! - - Press F1 for help. - Example commands: - - rpcs.chip.rpc.Device.GetDeviceInfo() - - LOG.warning('Message appears console log window.') - """) - - interactive_console = PwConsoleEmbed( - global_vars=local_variables, - local_vars=None, - loggers={ - 'Device Logs': [_DEVICE_LOG], - 'Host Logs': [logging.getLogger()], - 'Serial Debug': [logging.getLogger('pw_console.serial_debug_logger')], - }, - repl_startup_message=welcome_message, - help_text=__doc__, - app_title="CHIP Console", - ) - - interactive_console.add_sentence_completer(completions) - interactive_console.add_bottom_toolbar( - DeviceToolbar(client.client.channel(1).rpcs)) - - interactive_console.hide_windows('Host Logs') - interactive_console.hide_windows('Serial Debug') - - # Setup Python logger propagation - interactive_console.setup_python_logging() - # Don't send device logs to the root logger. - _DEVICE_LOG.propagate = False - with client: - interactive_console.embed() - - -def write_to_output(data: bytes, - unused_output: BinaryIO = sys.stdout.buffer, - detokenizer=None): - log_line = data - RegexStruct = namedtuple('RegexStruct', 'platform type regex match_num') - LEVEL_MAPPING = {"I": logging.INFO, "W": logging.WARNING, "P": logging.INFO, - "E": logging.ERROR, "F": logging.FATAL, "V": logging.DEBUG, "D": logging.DEBUG, - "": logging.INFO, "": logging.DEBUG, "": logging.ERROR, - "": logging.INFO, "": logging.WARNING, - "": logging.ERROR, "": logging.DEBUG, - "ERR": logging.ERROR, "DBG": logging.DEBUG, "INF": logging.INFO} - - ESP_CHIP_REGEX = r"(?P[IWEFV]) \((?P