Skip to content

Commit 14a98e9

Browse files
yufengwangcayufengwangca
authored
[Fabric-Sync] Initial version of fabric-sync example (#36136)
* [Fabric-Sync] Initial version of fabric-sync example * Add Readme.txt * Remove unused define flag
1 parent 9099608 commit 14a98e9

File tree

12 files changed

+6977
-0
lines changed

12 files changed

+6977
-0
lines changed

‎docs/examples/fabric_sync.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Fabric Sync
2+
3+
```{toctree}
4+
:glob:
5+
:maxdepth: 1
6+
7+
fabric-sync/README
8+
```

‎examples/fabric-sync/.gn

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

‎examples/fabric-sync/BUILD.gn

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Copyright (c) 2024 Project CHIP Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import("//build_overrides/build.gni")
16+
import("//build_overrides/chip.gni")
17+
import("${chip_root}/build/chip/tools.gni")
18+
import("${chip_root}/src/lib/lib.gni")
19+
20+
assert(chip_build_tools)
21+
22+
executable("fabric-sync") {
23+
cflags = [ "-Wconversion" ]
24+
25+
include_dirs = [
26+
".",
27+
"${chip_root}/src/lib",
28+
]
29+
30+
sources = [ "main.cpp" ]
31+
32+
deps = [
33+
"${chip_root}/examples/fabric-sync/bridge:fabric-bridge-lib",
34+
"${chip_root}/examples/fabric-sync/bridge:fabric-bridge-zap",
35+
"${chip_root}/examples/platform/linux:app-main",
36+
"${chip_root}/src/lib",
37+
"${chip_root}/third_party/inipp",
38+
]
39+
40+
output_dir = root_out_dir
41+
}
42+
43+
group("default") {
44+
deps = [ ":fabric-sync" ]
45+
}

‎examples/fabric-sync/README.md

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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+
`ATTRIBUTE_MASK_EXTERNAL_STORAGE` in the ZCL database and therefore will
55+
rely on the application to maintain storage for the attribute. Consequently,
56+
reads or writes to these attributes must be handled within the application
57+
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+
```
86+
./scripts/examples/gn_build_example.sh examples/fabric-sync out/debug/standalone
87+
```
88+
89+
### For Raspberry Pi 4 example:
90+
91+
TODO
92+
93+
## Running the Complete Example on Ubuntu
94+
95+
- Building
96+
97+
Follow [Building](#building) section of this document.
98+
99+
- Run Linux Fabric Sync Example App
100+
101+
```sh
102+
cd ~/connectedhomeip/
103+
sudo out/debug/fabric-sync
104+
```

‎examples/fabric-sync/args.gni

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Copyright (c) 2024 Project CHIP Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import("//build_overrides/chip.gni")
16+
17+
import("${chip_root}/config/standalone/args.gni")
18+
19+
chip_device_project_config_include = "<CHIPProjectAppConfig.h>"
20+
chip_project_config_include = "<CHIPProjectAppConfig.h>"
21+
chip_system_project_config_include = "<SystemProjectConfig.h>"
22+
23+
chip_project_config_include_dirs =
24+
[ "${chip_root}/examples/fabric-sync/bridge/include" ]
25+
chip_project_config_include_dirs += [ "${chip_root}/config/standalone" ]
26+
27+
chip_build_libshell = true
28+
29+
chip_enable_additional_data_advertising = true
30+
31+
chip_enable_rotating_device_id = true
32+
33+
chip_config_network_layer_ble = false
34+
35+
matter_enable_tracing_support = true
36+
matter_log_json_payload_hex = true
37+
matter_log_json_payload_decode_full = true
38+
39+
# Thread devices do not support WakeOnLan because their mac address is >48bit
40+
chip_enable_openthread = false

‎examples/fabric-sync/bridge/BUILD.gn

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Copyright (c) 2024 Project CHIP Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import("//build_overrides/chip.gni")
16+
import("${chip_root}/src/app/chip_data_model.gni")
17+
import("${chip_root}/src/lib/lib.gni")
18+
19+
config("config") {
20+
include_dirs = [ "include" ]
21+
}
22+
23+
chip_data_model("fabric-bridge-zap") {
24+
zap_file = "fabric-bridge.zap"
25+
is_server = true
26+
}
27+
28+
# This includes all the clusters that only exist on the dynamic endpoint.
29+
source_set("fabric-bridge-common") {
30+
public_configs = [ ":config" ]
31+
32+
sources = [
33+
"${chip_root}/src/app/clusters/ecosystem-information-server/ecosystem-information-server.cpp",
34+
"${chip_root}/src/app/clusters/ecosystem-information-server/ecosystem-information-server.h",
35+
]
36+
37+
public_deps = [ ":fabric-bridge-zap" ]
38+
}
39+
40+
source_set("fabric-bridge-lib") {
41+
public_configs = [ ":config" ]
42+
43+
sources = [ "include/CHIPProjectAppConfig.h" ]
44+
45+
deps = [
46+
"${chip_root}/examples/fabric-sync/bridge:fabric-bridge-common",
47+
"${chip_root}/examples/platform/linux:app-main",
48+
"${chip_root}/src/lib",
49+
]
50+
}

0 commit comments

Comments
 (0)