0x0xBS Docs

Connect a device

For device owners: register hardware, wire up MQTT with the private connectorId, and expose services.

1. 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.

2. Connect over MQTT

The device connects to the broker 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 command
d/<connectorId>/reply    # device → server: a result
d/<connectorId>/status   # device → server: online/offline

3. 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:

// device → d/<connectorId>/reply
{
  "type": "GET_RESULT",
  "reqId": "a1b2c3d4",
  "service_id": "455e8ec1-…",
  "api_key": "bs_…",        // raw key; the server hashes + compares
  "result": "OK-1"
}

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

4. 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.

Keep the connectorId and apiKey secret. See Security.