# In a Terminal

This page runs the device, the experiment and the analyzer from the previous pages
together, on one computer, each in its own terminal window. Nothing is needed
beyond plesty-lib and the scripts you already wrote.

PLESTY also has a desktop application, plesty-bench, which starts devices and
experiments for you with buttons. It runs the same kind of programs as this page, so
what you do here is also what happens underneath it.

```text
terminal 1   serve_pm.py      offers the power meter over the network, on port 5555
terminal 2   power_scan.py    runs the scan, using the power meter from terminal 1
terminal 3   power_viz.py     shows the scan's data in a window while it runs
afterwards   analyze.py       finds the peak in the recorded scan
```

As on the earlier pages, the power meter is `DemoDevice`, so no instrument is needed
(see [Try it without the instrument](device.md#try-it-without-the-instrument)).

## 1. Offer the power meter over the network

A server makes a device usable from other programs (see
[Use it from another computer](device.md#use-it-from-another-computer)). Here the
other program runs on the same computer, but it reaches the device the same way.

```python
# serve_pm.py
from plesty.lib.service import build_server, run_server
from plesty.lib.sim.demo_device import MOCK_ADDRESS, DemoDevice

server = build_server(DemoDevice(MOCK_ADDRESS), address="tcp://*:5555")
run_server(server.run())
```

In terminal 1:

```bash
python serve_pm.py            # keeps running until you press Ctrl-C
```

To check it, open a client from a Python prompt in another terminal. `localhost`
means "this computer":

```python
from plesty.lib.service import build_client

client = build_client(address="tcp://localhost:5555")
print(client.identity())                            # PLESTY,DemoDevice,DEMO-0001,1.0.0
client.write("wavelength", 633.0)
print(client.query("wavelength"))                   # 633.0
```

With a real instrument, serve your own device class in the same way.

## 2. Run the scan

Use the command-line version of `power_scan.py`, from
[Give it a command line](experiment.md#give-it-a-command-line). It looks for the
power meter's address in the environment variable `PM_ADDRESS`. In terminal 2, set
the variable and start the scan:

```bash
export PM_ADDRESS=tcp://localhost:5555    # Windows PowerShell: $env:PM_ADDRESS = "tcp://localhost:5555"

python power_scan.py --dry-run            # show the plan, connect nothing
python power_scan.py                      # Run completed: powerscan_<date>-<time> (runs/...)
```

Instead of setting the variable in each terminal, you can write the line
`PM_ADDRESS=tcp://localhost:5555` into a file called `.env` in the folder you start
the script from (see [The .env File](../common/env_file.md)).

To stop a scan, press `Ctrl-C`. Do not close the terminal or kill the process
instead: `Ctrl-C` lets plesty-lib write down where the run stopped, and without that
note the run cannot be continued. To continue it:

```bash
python power_scan.py --resume powerscan_<date>-<time>
```

## 3. Watch the data

`Viz` makes a viewer for an experiment's runs. You write only the plots, each as a
function that receives the run's data so far and returns what to draw. `Viz` does
everything else: it finds the newest run, opens a window, and redraws the plots as
new records arrive.

```python
# power_viz.py
import sys

from plesty.lib.monitor import Line, Viz

viz = Viz("Power scan", experiment="powerscan")


@viz.plot("Power")
def power(data):
    return [Line(x=data.column("wavelength_nm"), y=data.column("power_w"),
                 x_label="Wavelength (nm)", y_label="Power (W)")]


if __name__ == "__main__":
    sys.exit(viz.main())
```

- `Viz("Power scan", experiment="powerscan")` gives the window a title and says
  which experiment's runs to show.
- `data.column("power_w")` is the `power_w` value of every record so far, as an
  array.
- `Line` draws those values as a curve.

The window needs the `gui` extra, and making a video also needs the `record` extra
(see [Install](../install.md)):

```bash
uv add "plesty-lib[gui,record]"
```

In terminal 3:

```bash
python power_viz.py monitor --run-root runs              # watch the newest run as it happens
python power_viz.py monitor --run-root runs --replay 1   # play a finished run back, one record at a time
python power_viz.py render --run-root runs               # save the newest run as a video, no window opened
```

`render` never opens a window, so it also works on a computer without a screen.

## 4. Find the peak

Put the code of [Run it on a recorded scan](analyzer.md#run-it-on-a-recorded-scan)
and [Save a report](analyzer.md#save-a-report) into one file, `analyze.py`, and run
it after the scan has finished:

```bash
python analyze.py             # prints the peak wavelength
```

It also saves the report, `power_peak.report.json`, in the run's folder.

## A control panel instead of code

To change parameters and call operations by hand, open the device in a **control
panel**: a window with one field per parameter and one button per operation, built
from what the device declares. It needs the `gui` extra.

The power meter from step 1 is still served, so give the panel a client for it,
the same client as in step 1:

```python
from plesty.lib.service import build_client
from plesty.lib.ui import DevicePanel, run

client = build_client(address="tcp://localhost:5555")
run([DevicePanel(client, name="pm", title="Demo power meter")])
```

The panel is then one more program using the served device, next to the
experiment. Without a server, the panel can open a device in its own program
instead, through `LocalHandle`:

```python
from plesty.lib.sim.demo_device import MOCK_ADDRESS, DemoDevice
from plesty.lib.ui import DevicePanel, LocalHandle, run

device = DemoDevice(MOCK_ADDRESS)
device.connect()
try:
    run([DevicePanel(LocalHandle(device), name="pm", title="Demo power meter")])
finally:
    device.disconnect()
```

A real instrument can be open in only one program at a time, so do not serve it
and open it through `LocalHandle` at once.

## Advanced topics

| You want to … | Read |
|---|---|
| set addresses and ports once, instead of in every terminal | [The .env File](../common/env_file.md) |
| let several programs use the served device at the same time | [Multi-Client Access Control](../device/service.md#multi-client-access-control) |
| run the experiment with its devices on other computers | [The Setup File](../experiment/setup_file.md) |
| know everything `data` in a plot function can answer | [What it answers](../viewing/run_data.md#what-it-answers) |
| draw points, images or single numbers instead of a line | [The drawables](../viewing/plots.md#the-drawables) |
| record the window to a video from your own code | [Recording a run](../viewing/ui.md#recording-a-run) |
| know how a control panel reaches a device, here or on another computer | [Where the device is](../viewing/ui.md#where-the-device-is) |