# Install and update modules

The bench runs two kinds of hub module:

- a **device module** — `plesty-pm100d`, `plesty-k10cr1` — drives one kind of
  instrument and serves it on the network;
- an **experiment module** — `plesty-pol-pl` — runs a measurement across
  several devices; see [Run an experiment](experiment.md).

The bench keeps a **store** of installed modules, each in an environment of
its own, and several versions of one module can sit side by side. Installing
puts a module in the store; declaring a device or an experiment uses it.

## Install from the hub

1. *Hub ▸ Browse…* (Ctrl+K). It lists the Hub's modules at the quantum
   standard, with each one's latest release, what this bench already has, and
   whether it passes its checks and field tests.
2. Search, and narrow by kind or vendor.
3. Choose the **source**:
   - **Release (PyPI)** at a version — what a bench in service runs;
   - **Repository (git)** at a ref — a branch, tag or commit, for a module
     being worked on. Field tests need this: a release does not carry them.
4. **Install module**. It runs as a job: it takes a minute or two, and closing
   the window does not stop it.

A version that was tagged a moment ago may not be on PyPI yet; the install
then takes the repository at that tag instead, and says so in its log.
**Refresh** asks the hub again for a module published while the window was
open.

On the command line:

```bash
plesty-server module install plesty-pm100d                    # newest release
plesty-server module install plesty-pm100d --version 0.1.0    # a given release
plesty-server module install plesty-k10cr1 \
    --git https://gitlab.com/plesty/hub/devices/thorlab/plesty-k10cr1.git --ref exp
plesty-server module list
```

## Use a folder you are working in

A module you are editing is a repository already on this machine. The bench
can run it from there, with its own `.venv`, without copying anything.

1. *Hub ▸ Load from…*.
2. **Folder**: the repository. The dialog says what it is — or why it cannot
   be loaded.
3. **Ref**: the branch to use. Choosing another one checks it out in the
   folder, which is refused while the folder has uncommitted changes.
4. **Load module**.

A loaded experiment is offered in *Create run* as `name (local)`.

```bash
plesty-server module load ~/src/plesty-k10cr1 --ref feat/homing
```

## Several versions at once

The store is keyed by package **and** version, so:

- a device pinned to `0.3.0` keeps running it while `0.4.0` is installed
  beside it;
- going back is pointing the declaration at the version still there — nothing
  is downloaded again;
- two devices at the same release share one environment.

## Update

Select the device and press **Update** ![Update](../imgs/gui/btn-device-update.png){height=22px}.

- A **repository** install pulls its ref and re-syncs.
- A **release** install is reinstalled at the same version. To move to a newer
  release, change the version in [Device config](../gui/devices.md#edit-device-config)
  and press **Install** ![Install](../imgs/gui/btn-device-install.png){height=22px}; the
  old environment stays until you remove it.

```bash
plesty-server update k10cr1-dev                 # pull and re-sync
plesty-server update k10cr1-dev --ref main      # a checkout at main, beside the old one
```

## Remove

**Uninstall** ![Uninstall](../imgs/gui/btn-device-uninstall.png){height=22px} stops the
device and removes its environment — unless another declared device still
uses it. **Remove** ![Remove](../imgs/gui/btn-device-remove.png){height=22px} only drops
the declaration. To clear the whole store, see
[Remove only part of the data](uninstall.md#remove-only-part-of-the-data).

How the bench decides which installed version serves a declaration, and where
git comes from: [The installer](../design/installer.md).