Skip to main content

Write an edge-bridge driver

When a machine sits on a private network Cobblr can't dial, or speaks a protocol no HTTP manifest can express, you run a small service at your location and Cobblr talks to that. The service is the edge bridge, and the piece that teaches it one machine is a driver. Full detail lives in edge-bridge drivers; this page places it against the other options so you pick the right one.

Which extension do I need​

Work down this list and stop at the first match:

  1. The manager speaks REST and Cobblr can reach it. Write a declarative machine-driver manifest. No code, no separate service.
  2. The manager speaks REST but sits behind a NAT Cobblr can't reach. Keep the declarative connection and run the bridge in front of it, or serve the fixed edge-adapter contract yourself. Cobblr only ever makes an HTTP call to a URL you control.
  3. The machine speaks something no manifest can express (MQTT, a binary protocol, a login handshake). Write an edge-bridge driver. This is the case this page is about.

What a bridge driver is​

A driver is a single default export: a package with a kind, a name, an apiVersion, and a createDriver factory that returns the methods the bridge calls (list devices, upload a file, start a job, report status). The bridge loads it by npm name or local path and runs it like a built-in. Because it is a normal package, it can live in its own repo, stay private, or ship in your own product.

The bridge itself serves a fixed webhook contract to Cobblr:

GET  {base}/devices            -> [ { id, name, state, enabled? } ]
POST {base}/upload  (multipart "file") -> { fileId }
POST {base}/submit  { fileId, target? } -> { jobId, queued? }
GET  {base}/status/{jobId}     -> { state, progress? }
POST {base}/command { command, params } -> { ok, ref? }   (actuator; optional)

Your driver's job is to translate those calls into whatever the machine actually speaks. The state string you return is free-form; Cobblr maps words like running and done onto its own job states.

Start from a built-in driver​

Copy the built-in driver closest to your machine and change what differs. The mock driver is the smallest complete one, so it works as a skeleton. Put your version in its own package, point the bridge's drivers: config at it (a published package or a local path), then give a connection your driver's kind. The built-in drivers are worth reading for shape as well as content: each splits pure protocol logic, which you can unit-test with no hardware, from the actual I/O.

The hardware-free path​

For a plain actuator or sensor (a relay, a valve, a scale, an RFID reader), you may not need a host running the bridge at all. The edge firmware turns an ESP32 into a connector that serves the same edge-adapter contract directly, with no Pi and no Node runtime. It reads a flashed declarative profile rather than a driver package, so the extension is data on the chip. Read the edge-adapter contract for how the two meet.