Files and settings

Every file a bench reads or writes, in one place — for looking one up. The console writes all of them for you; this page is for when you want to read or edit one yourself.

The home directory

Everything the bench writes lives under one folder, the home — ~/.plesty/server unless --home DIR, home: in the fleet file or PLESTY_SERVER_HOME says otherwise (in that order).

~/.plesty/server/
├── fleet.yaml       a bench's fleet from before fleets/ (./fleet.yaml is looked at first)
├── last-fleet       which fleet file the console opened last
├── fleets/          this bench's fleets, <name>.yaml each; a new bench starts with an
│                    empty default.yaml
├── agent.yaml       the agent's address, token, worker count, role and data path
├── peers.yaml       on a master: the other benches it drives, with their tokens
├── packages/        installed modules, one environment per version
├── repos/           repository checkouts, one per (package, ref)
├── run/<name>/      each device's working folder — and its .env
├── runs/<name>/     experiment runs, when the module names no shared data folder
├── data/            where the devices write while no Plesty share is set: each its
│                    data_dir, or tmp/<name>
├── demo/            the welcome's demo: its runs, which its spectrometer replays
├── last-operator.txt who created the last run; welcome-seen, update-check.json
├── state/           what each server was started with, and whether it ended
├── logs/            <name>-<date>-<time>.log per device start or clear (<name>.current
│                    names the one in use), jobs/<id>.log per job
├── jobs/            the record of every install, update, field test and run
└── tools/           what the bench installed for itself (git, on Windows)

One machine can hold several benches by giving each its own home. They take ports from the same range, so they move around each other rather than collide. Backing up a bench is copying this folder; see Keep what you need first.

The fleet file

fleet.yaml says what this bench runs: its devices and its experiments. Device ▸ Add device… and plesty-server declare write it; Edit ▸ Fleet file… shows it whole.

version: 1

devices:
  pm100d:
    package: plesty-pm100d
    version: 0.2.1
    args: [--tcp-port, "5551", --address, "USB0::0x1313::0x8078::P0031744::INSTR"]
    env:
      PLESTY_REPORT_ARCHIVE: /shares/plesty/reports
    autostart: true

  k10cr1-dev:
    package: plesty-k10cr1
    git: https://gitlab.com/plesty/hub/devices/thorlab/plesty-k10cr1.git
    ref: exp
    args: [--address, "55123457"]
    autostart: false

experiments:
  pol-pl:
    package: plesty-pol-pl
    git: https://gitlab.com/plesty/hub/experiments/plesty-pol-pl.git
    ref: exp
    config: config/default.yaml

A device

Key	Means
the entry’s name	The device’s name on this bench. It names its log, its folder and its process record, so it must be unique.
`package`	The hub device module that runs it.
`version`	A release from PyPI. Leave it out to take the newest at install time.
`git` + `ref`	Install from a repository instead — a branch, tag or commit. `ref` defaults to `v<version>` when a version is given. Field tests need this.
`args`	Passed to the device server — the module’s own options, such as `--address`.
`env`	Environment for the server and its field tests. It wins over the device’s `.env`.
`port`	The port to serve on. Usually left out: see Ports.
`autostart`	Whether the device is in the working fleet — the check box in the console.
`data_dir`	Where the device writes, relative to the bench’s data path (Server ▸ Configure…): `pol-pl/cam`. Left out, it writes to `tmp/<name>`. Never absolute, never `..`.

Two entries may run the same package at different versions, or the same version twice on two ports.

An experiment

Key	Means
`package`	The hub experiment module.
`git` + `ref`	Where it is installed from. An experiment is normally installed from its repository: its `config/` files and `.env.example` are there and not in the release.
`version`	A release, for a module whose release carries what it needs.
`path`	A repository on this machine to run instead of an install — what Hub ▸ Load from… declares.
`config`	The configuration file a new run starts from.
`args`	Appended to the module’s command.
`env`	Environment for its runs. A `<DEVICE>_ADDRESS` set here points the run at that address, and the bench does not start that device itself.

An experiment has no port and no autostart: fleet up does not start it.

Ports

Each device server listens on its own TCP port — what an experiment connects to. Unless the declaration names one, the bench picks the lowest free port from 5551 upwards (5550 is the agent’s) and writes it into the fleet file, so a device keeps the same port from then on.

A port the bench picked, or one written as port:, is moved to a free one if something else holds it at start time — the bench says so.
A port you named in args (--tcp-port 5551) or env is not moved: the server was told that number. start reports it busy and stops.

The rules in full are in Ports.

A device’s `.env`

Each device has its own <home>/run/<name>/.env, read by its server and its field tests — the place for an address, a serial number or a calibration constant. It stays on the bench, unlike a fleet file that may be copied elsewhere. Edit it in Device config ▸ .env.

DEVICE_ADDRESS=USB0::0x1313::0x8078::P0031744::INSTR
PLESTY_REPORT_ARCHIVE=/shares/plesty/reports

The fleet’s env: wins over it, and it wins over the environment the bench itself was started with. On the first install it is filled from the module’s .env.example; a later install adds keys the new example has and never overwrites a value you set.

The other files

File	Where	Holds	Written by
`agent.yaml`	the home	`bind`, `token`, `workers`, `role`, `data_share`, `data_folder`	Server ▸ Configure…, `plesty-server data-path`
`peers.yaml`	the home	the benches a master drives: address and token each	Server ▸ Benches…
`setup.yaml`	an experiment module’s folder	the benches and devices the experiment runs across, as variables	Configure… ▸ Device Setup — see Run an experiment
experiment `.env`	beside `setup.yaml`	the values of those variables: addresses, tokens, shared-data folders	installing the module; Device Setup
run `config.yaml`	each run’s folder	the configuration that run starts and resumes with	Create run, Configure…

agent.yaml, peers.yaml and the experiment .env hold tokens and are readable by their owner only. None of them belongs in a repository; fleet.yaml and setup.yaml do.

Environment variables

The variables the bench reads are in the CLI overview. The ones it sets for what it starts:

Variable	Set for	Value
`DEVICE_DATA_ROOT`	every device the bench starts, once its share is set	`<share>/<bench folder>`: where the device may write
`DEVICE_DATA_PATH`	every device the bench starts, once its share is set	`<bench folder>/<data_dir>`, else `<bench folder>/tmp/<name>`; a device `.env` or the fleet’s `env:` still wins
`PLESTY_DATA`	every device and experiment run the bench starts, once its share is set	the Plesty share as this machine mounts it; a run’s `.env` still wins
`<DEVICE>_ADDRESS`	an experiment’s run	`tcp://<host>:<port>` of each of its devices, e.g. `HWP_ADDRESS`