Sync csa branch with main (#646)

Author: mkardous-silabs

.gemini/styleguide.md

@@ -1,12 +1,29 @@
 # Gemini Code Review Instructions
 
 - Do not comment on content for XML files or .matter content for clusters
-- Assume the matter specification is unknown and out of scope. Do not make uninformed assumptions about the Matter specification, or its contents.
-- Do not comment unless a change is probably desirable 
+- The SDK is implementing an in-progress matter specification that may not be available yet.
+  Assume the matter specification is unknown and out of scope. Do not make uninformed assumptions
+  about the Matter specification, or its contents.
+- Do not comment unless a change is probably desirable
 - Do not repeat yourself. Be concise without losing meaning
 - Do not over-explain what you see in the code. Only describe code if there are specific questions or concerns (or if a question is asked)
 - Ensure that extensions or fixes to existing code should match the prevailing style of the original code
 - Look for common typos and suggest fixes
-- The current year is 2025.
 - Wrong years and years in the future are OK. Humans will catch these issues.
-- Comments regarding issues about whitespace or code alignment are not needed. A code formatter will take care of these problems.
+- The SDK uses automated code formatting. Do not comment on whitespace, line length or other formatting
+  or whitespace issues. A code formatter will handle this.
+
+## Development guides
+
+The SDK source code contains guides for development best practices in `docs/guides`, `docs/testing` and other `docs` locations.
+Use these as a reference for finding common patterns and potential issues in new code. In particular:
+  - [docs/guides/writing_clusters](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/writing_clusters.md) describes how cluster handling
+    is to be implemented
+  - [docs/guides/migrating_ember_cluster_to_code_driven.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/migrating_ember_cluster_to_code_driven.md)
+    describes how ember clusters can be migrated to code driven
+  - [docs/testing/unit_testing.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/testing/unit_testing.md)
+    describes how to implement unit testing
+  - [docs/testing/integration_tests.md](https://github.com/project-chip/connectedhomeip/blob/master/docs/testing/integration_tests.md)
+    describes how to implement integration tests.
+
+

.github/workflows/analyze-changed-paths.yaml

@@ -36,14 +36,11 @@ env:
     CHIP_NO_LOG_TIMESTAMPS: true
 
 jobs:
-    changed_paths:
-      uses: ./.github/workflows/analyze-changed-paths.yaml
-
     build_linux_gcc_debug:
         name: Build on Linux (gcc_debug)
-        needs: changed_paths
+
         runs-on: ubuntu-latest
-        if: github.actor != 'restyled-io[bot]' && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]'
 
         container:
             image: ghcr.io/project-chip/chip-build:167
@@ -151,9 +148,9 @@ jobs:
 
     build_linux:
         name: Build on Linux (fake, gcc_release, clang, simulated)
-        needs: changed_paths
+
         runs-on: ubuntu-latest
-        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true
 
         container:
             image: ghcr.io/project-chip/chip-build:167
@@ -329,9 +326,9 @@ jobs:
 
     build_linux_python_lib:
         name: Build on Linux (python_lib)
-        needs: changed_paths
+
         runs-on: ubuntu-latest
-        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true
 
         container:
             image: ghcr.io/project-chip/chip-build:167
@@ -392,9 +389,9 @@ jobs:
 
     build_linux_python_lighting_device:
         name: Build on Linux (python lighting-app)
-        needs: changed_paths
+
         runs-on: ubuntu-latest
-        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true
 
         container:
             image: ghcr.io/project-chip/chip-build:167
@@ -426,9 +423,8 @@ jobs:
 
     build_darwin:
         name: Build on Darwin (clang, simulated)
-        needs: changed_paths
         runs-on: macos-13
-        if: github.actor != 'restyled-io[bot]'  && inputs.run-codeql != true && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]'  && inputs.run-codeql != true
 
         steps:
             - name: Checkout
@@ -514,11 +510,11 @@ jobs:
 
     build_linux_gcc_coverage:
         name: Build on Linux (coverage)
-        needs: changed_paths
+
         env:
             TSAN_OPTIONS: "halt_on_error=1 suppressions=scripts/tests/chiptest/tsan-linux-suppressions.txt"
 
-        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]' && inputs.run-codeql != true
         runs-on: ubuntu-latest
 
         container:

.github/workflows/build.yaml

@@ -43,12 +43,9 @@ env:
     CHIP_NO_LOG_TIMESTAMPS: true
 
 jobs:
-    changed_paths:
-      uses: ./.github/workflows/analyze-changed-paths.yaml
-
     test_suites_linux:
         name: Test Suites - Linux
-        needs: changed_paths
+
         strategy:
             matrix:
                 build_variant: [no-ble-no-shell-tsan-clang]
@@ -61,7 +58,7 @@ jobs:
             DISABLE_CCACHE: ${{ (github.event_name == 'workflow_dispatch' && inputs.disable_ccache == 'true') && 'true' || (contains(github.event.head_commit.message, '[no-ccache]') && 'true') || 'false' }}
             CCACHE_KEY_SUFFIX: ${{ github.event_name == 'workflow_dispatch' && inputs.cache_suffix || '' }}
 
-        if: github.actor != 'restyled-io[bot]' && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]'
         runs-on: ubuntu-latest
 
         container:
@@ -436,7 +433,7 @@ jobs:
 
     test_suites_darwin:
         name: Test Suites - Darwin
-        needs: changed_paths
+
         strategy:
             matrix:
                 build_variant: [no-ble-no-shell-asan-clang, no-ble-no-shell-tsan-clang]
@@ -447,7 +444,7 @@ jobs:
             TSAN_OPTIONS: "halt_on_error=1"
             LSAN_OPTIONS: detect_leaks=1 suppressions=scripts/tests/chiptest/lsan-mac-suppressions.txt
 
-        if: github.actor != 'restyled-io[bot]' && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]'
         runs-on: macos-13
 
         steps:
@@ -553,8 +550,8 @@ jobs:
 
     repl_tests_linux:
         name: REPL Tests - Linux
-        needs: changed_paths
-        if: github.actor != 'restyled-io[bot]' && needs.changed_paths.outputs.non_md_changes == 'true'
+
+        if: github.actor != 'restyled-io[bot]'
 
         strategy:
             matrix:
@@ -849,17 +846,17 @@ jobs:
                   scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/test_TC_ICDM_2_1_min_pics.py'
                   scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/test_TC_SC_7_1.py'
                   scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestDecorators.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestChoiceConformanceSupport.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestConformanceSupport.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestConformanceTest.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestDefaultWarnings.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestIdChecks.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestMatterTestingSupport.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestPics.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestSpecParsingDeviceType.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestSpecParsingNamespace.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestSpecParsingSelection.py'
-                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/TestSpecParsingSupport.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestChoiceConformanceSupport.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestConformanceSupport.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestConformanceTest.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestDefaultWarnings.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestIdChecks.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestMatterTestingSupport.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestPics.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestSpecParsingDeviceType.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestSpecParsingNamespace.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestSpecParsingSelection.py'
+                  scripts/run_in_python_env.sh out/venv 'python3 src/python_testing/test_testing/TestSpecParsingSupport.py'
                   scripts/run_in_python_env.sh out/venv 'PYTHONPATH=src/python_testing:$PYTHONPATH python3 -m unittest discover -s src/python_testing/mdns_discovery/tests -p "test_*.py"'
 
             - name: Run Tests
@@ -913,15 +910,15 @@ jobs:
 
     repl_tests_darwin:
         name: REPL Tests - Darwin (Build Only)
-        needs: changed_paths
+
         strategy:
             matrix:
                 build_variant: [no-ble-no-wifi-tsan-clang]
         env:
             BUILD_VARIANT: ${{matrix.build_variant}}
             TSAN_OPTIONS: "halt_on_error=1"
 
-        if: github.actor != 'restyled-io[bot]' && needs.changed_paths.outputs.non_md_changes == 'true'
+        if: github.actor != 'restyled-io[bot]'
         runs-on: macos-13
 
         steps:

.github/workflows/tests.yaml

@@ -224,7 +224,7 @@ restylers:
           - "**/*.sh"
           - "**/*.bash"
     - name: autopep8
-      image: restyled/restyler-autopep8:v2.0.0
+      image: restyled/restyler-autopep8:v2.3.0
       command:
           - autopep8
           - "--in-place"

.restyled.yaml

@@ -864,7 +864,7 @@ def cli():
 @optgroup.option('--use-test-net-dcld', type=str, default='', metavar='PATH', help="Location of `dcld` binary, to use `dcld` for mirroring TestNet.")
 @optgroup.option('--use-main-net-http', is_flag=True, type=str, help="Use RESTful API with HTTPS against public MainNet observer.")
 @optgroup.option('--use-test-net-http', is_flag=True, type=str, help="Use RESTful API with HTTPS against public TestNet observer.")
-@optgroup.option('--use-local-data', is_flag=True, type=bool, help="Fake response directory: see \" DATA_DIR/",)
+@optgroup.option('--use-local-data', is_flag=True, type=bool, help="Fake response directory: see \" DATA_DIR/")
 @optgroup.group('Required arguments if use-local-data is used', cls=AllOptionGroup)
 @optgroup.option('--certificates', type=click.File('rb'), multiple=True, help='Paths to PEM formated certificates (i.e. PAA) in DCL but missing from the revocation-points-response file.')
 @optgroup.option('--crls', type=click.File('rb'), multiple=True, help='Paths to the crl der files')

credentials/generate_revocation_set.py

@@ -23,6 +23,11 @@ type-safe accessors in
 In a code-driven implementation, this data must be moved into member variables
 within your new cluster class.
 
+In some cases the cluster directory may not exist. In that case, create a new
+directory and add the mapping in
+[src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json)
+under the `ServerDirectories` key.
+
 ### `AttributeAccessInterface` (`AAI`) and `CommandHandlerInterface` (`CHI`)
 
 When more complex logic is needed, Ember clusters use these interfaces.
@@ -100,8 +105,31 @@ new code-driven class structure.
 
 #### Command Handling
 
--   Translate `emberAf...Callback` functions into logic inside your
-    `InvokeCommand` method.
+-   Translate `CommandHandlerInterface` calls or `emberAf...Callback` functions
+    into logic inside your `InvokeCommand` method:
+
+    -   ember calls of the form `emberAf<CLUSTER>Cluster<COMMAND>Callback` will
+        be converted to a switch `case <CLUSTER>::Commands::<COMMAND>::Id: ...`
+        implementation
+
+        Example:
+
+        ```cpp
+        // This
+        emberAfAccessControlClusterReviewFabricRestrictionsCallback(...);
+
+        // Becomes this in the `InvokeCommand` implementation:
+        switch (request.path.mCommandId) {
+          // ...
+          case AccessControl::Commands::ReviewFabricRestrictions::Id:
+             // ...
+        }
+        ```
+
+    -   Command Handler Interface logic translates directly: `CHI` has a switch
+        on command ID inside its `InvokeCommand` call. You should have the same
+        logic inside the `ServerClusterInterface` processing logic.
+
 -   The `InvokeCommand` method can return an `ActionReturnStatus` optional. For
     better readability, prefer returning a status code directly (e.g.,
     `return Status::Success;`) rather than using the command handler to set the
@@ -157,6 +185,11 @@ data.
    `zcl-with-test-extensions.json`, add all of your cluster's non-list
    attributes to the `attributeAccessInterfaceAttributes` list. This tells ZAP
    not to allocate RAM for these attributes, as your class now manages them.
+3. Re-run ZAP regeneration, like
+
+    ```bash
+    ./scripts/run_in_build_env.sh 'scripts/tools/zap_regen_all.py'
+    ```
 
 ---
 

docs/guides/migrating_ember_cluster_to_code_driven.md

@@ -46,8 +46,23 @@ generated from XML definitions located in
 
 ### File Structure
 
-Create a new directory for your cluster at `src/app/clusters/<cluster-name>/`.
-This directory will house the cluster implementation and its unit tests.
+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](https://github.com/project-chip/connectedhomeip/blob/master/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
 
@@ -91,10 +106,34 @@ attribute's value changes.
 -   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:
+
+            ```cpp
+            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](https://github.com/project-chip/connectedhomeip/blob/master/src/app/data-model-provider/ActionReturnStatus.h)
+        when no notification should be sent (e.g. write was a `noop` because
+        existing value was already the same).
+
+            Canonical example is:
+
+            ```cpp
+            VerifyOrReturnValue(mValue != value, ActionReturnStatus::FixedStatus::kWriteSuccessNoOp);
+            ```
+
 #### Persistent Storage
 
 -   **Attributes:** For scalar attribute values, use `AttributePersistence` from
@@ -162,6 +201,12 @@ implementation.
       `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
+
+    ```bash
+    ./scripts/run_in_build_env.sh 'scripts/tools/zap_regen_all.py'
+    ```
 
 ---
 

docs/guides/writing_clusters.md

@@ -2950,8 +2950,8 @@ endpoint 0 {
   }
 
   server cluster DiagnosticLogs {
-    ram      attribute featureMap default = 0;
-    ram      attribute clusterRevision default = 1;
+    callback attribute featureMap;
+    callback attribute clusterRevision;
 
     handle command RetrieveLogsRequest;
   }