Important
This is an actively developed controller, not a certified production release. Current production acceptance is tracked in issue #2. Build artifacts, source tests and screenshots are not proof of physical-board acceptance.
An ESP32-S3 / ESP8266 + ATmega328P controller with an mpv-free Windows workspace, embedded Web interface, CLI/TUI and an Android preview. Controls must follow the connected board's acknowledged capabilities; offline or unsupported peripherals are not invented by the client. Pealayer supplies real reusable desktop foundations, PCController supplies protocol/contracts, and the earlier boards supply hardware mapping and reusable drivers. Exact reuse gaps remain tracked rather than hidden.
Each firmware build selects one board role using -GameMode table-selection
or -GameMode first-wins. The table role provides a persistent red-to-white
lock and atomic cell-color imports. Rust and Flutter support genuine Excel,
CSV and JSON documents; the embedded Web UI supports CSV and JSON.
See board roles, lock semantics and assignment APIs.
Web device-settings preview — actual embedded UI, simulated device state
This screenshot is from a read-only HTTP fixture. It is not a live board or a claim that every requested native/mobile setting is complete.
flowchart LR
Desktop[Windows · egui / CLI / TUI] <-->|JSON / WebSocket / USB| ESP[ESP32-S3 · retained ESP8266 target]
Web[Embedded Web interface] <-->|Shared API state| ESP
Mobile[Android preview] <-->|Wi-Fi API / BLE on S3| ESP
ESP --> LEDs[Addressable LED cells]
ESP <-->|COBS + CRC · UART| AVR[ATmega328P]
ESP -->|ISP recovery / updates| AVR
AVR --> Panel[Keys · shift registers · TM1637 · buzzer]
ESP <-->|Configurable TLS links| Cloud[MQTT / WebSocket]
The coordinated source release is 0.2.8; the authoritative client build is
recorded in the shared release identity. Apps and
firmware enforce the shared minimum supported release by default, independently
disableable at build time. HTTP headers, discovery and /api/peer/info identify
each party; /api/clients exposes bounded, nonsecret peer introductions. API
paths remain unversioned, with additive capabilities rather than build-specific
adapters. Older installed products need a coordinated update; this source/build
checkpoint is not a deployment. See policy, build flags and recovery.
Native Preferences → Connection → Share connection can publish the selected
USB or network board through the existing HTTP/WebSocket table APIs, with opt-in
mDNS/DNS-SD, SSDP and MNDP discovery. USB remains offline unless sharing is
enabled. Other clients use http://<configured-hostname>.local:8789; downstream
board identity and sole serial ownership are preserved. See the
bridge contract and remaining scope.
The native network bridge forwards guarded upstream firmware transfers; a USB-only
route never silently starts network management. Binary pixel streaming and full
PCController peer-RPC parity remain pending; real LAN acceptance stays open in issue #2.
Authentication defaults off in the current firmware; older installations can retain persisted credentials. Inspect Device access or use the explicit USB recovery utility rather than guessing a factory password. See Access and recovery and the explicit PU850 parity audit. ESPAsyncWebServer now hosts the Web UI/API/WebSocket, ESP OTA and AVR ISP in the same firmware.
Version 0.2.7 adds pinned remote two-board updates and full operational telemetry. The 50-route PU850 mapping records exact adaptations and exclusions. Physical and publisher acceptance remain open in issue #7; no production deployment is implied by a passing build.
PakarController is a two-controller game platform built from the reusable parts of AtomicDeploy's earlier PuzzleBoard, 40LED, Puzzles, pu850-esp, PCController, and Pealayer work.
- The ATmega328P owns deterministic keys, shift-register outputs, the ninth ADC6 button, TM1637 display, buzzer, melodies, and winner arbitration.
- The ESP32-S3 owns the MT16703/WS2811-compatible LED field, Wi-Fi/API/UI, streaming, self-OTA, AVR ISP recovery, and LittleFS firmware backups.
- The retained ESP8266 target shares the integrated firmware; Bluetooth is S3-only.
- Both use the PCController COBS + CRC-8/ATM UART envelope at 38400 baud. The AVR uses its hardware UART; S3 uses a separate hardware UART (ESP8266 uses SoftwareSerial), while the USB UART is a second framed 115200-baud PC transport.
- The Windows controller uses Pealayer's eframe/egui design approach without linking or loading mpv.
- Optional outbound cloud links provide TLS MQTT telemetry/commands and a configurable WebSocket client. MQTT and WebSocket secrets are write-only and stored in checksum-backed LittleFS configuration. See bidirectional commands, events and integration contract for LAN/Internet HTTP, WebSocket and MQTT paths and their verification limits.
- The PU850-derived network toolbox also includes mDNS discovery and a password-authenticated Telnet command shell without taking over either UART.
No I2C peripheral is enabled or required.
See docs/HARDWARE.md, docs/HARDWARE-VERIFICATION.md,
docs/ARCHITECTURE.md, docs/API.md, docs/TOOLCHAIN.md, and
docs/LEGACY-CODE-AUDIT.md before wiring or flashing.
The native Windows app is in desktop/. It deliberately has no mpv or
libmpv2 dependency. Its eframe, reqwest, serde versions and system-aware
visual styling are derived from Pealayer's MIT-licensed desktop foundation.
It can stream a generated rainbow or sample the primary screen into the 10 by
8 staggered table through the authenticated WebSocket.
The Streaming panel exposes a shared target rate (60 FPS by default; 0 is
uncapped) and measured completed host frame writes. This is not measured LED
refresh. Monitor/region selection and live frame-rate acceptance remain open.
Use the current main checkout and existing SDK installations:
git clone https://github.com/atomicdeploy/PakarController.git
cd PakarController
.\pakar.cmd doctor
.\pakar.cmd all # plan only, no SDK compilationWindows and Bash entrypoints share one dispatcher, staged output, validated arguments and guarded build wrappers. Node 20.19+ and PowerShell 7 are required. The central firmware pins are unchanged by builds; installation and dependency updates are explicit:
.\pakar.cmd dependencies --plan
.\pakar.cmd firmware --target esp32s3 --plan
.\pakar.cmd firmware --target esp32s3 --link-mode buffered --s3-flash-mb 16 --s3-psram opi
.\pakar.cmd desktop --mode Check --plan
.\pakar.cmd mobile --mode ApkPreview --build-only --planLinux/macOS use bash pakar.sh with the same options. Legacy build.cmd and
bash build.sh polling / bash build.sh busy-wire remain aliases; tests are
explicit rather than hidden build side effects. CI builds polling/busy-wire
ESP8266+AVR pairs and buffered S3+AVR; deployed peers need compatible build
flags. Every merged AVR+Urboot image must be exactly 32 KiB.
Run .\pakar.cmd test protocol for COBS/CRC bounds/corruption fixtures.
The script tooling reference covers common help,
JSON/quiet output, proxy support, dependency maintenance, artifact checksums,
automatic update plans, platform limits and exact PU850 source imports.
Build the Windows application with:
.\tools\build-desktop.ps1 # Check, no executable link
.\tools\build-desktop.ps1 -Mode Test # Changed native behavior
.\tools\build-desktop.ps1 -Mode Release # Only when an app update is neededBuild storage policy: docs/BUILD-STORAGE.md. Native
debug/test symbols are disabled by default, with incremental reuse retained.
Build scripts refuse low free space or an oversized canonical Cargo cache.
Firmware compilation is incremental; use -Target avr or -Target esp8266 for
an isolated board change and -Clean only when diagnosing a stale cache.
Linux supports bash build.sh busy-wire esp8266 (optional --clean).
Use one stable staging directory and tools/stage-desktop.ps1; identical builds
skip copying. Fixtures can run directly from the canonical built executable.
Before any task or tool failure, follow donor-first preflight:
./tools/consult-reuse.ps1 -Concern build-storage (or capture, ui-shell, preferences,
windows-desktop, network-cloud, firmware-hardware, updates-telemetry, games-streaming).
Read actual matched donor code before a replacement or unsupported claim. Build,
stage and capture wrappers enforce hash-bound reviewed-slice gates automatically;
pending mappings remain visible and are not accepted exclusions.
The same executable provides scriptable CLI and interactive TUI surfaces. Set
PAKAR_ENDPOINT, and optionally PAKAR_USER / PAKAR_PASSWORD, then use:
PakarController.exe --status
PakarController.exe --command cell 17 red fade
PakarController.exe --command mode snake
PakarController.exe --tuiLogical IDs are row-major: 1 is upper-left, 2 is next to it, and 11 begins the second row. Graphical tables offset one-based odd columns by half a cell in Y; each cell contains six LEDs. Physical strip order is a separate editable map. The interactive terminal now has contextual pages, shared Find/selection, explicit bulk white/red/off actions and the shared CLI command palette. See terminal controls and remaining acceptance. Staggered graphics, richer editors and full TUI parity remain open in issue #2.
The CI/CD pipeline checks generated interface, branding and donor-evidence contracts, tests both UART build variants, builds the Windows client and analyzes/tests/builds the Android preview. It stops at the first failed command. Timeouts, superseded-run cancellation and short artifact retention bound wasted work. The tooling matrix checks shared CLI fixtures and guarded command plans on Windows/Linux/macOS; these are not native package or hardware acceptance. CodeQL scans Actions and JavaScript; it does not claim Rust, AVR C++ or physical hardware coverage.
The expanded pipeline supports version tags and explicit owner dispatch for draft prereleases, with Windows and two-board firmware packages, Android preview, SHA-256 checksums, source/run manifest and provenance attestation. No automatic flash occurs and no development artifact is silently promoted to a production release. PU-derived dependency checking and exact-artifact device deployment have separate guarded workflows. Deployment is disabled until the owner explicitly configures its runner/environment/opt-in. See shared tooling and activation and repository governance. Source configuration does not certify that a current GitHub run passed or a device was updated.
| Start here | Purpose |
|---|---|
| Hardware | Pin mapping and wiring |
| API | Device transport and commands |
| Bluetooth LE | S3 offline Android control, identity, settings and transport limits |
| Client updates & monitoring | Configurable release endpoint, enrollment, telemetry and safe cleanup |
| Architecture | Board responsibilities |
| Source comparison | File-by-file reuse and justified omissions |
| Production checklist | Open acceptance and delivery work |
| Repository governance | Labels, settings, CI/CD and release policy |
Read CONTRIBUTING.md before changing code or wiring. Report bugs with the device/application versions, acknowledged capabilities and transport; redact credentials and personal telemetry. See SECURITY.md for private vulnerability reporting. Licensed under MIT; donor notices and applicable third-party licenses must be retained.