Omega Device RPC setup

This guide walks you through device-side setup for Device RPC: enabling the Omega module, running the bundled echo example, and confirming the platform sees your service schema.

Enable the module

Add device-rpc to your Omega profile. The reference profile is omega/profiles/rpc-example.yaml — add an explicit bridge_id as in the minimal block below if the profile does not already set one. Minimal configuration:

modules:
  required:
    - shadow
    - heartbeat
    - device-rpc

security:
  capabilities:
    shadow: true
    heartbeat: true
    device-rpc: true

device-rpc:
  qos: 1
  bridge_id: rpc-example   # set explicitly; recommend matching your device id

Field	Description
`device-rpc.qos`	MQTT QoS for RPC bridge traffic (reference profile uses 1)
`device-rpc.bridge_id`	Identifier the cloud uses to reach this device — set it explicitly in YAML; we recommend matching your device id

Broker URL, TLS, credentials, and connection.root_topic come from the connection: block (or their env var overrides), not from device-rpc.

Connection env vars: OMEGA_MQTT_BROKER_URL, OMEGA_DEVICE_ID, OMEGA_ROOT_TOPIC, plus optional OMEGA_MQTT_USERNAME, OMEGA_MQTT_PASSWORD, and TLS cert paths (OMEGA_TLS_CA_PATH, OMEGA_TLS_CERT_PATH, OMEGA_TLS_KEY_PATH).

Run locally

Terminal 1 — MQTT broker:

docker run --rm -p 1883:1883 eclipse-mosquitto:2

Terminal 2 — Omega with the echo profile:

export OMEGA_MQTT_BROKER_URL=tcp://127.0.0.1:1883
export OMEGA_DEVICE_ID=rpc-example
export OMEGA_ROOT_TOPIC=omega/rpc-example

cd omega
make run-rpc-example
# or: go run ./cmd/omega -profile profiles/rpc-example.yaml

Omega connects to mosquitto, announces the gRPC schema, and serves the bundled golain.device.v1.EchoService.

Run against Golain

export OMEGA_MQTT_BROKER_URL=ssl://mqtt.ilyama.golain.io:8883
export OMEGA_DEVICE_ID=<your-device-name>
export OMEGA_ROOT_TOPIC=<console-assigned-root-topic>
export OMEGA_TLS_CA_PATH=/path/to/ca.pem
export OMEGA_TLS_CERT_PATH=/path/to/device.crt
export OMEGA_TLS_KEY_PATH=/path/to/device.key

cd omega
make run-rpc-example

OMEGA_ROOT_TOPIC must match the root topic assigned in the Console for this device. A mismatch causes schema announce and invoke failures even when MQTT looks healthy.

Set device-rpc.bridge_id in your profile to match the device id you registered. Update bridge_id whenever you change the device identity.

Verify schema registration

After Omega connects, confirm the platform bound your service schema:

export TOKEN=<your-oidc-access-token>
export ORG_ID=<your-org-uuid>
export PROJECT_ID=<your-project-uuid>
export DEVICE_ID=<your-device-uuid>

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "ORG-ID: $ORG_ID" \
  "https://api.ilyama.golain.io/core/api/v1/projects/$PROJECT_ID/devices/$DEVICE_ID/rpc/services"

A bound device returns a descriptor_digest and a non-empty services array. Empty services means announce or reflection has not completed yet. Optional — force reflection (when the device is online but services are stale):

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "ORG-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.ilyama.golain.io/core/api/v1/projects/$PROJECT_ID/devices/$DEVICE_ID/rpc/reflect"

Requires can_write_device_metadata on the device.

Echo example service

The bundled example implements golain.device.v1.EchoService:

Method	Cloud invoke
`Echo`	Supported (unary) — sync path
`EchoServerStream`	Supported (server-stream) — `/streams/` path with SSE
`EchoClientStream`	Device only — sync path returns 501
`EchoBidiStream`	Device only — sync path returns 501

Proto source: omega/modules/device-rpc/proto/golain/device/v1/echo.proto. Request body for Echo:

{"message":"hello from cloud"}

Success response prefixes the message:

{"message":"Echo: hello from cloud","sequence":1}

Server-stream example — same request body, SSE response:

curl -N -X POST \
  "https://rpc.ilyama.golain.io/projects/$PROJECT_ID/devices/$DEVICE_ID/streams/golain.device.v1.EchoService/EchoServerStream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ORG-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message":"stream me"}'

→ Full streaming guide: Invoking methods — Stream a method (SSE)

Example invoke

After schema binding, try a synchronous call from your machine:

curl -sS -X POST \
  "https://rpc.ilyama.golain.io/projects/$PROJECT_ID/devices/$DEVICE_ID/golain.device.v1.EchoService/Echo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ORG-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{"message":"hello from cloud"}'

→ Full caller guide: Invoking methods

Bring your own gRPC service

Define .proto services and generate Go stubs.
Register your service on a gRPC server with gRPC reflection enabled (required for platform schema registration).
Wire your server into the Omega device-rpc module build.
Regenerate embedded descriptors:
cd omega make rpc-generate
Deploy the device. On connect, the platform reflects and binds your new schema automatically.

Any proto change produces a new descriptor_digest. Devices on old firmware keep their previous binding until they announce the new digest. Plan OTA rollouts accordingly; use POST .../rpc/reflect to verify binding after upgrade.

Idempotency for queued invoke

If cloud callers use Queued invoke, the platform may deliver the same RPC to your handler more than once. The platform does not attach call_id to the gRPC request bytes sent to the device.

Implement idempotency in every handler reachable via queued invoke. Non-idempotent operations (actuators, payments, counters) will double-apply unless you guard them. See Queued invoke — device-side idempotency.

Next steps

Invoking methods — HTTP API from integrators
Queued invoke — offline-tolerant delivery
How it works — registration and invoke overview
Troubleshooting — announce and invoke issues

For announce-only testing without a live MQTT broker listener, set connection.transport: memory in a copied profile. Schema announce logic runs; the RPC listener is skipped.

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

Omega Device RPC setup

Enable the module

Run locally

Run against Golain

Verify schema registration

Echo example service

Example invoke

Bring your own gRPC service

Idempotency for queued invoke

Next steps

​Enable the module

​Run locally

​Run against Golain

​Verify schema registration

​Echo example service

​Example invoke

​Bring your own gRPC service

​Idempotency for queued invoke

​Next steps

Enable the module

Run locally

Run against Golain

Verify schema registration

Echo example service

Example invoke

Bring your own gRPC service

Idempotency for queued invoke

Next steps