[Fabric-Sync] Initial version of fabric-sync example (project-chip#36136

)

* [Fabric-Sync] Initial version of fabric-sync example

* Add Readme.txt

* Remove unused define flag

docs/examples/fabric_sync.md

@@ -0,0 +1,8 @@
+## Fabric Sync
+
+```{toctree}
+:glob:
+:maxdepth: 1
+
+fabric-sync/README
+```

examples/fabric-sync/.gn

@@ -0,0 +1,25 @@
+# Copyright (c) 2024 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/build.gni")
+
+# The location of the build configuration file.
+buildconfig = "${build_root}/config/BUILDCONFIG.gn"
+
+# CHIP uses angle bracket includes.
+check_system_includes = true
+
+default_args = {
+  import("//args.gni")
+}

examples/fabric-sync/BUILD.gn

@@ -0,0 +1,45 @@
+# Copyright (c) 2024 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/build.gni")
+import("//build_overrides/chip.gni")
+import("${chip_root}/build/chip/tools.gni")
+import("${chip_root}/src/lib/lib.gni")
+
+assert(chip_build_tools)
+
+executable("fabric-sync") {
+  cflags = [ "-Wconversion" ]
+
+  include_dirs = [
+    ".",
+    "${chip_root}/src/lib",
+  ]
+
+  sources = [ "main.cpp" ]
+
+  deps = [
+    "${chip_root}/examples/fabric-sync/bridge:fabric-bridge-lib",
+    "${chip_root}/examples/fabric-sync/bridge:fabric-bridge-zap",
+    "${chip_root}/examples/platform/linux:app-main",
+    "${chip_root}/src/lib",
+    "${chip_root}/third_party/inipp",
+  ]
+
+  output_dir = root_out_dir
+}
+
+group("default") {
+  deps = [ ":fabric-sync" ]
+}

examples/fabric-sync/README.md

@@ -0,0 +1,104 @@
+# Matter Linux Fabric Sync Example
+
+An example application to implement the Fabric Synchronization feature and
+demonstrates the end-to-end Fabric Synchronization feature using dynamic
+endpoints.
+
+Fabric Synchronization feature will facilitate the commissioning of end devices
+from one fabric to another without requiring user intervention for every end
+device. It defines mechanisms that can be used by multiple
+ecosystems/controllers to communicate with one another to simplify the
+experience for users.
+
+This doc is tested on **Ubuntu 22.04 LTS (aarch64)**
+
+<hr>
+
+-   [Matter Linux Fabric Sync Example](#matter-linux-fabric-sync-example)
+    -   [Theory of Operation](#theory-of-operation)
+    -   [Building](#building)
+    -   [Running the Complete Example on Ubuntu](#running-the-complete-example-on-ubuntu)
+
+<hr>
+
+## Theory of Operation
+
+### Dynamic Endpoints
+
+The Fabric-Sync Example makes use of Dynamic Endpoints. Current SDK support is
+limited for dynamic endpoints, since endpoints are typically defined (along with
+the clusters and attributes they contain) in a .zap file which then generates
+code and static structures to define the endpoints.
+
+To support endpoints that are not statically defined, the ZCL attribute storage
+mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS`
+additional endpoints. These additional endpoint structures must be defined by
+the application and can change at runtime.
+
+To facilitate the creation of these endpoint structures, several macros are
+defined:
+
+`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)`
+`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)`
+`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)`
+
+-   These three macros are used to declare a list of attributes for use within a
+    cluster. The declaration must begin with the
+    `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of
+    the allocated attribute structure. Each attribute is then added by the
+    `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally,
+    `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the
+    definition.
+
+-   All attributes defined with these macros will be configured as
+    `ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will
+    rely on the application to maintain storage for the attribute. Consequently,
+    reads or writes to these attributes must be handled within the application
+    by the `emberAfExternalAttributeWriteCallback` and
+    `emberAfExternalAttributeReadCallback` functions. See the bridge
+    application's `main.cpp` for an example of this implementation.
+
+`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)`
+`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)`
+`DECLARE_DYNAMIC_CLUSTER_LIST_END`
+
+-   These three macros are used to declare a list of clusters for use within a
+    endpoint. The declaration must begin with the
+    `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the
+    allocated cluster structure. Each cluster is then added by the
+    `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously
+    defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros and the lists of
+    incoming/outgoing commands terminated by kInvalidCommandId (or nullptr if
+    there aren't any commands in the list). Finally,
+    `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the
+    definition.
+
+`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)`
+
+-   This macro is used to declare an endpoint and its associated cluster list,
+    which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros.
+
+## Building
+
+    ### For Linux host example:
+
+    ```
+    ./scripts/examples/gn_build_example.sh examples/fabric-sync out/debug/standalone
+    ```
+
+    ### For Raspberry Pi 4 example:
+
+    TODO
+
+## Running the Complete Example on Ubuntu
+
+-   Building
+
+    Follow [Building](#building) section of this document.
+
+-   Run Linux Fabric Sync Example App
+
+    ```sh
+    cd ~/connectedhomeip/
+    sudo out/debug/fabric-sync
+    ```

examples/fabric-sync/args.gni

@@ -0,0 +1,40 @@
+# Copyright (c) 2024 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/chip.gni")
+
+import("${chip_root}/config/standalone/args.gni")
+
+chip_device_project_config_include = "<CHIPProjectAppConfig.h>"
+chip_project_config_include = "<CHIPProjectAppConfig.h>"
+chip_system_project_config_include = "<SystemProjectConfig.h>"
+
+chip_project_config_include_dirs =
+    [ "${chip_root}/examples/fabric-sync/bridge/include" ]
+chip_project_config_include_dirs += [ "${chip_root}/config/standalone" ]
+
+chip_build_libshell = true
+
+chip_enable_additional_data_advertising = true
+
+chip_enable_rotating_device_id = true
+
+chip_config_network_layer_ble = false
+
+matter_enable_tracing_support = true
+matter_log_json_payload_hex = true
+matter_log_json_payload_decode_full = true
+
+# Thread devices do not support WakeOnLan because their mac address is >48bit
+chip_enable_openthread = false

examples/fabric-sync/bridge/BUILD.gn

@@ -0,0 +1,50 @@
+# Copyright (c) 2024 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import("//build_overrides/chip.gni")
+import("${chip_root}/src/app/chip_data_model.gni")
+import("${chip_root}/src/lib/lib.gni")
+
+config("config") {
+  include_dirs = [ "include" ]
+}
+
+chip_data_model("fabric-bridge-zap") {
+  zap_file = "fabric-bridge.zap"
+  is_server = true
+}
+
+# This includes all the clusters that only exist on the dynamic endpoint.
+source_set("fabric-bridge-common") {
+  public_configs = [ ":config" ]
+
+  sources = [
+    "${chip_root}/src/app/clusters/ecosystem-information-server/ecosystem-information-server.cpp",
+    "${chip_root}/src/app/clusters/ecosystem-information-server/ecosystem-information-server.h",
+  ]
+
+  public_deps = [ ":fabric-bridge-zap" ]
+}
+
+source_set("fabric-bridge-lib") {
+  public_configs = [ ":config" ]
+
+  sources = [ "include/CHIPProjectAppConfig.h" ]
+
+  deps = [
+    "${chip_root}/examples/fabric-sync/bridge:fabric-bridge-common",
+    "${chip_root}/examples/platform/linux:app-main",
+    "${chip_root}/src/lib",
+  ]
+}