Connect a device

Register the device

From the dashboard, create a device. You receive three things:

• deviceId — public. Share it with agents.
• connectorId — private. Flash it into firmware; never share it.
• apiKey — secret, shown once. The device sends it back on each reply to authenticate itself.

Connect over MQTT

Preferred path: the OxBS Firmware SDK — wrap(), setPrice(), begin(). The library owns the MQTT session. Hand-roll only if you are not on ESP32 / Arduino.

The device connects using its connectorId as the MQTT client id, and subscribes to its command topic. All topics are keyed by the connectorId:

d/<connectorId>/cmd      # server → device: a commandd/<connectorId>/reply    # device → server: a resultd/<connectorId>/status   # device → server: online/offline

Respond to commands

The server publishes GET_QUOTE (price) and GET_RESULT (do the work) commands. The device replies on the reply topic, echoing reqId, the service_id, and its raw api_key:

{  "type": "GET_RESULT",  "reqId": "a1b2c3d4",  "service_id": "455e8ec1-…",  "api_key": "bs_…",  "result": "OK-1"}

A runnable ESP32 stand-in lives in simulations/esp.ts. Set CONNECTOR_ID to your device's connectorId.

Add services

Create one service per capability. Set the type (free/paid), payout wallet + chain (for paid), password protection, and the argument schema (name, type, required, description). Agents read that schema via discovery.