Sync Bridge

For the illustrated installation and automatic deployment workflow, see Center and edge deployment.

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.

Prepare access and choose roles

Before you start

1. Create one Sync Bridge target on the Hub and one on each Edge.
2. If TLS is required, prepare a server certificate for the Hub and a client certificate with its private key for each Edge, and trust the issuing CA on both sides in Development Configuration → Certificate Management. The Edge certificate DNS name or subject name must match that Edge's Local Peer ID. No certificates are required when TLS is disabled.
3. Use the same verification token on both sides and a unique local Peer ID for every node.
4. Allow each Edge to reach the Hub listening address and port.

Open the plugin

Open Development Configuration → Data Forwarding and:

1. Save one Sync Bridge target on the Hub and one on each Edge.
2. Fill in the target group, name, enable state, and start timeout.
3. In Target properties, choose the role and configure its listen address or Hub endpoint list, identity, and synchronization limits. Select Enable mutual TLS and choose certificates when encryption is required.
4. 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.

Connections, failover and security

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.

An actual link error triggers reconnection, such as a heartbeat failure or timeout, a real-time send/acknowledgement timeout, a configuration-sync error, or a closed transport. Every connection cycle starts at the first HubEndpoints entry. Only a failed connection or handshake advances to the next entry in that cycle; an available original endpoint can be selected again. The connected Hub then receives configuration verification and latest-state recovery before normal updates continue.

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)	Handshake secret required for both TCP and TLS; Hub and Edge values must match exactly.
Enable mutual TLS	Disabled	Both sides must use the same setting. Enable for mutual TLS; disable for TCP with certificate settings hidden.
Transport certificate	Empty (required with TLS)	Select from the dropdown. The Hub lists server certificates; an Edge lists client certificates.
Transport CA certificate	Empty (required with TLS)	Select the CA used to validate the peer certificate chain from the dropdown.
TLS target host	Configured per endpoint	With TLS enabled, each Edge endpoint must match the Hub certificate DNS name or SAN; the Hub listener role does not use this field.
TLS protocol	System default	Select TLS 1.2, TLS 1.3, or both. Selecting System default lets the operating system negotiate and clears explicit protocol selections. The dropdown offers only these three options; SSL 2.0, SSL 3.0, TLS 1.0, TLS 1.1, and other invalid protocol values are rejected.
Check certificate revocation	Enabled	Checks whether the peer certificate has been revoked according to the project certificate policy.

Choose the role before opening Transport certificate. If the required certificate is missing, generate or import a certificate with the correct purpose in Certificate Management, then reopen the dropdown. Changing roles does not replace the saved certificate automatically; confirm its purpose before saving.

The Edge certificate name binds its node identity and differs from the resource name in Certificate Management. For example, a Local Peer ID of edge-01 requires an Edge certificate DNS name or subject name of edge-01. The Hub certificate name instead matches the endpoint's TLS target host. A trusted CA and the correct certificate purpose alone do not complete authentication. After changing a Peer ID, select a matching certificate, then verify a new session, committed configuration revision, and a new source value at the Hub.

Alternatively, use Studio → Site Management → Data Synchronization to connect both gateways, select the Edge forwarding group, and configure and enable synchronization. Enabling TLS in that workflow generates and installs the required certificates automatically, without a synchronization pairing package.

Configure synchronization and backfill

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	Batches samples before sending; repeated samples for one variable are preserved.
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 sample records in one batch; repeated samples for one variable each count as a record.
Recovery latest-snapshot limit	200000	1 to 1000000	Latest variable identities retained for reconnect or manual snapshot recovery. An insufficient limit drops recovery values; it is independent of history cache rows.
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.

The byte limit covers the complete UTF-8 batch, including peer, epoch, sequence, revision, timestamps, array structure, and multibyte text. Configuration chunks use their own limit; Begin, every Push, and Commit must finish before the configuration is applied.

For a scope of 65 variables, a batch count of 16 creates several acknowledged batches. A recovery limit of 4 cannot restore all 65 latest values even when configuration was committed completely. Size it for the actual scope and check dropped counts and source identities in diagnostics.

Concurrent configuration peers controls Hub maintenance requests across Edges. It does not add real-time upload workers. Edge upload concurrency must remain 1; other values are rejected. Check each peer's revised metadata and committed configuration after concurrent maintenance.

Offline cache and central history

The Edge uses the same CacheDB queue as MQTT upload targets. Group-produced changes and scheduled snapshots remain queued during disconnection or send failure and are removed after a successful Hub acknowledgement. Persisted records survive target restarts. The Hub role does not create an outbound cache.

Setting	Description
Enable failed-send retry cache	Enabled by default. Disabling it discards disconnected or failed records without retry.
Maximum cache rows	Default 262144, greater than 0. Each queue removes its oldest records when full; a row can hold a change or a snapshot.
Memory queue limit	Default 100000, greater than 0. At capacity, persist pending records first. If persistence fails, retain accepted records and reject new records for upstream retry.
Upload shard size	Default 2000, greater than 0. Real-time batch count and byte limits also apply.
Upload concurrency	Must be 1 to preserve sequence order on the connection.
Filter offline data	Disabled by default. Filters samples that were offline at the source; group filtering also applies.

To backfill central history:

1. Enable Edge caching and configure the group scope and change or scheduled triggers.
2. On the Hub, open Development Configuration → Data Forwarding, include the mirror variables in a group, and enable a Historical Data Storage target with the required database and time zone.
3. Late and unchanged samples enter history with their source timestamps while current values retain the latest state. Backfill stores the processed Edge value without reapplying the center's read expression.
4. Check the backlog under Debug → Cache, then query the disconnected period in central history. See Offline cache and historical backfill for time columns and plugin limits.

Backfill follows the central group's scope, enable state and online filter. It bypasses change detection, scheduled resampling and replacement by a latest group snapshot. Central scheduled collection still produces additional local records; select change triggering when only source records are required.

Only records actually produced and retained within cache limits can be replayed. Disabled targets do not collect new records, and variables removed from scope are excluded. A Hub acknowledgement confirms batch processing, not a database commit; database targets write through their own queues. Lost acknowledgements and partial-batch retries can create duplicate records. Switching Hubs does not replicate already acknowledged data to another Hub.

Verify latest-state recovery and replay of older samples separately. Reconnection can restore current state even with failed-send retention disabled; it does not recreate discarded old samples. Track normal staging and in-flight records separately. Target offline filtering applies to ordinary cached sending. The latest recovery snapshot still preserves source quality, so offline states can appear during recovery with that filter enabled.

An acknowledgement can time out after the Hub has already applied a batch. A retry may return Applied or Duplicate. Compare the same variable identity and source timestamp; a repeated acknowledgement is not a new sample. Failure initiates reconnection, but an available preferred endpoint can be selected again rather than immediately switching to a backup.

Configuration and real-time rules

• The Hub can request configuration from one Edge or all known Edges.
• The Hub creates mirror devices and variables without collection channels. The device editor displays SyncBridge Mirror and its automatic management description; its plugin cannot be replaced manually. Maintain connection settings on the owning Sync Bridge target.
• Mirrors are internal devices managed by the server and cannot be manually created, copied, or deleted. Device management labels them Internal. A selection containing internal devices cannot be deleted; Clear Devices removes only regular collection devices and retains mirrors and their variables. Protection also applies while a mirror is disabled or offline.
• Internal devices remain editable: you can change their name, description, log level, enabled state, and remarks. Saving these local settings preserves their internal identity and deletion protection.
• 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 current values are restored and cached records are replayed before new samples continue.

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.

Debug and acceptance checks

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.

Synchronization and write-back checks

1. Select synchronization on reconnect, connect, then change an in-scope Edge variable description. New values can arrive while the Hub description remains at the previous revision.
2. Request synchronization on the Hub or reconnect the Edge. Confirm the new description and revision.
3. Select synchronization on change and reconnect, change the description again, and verify automatic metadata and value updates.
4. Repeat checks for each Hub; endpoint failover does not synchronize their historical databases.

Reverse writes require the Hub mirror's write and RPC permissions, reverse RPC enabled on both targets, the Edge source variable's write and RPC permissions, and field-protocol/device permission. New mirrors are read-only with RPC disabled. Test a denied permission at a safe point, then enable the required permissions and write a different value. Compare the per-variable result, independent source value, new Edge sample, and Hub mirror.

Multiple Hubs and historical replay

1. Record the active Hub, revision, applied sequence, and source value.
2. During maintenance, interrupt the active link. Check the failover count, failed-endpoint error, configuration commit, and latest state on the backup Hub.
3. Produce a new source value and check its time and sequence. Restore the preferred Hub and confirm that the healthy current connection remains in use.
4. For individual history records, select change triggering without group batching. Disconnect all Hubs, produce distinct values at distinct times, and reconnect. Check the recovery snapshot separately from cached batches and acknowledgements.
5. Query the disconnected interval in the Hub database and confirm that the live mirror retains its newest value. Snapshot capacity, cache capacity, shard size, and real-time limits constrain different stages.

See Offline cache and replay for queue sizing and duplicate handling.

Verify the target

1. Enable the Hub and Edge targets. Confirm that the Hub debug panel lists the Edge Peer ID as connected.
2. Request a single-Edge configuration synchronization from the Hub and confirm matching revision and checksum.
3. Change one approved test variable inside the Edge forwarding range.
4. Confirm the value, update time, and inbound sequence on the Hub, and make sure pending and inflight counts return to normal.
5. Interrupt the current Hub's actual link. Confirm that an error triggers a new priority-ordered connection cycle and an unavailable preferred Hub leads to a backup. A recovered primary must not displace a healthy backup connection automatically.
6. Interrupt the current backup. On the next connection cycle, confirm that endpoints are retried from highest priority and synchronization resumes.
7. During maintenance, interrupt all Hub links and generate several Edge samples. Restore connectivity and verify that the cache drains, central history retains original collection and record times, and current values do not roll back.

Troubleshooting

Symptom	Check
Edge cannot connect to Hub	Hub listen address, Edge remote address, firewall, verification token, and both target logs.
TLS handshake or subsequent identity authentication fails	Check the certificate and private key, CA, purpose, validity, and revocation policy. The Edge certificate DNS name or subject name must match its Local Peer ID; the Hub certificate name must match the TLS target host.
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.