# ISC QtQuick App

Small PySide6 + Qt Quick application scaffold for the `ISenseCloud` desktop UI shell.

## Requirements

- Python 3.11+ (tested with Python 3.14 in this workspace)
- macOS, Linux, or Windows with GUI support

## Setup

From the project root:

### Option A: Using `uv` (Recommended)
If you have [uv](https://docs.astral.sh/uv/) installed:
```bash
uv sync
```

### Option B: Using `pip`
```bash
python3 -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .            # install the `pygui` package (src/ layout) in editable mode
```

## Run

### Option A: Using `uv`
```bash
uv run python -m pygui
```

### Option B: Using standard Python (venv)
```bash
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
python -m pygui             # or run the `isc` console script
```

This launches the Qt window and loads the `ISC` QML module from `src/pygui/ISC/Main.qml`.

## Project Structure

The application lives under a `src/` layout as the `pygui` package:

- `src/pygui/__main__.py`: PySide6 bootstrap; creates the Qt app and loads QML module `ISC/Main`. Entry point for `python -m pygui`.
- `src/pygui/backend/`: Qt-facing models, controllers, and visualizers organized into subdirectories:
  - `controllers/`: QML-facing controllers (Session & Device controllers).
  - `data/`: local settings, file browser, and CSV recorder utilities.
  - `models/`: data models (Session, Thresholds, Frame Player, Frame representation).
  - `visualization/`: QML wafer map item integration.
  - `wafer/`: layout definitions, coordinate mappings, and files parser.
- `src/pygui/serialcomm/`: serial port transport, device service scanning, and protocol data-parser layer.
- `src/pygui/ISC/`: the `ISC` QML module (UI).
  - `Main.qml`: top-level window definition.
  - `HomePage.qml`: main UI layout (left action rail, workspace panel, footer tabs).
  - `Theme.qml`: shared theme constants and dark/light mode tokens.
  - `qmldir`: QML module registration.
- `tests/`: pytest suite.
- `packaging/`: PyInstaller spec (`isc.spec`) and app icons.

## Window Configuration

Window dimensions and constraints are defined in `src/pygui/ISC/Main.qml`:

- **Default size**: 1400 × 820 pixels
- **Minimum size**: 1100 × 700 pixels
- **Title bar**: "ISenseCloud"

To adjust the window, edit the `Window` block in `src/pygui/ISC/Main.qml`:

```qml
Window {
    width: 1400
    height: 820
    minimumWidth: 1100
    minimumHeight: 700
    visible: true
    title: qsTr("ISenseCloud")
}
```

## Customization

- Toggle dark/light mode in `src/pygui/ISC/Theme.qml` via `isDarkMode`.
- Update sidebar and footer labels in `src/pygui/ISC/HomePage.qml` through `sideActions` and `bottomTabs`.

## Troubleshooting

- If the app does not start, verify the virtual environment is active and dependencies are installed:

  *Using `uv`:*
  ```bash
  uv sync
  ```

  *Using `pip`:*
  ```bash
  source .venv/bin/activate   # or .venv\Scripts\activate on Windows
  pip install -r requirements.txt
  ```

- If no window appears, ensure you are running in a desktop session with GUI access.

- **Windows COM Port Connection Issues:** 
  * Standard Windows serial drivers don't support custom baud rates (e.g. `888888`), throwing an expected `OSError(22)` warning before falling back to `115200` baud.

### Step-by-Step Windows Simulator Connection Guide

#### Step 1: Create the Virtual Serial Port Bridge
Open **HHD Virtual Serial Port Tools**. Under the **Local Bridges** panel on the left, click the green **`+`** (Add) button to create a new port pair. Configure it to bridge **`COM5 ↔ COM6`**.

![HHD Virtual Serial Port Tools showing COM5 ↔ COM6 Local Bridge](image.png)

#### Step 2: Configure and Start the Wafer Simulator
Launch the **Wafer Simulator Control Panel** (`wafer_sim_gui.py`):
1. Set the **Serial Port** to **`COM5`**.
2. **Uncheck** the `Auto-create Virtual Port (com0com)` checkbox.
3. Choose your desired **Wafer Type** (e.g., `aepwafer`) and **Family Code** (e.g., `A`).
4. Click **Start Simulator**. Once the client connects, you will see `Streaming (D2)` status and active data transfer logs.

![Wafer Simulator Control Panel configured on COM5 and streaming](image-2.png)

#### Step 3: Run the UI and Connect
Launch the `pygui` client application. On the left navigation rail, click **DETECT WAFER**. The application will scan all active COM ports, automatically detect the virtual wafer simulator on **`COM6`**, and update the status indicator to **Connected** (green).

![ISenseCloud UI displaying successful connection on COM6](image-1.png)