|
| 1 | +# Matter Linux Fabric Sync Example |
| 2 | + |
| 3 | +An example application to implement the Fabric Synchronization feature and |
| 4 | +demonstrates the end-to-end Fabric Synchronization feature using dynamic |
| 5 | +endpoints. |
| 6 | + |
| 7 | +Fabric Synchronization feature will facilitate the commissioning of end devices |
| 8 | +from one fabric to another without requiring user intervention for every end |
| 9 | +device. It defines mechanisms that can be used by multiple |
| 10 | +ecosystems/controllers to communicate with one another to simplify the |
| 11 | +experience for users. |
| 12 | + |
| 13 | +This doc is tested on **Ubuntu 22.04 LTS (aarch64)** |
| 14 | + |
| 15 | +<hr> |
| 16 | + |
| 17 | +- [Matter Linux Fabric Sync Example](#matter-linux-fabric-sync-example) |
| 18 | + - [Theory of Operation](#theory-of-operation) |
| 19 | + - [Building](#building) |
| 20 | + - [Running the Complete Example on Ubuntu](#running-the-complete-example-on-ubuntu) |
| 21 | + |
| 22 | +<hr> |
| 23 | + |
| 24 | +## Theory of Operation |
| 25 | + |
| 26 | +### Dynamic Endpoints |
| 27 | + |
| 28 | +The Fabric-Sync Example makes use of Dynamic Endpoints. Current SDK support is |
| 29 | +limited for dynamic endpoints, since endpoints are typically defined (along with |
| 30 | +the clusters and attributes they contain) in a .zap file which then generates |
| 31 | +code and static structures to define the endpoints. |
| 32 | + |
| 33 | +To support endpoints that are not statically defined, the ZCL attribute storage |
| 34 | +mechanisms will hold additional endpoint information for `NUM_DYNAMIC_ENDPOINTS` |
| 35 | +additional endpoints. These additional endpoint structures must be defined by |
| 36 | +the application and can change at runtime. |
| 37 | + |
| 38 | +To facilitate the creation of these endpoint structures, several macros are |
| 39 | +defined: |
| 40 | + |
| 41 | +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)` |
| 42 | +`DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)` |
| 43 | +`DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)` |
| 44 | + |
| 45 | +- These three macros are used to declare a list of attributes for use within a |
| 46 | + cluster. The declaration must begin with the |
| 47 | + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN` macro which will define the name of |
| 48 | + the allocated attribute structure. Each attribute is then added by the |
| 49 | + `DECLARE_DYNAMIC_ATTRIBUTE` macro. Finally, |
| 50 | + `DECLARE_DYNAMIC_ATTRIBUTE_LIST_END` macro should be used to close the |
| 51 | + definition. |
| 52 | + |
| 53 | +- All attributes defined with these macros will be configured as |
| 54 | + `MATTER_ATTRIBUTE_FLAG_EXTERNAL_STORAGE` in the ZCL database and therefore |
| 55 | + will rely on the application to maintain storage for the attribute. |
| 56 | + Consequently, reads or writes to these attributes must be handled within the |
| 57 | + application by the `emberAfExternalAttributeWriteCallback` and |
| 58 | + `emberAfExternalAttributeReadCallback` functions. See the bridge |
| 59 | + application's `main.cpp` for an example of this implementation. |
| 60 | + |
| 61 | +`DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)` |
| 62 | +`DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)` |
| 63 | +`DECLARE_DYNAMIC_CLUSTER_LIST_END` |
| 64 | + |
| 65 | +- These three macros are used to declare a list of clusters for use within a |
| 66 | + endpoint. The declaration must begin with the |
| 67 | + `DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN` macro which will define the name of the |
| 68 | + allocated cluster structure. Each cluster is then added by the |
| 69 | + `DECLARE_DYNAMIC_CLUSTER` macro referencing attribute list previously |
| 70 | + defined by the `DECLARE_DYNAMIC_ATTRIBUTE...` macros and the lists of |
| 71 | + incoming/outgoing commands terminated by kInvalidCommandId (or nullptr if |
| 72 | + there aren't any commands in the list). Finally, |
| 73 | + `DECLARE_DYNAMIC_CLUSTER_LIST_END` macro should be used to close the |
| 74 | + definition. |
| 75 | + |
| 76 | +`DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)` |
| 77 | + |
| 78 | +- This macro is used to declare an endpoint and its associated cluster list, |
| 79 | + which must be previously defined by the `DECLARE_DYNAMIC_CLUSTER...` macros. |
| 80 | + |
| 81 | +## Building |
| 82 | + |
| 83 | +- For Linux host example: |
| 84 | + |
| 85 | + ```sh |
| 86 | + source scripts/activate.sh |
| 87 | + ./scripts/build/build_examples.py --target linux-x64-fabric-sync-no-ble build |
| 88 | + ``` |
| 89 | + |
| 90 | +- For Raspberry Pi 4 example: |
| 91 | + |
| 92 | + Pull Docker Images |
| 93 | + |
| 94 | + ```sh |
| 95 | + docker pull ghcr.io/project-chip/chip-build-crosscompile:112 |
| 96 | + ``` |
| 97 | + |
| 98 | + Run docker |
| 99 | + |
| 100 | + ```sh |
| 101 | + docker run -it -v ~/connectedhomeip:/var/connectedhomeip ghcr.io/project-chip/chip-build-crosscompile:112 /bin/bash |
| 102 | + ``` |
| 103 | + |
| 104 | + Build |
| 105 | + |
| 106 | + ```sh |
| 107 | + cd /var/connectedhomeip |
| 108 | +
|
| 109 | + git config --global --add safe.directory /var/connectedhomeip |
| 110 | +
|
| 111 | + ./scripts/run_in_build_env.sh \ |
| 112 | + "./scripts/build/build_examples.py \ |
| 113 | + --target linux-arm64-fabric-sync-no-ble-clang \ |
| 114 | + build" |
| 115 | + ``` |
| 116 | + |
| 117 | + Transfer the fabric-bridge-app binary to a Raspberry Pi |
| 118 | + |
| 119 | + ```sh |
| 120 | + scp ./fabric-sync ubuntu@xxx.xxx.xxx.xxx:/home/ubuntu |
| 121 | + ``` |
| 122 | + |
| 123 | +## Running the Complete Example on Ubuntu |
| 124 | + |
| 125 | +- Building |
| 126 | + |
| 127 | + Follow [Building](#building) section of this document. |
| 128 | + |
| 129 | +- Run Linux Fabric Sync Example App on two Linux machine E1 and E2 |
| 130 | + |
| 131 | + ```sh |
| 132 | + sudo rm -rf /tmp/chip_* |
| 133 | + cd ~/connectedhomeip/ |
| 134 | + out/debug/fabric-sync |
| 135 | + ``` |
| 136 | + |
| 137 | +- Initiate the FS Setup Process from E1 to E2 |
| 138 | + |
| 139 | + ```sh |
| 140 | + > app add-bridge 1 20202021 192.168.86.246 5540 |
| 141 | + Done |
| 142 | + > New device with Node ID: 0000000000000001 has been successfully added. |
| 143 | + A new device has been added on Endpoint: 2. |
| 144 | + ``` |
| 145 | + |
| 146 | +- Verify Reverse Commissioning of the Fabric-Bridge from E1 on E2 |
| 147 | + |
| 148 | + ```sh |
| 149 | + > New device with Node ID: 0000000000000002 has been successfully added. |
| 150 | + ``` |
| 151 | + |
| 152 | +- Pair Light Example to E2 |
| 153 | + |
| 154 | + Since Fabric-Bridge also functions as a Matter server, running it alongside |
| 155 | + the Light Example app on the same machine would cause conflicts. Therefore, |
| 156 | + you need to run the Matter Light Example app on a separate physical machine |
| 157 | + from the one hosting Fabric-Sync. |
| 158 | + |
| 159 | + ```sh |
| 160 | + > app add-device 3 <setup-pin-code> <device-remote-ip> <device-remote-port> |
| 161 | + ``` |
| 162 | + |
| 163 | + After the device is successfully added, you will observe the following |
| 164 | + message on E2 with the newly assigned Node ID: |
| 165 | + |
| 166 | + ```sh |
| 167 | + > New device with Node ID: 0x3 has been successfully added. |
| 168 | + ``` |
| 169 | + |
| 170 | + Additionally, you should also get notified when a new device is added to E2 |
| 171 | + from the E1: |
| 172 | + |
| 173 | + ```sh |
| 174 | + > A new device is added on Endpoint 3. |
| 175 | + ``` |
| 176 | + |
| 177 | +- Synchronize Light Example to E1 |
| 178 | + |
| 179 | + After the Light Example is successfully paired in E2, we can start to |
| 180 | + synchronize the light device to E1 using the new assigned dynamic endpointid |
| 181 | + on Ecosystem 2. |
| 182 | + |
| 183 | + ```sh |
| 184 | + > app sync-device <endpointid> |
| 185 | + ``` |
0 commit comments