Control device runtime

After OAuth client credentials authentication, a control device reads GET /iot/v1/devices/{device_id}/bootstrap to receive its runtime descriptor, then chooses one available runtime transport to exchange operational data with Realer: HTTPS polling or MQTT broker messaging.

Both transports use the same device identity, command and sensor catalog concepts, desired-state concept, and feed-data schema. HTTPS responses and MQTT acknowledgements expose stable application-level result fields for local firmware handling.

Choose one runtime transport

Runtime Use when Example applications API docs
HTTPS polling The device reads catalog state, polls desired states, sends feed data over direct requests, then sleeps or waits for the next polling cycle. Battery-powered sensors, environmental monitors, meter readers, or machines that report state periodically. Control device HTTPS flow
MQTT broker messaging The device keeps a broker connection open for MQTT publishes over TLS, desired-state messages, and application acknowledgements. Wall controllers, PLC gateways, access-control devices, or actuators that need low-latency desired-state delivery. Control device MQTT flow

Shared contract

Start with control device authentication. Then follow the runtime page for the transport your device uses.

  • Use the runtime bootstrap descriptor as the normal startup contract. It includes command and sensor definitions, expected and minimum cadence metadata, protocol-specific endpoint hints, and runtime revisions.
  • Use control device catalog docs for targeted granular command and sensor catalog reads.
  • Use desired-state delivery from the selected runtime: HTTPS polls /desired-states, MQTT subscribes to command desired_topic messages.
  • Use control device feeds docs for feed-data fields and command and sensor feed-data semantics.
  • Use field semantics for retry, ordering, correlation, expiry, and result-handling rules.
  • Use response codes for numeric HTTPS result handling in firmware.
  • For MQTT, use the MQTT payload reference after completing MQTT bootstrap.