led-simulator/README.md

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:

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)

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