ESP32 Playground / PlaygroundOS

English | 简体中文

ESP32 Playground is a personal hardware laboratory for the QD Electronics ES3N28P board built around an ESP32-S3 R8N16. Small experiments with display, input, USB, GPIO, RGB, audio, I2C, Wi-Fi, BLE, and LAN communication have gradually become PlaygroundOS (PGOS), a lightweight device base with system services, foreground applications, and one consistent input protocol.

This repository is a development snapshot of a personal experiment project, not production firmware. Feature status follows the source code and the records in docs/experiments/; hardware results are not a guarantee for other boards.

These selected captures come from the development board and show the system shell, games, on-device model UI, and audio tools. The complete capture archive remains local and is intentionally excluded from Git.

PGOS Shell	2048

TinyLM presets	Microphone tool

Breakout

See the hardware baseline for wiring, electrical limits, and reserved pins. Confirm 3.3 V compatibility, common ground, and power safety before connecting external modules or speakers.

• PlatformIO CLI
• Python 3.10 or newer
• An ES3N28P R8N16 board and a data-capable USB cable

pio run -e playground
pio run -e playground -t upload --upload-port COMx
pio device monitor --port COMx --baud 115200

PlatformIO restores the managed LCD dependency from main/idf_component.yml. Before the first build in a clean clone, restore the pinned local components with python tools/bootstrap_components.py. Component snapshots, locked revisions, and the parts that are not yet fully reproducible offline are described in docs/DEPENDENCIES.md.

python -m pip install -r tools/requirements.txt
python tools/playground_console.py --list
python tools/playground_console.py --port COMx
python tools/capture_screen.py --port COMx --output captures/home.png
python tools/capture_microphone.py --port COMx --duration 3000 --output captures/mic-test.wav

The USB console supports navigation, direct page access, status queries, RGB565 screenshots, and microphone recording. Wi-Fi SSIDs, passwords, and server addresses are configured at runtime through the device UI or console; they must not be written into source files. include/secrets.example.h contains placeholders only.

python -m pip install -r tools/requirements-studio.txt
python tools/pgos_studio.py --listen 0.0.0.0 --port 19000

Studio uses TCP port 19000 for control, 19001 for throughput tests, and 19002 for screen mirroring. The current control channels have no TLS or authentication and should only be used on a trusted home LAN. See SECURITY.md.

python -m unittest discover -s tools/tests -p "test_*.py"
pio run -e playground

Host tests cover game rules, input policy, resource conversion, protocol tools, and demo data. Passing host tests does not replace real-device checks for the display, gamepad, audio, wireless coexistence, or long-term stability; keep evidence in the corresponding experiment record.

main/       Firmware entry point and ESP-IDF orchestration
src/        PGOS apps, services, games, UI, and fixed third-party source
include/    Public headers and example configuration
boards/     Custom PlatformIO board definitions
tools/      Console, Studio, asset conversion, and host tests
docs/       Hardware baseline, architecture, roadmap, and experiments
licenses/   Font and icon license texts

Start with:

• Feature list
• Project plan
• PGOS architecture
• Wi-Fi and LAN plan
• Experiment index
• Reusable knowledge base
• Dependency policy
• Third-party notices and source index

• The Chinese TinyLM training/export sources are in src/third_party/esp32_ai/ and follow that directory's MIT notice. Roughly 430 MB of raw data, checkpoints, intermediate files, and model.bin are not in this repository; dataset, vocabulary, and model rights must be reviewed separately.
• src/games/Platformer* contains level data and pixel resources converted from third-party SMB fan projects and uses Mario/Nintendo-related names. These files are not automatically covered by the root MIT grant. Redistribution of source, firmware, or binaries requires permission or replacement with clearly licensed original assets.
• Fonts, icons, VAD, SpeexDSP, and build-time components retain their original licenses. See THIRD_PARTY_NOTICES.md for the full scope and direct source links.
• docs/vendor/ records board-vendor reference material. Do not upload vendor EXEs, APKs, flashing tools, or large source packages to a public repository.

Original PlaygroundOS code and documentation, unless a file or directory says otherwise, are released under the MIT License. The MIT License does not cover third-party source, fonts, models/data, vendor material, or the SMB derived resources. Preserve the applicable copyright and license notices when redistributing. Project author: @jie65535.