Devices

How Braven identifies the physical thing behind a measurement, how it gets linked, and what scope it lives at today.

A Device is the physical thing a Run measured — a sensor, a read-out board, a whole experimental setup. This page covers how identity, linking, and scope actually work today.

Identity: a stable key, not a name

A Device is identified by one thing: a stable key — a serial number, a MAC address, or any identifier you choose that stays the same every time that physical device is used. The key is the identity. Everything else (a type label, a display name) is metadata attached to that key, not part of what makes two readings “the same device.”

The first time Braven sees a key, it creates the Device record automatically. Every later sighting of the same key resolves to that same record — this is what lets a device accumulate history across many experiments.

Linking a device: two ways, and yes — it can happen in the pipeline

From the pipeline script (recommended)

Call braven.device(key) inside your pipeline script (or direct-logging script) and log to it directly — the device is created or resolved automatically, no manual step afterward:

import braven

for sensor_id, snr in results.items():
    braven.device(sensor_id).log_summary("SNR", snr)

# experiment-level value, not tied to one device
braven.log_summary("max_device_mismatch", spread)

This is the answer to “does linking have to be done manually per run?” — no, if your script knows the device key (from a filename, a config file, an instrument identifier), tag it in the script and every run links itself automatically. You can optionally pass a type hint on first sight: braven.device(sensor_id, "Photodiode").

Manually in the app

On an experiment’s detail page, you can assign or unlink a Device directly — useful for experiments created before a device was known, or ingested by the folder watcher without a device-aware script. This is the fallback path, not the primary one.

A device is never re-typed by a later sighting. The type hint only applies the first time a key is seen; if a later call passes a different type for an existing key, Braven flags a type mismatch rather than silently overwriting history.

Device types and lineage

A device type can declare reference fields that point at another device type, letting devices form a lineage — for example a PCB that carries a chip, which came from a wafer. The unit that actually gets swapped into a setup and attached to an Experiment is the PCB; the chip↔wafer lineage is platform metadata curated once in the webapp and reused, not something the pipeline script populates. This is deliberate: the lab folder only knows “which PCB was on the bench,” not its full fabrication history.

Scope: devices are per-project today

This is the key thing to know if you’re deciding what to model as a Device: a device’s key is scoped to the Project it’s created in. If the same physical read-out board is used in two different projects (say, a temperature-characterization project and a glucose-calibration project), it is tracked as two separate Device records today — one per project — even though the key you use is identical in both.

Cross-project device sharing (one physical device, one record, reused across every project) is not yet supported. If you need to reference the same physical setup from multiple projects, keep a consistent key and treat the per-project split as a known limitation for now rather than a bug.

Deciding what to call “the device”

A practical rule of thumb: model the unit you actually swap in and out of the setup as the Device (the PCB, the sensor module) — not necessarily the whole bench rig, and not the individual components inside it. Components with their own identity (a chip, a wafer) are better represented as a device type’s reference fields (see above) than as separate top-level devices tagged on every experiment. If you’re weighing “device” vs. “config field” for something like a read-out board shared across measurement types, the deciding question is usually: does this thing accumulate its own history across experiments that I want to query later? If yes, it’s a Device. If it’s just a setting for this run, it’s Config.