# Setup Guide — Temperature Logger & PID Controller

## Quick Reference

| Task | Command |
| --- | --- |
| Logger GUI | `temp-logger-gui` |
| PID controller GUI | `pid-controller-gui` |
| Interactive SCPI terminal | `scpi-client` |
| CLI logger (with live plot) | `temp-logger` |
| CLI logger (data-only) | `temp-logger --no-plot` |

---

## Install (one-time)

### 1. Create a virtual environment

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

### 2. macOS only — install Tkinter

The GUIs use `tkinter`. On macOS it may not be included with Homebrew Python:

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

Then recreate the venv:

```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 pop up.

See [TKINTER_INSTALLATION.md](TKINTER_INSTALLATION.md) for detailed instructions.

---

## Tool descriptions

### `temp-logger-gui` — Temperature Logger GUI

Professional Tkinter interface with embedded matplotlib plots.

- Auto-detect or manual USB port selection
- WiFi/TCP connection support
- Dual-sensor synchronised readings (T₁, T₂, ΔT)
- Configurable AVG level (1 / 8 / 32 / 64)
- Dark-themed UI, scrolling info panel, Copy / Clear buttons
- CSV export with timestamped filenames

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

### `pid-controller-gui` — PID Controller GUI

Full-featured PID temperature controller over USB or WiFi.

- Live graphs: temperature, setpoint, TEC output vs time
- PID tuning panel (Kp, Ki, Kd) with Apply / Query
- Temperature ramp control (target, rate, hold time, progress bar)
- TEC direct output slider with emergency STOP
- WiFi status panel with auto-discover
- Built-in SCPI console for arbitrary commands
- Dark / Light theme toggle

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

### `scpi-client` — Interactive SCPI Terminal

Send SCPI commands interactively or as one-shots.

- Tab-completion of all SCPI commands
- Command history (arrow keys, persists across sessions)
- Pretty-printed responses with colours and icons
- OPC synchronisation for reliable command completion
- USB serial and WiFi/TCP

```bash
scpi-client                      # USB interactive
scpi-client -w 192.168.1.100    # WiFi interactive
scpi-client "*IDN?"             # single command
```

### `temp-logger` — CLI Logger

Headless or matplotlib-based temperature logging.

```bash
temp-logger                      # auto-detect, live plot
temp-logger --no-plot            # data only (fastest)
temp-logger --output data.csv   # custom filename
temp-logger --wifi 192.168.1.100 # WiFi mode
temp-logger --prefer-usb         # prefer USB over WiFi
```

---

## Recommended dual-tool workflow

Use **USB for logging** and **WiFi for control** simultaneously:

```bash
# Terminal 1 — continuous data logging via USB
temp-logger --output experiment.csv

# Terminal 2 — PID control via WiFi
pid-controller-gui
```

Only one application can hold the USB serial port at a time.
WiFi (TCP port 5025) provides a second independent connection.

---

## Troubleshooting

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

See [TKINTER_INSTALLATION.md](TKINTER_INSTALLATION.md). On macOS:

```bash
brew install tcl-tk python-tk@3.xx
```

### "Device not found"

```bash
# List available serial ports
python3 -c "import serial.tools.list_ports; print([p.device for p in serial.tools.list_ports.comports()])"
```

### Port busy (another app is using it)

Only one app can open USB serial at a time. Close the other app, or use
WiFi for one of the two tools.

### WiFi connection fails

```bash
# Check WiFi status via USB
scpi-client ":WIFI:CONNECTED?"
scpi-client ":WIFI:IP?"
```

If WiFi is not configured, create `wifi_config.txt` on the CIRCUITPY drive:

```txt
ssid=YourNetwork
password=YourPassword
```

---

## Performance notes

| Aspect | Value |
| --- | --- |
| CLI sampling rate | ~2 Hz (with AVG 8) to ~10 Hz (AVG 1) |
| GUI plot update | 200 ms (configurable) |
| CSV row size | ~60–100 bytes |
| Memory (GUI) | ~30–60 MB |

---

## Documentation index

| File | Contents |
| --- | --- |
| [README.md](README.md) | Package overview and install |
| [GUI_QUICKSTART.md](GUI_QUICKSTART.md) | 60-second getting started |
| [GUI_README.md](GUI_README.md) | Detailed `temp-logger-gui` reference |
| [REALTIME_LOGGER_README.md](REALTIME_LOGGER_README.md) | CLI `temp-logger` reference |
| [WIFI_SUPPORT.md](WIFI_SUPPORT.md) | WiFi connection guide |
| [WIFI_QUICKSTART.md](WIFI_QUICKSTART.md) | Quick WiFi setup |
| [TKINTER_INSTALLATION.md](TKINTER_INSTALLATION.md) | Tkinter on macOS |

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