Skip to main content
The platform controls a device by publishing control messages to its MQTT control topics; the device acts and publishes back on its report topics. Two things gate every command: the message must be signed (when signing is on), and the target module must be allowed by the device’s capabilities. Both are enforced on the device — the platform can only ask.

​
The control envelope

Every control message is a small JSON envelope:
  • action names the command; value / data carry its arguments (a string and/or a structured object).
  • timestamp is RFC 3339. nonce is unique per message. signature is the HMAC over the message.

​
Signing

Turn signing on in the profile:
With enabled: true, the device rejects any control message that:
  • has no valid signature (HMAC computed over action/value/data/timestamp/nonce with the shared key), or
  • is missing its timestamp or nonce, or
  • is older than max_age (stale), or
  • replays a nonce it has already seen — each nonce is accepted once, so a captured message can’t be resent.
Supply the key with key_env (an environment-variable name), not an inline key, so the secret stays out of the profile file. Oversized payloads are also rejected, per security.max_payload_bytes.
Signing is the recommended production posture. With enabled: false the envelope is still used but the signature/nonce/timestamp checks are skipped — only appropriate on a fully trusted link (local development).

​
Capability gating

A module only accepts control if the device’s profile grants its capability and the binary was built with the feature behind it:
A capability the build doesn’t provide is a fatal config error at load, not a silent no-op — so a device that’s online genuinely honors exactly the capabilities it advertises. Grant only what a device needs.

​
What you can drive

These are the control surfaces of the current module lineup. Each links to its exact topics in the topic reference.

OTA & deployments

Push a deployment plan or a direct artifact URL, release or cancel an in-flight update, and trigger self-update. Device reports progress, success, and logs. Topics: ota/control/*.

Inventory (SBOM/HBOM/PBOM)

Request a fresh software, hardware, or policy bill of materials. Device answers on inventory/report/*. Topic: inventory/control.

Node capabilities

Invoke a capability the device advertises in its node registry; result comes back on node/report/result. Topic: node/control.

Service runtime

Manage an OS service on the device. Topic: devices/control/request (the service-runtime module reports on devices/report/status).
Certificate renewal and rotation are also driven from the platform, on the device’s $golain/devices/{uuid}/cert/* topics — but that runs on its own schedule; see Enrollment → Renewal.

​
Typed services (Device RPC)

The envelope above is for module control. For typed, schema’d request/response services running on the device — your own protobuf-defined methods — use Device RPC, which is a separate, richer path with its own reflection and codegen.

Device RPC

Define services in protobuf, call them from the platform, discover them by reflection.

​
See also

  • Connect — every control and report topic, per module.
  • Configure Omega — security.signed_control and security.capabilities in full.