How Integration Works

Architecture overview

Every CoppelBox device holds a unique X.509 certificate and connects directly to AWS IoT Core over MQTT (TLS, port 8883) — there is no intermediary gateway between the device and the cloud. From there, the data flows one way through the platform:

CoppelBox Device (ESP32)
    │  MQTT over TLS — /cbox/{deviceId}/...
    ▼
AWS IoT Core
    │  IoT Rules (SQL-based routing; one rule per topic/purpose)
    ▼
DynamoDB  (device status, alerts, relay config, Ivy Board telemetry)
    │  DynamoDB Streams
    ▼
Lambda (DynamoDB-to-AppSync)
    │  GraphQL mutation
    ▼
AWS AppSync  ── WebSocket subscription ──▶  Your application

This is a push, not poll, architecture end to end: a device publishes a status packet, an IoT Rule writes it to DynamoDB, the DynamoDB Stream fires a Lambda, and that Lambda pushes a GraphQL mutation through AppSync to every subscribed client — typically in under a second, and almost always under five.

Each customer deployment (including yours) runs in its own AWS account, with its own IoT Core endpoint, DynamoDB tables, and AppSync API. Nothing is shared across customers at the infrastructure level.

What data is available

Data	Source topic	What it contains
Status / telemetry	/cbox/{deviceId}/status	Relay states, battery, network, system health, OTA progress, certificate expiry — published every 20 seconds and immediately on any relay change
Power / energy	/cbox/{deviceId}/status (real-time) and /cbox/{deviceId}/power (buffered history)	Voltage, current, frequency, active power and cumulative energy for the internal (and, if fitted, external) meter
Alerts	/cbox/{deviceId}/alerts	Fault and warning events — AC/DC power loss, meter loss, AP activation — with priority, state, and resend tracking
Relay configuration	/cbox/{deviceId}/config	Per-relay label, mode (normal / pulse-only), default pulse duration, and retained state
Ivy Board telemetry (if fitted)	/cbox/{deviceId}/ivy	Environmental sensor and output data from an attached Ivy Board module
OTA / firmware status	/cbox/{deviceId}/ota	Firmware update progress and post-update success/rollback notifications

See Telemetry and Alerts for the full payload shapes.

Integration options

There are two distinct ways to get this data into your own systems, and which one applies to you depends on the access you've been given — see Authentication & Access for the credentials model.

1. Through the platform's GraphQL API (AppSync) — the supported way for an external application to read device data and receive real-time updates. You sign in with a CoppelBox user account (Cognito) and query or subscribe over HTTPS/WebSocket. The fields returned mirror the MQTT payload shapes described in this guide (e.g. internalMeter, battery, ota appear with the same nested structure), so understanding the wire format below is directly useful even if you never touch MQTT yourself.
2. Understanding the underlying MQTT wire protocol — this is what a device actually sends. It's the authoritative reference for interpreting the data, whether you receive it via the API above or (if you've been provisioned with direct broker credentials for a bespoke integration) by subscribing to AWS IoT Core yourself. The rest of this guide — MQTT API, Telemetry, Alerts — documents that protocol.