# The Setup File

An experiment's devices often run on several computers: a spectrometer on the
computer its software is licensed on, a motor controller next to the optics, the
experiment itself on a third. An experiment module describes that arrangement in a
file called `setup.yaml`, at the top of the module.

## Benches

The file is written in terms of **benches**. A bench is a lab computer that runs
devices for experiments. On every bench except the one the experiment runs on, the
PLESTY application plesty-bench runs a small background program, the **bench
agent**, which installs a device's module, starts its server, and tells the
experiment where to find it.

You only need `setup.yaml` when the devices are started by bench agents. When you
start the device servers yourself, as in
[In a Terminal](../quickstart/terminal.md), set each device's address in `.env`
instead (see [The .env File](../common/env_file.md)).

## The file

```yaml
version: 1
benches:
  bench-local:                    # no address: the computer the run is on
    data: ${LOCAL_DATA}           # where it sees the lab's shared disk
  spec-pc:
    data: ${SPEC_PC_DATA}         # where it sees the same disk
    address: ${SPEC_PC_HOST}      # where its bench agent listens
    token: ${SPEC_PC_TOKEN}       # the password that agent checks
devices:
  hwp:  {package: plesty-k10cr1, host_name: bench-local, args: [--mock]}
  spec: {package: plesty-lightfield-spectrometer, host_name: spec-pc}
```

**`benches`** names each computer, with:

| Field | Meaning |
|---|---|
| `data` | where this bench sees the lab's shared disk (see [Data on a Shared Disk](shared_disk.md)) |
| `address` | where its bench agent listens. Leave it out for the bench the experiment runs on; at most one bench may have no address. |
| `token` | the password its bench agent checks |

**`devices`** names each device the experiment uses, with:

| Field | Meaning |
|---|---|
| `package` | the device module to install, as on PyPI |
| `host_name` | the bench it runs on; this computer when left out |
| `args` | command-line options for the device's server, such as `--mock` to use a simulator |

## Values live in `.env`, not in the file

`setup.yaml` is part of the module and shared with everyone who uses it, so it holds
no lab's actual addresses or passwords. Each bench field is written as
`${VARIABLE}`, and the value of that variable is set in the module's `.env` file,
which is not shared. A value written directly into `setup.yaml` is refused
(`SetupError`).

On a fresh copy of the module there is no `.env`. The first start creates one, with a
line for every variable `setup.yaml` names (filled with the value suggested in
`.env.example` if there is one, otherwise empty), and stops before connecting
anything, naming the variables still to set. Exit code 2 means exactly that.
`--dry-run` connects nothing and needs none of them.

## What the run receives

When the run starts, [The Command Line](command_line.md) reads `setup.yaml` and sets
`PLESTY_DATA`: where this computer sees the shared disk, from this bench's `data`. A
variable that is already set, by hand or in `.env`, is left as it is.

Each device's address, `<DEVICE>_ADDRESS`, is not in the file: the bench agent that
starts a device picks a free network port for it on each start, and the bench passes
the address to the run it starts.

Where a device may save files is not in the file either: its own bench says so, with
the bench's folder on the shared disk (see
[Data on a Shared Disk](shared_disk.md#telling-the-devices-where-to-save)).

The run records in its journal where each device was for this start: its bench, the
address it was given, and its bench's view of the shared disk. A token is never
recorded.

## Keeping `.env` in step with the file

Two functions in `plesty.lib.experiment.setup` help a program that edits the setup:

- `seed_env(root)` adds a line to `.env` for every variable `setup.yaml` names that
  it does not have yet.
- `split_benches` takes benches written with actual values and returns the
  `${VARIABLE}` form for `setup.yaml` and the values for `.env`. A field keeps the
  variable it already has; a new one is named after its bench, such as
  `LAB_PC_ADDRESS`.

`.env` is written so that only its owner can read it.