Skip to main content
Integrators and operators configuring brokers or custom edge agents should use this reference. Normative source: ilyama edge-client-guide.

​
Transport

Omega supports both via OMEGA_MQTT_BROKER_URL.

​
Authentication

  • mTLS (recommended): client cert issued by Golain cert worker or JITR
  • Username/password: from device MQTT details in console
Broker resolves org_id, project_id, fleet_id, device_id from session — client must never send these as trusted JSON fields.

​
Clean session

Set clean_session: false (persistent session). Required so broker can deliver QoS 1 downlink controls while device was offline. Omega ilyama-edge client:

​
Topic prefix

All sync topics under project-scoped prefix:
  • topic_slug: project TopicSlug when configured
  • device_name: registered device name (MQTT client id)
Without slug:
(Leading slash, empty slug segment.) Set via OMEGA_ROOT_TOPIC in Omega.

​
Example

Project slug acme-prod, device gw-07:

​
Topic table

ACL: Device cannot publish to sync/ingest/control. Device must subscribe to it at QoS 1 immediately after connect.

​
QoS and delivery

  • Device publishes: QoS 1
  • Server downlink: QoS 1
  • At-least-once delivery — dedup on server (batch_id or per-row keys)
Safe to retry same batch_id on MQTT redelivery.

​
Broker → worker routing (edge v2)

Client MQTT topics are unchanged. On the server, the mqtt-broker hook publishes to edge_ingress_exchange (not the legacy telemetry_ingress_exchange / integration ingress path): The edge worker consumes these queues and stages governance events on edge_exchange (schema reviews, lineage pause/resume, materialization). Downlink: edge worker stages edge.ingest_control.requested.v1 on mqtt_downlink_exchange → broker publishes to the device’s sync/ingest/control topic.

​
Startup checklist (device)

  1. Connect MQTT with persistent session + mTLS.
  2. Subscribe {prefix}/sync/ingest/control QoS 1.
  3. Load durable state: batch_seq, commit_seq, journal_epoch, schema hashes, pause watermarks.
  4. Detect schema drift; optional sync/schema/observe.
  5. Resume draining backpressure buffer if paused.
  6. Start flush loop (5s / 512 KiB).