# GUI Quick Start Guide

## Installation

### 1. Create a virtual environment (macOS / Linux)

```bash
cd temp-logger
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
```

### 2. macOS only — install Tkinter

```bash
brew install tcl-tk
brew install python-tk@3.xx   # replace xx with your Python minor version
```

After installing, **recreate** the venv so it picks up the new Tkinter:

```bash
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

Verify: `python3 -m tkinter` — a small test window should appear.

---

## Running the tools

### Temperature logger GUI

```bash
temp-logger-gui
```

### PID controller GUI

```bash
pid-controller-gui
```

### Interactive SCPI terminal (text-based)

```bash
scpi-client
```

### CLI temperature logger

```bash
temp-logger
```

---

## Quick Workflow — Temperature Logging (60 seconds)

1. **Plug in** the TMP117 instrument via USB.
2. **Launch:** `temp-logger-gui`
3. **Click ▶ START** — the GUI auto-detects the port and begins logging.
4. **Watch** the live temperature and ΔT plots.
5. **Click ⏹ STOP** — CSV data is saved automatically.

## Quick Workflow — PID Control

1. **Launch:** `pid-controller-gui`
2. **Connect** (USB or WiFi — the GUI auto-discovers the WiFi IP).
3. **Set** target temperature and PID gains, or start a ramp.
4. **Monitor** live temperature, setpoint, and TEC output graphs.
5. **SCPI console** at the bottom lets you send any command directly.

---

## GUI Components — `temp-logger-gui`

| Component | Purpose |
| --- | --- |
| Serial Port selector | Choose USB port (or Auto-detect) |
| Connection Type | Auto / Force WiFi / Force USB |
| Output File | Set CSV filename |
| AVG Level | Sensor averaging (1 / 8 / 32 / 64) |
| ▶ START / ⏹ STOP | Begin / end data collection |
| Live plots | T₁ & T₂ vs time, ΔT vs time |
| Info panel | Scrolling log messages with Copy / Clear |
| Status bar | Connection state, point count, sensor mode |

## GUI Components — `pid-controller-gui`

| Component | Purpose |
| --- | --- |
| Connection panel | USB / WiFi selector with auto-discover |
| Live Status | Temperature, setpoint, error, output % |
| PID Tuning | Kp, Ki, Kd fields with Apply / Query |
| Ramp Control | Target, rate, hold time, Start / Stop |
| TEC Control | Direct output slider + STOP button |
| Temperature plot | T, setpoint, and TEC output vs time |
| SCPI Console | Send arbitrary commands |
| Theme toggle | Dark / Light theme |

---

## Troubleshooting

### "Device not found"

- Check USB cable and try a different port.
- Click the ↻ refresh button to rescan ports.
- Verify with `scpi-client` that the device responds.

### `ModuleNotFoundError: No module named '_tkinter'`

- See [TKINTER_INSTALLATION.md](TKINTER_INSTALLATION.md).

### Plot window doesn't appear

- Ensure `matplotlib` is installed: `pip install matplotlib`.

---

## File Output

CSV files are named `tmp117_log_YYYYMMDD_HHMMSS.csv` and contain:

```txt
Elapsed_Time_s,Timestamp,T1_C,T2_C,Skew_ms,Delta_T_C
0.0,2026-02-06T10:45:00.123,25.12,25.08,0.73,0.04
```

---

## Next Steps

- **Analyse data**: `import pandas as pd; df = pd.read_csv("tmp117_log_*.csv")`
- **Control temperature**: `pid-controller-gui` or `scpi-client`
- **WiFi setup**: See [WIFI_QUICKSTART.md](WIFI_QUICKSTART.md)

(c) 2024-26 Prof. Flavio ABREU ARAUJO. All rights reserved.
