The Operational State cluster and its derived clusters

The Operational State cluster (0x0060) is a code-driven cluster that implements the base logic for Operational State and its derived clusters (RVC Operational State, Oven Cavity Operational State). It is implemented as OperationalState::OperationalStateCluster (extends DefaultServerCluster) and follows the code-driven data model pattern.

How to use an Operational State cluster

All Operational State derived clusters have their own Instance class within their respective namespace. This class is a legacy compatibility wrapper around the underlying OperationalStateCluster; new code should use OperationalStateCluster directly.

Required delegate

Create a class that inherits OperationalState::Delegate and implement the virtual callback methods. Pass the delegate to Instance (or directly to the cluster class).

Initialization in your application

Override the Matter<ClusterName>ClusterInitCallback function generated by the ZAP code-driven init/shutdown template. This is the server-side init hook for code-driven clusters:

// application delegate file (.cpp)
void MatterOperationalStateClusterInitCallback(chip::EndpointId endpointId)
{
    // Create delegate and instance, then call Init().
    gDelegate = new MyOperationalStateDelegate;
    gInstance  = new OperationalState::Instance(gDelegate, endpointId);
    gInstance->SetOperationalState(to_underlying(OperationalState::OperationalStateEnum::kStopped));
    gInstance->Init();
}

void MatterOperationalStateClusterShutdownCallback(chip::EndpointId endpointId,
                                                    MatterClusterShutdownType)
{
    delete gInstance;  gInstance  = nullptr;
    delete gDelegate;  gDelegate  = nullptr;
}

Weak no-op stubs for these functions are provided by CodegenIntegration.cpp so that applications that do not need custom state survive linking without defining them.

Note emberAf<ClusterName>ClusterInitCallback and emberAf<ClusterName>ClusterShutdownCallback (without the Server qualifier) are client-side hooks and must not be used for server cluster initialization. The correct server-side hooks are Matter<ClusterName>ClusterInitCallback and Matter<ClusterName>ClusterShutdownCallback, as shown above.

Note ZAP accessor functions for these clusters do not exist. Use the instance's Set… and Get… methods to access attributes.

How to add new derived clusters

Once a new Operational State derived cluster has been defined in the spec:

1. Add the cluster XML to src/app/zap-templates/zcl/data-model/chip/.
2. Add the cluster to CodeDrivenClusters in src/app/common/templates/config-data.yaml.
3. Regenerate ZAP and py_matter_idl outputs (scripts/tools/zap/zap_regen_all.py).
4. Subclass OperationalStateCluster (see RvcOperationalStateCluster as a reference) and register it via RegisteredServerCluster.
5. Extend the all-clusters-app example with the new cluster.