Device Shadow

Every edge deployment has a device shadow — a cloud-side data structure that tracks the configuration state of the edge gateway. The shadow acts as an intermediary between the cloud platform (which defines what the configuration should be) and the edge gateway (which reports what it has actually applied).

Shadow state model

The shadow consists of three sections:

Desired state

The desired state is managed by the cloud platform. It represents the configuration that should be running on the edge gateway. When you publish a configuration, the platform updates the desired state.

Reported state

The reported state is managed by the edge gateway. The config agent updates it after attempting to apply a configuration.

Delta

The delta is computed automatically by comparing the desired and reported states.

How synchronization works

The config agent on the edge gateway polls the cloud every 30 seconds. When it detects that the desired config version is higher than the reported version, it starts the synchronization process:

1. Poll — the agent calls the shadow API and checks delta.hasChanges
2. Mark applying — the agent notifies the cloud that it is applying the configuration
3. Download — the agent downloads the configuration bundle (profiles and devices)
4. Apply — the agent sends the profiles and devices to the local edge core-metadata service
5. Report — the agent reports the result back to the cloud (success or errors)

If the application succeeds, the reported config version is updated to match the desired version, and the sync status becomes In Sync. If it fails, the errors are recorded in the reported state, and the sync status becomes Error.

Edge configuration bundle

The configuration bundle that the agent downloads contains two sections:

Device profiles

Each connector in the site generates one device profile. A profile defines the data points (called device resources) that Fleetera Edge should read from the connected equipment.

A device resource includes:

• Name — a unique identifier combining the asset alias and variable key (for example, pump_01_DischargePressure)
• Value type — the data type (for example, Float64, Int32, Bool)
• Read/write mode — whether the resource is read-only or read-write
• Units — the engineering unit (for example, kW, °C)
• Attributes — protocol-specific addressing (for example, an OPC UA node ID)

Device configurations

Each connector also generates one device configuration. A device configuration tells Fleetera Edge how to connect to the equipment and what data to collect.

A device configuration includes:

• Service name — the edge device service to use (for example, device-opc-ua-1)
• Profile name — the device profile to apply
• Protocol settings — endpoint address, security policy, and authentication
• Auto events — the collection schedule for each data point, derived from the binding sampling interval

Discovery utility

OPC UA address space discovery is performed by an optional Edge Crawler utility container that ships alongside Fleetera Edge. Discovery is only available when:

1. A deployment exists for the site
2. The deployment status is Online (the gateway has reported a heartbeat)
3. The crawler utility is enabled on the deployment (utilities.crawler = true)

Toggling the crawler utility is a configuration change like any other — flipping it republishes the deployment's compose file and the edge gateway pulls the new container on its next sync cycle (typically about 30 seconds). The connector's Data Model tab surfaces a readiness banner that walks the user through any missing prerequisite and offers a one-click Enable Discovery Utility action.

Config agent

The config agent is a lightweight Go application that runs as a Docker container alongside Fleetera Edge on the edge gateway. It handles:

• Configuration polling — checks for changes every 30 seconds
• Configuration application — downloads and applies profiles and devices to Fleetera Edge
• Heartbeats — sends a heartbeat to the cloud every 60 seconds
• Error reporting — reports application failures with structured error details
• Idempotent updates — uses a create-or-update pattern so that re-applying the same configuration is safe

The agent starts by waiting for the core-metadata service to become ready, then enters its polling loop. It handles graceful shutdown on SIGINT and SIGTERM signals.