Skip to content

Session Lifecycle

An external session follows this sequence:

  1. hello
  2. query_state
  3. subscribe
  4. commands and events

Required Sequence

The first three frames sent by a driver establish authentication, the authoritative state baseline, and the event subscription.

First frames sent by the driver
{"type":"hello","protocol_version":"1.0","auth":{"mode":"integration_token","token":"integration-secret"}}
{"type":"query_state","protocol_version":"1.0"}
{"type":"subscribe","protocol_version":"1.0"}

Reconnect rule

Repeat the full lifecycle after every reconnect and discard stale local assumptions until the new baseline is applied.

Authentication

External clients authenticate in hello using an integration token supplied by the installer or operator.

Invalid, missing, or revoked tokens produce error_response(error_code="unauthorized") and the connection closes.

Clients must send protocol_version: "1.0" on hello and every later request. The current processor tolerates an omitted version on hello for compatibility, but integrations must not rely on that behavior; later requests require an exact version match.

Baseline

After hello, send query_state before subscribing or commanding. Apply its response as the authoritative baseline before processing later deltas.

The external baseline contains motors and groups. It does not contain processor settings or group membership topology. Supported scopes are all, motors, and groups.

Baseline Recovery

The processor preflights the complete serialized response against the 1 MiB external frame limit. If scope="all" is too large, it returns a correlated error_response(error_code="response_too_large", retryable=false), keeps the connection open, and leaves the session query-required. Request scope="motors" and then scope="groups" to assemble the baseline without reconnecting. A successful scoped query advances the lifecycle. If either individual scope is still too large, it returns the same error; protocol 1.0 does not paginate.

Liveness

With default settings, the processor closes an external connection after 90 seconds without an inbound frame. A long-lived client should send ping every 30 seconds while it has no other requests to send. Outbound events do not extend the inbound deadline.

ping is available after hello. It does not advance lifecycle state and does not replace reconnect re-baselining. A pong is a direct response and may arrive interleaved with subscribed events or a deferred command response.

Request Correlation

request_id is optional on every request. When supplied, it must be a string containing 1 through 64 Unicode code points. The matching normal or error response echoes a valid ID; otherwise the response omits it. Empty, non-string, and over-length IDs produce an uncorrelated invalid_message. An ID-less client should keep at most one request outstanding so direct responses remain unambiguous.