Device route architecture¶
Your integration contract is a hostname, two ports, two protocols and one certificate chain. Everything the platform does after that is deliberately opaque: it is free to change — and does — without any change to what a device sends or receives.
┌───────────────────────────── Your device / terminal ────────────────────────┐
│ Unified DDI SDK: Python │ Android/Kotlin │ C │ emulator │
│ │
│ Holds: private key (never leaves the device) │
│ device certificate ─ SAN carries the authoritative thing_id │
│ CA chain ─ used to verify the endpoint below │
└──────────────┬──────────────────────────────────────┬───────────────────────┘
│ │
│ TLS 443 (mTLS after enrolment) │ MQTT 8883 (mTLS)
│ identify, provision, rotate, │ telemetry, client
│ time, OTA poll/download/feedback │ attributes, commands,
│ │ shared configuration
▼ ▼
┌───────────────────────────────────────────────────────────────┐
│ things.flexgalaxy.ai │
│ the ONLY managed-environment device hostname │
│ │
│ Presents a server certificate issued by the SAME device CA │
│ chain your certificate chains to. Pin that chain; do not │
│ pin a public web CA and do not pin an IP address. │
│ │
│ Requires a client certificate on both ports. No anonymous │
│ and no plaintext listener exists on either. │
└───────────────────────────────┬───────────────────────────────┘
│
═════════════════▼═════════════════
FlexGalaxy.AI platform boundary
═══════════════════════════════════
Beyond this line nothing is part of your contract: not a host,
not a port, not a product name, not a message bus. The device
never authenticates to, addresses, or is configured with any of
it. Enrolment, OTA storage, telemetry routing and the management
applications all live here and may move at any time.
═══════════════════════════════════
▲
│ a separate, browser-authenticated path
│ that never touches the device route
┌─────────────┴─────────────┐
│ Authorized human user │
│ management applications │
└───────────────────────────┘
What crosses the boundary, and what never does¶
Crosses to your device |
Never reaches your device |
|---|---|
Its own certificate, the CA chain, and connection settings |
any credential belonging to a backend system |
Commands and shared attributes addressed to it |
any hostname, tenant, controller id or token for a backend system |
OTA deployment documents and artifacts, relayed |
a direct link to wherever artifacts are stored |
Every OTA link a device follows must resolve back to
https://things.flexgalaxy.ai/ddi/v1/ota. The SDK rejects a link that changes
origin or escapes that prefix — treat a link that fails that check as a fault,
not as a redirect to follow.
Two planes that meet only behind the boundary¶
The human management plane and the device data plane are separate. A browser application never calls the device route, and a device never calls a browser application. Authoring a rollout, approving a licence or reviewing fleet state are human actions in a management application; the device only ever sees the result arrive over one of its two connections.
This is why a device is never configured with a management API key, and why a device certificate cannot be used to sign in to anything.
Composite products¶
A customer-visible product can contain more than one DDI identity. Give each
computer that independently opens MQTT and OTA sessions its own certificate and
thing_id, then group those identities under one management-plane asset. A
non-networked MCU can remain a component of its controller, with telemetry and
OTA installation proxied by that controller. See
Composite robot terminal design for the complete
two-device example.
Which calls use DDI¶
Device-originated identity, telemetry, attributes, commands, time, and OTA use the DDI device surface when that capability is marked live.
Bazaar management calls remain in Bazaar. DDI does not carry Marketplace, EntitleKit approval/billing, publication, or rollout-authoring traffic. A future certificate-bound device license-status route may be exposed by DDI, but the management workflow and external integrator AK/SK remain in EntitleKit.
TrustMint management calls remain in TrustMint APIs. Device data reaches those services only after the gateway or broker authenticates and translates it.