pyGUI/README.md

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 installed:

uv sync

Option B: Using pip

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

uv run python -m pygui

Option B: Using standard Python (venv)

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:

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:

  uv sync
  

  Using pip:

  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.

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.

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).