Control device field semantics

Field semantics explain why selected API fields exist and how firmware should use them. Keep JSON payloads machine-clean, then use the field semantics reference for retry, ordering, correlation, expiry, and result-handling behavior.

The rules apply to both runtime transports when the same field appears in HTTPS requests, HTTPS responses, MQTT publishes, MQTT acknowledgements, or MQTT desired-state messages.

On this page

Event identity and retries

Field Where it appears Firmware use Reason
message_id HTTPS feed-data items and MQTT publish payloads Generate one stable id for one local physical event. Reuse it when retrying that same event. Use a new id only for a new event or intentional reconciliation report. Lets Realer replay the same result for duplicate delivery and detect a conflict when the same id is reused for a different payload.
sequence_number MQTT desired-state messages and optional feed-data metadata For desired-state messages, track the latest value per command route and ignore stale lower values. Echo it when the acknowledgement includes sequence metadata. Do not use it as the retry key. Orders desired-state messages for a route and helps diagnostics. Duplicate detection still uses message_id.
value_received_at HTTPS feed-data items and MQTT publish payloads Send the time the device observed the physical value. Prefer ISO 8601 UTC. Keeps device-observed time separate from cloud receive time, which matters after offline periods, buffering, or retries.

Desired-state correlation

Field Where it appears Firmware use Reason
desired_id MQTT desired-state payloads and command feed-data reports Copy it into the command report when the device applies, rejects, or marks that desired command as stale. Omit it for local physical changes. Correlates the physical command report with the exact Realer desired command that caused it.
report_status Command feed-data reports with desired_id Use applied, rejected, or stale for Realer desired commands. A fresh desired-command report without this field is treated as applied. Omit it for local physical changes without desired_id; if sent, only reported is valid. Separates desired-command lifecycle from local physical state reports, which Realer stores as reported.

Application results

Field Where it appears Firmware use Reason
code Canonical HTTPS iot/v1 responses Use the numeric value for stable local behavior after reading the HTTP status class. Keep the mapping local so firmware can choose retry, safe behavior, or operator diagnostics. Gives devices an application-level result contract that is more precise than HTTP status alone.
status MQTT feed-data application acknowledgements Treat accepted and replayed as success. Treat conflict, rejected, and error as application failures. MQTT PUBACK means broker acceptance only. This field is the application result for MQTT publishes.
retryable MQTT feed-data application acknowledgements Retry only when this value is true and the local device policy allows another attempt. Prevents blind retry loops when the application result is a validation failure, conflict, or another non-retryable condition.
error.type HTTPS error responses and MQTT negative acknowledgements Use it for diagnostics, logs, and developer tooling after handling code or MQTT acknowledgement status. Provides a stable readable label for humans and agents without creating a second numeric response-code system.

Expiry and renewal

Field Where it appears Firmware use Reason
expires_in OAuth token and MQTT credential responses Stop using the token or MQTT credential after this lifetime. Prevents firmware from depending on expired authorization.
renew_after OAuth token and MQTT credential responses Start renewal at this hint instead of waiting for hard expiry. Keep local safe behavior if renewal cannot complete. Gives firmware a normal renewal point with time left for network retries.
session_hard_expires_in MQTT credential responses when returned Reconnect with a fresh CONNECT tuple before this session limit. Bounds broker authority for long-running MQTT sessions.
valid_for_seconds and expires_at MQTT desired-state messages Execute only inside the desired-command window. Report stale when the device cannot safely apply the command in time. Prevents delayed desired commands from being applied after their safe execution window.

General implementation rules

  • Keep JSON examples and firmware payloads free of comments; use the field semantics reference for rationale.
  • Ignore unknown JSON fields unless a later contract documents them as required.
  • Use identifiers exactly as documented for the transport. MQTT payload ids are public IoT ids; HTTPS path and body ids use the documented device, command, and sensor ids.
  • Record local safe behavior for network loss, expired authorization, application rejection, and stale desired-state messages.