src/app/clusters/operational-state-server/README.md

# 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:

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