Sync Bridge
Purpose
Sync Bridge synchronizes selected configuration and real-time variables between one public Hub and one or more Edge nodes. The Hub listens for and aggregates Edge connections. Each Edge connects to the Hub and publishes its local mirror.
Configure the forwarding group range and target runtime state through Data Forwarding. This page covers the complete Sync Bridge role, multi-Hub endpoints, mutual-TLS, synchronization, failover, and debug settings.
Before you start
- Create one Sync Bridge target on the Hub and one on each Edge.
- Prepare a transport certificate for every node and configure both sides to trust the same CA in Development Configuration → Certificate Management.
- Use the same verification token on both sides and a unique local Peer ID for every node.
- Allow each Edge to reach the Hub listening address and port.
Open the plugin
Open Development Configuration → Data Forwarding and:
- Save one Sync Bridge target on the Hub and one on each Edge.
- Fill in the target group, name, enable state, and start timeout.
- In Target properties, choose the role and configure its listen address or Hub endpoint list, identity, mutual TLS, and synchronization limits.
- Enable the targets, confirm the Hub and Edge are connected, then run configuration and real-time verification.
Basic target information
| Setting | Default | Configuration |
|---|---|---|
| Group | - | Select a saved forwarding group; an Edge publishes only that group's range. |
| Target name | - | Required and unique within the group. |
| Enable | Enabled | Disable to stop listening or connecting. |
| Log level | Info | Temporarily use Debug for TLS, handshake, or synchronization diagnostics. |
| Start timeout | 60 seconds | Valid range is 1 to 3600 seconds. |
Roles and connection
| Setting | Default | Description |
|---|---|---|
| Role | EdgePublisher | Select HubServer on the Hub or EdgePublisher on an Edge. |
| Local Peer ID | Empty (required) | Use 1 to 100 letters, digits, dots, underscores, or hyphens; every node must be unique. |
| Configuration sync mode | On change and reconnect | On reconnect compares only after connection or a Hub request. On change and reconnect also syncs when the Edge range changes. |
| Listen address | 0.0.0.0:7777 | Address used by the Hub. |
| Hub endpoints | Empty (required on Edge) | Edge tries the endpoint list in order. Each row contains a unique endpoint ID, Hub address, and TLS target host; up to 16 rows. Not used by the Hub role. |
Multi-Hub failover
An Edge keeps its current Hub connection while heartbeats, real-time acknowledgements, and configuration synchronization succeed. A normal idle connection does not trigger a switch.
Failover occurs only after an actual link error, such as a heartbeat failure or timeout, a real-time send/acknowledgement timeout, a configuration-synchronization error, or a closed transport connection. After the current endpoint fails, the Edge tries the next endpoint in HubEndpoints order, then verifies configuration and restores a full snapshot before continuing with real-time updates.
When the primary Hub recovers, the Edge does not probe it and does not automatically switch back from the current backup. If the current backup later fails and a new connection cycle starts, the Edge tries the endpoint list again from the highest priority. The debug page's current Hub, failover count, endpoint states, and latest error show why a switch occurred.
Authentication and TLS
| Setting | Default | Description |
|---|---|---|
| Verification token | Empty (required) | Second-stage handshake secret; Hub and Edge values must match exactly. |
| Transport certificate | Empty (required) | Select the node's server or client certificate for mutual TLS. |
| Transport CA certificate | Empty (required) | Select the CA used to validate the peer certificate chain. |
| TLS target host | Configured per endpoint | Each Edge endpoint must match the Hub certificate DNS name or SAN; the Hub listener role does not use this field. |
| TLS protocol | None (system default) | Select TLS 1.2 or TLS 1.3 when required; SSL 3.0, TLS 1.0, and TLS 1.1 are rejected. |
| Check certificate revocation | Enabled | Checks whether the peer certificate has been revoked according to the project certificate policy. |
Synchronization and capacity
| Setting | Default | Range | Description |
|---|---|---|---|
| Heartbeat interval (ms) | 5000 | 1000 to 60000 | Connection health-check interval. |
| Real-time flush window (ms) | 20 | 10 to 1000 | Combines variable changes before sending them. |
| Real-time acknowledgement timeout (ms) | 3000 | 500 to 60000 | Maximum wait for the Hub to acknowledge a real-time batch. |
| Variables per real-time batch | 2000 | 1 to 10000 | Maximum variables in one real-time batch. |
| Bytes per real-time batch | 262144 | 4096 to 1048576 | Maximum UTF-8 bytes in one real-time batch. |
| Configuration chunk bytes | 524288 | 4096 to 1048576 | Maximum UTF-8 bytes in one configuration chunk. |
| Concurrent configuration peers | 4 | 1 to 32 | Edge peers the Hub can request configuration from concurrently. |
| Allow reverse RPC | Disabled | - | Allows the Hub to write variables on an Edge; the variable write permission must also allow it. Enable only with explicit site authorization. |
Configuration and real-time rules
- The Hub can request configuration from one Edge or all known Edges.
- Revision, checksum, staged chunks, and one atomic commit prevent partial configuration from being applied.
- Existing mirror variables update only data type, unit, and description. The Hub keeps local names, expressions, alarms, history, and write permissions.
- If an Edge deletes a variable or removes it from scope, the Hub keeps the local mirror and marks the source missing.
- Real-time values are validated by Epoch, Sequence, and configuration revision. The Hub acknowledges applied values, and late values cannot overwrite newer state.
- After reconnecting, configuration is verified first, then a complete current-value snapshot is restored before incremental updates resume.
Target variable properties
This plugin has no additional target variable fields. A variable must already be inside the Edge target's forwarding group. Reverse writes must also satisfy source-variable permission and site safety rules.
Functions
| Function | Purpose |
|---|---|
| Status and peers | Use Status and peers to check the connection state and latest result. |
| Configuration synchronization | Use Configuration synchronization and review the returned result. |
| Send full snapshot | Use Send full snapshot with an approved test point and confirm site safety before execution. |
| Reconnect | Use Reconnect and review the returned result. |
| Export diagnostics | Use Export diagnostics to inspect mapped values, status, counters, recent messages, or the latest result. |
Target debug
Open Development Configuration → Data Forwarding, select the Sync Bridge target, and open Debug → Protocol Debug · SyncBridge.
| Feature | Purpose |
|---|---|
| Status and peers | Shows role, local node, transport state, peer connections, pending counts, latency, and the latest error. |
| Synchronize configuration | Lets a Hub request all or selected configuration from Edge peers. |
| Send full snapshot | Makes an Edge send the current forwarding-range snapshot immediately. |
| Reconnect | Makes an Edge disconnect and establish a new Hub connection. |
| Export diagnostics | Exports connection and synchronization statistics for troubleshooting. |
Transport ready means the local listener or connection component has started. A Hub with no connected Edge may still be shown as offline.
Verify the target
- Enable the Hub and Edge targets. Confirm that the Hub debug panel lists the Edge Peer ID as connected.
- Request a single-Edge configuration synchronization from the Hub and confirm matching revision and checksum.
- Change one approved test variable inside the Edge forwarding range.
- Confirm the value, update time, and inbound sequence on the Hub, and make sure pending and inflight counts return to normal.
- Interrupt the current Hub's actual link. Confirm that the Edge switches only after an error to the next endpoint; after the primary recovers, it must not switch back automatically.
- Interrupt the current backup. On the next connection cycle, confirm that endpoints are retried from highest priority and synchronization resumes.
Troubleshooting
| Symptom | Check |
|---|---|
| Edge cannot connect to Hub | Hub listen address, Edge remote address, firewall, verification token, and both target logs. |
| TLS handshake fails | Transport certificate, CA, TLS target host, certificate validity, and revocation check. |
| Connected but no variables arrive | Edge forwarding range, configuration sync mode, full snapshot, and pending count. |
| Configuration does not synchronize | Peer ID, configuration revision, sync mode, then run Synchronize configuration from the Hub. |
| Reverse write fails | Allow reverse RPC, source-variable write permission, value type, and site interlocks. |
| Hub switches while idle | Inspect heartbeat, real-time acknowledgement, and configuration-sync logs. A healthy idle connection is retained; only an actual error or closed connection triggers failover. |
| The primary Hub does not take back the connection | This is expected. The Edge does not probe a recovered primary. It retries the priority list only when the current endpoint later fails and a new connection cycle starts. |
Related links
- Data Forwarding: Edge forwarding ranges and common target operations.
- Certificate Management: Generate or import transport and CA certificates.
- See Roles and connection and Multi-Hub failover on this page for the complete Hub, Edge, and redundant-endpoint configuration.
- Plugin Manual Index: Other collection and data-forwarding plugins.