# led-simulator

Graphical **NeoPixel** simulator for host Python. It uses the same layout as device flash:

- **`led-driver/src`** → flash root **`/`** (application modules, `patterns/`, `presets.json`, …)
- **`led-driver/lib`** → **`/lib`** (Microdot, utemplate, …)

It runs the **whole application**: **`led-driver/src/main.py`** as **`__main__`** (`runpy.run_path(..., run_name="__main__")` → `asyncio.run(main(port=…))`). Startup matches the device — **`Settings`**, **`presets.load`**, **default preset** from settings, **`patterns/`**, **Microdot** **`/ws`**, **`presets_loop`**, **UDP hello**. Only **`machine`**, **`neopixel`**, **`network`**, **`utime`**, and **`ubinascii`** are stubbed (`stubs/`).

The GUI sets **`LED_SIM_ROOT`** so **`main.py`** can register the Microdot app for **Stop**, and **`LED_SIM_PORT`** for the HTTP/WebSocket listen port (default **80** on device when unset). On the ESP32 those variables are unset.

## Requirements

- Python 3.10+
- Tk (e.g. `python3-tk` on Debian/Ubuntu if the window fails to open)

## Run

From the repository root:

```bash
pipenv install   # optional; Microdot is vendored under led-driver/lib
python3 led-simulator/gui_main.py
```

## UI

- **Start** / **Stop**: start or stop the full **`main.py`** process (same code path as the chip).
- **HTTP / WS port**: Microdot listen port; WebSocket URL **`ws://127.0.0.1:<port>/ws`** (JSON **v1**).

Configure the app like on flash: **`workspace/settings.json`** (patched as device settings path), **`presets.json`** and **`patterns/`** under **`led-simulator/workspace/`** when the simulator creates symlinks from **`src/`**, or edit files directly under **`led-driver/src/`** if you use a real **`patterns/`** directory there.

Example pattern modules: **`led-simulator/examples/`** (`Blink`, `Chase`). Copy into **`patterns/`** as on the device.

## Notes

- Changing the port spinbox only takes effect on the next **Start**.
- If **`led-driver/src/patterns`** already exists as a normal directory, the simulator leaves it in place.

## Shell (no GUI)

```bash
cd led-driver/src
PYTHONPATH="../lib:../../led-simulator/stubs" LED_SIM_ROOT="../../led-simulator" LED_SIM_PORT=8765 \
  python3 main.py
```

(Adjust paths from your checkout root; **`LED_SIM_ROOT`** must point at **`led-simulator/`** so **Stop**-style hooks work if you use them.)