Add Readme.txt

docs/examples/fabric_sync.md

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

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
+    ```