Skip to main content
See Devices first if you haven’t already — this guide assumes you know what a device key is and how scope works. This page is the concrete “how do I actually do this” walkthrough.

​
If your pipeline script can identify the device

This is the path that requires no manual step per experiment — do this once, in the script, and every future run links itself.
1

Find or derive the device key in your script

Often the key is already in a filename, a config file, or an instrument’s identifier string. braven.path_params() can extract simple patterns from filenames automatically if that’s where it lives.
2

Call braven.device(key) instead of logging directly

3

Run the pipeline

On first sight of a key, Braven creates the Device record automatically. Every later run with the same key resolves to that same device and adds to its history — nothing else to configure.
Multiple devices in one experiment work the same way — call braven.device(...) once per device key, and keep experiment-level values (that apply to none of them specifically) on braven / run directly instead of on a device.

​
If the experiment already exists with no device

This happens for experiments ingested before a device-aware script existed, or dropped in by the folder watcher without device tagging.
1

Open the experiment

Go to Experiments, open the one you want to tag.
2

Assign a device

Use the device assignment control on the experiment detail page to attach an existing device (or create a new one) to this experiment.
3

Unlink if needed

The same control lets you unlink a device from an experiment — this removes the association without deleting any values already logged against that device elsewhere.
This manual path is the fallback, not the primary workflow — if you find yourself doing it for every new experiment in a folder, that’s the signal to add braven.device(key) to the pipeline script instead.

​
A note on retyping

A device is never re-typed by a later sighting — the type argument only applies the moment a key is first seen. If a later run passes a different type for an existing key, Braven flags it as a type mismatch in the run’s result rather than silently changing the device’s history. If you see a mismatch reported, it usually means two different physical things are (accidentally) sharing one key.