A small, portable and predictable application runtime for microcontrollers. MetaDeck's first hardware target is the original Raspberry Pi Pico (RP2040), while the same allocation-free core builds natively on macOS and Linux.
Documentación en español · Spanish learning guide · Architecture · Roadmap
MetaDeck is an early vertical slice, not a finished consumer operating system. The kernel, app lifecycle, IPC, package validation and USB protocol are implemented. The Pico display, touch, LVGL, flash filesystem and installable-app VM are not.
Small interactive devices need more structure than one growing loop(), but
cannot afford desktop assumptions. MetaDeck provides explicit lifecycle,
communication and hardware boundaries while keeping memory and per-tick work
bounded.
┌─────────────────────────────────────────────┐
│ Apps Launcher · Monitor · future MPK │
├─────────────────────────────────────────────┤
│ SDK identity-bound capabilities │
├─────────────────────────────────────────────┤
│ Services AppManager · IPC · MPK · USB │
├─────────────────────────────────────────────┤
│ Kernel EventBus · Scheduler · Clock │
├─────────────────────────────────────────────┤
│ Drivers Display · FileSystem · Transport│
├─────────────────────────────────────────────┤
│ Platforms RP2040/Pico SDK · macOS/Linux │
└─────────────────────────────────────────────┘
MetaDeck is not a miniature Linux. It has no processes, virtual memory or preemptive threads. It is a cooperative embedded runtime with fixed-capacity state, observable overload and platform-independent contracts.
| Area | Status | What exists today |
|---|---|---|
| Kernel | Working | bounded event queue and cooperative scheduler |
| App runtime | Working | install/start/stop, foreground/background lifecycle |
| IPC | Working | identity-bound endpoints and transactional broadcast |
| SDK isolation | Working | scoped IPC/storage/UI/clock capabilities |
.mpk |
Partial | deterministic builder, CRC and semantic manifest parser |
| PC protocol | Partial | framed, correlated Ping/Info/Launch over Pico CDC |
| Host | Partial | console composition and sandboxed filesystem |
| RP2040 | Partial | boot, heartbeat, runtime and direct TinyUSB transport |
| Display/touch/FS | Stub on Pico | contracts and null drivers only |
| App store/VM | Planned | architecture and package container only |
The detailed evidence and known limits are recorded in the implementation audit.
Requirements: a C++17 compiler, Make and Python 3.9+.
git clone https://github.com/Mark19000/MetaDeck-OS.git
cd MetaDeck-OS
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
make test-all
make runmake run starts the current console host harness. It does not yet emulate an
LCD or touch input.
make size-checkThis cross-builds the UF2 and fails if the ELF exceeds the configured RAM,
flash or main stack-frame budgets. The artifact is written to
.pio/build/pico/firmware.uf2.
With a physical Pico connected:
pio run -e pico -t upload
python3 tools/metadeck_cli.py /dev/cu.usbmodem101 info
python3 tools/metadeck_cli.py /dev/cu.usbmodem101 launch 2Linux ports commonly look like /dev/ttyACM0. Hardware claims require the
HIL checklist; the current revision has not completed
that checklist on a physical board.
| Command | Scope |
|---|---|
make test-all |
host build, C++/Python/FS tests, ASan/UBSan, fuzz smoke |
make test |
short C++ core/service suite |
make test-sanitize |
memory/undefined-behavior checks and fuzz smoke |
make size-check |
pinned Pico build and ELF/stack budgets |
CI runs the host gate on Ubuntu and macOS and the Pico budget build on Ubuntu.
Test builds force assertions on even if the environment defines NDEBUG.
- No dynamic allocation or exceptions in the portable runtime path.
- Registries, queues, mailboxes and wire payloads have compile-time limits.
- Cooperative callbacks must return quickly; I/O is incremental and budgeted.
- Apps receive scoped capabilities, never raw global buses or hardware drivers.
- Native apps are trusted and linked into firmware.
- Future installable apps will use bounded bytecode, not arbitrary ARM binaries.
- Corruption checks are not authentication; package signing remains future work.
The rationale behind these choices is kept as architecture decision records.
apps/ built-in native apps
components/kernel/ event queue, scheduler and kernel shell
components/sdk/ public app-facing API
components/services/ lifecycle, IPC and service composition
components/ui/ portable UI/compositor boundary
components/drivers/ hardware contracts
components/package/ MPK container and manifest validation
components/protocol/ framing, decoder and portable protocol service
platform/host/ macOS/Linux adapters
platform/rp2040/ Pico composition and TinyUSB transport
tools/ package builder, serial CLI and ELF gate
tests/ unit, integration, sanitizer and fuzz-smoke tests
docs/ references, manual, audit and decisions
- New to the project: complete Spanish manual
- App author: SDK reference
- Tool author: wire protocol and MPK format
- Platform author: architecture
- Hardware tester: HIL checklist
- Contributor: CONTRIBUTING.md
- Security reporter: SECURITY.md
MetaDeck is at a stage where small, measured changes are preferable to broad framework additions. Read CONTRIBUTING.md before opening a pull request and SUPPORT.md before asking for help. Please report security-sensitive findings privately as described in SECURITY.md.
MetaDeck OS is available under the Apache License 2.0. It permits commercial and private use, modification and redistribution, subject to its notice and change-marking conditions, and includes an express patent grant.