# Set up a bench

From an installed bench to an instrument an experiment can reach — about ten
minutes, most of it downloading. The example is a Thorlabs PM100D power meter;
any hub device module works the same way.

It starts where [Install](../install.md) ends, with the console open. On a new
bench both tabs are empty, and the status line names the fleet the bench
started with, `default.yaml`.

## 1. Install the device module

A **device module** is the driver for one kind of instrument, from the PLESTY
hub.

1. *Hub ▸ Browse…* (Ctrl+K).
2. Type `pm100d` into the search box and select **plesty-pm100d**.
3. Under *Source*, keep **Release (PyPI)** and its newest version.
4. Press **Install module**. A window follows the installation; close it when
   it says *done*.

Installing puts the module on the bench; it does not add an instrument yet.

## 2. Declare the instrument

A **declaration** tells the bench about one instrument: a name for it, the
module that drives it, and how to find it.

1. Press **Declare** ![Declare](../imgs/gui/btn-fleet-declare.png){height=22px} on the
   Devices card, or *Device ▸ Add device…* (Ctrl+N).
2. **Package**: `plesty-pm100d`. **Name**: keep `pm100d`, or name it after the
   instrument.
3. **Args**: how the module finds the instrument — for the PM100D its VISA
   address, `--address USB0::0x1313::0x8078::P0031744::INSTR`. The module's own
   documentation lists its options.
4. Leave **part of the working fleet** ticked, so the bench starts it with the
   others.
5. **OK**.

```{image} ../imgs/gui/dialog-declare.png
:width: 340px
:alt: The Declare device dialog
```

The declaration goes into the bench's fleet file,
`~/.plesty/server/fleets/default.yaml`, which picks a network port for the
device — 5551 for the first one.

## 3. Start it

Select the row and press **Start** ![Start](../imgs/gui/btn-device-start.png){height=22px}.
The state goes from `stopped` through `starting` to `running` once the server
answers — not merely once its process exists.

```{image} ../imgs/gui/start-device.gif
:width: 100%
:alt: Selecting a stopped device and pressing Start: the state turns from stopped to running and the log fills.
```

The **Log** pane shows what the server printed. If the state becomes `exited`
instead, the log says why — see [When a device will not start](#when-a-device-will-not-start).

## 4. Check that it answers

- **Control** — press **Control** ![Control](../imgs/gui/btn-device-control.png){height=22px},
  tick **Take control**, and read or set a value by hand. See
  [the Control window](../gui/devices.md#control-the-control-window).
- **Traffic** — every request the server handled, as it happens.

```{image} ../imgs/gui/take-control.gif
:width: 760px
:alt: Ticking Take control on a panel: its fields and buttons become usable.
```

The instrument is now reachable from any experiment PC at this bench's address
and the port in the table. Nothing else is needed on the bench.

## On the command line

The same steps, in a terminal on the bench:

```bash
plesty-server module install plesty-pm100d
plesty-server declare pm100d plesty-pm100d \
    --arg --address --arg "USB0::0x1313::0x8078::P0031744::INSTR"
plesty-server start pm100d        # installs first if needed; waits until it answers
plesty-server status
plesty-server log pm100d -n 50
```

## Next

- More instruments: repeat steps 1–3. Two devices may use the same module.
- The devices should come back after a reboot:
  [Keep a bench up without a window](headless.md).
- Test the module against the instrument: [Field-test a device](field_test.md).

## When a device will not start

| What you see | What it usually is |
|---|---|
| The state stays `starting`, then `exited` | The module could not open the instrument: a wrong address, the instrument in use by another program, a missing vendor driver. The **Log** has the driver's own error. |
| *port busy* when starting | The declaration names its port (`--tcp-port`) and something else holds it. Stop the other program, or remove `--tcp-port` so the bench picks a free one. |
| `exited` with nothing in the log, on Windows | The server was killed rather than asked to stop; the status says so when it recognises the exit code. An old module may not handle the stop request. |
| An install fails on a `.dev` dependency | A module under development needs a pre-release of `plesty-lib`. The install retries with pre-releases allowed and says so; if it still fails, the job's log has the reason. |
| *git not found* | Only modules installed from a repository need git. A Windows bench fetches its own; on macOS or Linux, install it from the package manager. |