Overview
The Frame Analytics Controller is a deployment-specific Linux edge device. It interfaces with physical equipment, collects state, maintains an authenticated communications path, enforces local policy, and executes only supported operations.
The Controller is not a remote shell with a relay attached. Broker messages map to explicit handlers. Unknown operations are rejected rather than passed to a shell, interpreter, eval(), or arbitrary subprocess.
Typical capabilities
Connectivity
4G LTE, Wi-Fi, Ethernet, serial links, and deployment-specific fallback paths.
Inputs
Digital and analog sensors, flow meters, switches, serial devices, cameras, GPS, and equipment state.
Outputs
Relays, indicators, motor-control interfaces, alarms, and other bounded actuators.
Local behavior
Watchdogs, safe defaults, command expiry, cached schedules, and operation during intermittent network service.
Controller command lifecycle
- Receive
Consume a message from the Controller's assigned, authenticated route.
- Authenticate
Verify broker identity and, where used, the message signature and certificate boundary.
- Validate
Check schema, Controller ID, command ID, timestamp, expiry, arguments, and supported operation.
- Authorize locally
Apply device capability, current state, and safety policy. A valid network message is not automatically a safe physical action.
- Journal before execution
Persist the command ID and intended transition so retries and restarts do not create duplicate physical actuation.
- Execute and report
Run the typed handler, capture measured state, and publish a success, rejection, expiry, or failure event.
Offline behavior
The Controller must define what remains possible when cellular service, DNS, the message broker, or the central platform is unavailable. Local protection and equipment interlocks stay authoritative. Cached schedules and deferred telemetry are deployment choices, not automatic defaults.
Commands should expire quickly enough for the equipment and operation. A reconnect should not replay an old action merely because transport eventually became available.
Deployment checklist
- Unique Controller identity and credentials
- Correct power budget, grounding, enclosure, and environmental rating
- Verified cellular bands, APN, antenna placement, signal, and data path
- Explicit GPIO, relay, and active-high/active-low mapping
- Electrical isolation and equipment interface reviewed
- Local fail-safe state tested with the network disconnected
- Command expiry and replay protection tested across restart
- Logs, health state, update, rollback, replacement, and recovery documented
Docker-only reference agent
The release includes an optional companion agent container under controller_agent/. It consumes only the fixed website Controller queue, verifies the signed reference-demo envelope, maps led.on to one GPIO handler, and stores replay state on a mounted volume. Production Controller images should be built and versioned independently from the public website image.
Operational tests
Exercise combinations, not neat single failures: power loss during a command, modem reconnection during telemetry, a broker outage, certificate expiry, duplicate delivery, a Controller restart with an actuator active, a full replay database, and a sensor value that remains plausible while no longer changing.