docs: update setup instructions for uv, clarify Windows compatibility, and add simulator connection guide with supporting screenshots

README.md

@@ -4,16 +4,23 @@ Small PySide6 + Qt Quick application scaffold for the `ISenseCloud` desktop UI s
 
 ## Requirements
 
-- Python 3.10+ (tested with Python 3.14 in this workspace)
+- 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
+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
@@ -21,8 +28,14 @@ pip install -e .            # install the `pygui` package (src/ layout) in edita
 
 ## Run
 
+### Option A: Using `uv`
 ```bash
-source .venv/bin/activate
+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
 ```
 
@@ -33,8 +46,13 @@ This launches the Qt window and loads the `ISC` QML module from `src/pygui/ISC/M
 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 and controllers (device, settings, file browser, wafer parsing).
-- `src/pygui/serialcomm/`: serial port, device service, and data-parser layer.
+- `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).
@@ -71,11 +89,41 @@ Window {
 
 ## Troubleshooting
 
-- If the app does not start, verify the venv is active and dependencies are installed:
+- If the app does not start, verify the virtual environment is active and dependencies are installed:
 
+  *Using `uv`:*
   ```bash
-  source .venv/bin/activate
+  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)