PagerOS

This is a monorepo for PagerOS, simulator/workbench experiments, firmware research, and local device tooling.

Start with ARCHITECTURE.md for the full plan: host simulation, TinyGo-style WASM simulation, Wokwi/QEMU real firmware execution, and the future desktop workbench.

Layout

apps/
  go-device-sim/
    Plain-Go local fake device environment.

configs/
  feather-pager.json
    Editable device config for the local simulator.

pageros/
  Placeholder for the actual PagerOS source.

rust/
  Rust/PagerOS implementation track notes and future crates.

research/
  Notes on TinyGo, Wokwi, QEMU, Rust WASM, and simulator design.

experiments/
  legacy-bun-playground/
    First Bun proof-of-concept runner, kept for reference.

docs/
  Older playground notes and supporting docs.

The root is intentionally not a Bun, Go, Rust, or Node workspace. Each track owns its own tooling.

Current Default: Go Device Sim

Run the local fake board:

cd apps/go-device-sim
go run . --config ../../configs/feather-pager.json

Then open the printed URL, usually:

http://localhost:8790

The simulator renders a small board graphic, maps keyboard keys to buttons, tracks pressed state, and can pipe button events to a configured child process.

Default keys:

ArrowUp / ArrowDown / ArrowLeft / ArrowRight
Enter
Backspace
Escape
z
x

Button events use this simple host-mode protocol:

button down select
button up select

Config

Device configs are plain JSON for now so the Go prototype has no parser dependency.

Example button:

{
  "name": "select",
  "label": "OK",
  "key": "Enter",
  "x": 210,
  "y": 454,
  "r": 26
}

Set program.cmd when you want the simulator to launch a process and send it button events over stdin.

Direction

There are separate execution tracks:

• host: fast local process simulation.
• wasm-sim: TinyGo-style source-to-WASM simulation for PagerOS-style code.
• wokwi: real ESP32 firmware simulation for .bin, .elf, and .uf2 artifacts.
• qemu: real ESP32 firmware execution/debugging through Espressif QEMU.

The local board graphic and button mapping belong to our workbench. Real ESP32 firmware execution belongs to Wokwi/QEMU or another real emulator backend.