diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 44470a612f42c7..e52ea37f231bae 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 @@ -520,6 +531,7 @@ EvalCode EvalCodeWithName EvalFrameDefault EVB +EventLogging evk exceptfds ExchangeContext @@ -592,6 +604,7 @@ GetDeviceInfo GetDns GetIP getManualTests +GetSafeAttributePersistenceProvider getstarted getTests GH @@ -627,6 +640,7 @@ Gv gz gzbf HaloaceticAcidsConcentrationMeasurement +HandleCommand hardcoded hardknott hardwarever @@ -698,6 +712,7 @@ installDebug instantiation integrations IntelliSense +InteractionModelEngine InteractionModelVersion Interoperable introvideos @@ -802,6 +817,7 @@ localhost LocalizationConfiguration localstatedir LockingState +LogEvent loopback LowPower LPC @@ -830,6 +846,7 @@ matterc MatterCustomTrace matterd MatterLock +MatterReportingAttributeChangeCallback matterSdkSourceBuild matterSourceBuildAbiFilters matterUTestLib @@ -1063,6 +1080,7 @@ plaintext PlatformManager PlatformManagerImpl plt +PluginServerCallback png Podman PollControl @@ -1150,6 +1168,8 @@ recommand recommanded recurse regen +registerAttributeAccessOverride +RegisterCommandHandler RelativeHumidityMeasurement RemainAfterExit remoteDeviceId @@ -1159,6 +1179,7 @@ RendezvousParameters RendezVousTest REPL repo +repos req Requestor Requestor's 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