Skip to main content

The simulator

The Kog simulator is not a preview or a web approximation — it is the same native runtime (LVGL, the JS engine, the Kog host layer) compiled for your desktop, executing the same bytecode bundle your board would run. If it works in the sim, the rendering and logic are identical on hardware.

Using it​

npm run dev            # opens the simulator automatically (default target)
npx kog simulate       # simulator without the dev server

The window matches your configured display (from board.yaml or kog.config.ts) — resolution, and eventually shape: round displays render round.

Getting a window on macOS​

Homebrew's sdl2 is now sdl2-compat — the SDL2 API implemented over SDL3 — which loads libSDL3.dylib at runtime. If it can't find SDL3 on the dynamic-load path, the simulator falls back to headless rather than hanging: it still runs (hot reload, console.log, and tests all work), it just doesn't open a window, and it tells you so. To get a visible window, put SDL3 on the load path:

DYLD_LIBRARY_PATH=/opt/homebrew/lib kog dev      # or DYLD_LIBRARY_PATH=$(brew --prefix)/lib

Pass --headless to skip the window on purpose (CI, over SSH, or when you only need the logs).

  • Pointer: mouse acts as the touchscreen.
  • Hot reload: identical to device — save and it remounts in under a second, preserving your current screen and navigation state.
  • console.log: appears in your kog dev terminal, source-mapped.
  • Errors: compile errors overlay in the sim; runtime errors show the same error screen a device would, with the full stack in the terminal.

Virtual hardware​

GPIO, ADC, and PWM work in the simulator against a virtual pin table:

  • Number keys toggle configured digital input pins (so useButton(0, ...) is testable by pressing 0).
  • The dev server can script pin and ADC values (setPin, setAdc) over the dev channel — useful in tests.
  • I2C/SPI transactions resolve through the same async path as real hardware, returning mock responses you can register.

This means an app that reads a sensor and reacts to a button can be developed end-to-end before your board arrives.