Jimmy
42c14361e8
Add host simulator scaffolding, examples, and docs so led-driver main can run end-to-end with MicroPython module stubs. Co-authored-by: Cursor <cursoragent@cursor.com>
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 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.)
|