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

Recommended Implementation Pattern

For optimal flash and RAM usage on resource-constrained devices, we strongly recommend a combined implementation pattern. You should avoid splitting the implementation into separate logic and translation layers, as this introduces unnecessary overhead.

  • Combined Implementation (Recommended):

    • The cluster's logic, data storage, and ServerClusterInterface implementation are all contained within a single class (often by deriving from DefaultServerCluster).
    • This minimizes boilerplate and virtual function translation layers, resulting in a significantly smaller flash footprint.
    • Example: The Basic Information cluster is a good example of a combined implementation.

  • Modular Implementation / ClusterLogic (Not Recommended):

    • Historically, some clusters separated core business logic into a type-safe ClusterLogic class, with a ClusterImplementation class acting as a translation layer.
    • While this isolated the logic for testing, it adds noticeable flash and RAM overhead and is discouraged for new clusters.
    • Example: The Administrator Commissioning cluster demonstrates this legacy modular implementation.

  • 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.

Design Principles

When designing and implementing a cluster, adhere to the following principles to ensure a high-quality and developer-friendly experience:

Prioritize Easy Application Development

Clusters should aim to do as much work as possible autonomously, reducing the burden on the application developer.

  • Handle Common Logic Internally: Implement persistence (NVM), timers, and complex state machines within the cluster itself. The application should only be notified of significant events or changes it needs to act upon. For example, a state machine managing a multi-step process like a firmware update, door lock/unlock sequence with retries, or a calibration procedure should typically reside within the cluster, rather than requiring the application to manage the intermediate steps and timeouts.
  • Provide Helper Abstractions: If a cluster requires the application to implement complex logic, consider providing helper classes or default implementations that simplify the task.
  • Encapsulate Complexity: Avoid deferring low-level details (like raw storage keys or individual timer management) to the application.

Delegate/Driver Pattern for Validation

When an application needs to be involved in a cluster operation (especially writes or commands), use a delegate (or driver) interface that acts as a “pre-check.”

  • Pre-Write Validation: For writable attributes, provide a callback that allows the application to accept or reject the new value before it is applied to the cluster's internal state or persisted.
  • Delegate Veto: Callbacks must return a Protocols::InteractionModel::Status. Returning any status other than Success allows the application to reject the proposed change. The cluster MUST honor this by failing the operation and propagating the delegate's status code to the initiator.
  • Perform Cluster-Level Checks First: The cluster remains responsible for all spec-defined validations (e.g., range checks, constraint validations, or state-based restrictions) before involving the application delegate.
  • Avoid Redundant Notifications: Ensure that no-op operations (e.g., writing the same value that is already present) are handled early and do not trigger delegate callbacks or change notifications.

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 Accessors

Your cluster implementation must provide public getter and setter APIs for each attribute to allow applications to interact with cluster state.

  • Getter Methods: Provide a getter method for every attribute (e.g., GetCurrentSensitivityLevel(), GetAlarmsActive()). Applications need these to read the current cluster state.

    • Return by value (preferred): Getters should return copies of data whenever practical. This avoids lifetime and ownership concerns.

    • Avoid returning pointers or references: Returning pointers or references to internal cluster data create lifetime risks—if the underlying memory is deallocated while the caller still holds the pointer, use-after-free bugs can occur. If you must return a pointer or reference, clearly document that the returned value is only valid for immediate use and must not be stored.

  • Setter Methods: Provide methods to modify all non-fixed (mutable) attributes in spec-compliant ways. For simple attributes, this may be a straightforward setter (e.g., SetCurrentSensitivityLevel()). However, spec compliance may require updating multiple attributes together atomically—in such cases, provide a higher-level API that encapsulates the required behavior rather than individual setters. When the application‘s driver state changes, these methods can be used to update the cluster’s state accordingly. Setters are also responsible for triggering attribute change notifications (see Attribute Change Notifications).

  • Example: The Boolean State Configuration cluster demonstrates this pattern.

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.

      Crucial: No-op writes (where the value remains unchanged) MUST NOT trigger:

      • Network attribute change notifications.
      • Application-level delegate/driver callbacks.

      Canonical example is:

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

  • Per-Attribute Change Callbacks: As a concrete realization of the Delegate/Driver Pattern for Validation, each mutable attribute should have a corresponding On<AttributeName>Changed callback in the delegate interface. These are pre-write hooks invoked after spec-level validation and the no-op guard, but before the value is committed. The callback must always receive the proposed new value, not the current (stale) value. Returning true accepts the change; returning false vetoes it. The cluster must then fail the operation with Protocols::InteractionModel::Status::Failure (for APIs returning Status) or CHIP_ERROR_INCORRECT_STATE (for APIs returning CHIP_ERROR). Default implementations should return true so applications only override the callbacks they need.

    Example: The Boolean State Configuration delegate declares:

    virtual bool OnCurrentSensitivityLevelChanged(uint8_t newValue) { return true; }
virtual bool OnAlarmsActiveChanged(chip::BitMask<AlarmModeBitmap> newValue) { return true; }
virtual bool OnAlarmsSuppressedChanged(chip::BitMask<AlarmModeBitmap> newValue) { return true; }
virtual bool OnAlarmsEnabledChanged(chip::BitMask<AlarmModeBitmap> newValue) { return true; }
virtual bool OnSensorFaultChanged(chip::BitMask<SensorFaultBitmap> newValue) { return true; }

    And the cluster invokes them in the standard order—validate, guard no-op, call delegate, then commit and notify:

    VerifyOrReturnError(level < mSupportedSensitivityLevels, CHIP_IM_GLOBAL_STATUS(ConstraintError));
VerifyOrReturnError(mCurrentSensitivityLevel != level, CHIP_NO_ERROR);

if (mDelegate != nullptr)
{
    VerifyOrReturnError(mDelegate->OnCurrentSensitivityLevelChanged(level), CHIP_ERROR_INCORRECT_STATE);
}

mCurrentSensitivityLevel = level;
NotifyAttributeChanged(CurrentSensitivityLevel::Id);

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/.

Use the chip::Testing::ClusterTester utility to write your unit tests. This modern API removes the need to manually mock encoders, handlers, or raw TLV buffers. More on ClusterTester Helper Class Guide.

  • Test Setup: Create a mock delegate to inject fake data into your cluster instance.
  • Menu Verification: Ensure Attributes() and AcceptedCommands() return the correct metadata, or ClusterTester will reject your reads/invocations.
  • Reads: Test ReadAttribute via tester.ReadAttribute() and verify data matches your mock.
  • Commands: Test commands via tester.Invoke() and ensure specific Protocols::InteractionModel::Status codes are returned accurately based on delegate responses.
  • Reporting: Verify reporting logic by reading tester.GetDirtyList() to ensure state changes properly mark attributes as dirty, while No-Op writes do not.

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, you must:

    • 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. Regenerate ZAP: 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.