Add Fabric Synchronization Guide

docs/guides/fabric_synchronization_guide.md

@@ -0,0 +1,164 @@
+# Fabric Synchronization Guide
+
+-   [Fabric Synchronization Guide](#fabric-synchronization-guide)
+    -   [Fabric Sync Example Applications](#fabric-sync-example-applications)
+    -   [Run Fabric Sync Demo on RP4](#run-fabric-sync-demo-on-rp4)
+
+## Fabric Sync Example Applications
+
+Fabric-Admin and Fabric-Bridge example applications are provided to demonstrate
+Fabric Synchronization feature. You can find them in the examples.
+
+![matter_fabric_synchronization](images/matter_fabric_synchronization.png)
+
+Fabric-Admin example app implements the Fabric Administrator role and
+communicate with the Fabric-Bridge-App on the other side, facilitating the
+Fabric Synchronization process.
+
+Fabric-Bridge-App example app implements the Aggregator device type with Fabric
+Synchronization condition met and demonstrates the end-to-end Fabric
+Synchronization feature using dynamic endpoints.
+
+Fabric Synchronization can be triggered from either side. The initiator of the
+Fabric Synchronization process, who shares their devices, takes on the
+Commissioner role. The recipient of the Fabric Synchronization request, who
+receives the shared devices, assumes the Commissionee role. This flexibility
+enables a seamless and efficient synchronization process.
+
+### Building the Example Application
+
+-   Building the Fabric-Admin Application
+
+    [Fabric-Admin](https://github.com/project-chip/connectedhomeip/tree/master/examples/fabric-admin/README.md)
+
+*   Building the Fabric-Bridge Application
+
+    [Fabric-Bridge](https://github.com/project-chip/connectedhomeip/tree/master/examples/fabric-bridge-app/linux/README.md)
+
+## Run Fabric Sync Demo on RP4
+
+### Setup Fabric Source
+
+Connect to the Fabric Source server:
+
+```
+ssh ubuntu@xxx.xxx.xxx.xxx
+```
+
+Password: <password>
+
+Run the Fabric Source script:
+
+```
+./run_fabric_source.sh
+```
+
+### Setup Fabric Sink
+
+Connect to the Fabric Sink server:
+
+```
+ssh ubuntu@xxx.xxx.xxx.xxx
+```
+
+Password: <password>
+
+Run the Fabric Sink script:
+
+```
+./run_fabric_sink.sh
+```
+
+### Fabric Sync Setup
+
+Enable Fabric Auto Sync:
+
+In Fabric-Sync console:
+
+```
+fabricsync enable-auto-sync 1
+```
+
+Pair the Fabric-Source bridge to Fabric-Sync with node ID 1:
+
+```
+fabricsync add-bridge 1 <fabric-sink-ip>
+```
+
+### Pair Light Example to Fabric-Source
+
+Pair the Light Example with node ID 3 using its payload number:
+
+```
+pairing already-discovered 3 20202021 <ip> 5540
+```
+
+After the Light Example is successfully paired in Fabric-Source, it will be
+synced to Fabric-Sink with a new assigned node ID.
+
+Toggle the Light Example:
+
+From Fabric-Source:
+
+```
+onoff on <node-id> 1
+onoff off <node-id> 1
+```
+
+From Fabric-Sink: (Use the node ID assigned)
+
+```
+onoff on x 1
+onoff off x 1
+```
+
+### Remove Light Example from Fabric-Source
+
+Unpair the Light Example:
+
+```
+pairing unpair <node-id>
+```
+
+After the Light Example is successfully unpaired from Fabric-Source, it will
+also be removed from the Fabric-Sink.
+
+### Pair Commercial Switch to Fabric-Source
+
+Pair the switch using its payload number:
+
+In Fabric-Source console:
+
+```
+pairing code-wifi <node-id> <ssid> <passwd> <payload>
+```
+
+After the switch is successfully paired in Fabric-Source, it will be synced to
+Fabric-Sink with a new assigned node ID.
+
+Toggle the switch:
+
+From Fabric-Source:
+
+```
+onoff on <node-id> 1
+onoff off <node-id> 1
+```
+
+From Fabric-Sink: (Use the node ID assigned)
+
+```
+onoff on <node-id> 1
+onoff off <node-id> 1
+```
+
+### Remove Switch from Fabric-Source
+
+Unpair the switch:
+
+```
+pairing unpair <node-id>
+```
+
+After the switch is successfully unpaired from Fabric-Source, it will also be
+removed from the Fabric-Sink.

examples/fabric-admin/scripts/run_fabric_sink.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Default paths
+FABRIC_ADMIN_PATH="./fabric-admin"
+FABRIC_ADMIN_LOG="/tmp/fabric_admin.log"
+
+# Detect platform and set default paths
+if [[ $(uname -m) == "x86_64" ]]; then
+    FABRIC_ADMIN_PATH="out/debug/standalone/fabric-admin"
+fi
+
+# Check if --verbose option is specified
+VERBOSE=false
+for arg in "$@"; do
+    if [ "$arg" == "--verbose" ]; then
+        VERBOSE=true
+        break
+    fi
+done
+
+# Kill fabric-admin if it is running
+echo "Checking for running fabric-admin process..."
+fabric_admin_pid=$(pgrep -f "$FABRIC_ADMIN_PATH")
+if [ ! -z "$fabric_admin_pid" ]; then
+    echo "Found fabric-admin with PID $fabric_admin_pid, attempting to kill..."
+    kill -9 "$fabric_admin_pid"
+    echo "Killed fabric-admin with PID $fabric_admin_pid"
+fi
+
+# Remove /tmp/chip_* files and directories
+echo "Removing /tmp/chip_* files and directories..."
+sudo rm -rf /tmp/chip_*
+echo "Removed /tmp/chip_* files and directories"
+
+# Start fabric-admin with or without log file path based on --verbose option
+echo "Starting fabric-admin..."
+if [ "$VERBOSE" = true ]; then
+    "$FABRIC_ADMIN_PATH"
+else
+    "$FABRIC_ADMIN_PATH" --log-file-path "$FABRIC_ADMIN_LOG"
+fi

examples/fabric-admin/scripts/run_fabric_source.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# Default paths
+FABRIC_ADMIN_PATH="./fabric-admin"
+FABRIC_BRIDGE_APP_PATH="./fabric-bridge-app"
+FABRIC_ADMIN_LOG="/tmp/fabric_admin.log"
+FABRIC_BRIDGE_APP_LOG="/tmp/fabric_bridge_app.log"
+
+# Detect platform and set default paths
+PLATFORM=$(uname -m)
+if [[ "$PLATFORM" == "x86_64" ]]; then
+    FABRIC_ADMIN_PATH="out/debug/standalone/fabric-admin"
+    FABRIC_BRIDGE_APP_PATH="out/debug/standalone/fabric-bridge-app"
+fi
+
+# Check if --verbose option is specified
+VERBOSE=false
+for arg in "$@"; do
+    if [ "$arg" == "--verbose" ]; then
+        VERBOSE=true
+        break
+    fi
+done
+
+# Stop any running instances and clean up
+
+if [[ "$PLATFORM" == "x86_64" ]]; then
+    ./examples/fabric-admin/scripts/stop_fabric_source.sh
+elif [[ "$PLATFORM" == "aarch64" ]]; then
+    ./stop_fabric_source.sh
+fi
+
+# Start fabric-bridge-app if available and redirect its output to /dev/null
+if [ -f "$FABRIC_BRIDGE_APP_PATH" ]; then
+    "$FABRIC_BRIDGE_APP_PATH" >"$FABRIC_BRIDGE_APP_LOG" 2>&1 &
+    echo "Started fabric-bridge-app"
+fi
+
+# Start fabric-admin with or without log file path based on --verbose option
+if [ "$VERBOSE" = true ]; then
+    "$FABRIC_ADMIN_PATH"
+else
+    "$FABRIC_ADMIN_PATH" --log-file-path "$FABRIC_ADMIN_LOG"
+fi

examples/fabric-admin/scripts/stop_fabric_source.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+FABRIC_ADMIN_PATH="./fabric-admin"
+FABRIC_BRIDGE_APP_PATH="./fabric-bridge-app"
+
+# Kill fabric-admin if it is running
+fabric_admin_pid=$(pgrep -f "$FABRIC_ADMIN_PATH")
+if [ ! -z "$fabric_admin_pid" ]; then
+    kill -9 "$fabric_admin_pid"
+    echo "Killed fabric-admin with PID $fabric_admin_pid"
+fi
+
+# Kill fabric-bridge-app if it is running
+fabric_bridge_app_pid=$(pgrep -f "$FABRIC_BRIDGE_APP_PATH")
+if [ ! -z "$fabric_bridge_app_pid" ]; then
+    kill -9 "$fabric_bridge_app_pid"
+    echo "Killed fabric-bridge-app with PID $fabric_bridge_app_pid"
+fi
+
+# Remove /tmp/chip_* files and directories
+sudo rm -rf /tmp/chip_*
+echo "Removed /tmp/chip_* files and directories"