The edge-adapter contract

:::info Two things on this page The contract is shipped and real: the software edge bridge serves it today, and Cobblr's built-in edge_adapter connection speaks it. What the firmware does with that contract is compile-verified and hardware-verified by nobody yet, so read the chip-side claims as what the code intends to do. See Edge firmware for the full status. :::

Cobblr reaches every machine on your network the same way: it makes an HTTP call to a URL and reads a small JSON response. That fixed set of calls is the edge-adapter contract. The software edge bridge serves it, and so does this firmware. Cobblr never holds a device handle or drives a pin; it coordinates, and the thing at the URL controls the hardware.

The contract was designed around fabrication (upload a file, submit a job, poll status), which is a poor fit for a microcontroller. So the chip serves the actuator and sensor subset and honestly refuses the rest.

What the chip serves

Method	Path	Body	Returns	Auth
GET	/healthz		{ ok, fw, up, provisioned }	no
GET	/devices		[ { id, name, kind, state, enabled } ]	yes
POST	/command	{ command, params }	{ ok, ref, seconds? }	yes
GET	/reading/{id}		{ value, unit?, at? }	yes
POST	/provision	profile JSON	{ ok, rebooting }	in setup, then yes
POST	/upload, /submit; GET /status/{id}		501

/command is fire-and-acknowledge: the chip starts the action (drives the pin, arms the auto-release watchdog for a pulse) and answers within Cobblr's per-call budget. There is no long-lived job to poll, which is why the fabrication routes return 501 rather than pretending. They are present and answer 501 on purpose, so Cobblr's probe sees a real adapter instead of a missing route.

The state a device reports is free-form. Cobblr maps words like on, idle, running, and done onto its own states, so the firmware can report plain words.

Auth

The data routes require Authorization: Bearer <token>, compared in constant time so a wrong token can't be guessed byte by byte. The token is the profile's token; set the Cobblr connection's apiKey to the same value. Cobblr sends the header only when the connection stored an apiKey, so an empty token leaves the chip open, which is a bench-only mode.

/provision is the exception: it is open while the chip is in setup mode (there is no token yet) and token-gated once provisioned, so replacing the profile later is authenticated.

Reaching the chip

Two connection types both speak this contract:

• A declarative connection whose machine-driver manifest points its commands at /command. This is the path the firmware repo demonstrates, and it needs no platform change: Cobblr calls the chip directly.
• The built-in edge_adapter connection kind, whose base URL is the chip's address. It speaks this fixed contract, including /command, so an edge_adapter connection is a valid target of a digifab:run-command wire.

An instance on the same network reaches the chip's LAN address directly. An instance elsewhere does not, since private addresses are blocked, so until the firmware's own outbound relay phase lands the chip needs to sit behind a tunnel you run.

The inbound direction

The contract above is outbound: Cobblr calls the chip. Sensors also push the other way. A device with a report rule POSTs a small event to Cobblr's ingest endpoint, carrying the connection id, the device id, and the reading:

{ "connection": "<conn id>", "device": "scale", "kind": "reading", "value": 742, "unit": "g" }

Cobblr emits an event and resolves the (connection, device) pair to a linked entity, so the link is the configuration and the common case needs no wire. The shipped flagship path maps a scale's grams onto an inventory part's stock, proven end to end in the platform's tests. An RFID tap arrives as a scanned event and a counter as a counted event, for check-out and throughput use-cases. Wiring the push into a profile is covered under readings that push into Cobblr.