Writing and Updating Clusters

This guide provides a comprehensive walkthrough for creating a new Matter cluster implementation, referred to as a “code-driven” cluster.

Overview of the Process

Writing a new cluster involves the following key stages:

  1. Define the Cluster: Generate or update the cluster definition XML based on the Matter specification.
  2. Implement the Cluster: Write the C++ implementation for the cluster's logic and data management.
  3. Integrate with Build System: Add the necessary files to integrate the new cluster into the build process.
  4. Integrate with Application: Connect the cluster to an application's code generation configuration.
  5. Test: Add unit and integration tests to verify the cluster's functionality.

Part 1: Cluster Definition (XML)

Clusters are defined based on the Matter specification. The C++ code for them is generated from XML definitions located in src/app/zap-templates/zcl/data-model/chip.

  • Generate XML: To create or update a cluster XML, use Alchemy to parse the specification's asciidoc. Manual editing of XML is discouraged, as it is error-prone.

  • Run Code Generation: Once the XML is ready, run the code generation script. It's often sufficient to run:

    ./scripts/run_in_build_env.sh 'scripts/tools/zap_regen_all.py'

    For more details, see the code generation guide.

Part 2: C++ Implementation

File Structure

Create a new directory for your cluster at src/app/clusters/<cluster-directory>/. This directory will house the cluster implementation and its unit tests.

For zap-based support, the directory mapping is defined in src/app/zap_cluster_list.json under the ServerDirectories key. This maps the UPPER_SNAKE_CASE define of the cluster to the directory name under src/app/clusters.

Naming conventions

Names vary, however to be consistent with most of the existing code use:

  • cluster-name-server for the cluster directory name
  • ClusterNameSnakeCluster.h/cpp for the ServerClusterInterface implementation
  • ClusterNameSnakeLogic.h/cpp for the Logic implementation if applicable

Recommended Modular Layout

For better testability and maintainability, we recommend splitting the implementation into logical components. The Software Diagnostics cluster is a good example of this pattern.

  • ClusterLogic:
    • A type-safe class containing the core business logic of the cluster.
    • Manages all attribute storage.
    • Should be thoroughly unit-tested.
  • ClusterImplementation:
    • Implements the ServerClusterInterface (often by deriving from DefaultServerCluster).
    • Acts as a translation layer between the data model (encoders/decoders) and the ClusterLogic.
  • ClusterDriver (or Delegate):
    • An optional interface providing callbacks to the application for cluster interactions. We recommend the term Driver to avoid confusion with the overloaded term Delegate.

Choosing the Right Implementation Pattern

When implementing a cluster, you have two primary architectural choices: a combined implementation and a modular implementation. The best choice depends on the cluster's complexity and the constraints of the target device, particularly flash and RAM usage.

  • Combined Implementation (Logic and Data in One Class):

    • Description: In this pattern, the cluster's logic, data storage, and ServerClusterInterface implementation are all contained within a single class.
    • Pros: Simpler to write and can result in a smaller flash footprint, making it ideal for simple clusters or resource-constrained devices.
    • Cons: Can be harder to test and maintain as the cluster's complexity grows.
    • Example: The Basic Information cluster is a good example of a combined implementation.

  • Modular Implementation (Logic Separated from Data Model):

    • Description: This pattern separates the core business logic into a ClusterLogic class, while the ClusterImplementation class handles the translation between the data model and the logic.
    • Pros: Promotes better testability, as the ClusterLogic can be unit-tested in isolation. It is also more maintainable for complex clusters.
    • Cons: May use slightly more flash and RAM due to the additional class and virtual function calls.
    • Example: The Software Diagnostics cluster demonstrates a modular implementation.

Recommendation: Start with a combined implementation for simpler clusters. If the cluster's logic is complex or if you need to maximize testability, choose the modular approach.

BUILD file layout

The description below will describe build files under src/app/clusters/<cluster-directory>/. You are expected to have the following items:

BUILD.gn

This file will contain a target that is named <cluster-directory>, usually a source_set. This file gets referenced from src/app/chip_data_model.gni by adding a dependency as deps += [ "${_app_root}/clusters/${cluster}" ], so the default target name is important.

app_config_dependent_sources

There are two code generation integration support files: one for GN and one for CMake. The way these work is that chip_data_model.gni/chip_data_model.cmake will include these files and bundle ALL referenced sources into ONE SINGLE SOURCE SET, together with ember code-generated settings (e.g. endpoint_config.h and similar files that are application-specific)

As a result, there will be a difference between .gni and .cmake:

  • app_config_dependent_sources.gni will typically just contain CodegenIntegration.cpp and any other helper/compatibility layers (e.g. CodegenIntegration.h if applicable)
  • app_config_dependent_sources.cmake will contain all the files that the .gni file contains PLUS any dependencies that the BUILD.gn would pull in but cmake would not (i.e. dependencies not in the libCHIP builds). These extra files are often the *.h/*.cpp files that were in the BUILD.gn source set.

EXAMPLE taken from (src/app/clusters/basic-information):

# BUILD.gn
import("//build_overrides/build.gni")
import("//build_overrides/chip.gni")

source_set("basic-information") {
   sources = [ ... ]
   public_deps = [ ... ]
}

# app_config_dependent_sources.gni
app_config_dependent_sources = [ "CodegenIntegration.cpp" ]

# app_config_dependent_sources.cmake
# This block adds the codegen integration sources, similar to app_config_dependent_sources.gni
TARGET_SOURCES(
  ${APP_TARGET}
  PRIVATE
    "${CLUSTER_DIR}/CodegenIntegration.cpp"
)

# These are the things that BUILD.gn dependencies would pull
TARGET_SOURCES(
  ${APP_TARGET}
  PRIVATE
    "${CLUSTER_DIR}/BasicInformationCluster.cpp"
    "${CLUSTER_DIR}/BasicInformationCluster.h"
)

Implementation Details

Attribute and Feature Handling

Your implementation must correctly report which attributes and commands are available based on the enabled features and optional items.

  • Use a feature map to control elements dependent on features.
  • Use boolean flags or BitFlags for purely optional elements.
  • Ensure your unit tests cover different combinations of enabled features and optional attributes/commands.

Attribute Change Notifications

For subscriptions to work correctly, you must notify the system whenever an attribute's value changes.

  • The Startup method of your cluster receives a ServerClusterContext.

  • Use the context to call interactionContext->dataModelChangeListener->MarkDirty(path). A NotifyAttributeChanged helper exists for paths managed by this cluster.

    • For write implementations, you can use NotifyAttributeChangedIfSuccess together with a separate WriteImpl such that any successful attribute write will notify.

      Canonical example code would look like:

      DataModel::ActionReturnStatus SomeCluster::WriteAttribute(const DataModel::WriteAttributeRequest & request,
                                                                  AttributeValueDecoder & decoder)
{
        // Delegate everything to WriteImpl. If write succeeds, notify that the attribute changed.
        return NotifyAttributeChangedIfSuccess(request.path.mAttributeId, WriteImpl(request, decoder));
}

    • For the NotifyAttributeChangedIfSuccess ensure that WriteImpl is returning ActionReturnStatus::FixedStatus::kWriteSuccessNoOp when no notification should be sent (e.g. write was a noop because existing value was already the same).

      Canonical example is:

      VerifyOrReturnValue(mValue != value, ActionReturnStatus::FixedStatus::kWriteSuccessNoOp);

Persistent Storage

  • Attributes: For scalar attribute values, use AttributePersistence from src/app/persistence/AttributePersistence.h. The ServerClusterContext provides an AttributePersistenceProvider.
  • General Storage: For non-attribute data, the context provides a PersistentStorageDelegate.

Optimizing for Flash/RAM

For common or large clusters, you may need to optimize for resource usage. Consider using C++ templates to compile-time select features and attributes, which can significantly reduce flash and RAM footprint.

Advanced ServerClusterInterface Details

While ReadAttribute, WriteAttribute, and InvokeCommand are the most commonly implemented methods, the ServerClusterInterface has other methods for more advanced use cases.

List Attribute Writes (ListAttributeWriteNotification)

This method is an advanced callback for handling large list attributes that may require special handling, such as persisting them to storage in chunks. A typical example of a cluster that might use this is the Binding cluster. For most clusters, the default implementation is sufficient.

Event Permissions (EventInfo)

You must implement the EventInfo method if your cluster emits any events that require non-default permissions to be read. For example, an event might require Administrator privileges. While not common, this should be verified for every new cluster implementation and checked during code reviews to ensure event access is correctly restricted.

Accepted vs. Generated Commands

The distinction between AcceptedCommands and GeneratedCommands can be understood using a REST API analogy:

  • AcceptedCommands: These are the “requests” that the server cluster can process. In the Matter specification, these are commands sent from the client to the server (client => server).
  • GeneratedCommands: These are the “responses” that the server cluster can generate after processing an accepted command. In the spec, these are commands sent from the server back to the client (server => client).

These lists are built based on the cluster's definition in the Matter specification.

Unit Testing

  • Unit tests should reside in src/app/clusters/<cluster-name>/tests/.
  • At a minimum, ClusterLogic should be fully tested, including its behavior with different feature configurations.
  • ClusterImplementation can also be unit-tested if its logic is complex. Otherwise, integration tests should provide sufficient coverage.

Part 3: Build and Application Integration

Build System Integration

The build system maps cluster names to their source directories. Add your new cluster to this mapping:

  • Edit src/app/zap_cluster_list.json and add an entry for your cluster, pointing to the directory you created.

Application Integration (CodegenIntegration.cpp)

To integrate your cluster with an application's .zap file configuration, you need to bridge the gap between the statically generated code and your C++ implementation.

  1. Create CodegenIntegration.cpp: This file will contain the integration logic.

  2. Create Build Files: Add app_config_dependent_sources.gni and app_config_dependent_sources.cmake to your cluster directory. These files should list CodegenIntegration.cpp and its dependencies. See existing clusters for examples.

  3. Use Generated Configuration: The code generator creates a header file at <app/static-cluster-config/<cluster-name>.h that provides static, application-specific configuration. Use this to initialize your cluster correctly for each endpoint.

  4. Implement Callbacks: Implement Matter<Cluster>ClusterInitCallback(EndpointId) and Matter<Cluster>ClusterShutdownCallback(EndpointId) in your CodegenIntegration.cpp.

  5. Update config-data.yaml: To enable these callbacks, add your cluster to the CodeDrivenClusters array in src/app/common/templates/config-data.yaml.

  6. Update ZAP Configuration: To prevent the Ember framework from allocating memory for your cluster's attributes (which are now managed by your ClusterLogic), you must:

    • In src/app/common/templates/config-data.yaml, consider adding your cluster to CommandHandlerInterfaceOnlyClusters if it does not need Ember command dispatch.
    • In src/app/zap-templates/zcl/zcl.json and zcl-with-test-extensions.json, add all non-list attributes of your cluster to attributeAccessInterfaceAttributes. This marks them as externally handled.

  7. Once config-data.yaml and zcl.json/zcl-with-test-extensions.json are updated, run the ZAP regeneration command, like

    ./scripts/run_in_build_env.sh 'scripts/tools/zap_regen_all.py'

Part 4: Example Application and Integration Testing

  • Write unit tests to ensure cluster test coverage
  • Integrate into an Example: Add your cluster to an example application, such as the all-clusters-app, to test it in a real-world scenario.
    • use tools such as chip-tool or matter-repl to manually validate the cluster
  • Add Integration Tests: Write integration tests to validate the end-to-end functionality of your cluster against the example application.