> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bravenlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link a device

> Step-by-step — attach a physical device to an experiment, whether your pipeline already knows the device key or not.

See [Devices](/concepts/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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Call braven.device(key) instead of logging directly">
    ```python theme={null}
    import braven

    device_key = "SENSOR-4471"  # e.g. parsed from the filename
    dev = braven.device(device_key, type="Photodiode")  # type is only used the first time this key is seen

    dev.log_config("bias_voltage", 3.3)
    dev.log_summary("SNR", 14.2)
    dev.plot_series("response_curve", y=signal, x=wavelength)
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

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

<Steps>
  <Step title="Open the experiment">
    Go to **Experiments**, open the one you want to tag.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.