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 HTTPS desired-state responses, MQTT desired-state messages, and optional feed-data metadata For desired-state items, track the latest value per command/resource context and ignore stale lower values. Echo it when the acknowledgement includes sequence metadata. Do not use it as the retry key. Orders desired-state delivery 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.

Runtime descriptors

Field Where it appears Firmware use Reason
available_protocols Runtime bootstrap Select only a protocol listed for this device. Do not infer that HTTPS and MQTT are both available when only one appears. Keeps the bootstrap descriptor protocol-aware without forcing false symmetry between HTTPS and MQTT.
catalog_revision and runtime_revision Runtime bootstrap Cache the descriptor only while the revision values match the local cache. Refresh bootstrap after reconnecting from a long offline interval or when local validation detects a mismatch. Treat generated_at as response freshness metadata, not as a cache-busting revision by itself. Gives firmware a stable way to identify which catalog and runtime hints it booted with without forcing a cache miss for every bootstrap read.
backoff Runtime bootstrap Use the documented HTTP Retry-After header first; use descriptor defaults only when the server response has no more specific retry hint. Lets firmware apply one conservative retry policy across bootstrap and runtime requests.

Desired-state correlation

Field Where it appears Firmware use Reason
desired_id HTTPS desired-state responses, 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.

UI-visible derived state

Resource cards and resource-control panels derive compact user-visible status from feed data, desired-state messages, catalog metadata, device availability, and authorization. These summaries are not extra firmware fields.

Derived state Primary inputs User-visible meaning
Command request lifecycle Desired-state messages and command feed-data reports Until a report with the matching desired_id arrives, Realer can show the last known current value together with the requested value. Request sent means accepted/sent, not physical success.
Sensor freshness value, value_received_at, expected_update_interval_seconds, minimum_supported_update_interval_seconds, and freshness policy Realer marks a reading stale only when a developer expected cadence or resource-owner override exists. The purchased plan defines the fastest supported cadence: HTTPS uses the request interval, and MQTT uses the source publish interval. Legacy values below that floor are clamped at runtime; without a configured policy, Realer can show the value and timestamp without marking it stale.
Capability status Command lifecycle, sensor freshness, device availability, and authorization Machine-facing summaries use active, warning, unavailable, or unknown. Resource cards roll those states up as Available, Limited, or Unavailable. An online command request waiting for acknowledgement is shown on the command row without necessarily degrading the resource from Available; offline pending, timeouts, failures, stale readings, and unavailable capabilities remain attention states.

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 HTTPS desired-state responses and 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 public IoT identifiers exactly as documented for the transport. HTTPS path/body ids and MQTT topic/payload ids are opaque public ids, not database row ids.
  • Record local safe behavior for network loss, expired authorization, application rejection, and stale desired-state messages.