NucleoOS

The web‑native operating system for the M5Stack Cardputer

The OS runs on the device. Your browser is the rich operator console. One ESP32‑S3, no PSRAM, ~512 KB of RAM — turned into a real, modern, multi‑app OS with an AI assistant that uses the best brain you have (offline on the device, your own PC's models, or the cloud), a desktop‑class web shell, a pocket game console, a security lab, voice transcription and image generation.

ESP32‑S3 / M5StampS3 · ESP‑IDF firmware · PWA web shell · English‑only codebase

⬇️ Install · 📋 What's new in v0.8.0 · 📖 User Guide · 💬 Discord

_{Free for noncommercial use · commercial use requires a paid license → [email protected]}

_{⚠️ Includes security-testing tools — authorized testing, research & education only. Read the rules ↓}

You need: a Cardputer (original or ADV — same firmware), a USB‑C data cable and a microSD card formatted FAT32.

⚠️ FAT32 only — not exFAT. Cards over 32 GB come exFAT from the factory and Windows won't offer FAT32 for them: reformat with a tool such as guiformat or Rufus. On an exFAT card the firmware boots, but the web OS can't be read and the browser shows the Rescue page ("The desktop shell is unavailable on this device").

1. Open indecenti.github.io/NucleoOs in Chrome or Edge on a desktop.
2. Plug in the Cardputer and click Connect & install NucleoOS.
3. When it finishes, press reset.

Already running M5Launcher? NucleoOS installs as a guest next to them.

1. Download nucleoos-latest.bin and copy it to the SD card.
2. In the Launcher, pick it from the SD installer. Updates also go through the Launcher.
3. The .bin is only the firmware. The web OS lives on the card: extract nucleoos-latest-sd.zip to the card root, or let the first‑boot wizard download it over Wi‑Fi (see below).
4. The Native C store needs NucleoOS 0.8.4 or later installed by the Launcher: it then creates a 448 KB flash partition (nucleo_nap) the native apps run from. On an older install the store is greyed out: install the new .bin from the Launcher again.

Download nucleoos-latest.bin, then with esptool (pip install esptool):

esptool --chip esp32s3 --baud 921600 write_flash 0x0 nucleoos-latest.bin

• SD content. NucleoOS serves its apps from the card. Once on Wi‑Fi, the first‑boot wizard downloads it by itself — verified, resumable, skippable. Or extract nucleoos-latest-sd.zip to the card root so /apps, /www, /system and /data sit at the top. The zip is card content, never a firmware.
• First boot. A short wizard on the Cardputer's keyboard asks for language, Wi‑Fi (or starts the device's own access point) and a name. The screen then shows an address: open it in a browser on the same network and pair with the 6‑digit PIN (Control Center ▸ Web, or Settings ▸ Device).
• Updates come by themselves: Settings ▸ Updates offers a checksum‑verified one‑click update, with A/B slots and automatic rollback, and syncs the SD content (only changed files).

All files: latest release · full walkthrough: User Guide.

Most Cardputer firmwares are a menu of tools. NucleoOS is an actual OS — a registry of capability‑scoped apps, an event‑sourced bus, pairing/auth, OTA with rollback, an i18n engine, notifications, a power manager, and two complete user interfaces that share one contract:

The split is deliberate: heavy work goes to the browser, never to the 18 KB device heap. That is the single idea that lets a no‑PSRAM microcontroller host an experience this large.

_{The native on‑device UI (240×135) — launcher → music → video — captured live over Wi‑Fi from the device's own GET /api/screen endpoint, which streams the physical panel as a BMP, no canvas, ~0 heap.}

NucleoOS runs on both the original M5Stack Cardputer and the newer Cardputer ADV — a single universal binary auto‑detects which one you have (keymap + audio codec HAL) at boot, so you build once and flash either.

_{Left: original Cardputer (M5StampS3). Right: Cardputer ADV (Stamp‑S3A, bigger battery, IMU, 3.5 mm out). Product photos © M5Stack.}

• A second screen. Plug a 2.8" 320×240 SPI touch display into the Cardputer ADV's EXT header and the launcher, the games and the apps get their own layout for it, with direct touch: tap a tile, drag a list, press the content itself. The Cardputer's screen becomes a companion (what you type, the score, the hints). The panel has its own brightness, a 4-point touch calibration and switches off with the Cardputer in standby. Wiring and schematic ↓
• The Store has native apps. Two channels, asked first: Native C apps that run on the Cardputer itself (signed modules installed on the SD card, loaded when you open them) and Web apps served to your browser. Every catalog and package is signed offline and checked on the device before anything installs. How it works ↓
• Games ship from the Store, not inside the firmware: about 480 KB of flash freed for the OS. After updating, open Store ▸ Native C and install the ones you play; saves, pins and recents carry over.
• One web OS for every NucleoOS device. The web desktop and its apps now come from the shared nucleo-webos build (also used by the Handheld and the P4), with the same Store in the browser.

Previous release (v0.7.5): opt-in auto-update with a cancellable countdown, the whole native UI in the OS language, a Torch with red/orange light and SOS.

Full notes: CHANGELOG.md. Installed devices are offered the update in Settings ▸ Updates.

An optional 2.8" SPI TFT (the common red "2.8" TFT SPI 240x320" V1.1 / V1.2 board: ILI9341 or ST7789V controller, XPT2046 resistive touch) on the ADV's EXT 2×7 header. No settings are needed with the wiring below: the firmware finds the module at boot (it reads the touch chip), and with nothing plugged in nothing changes. The original Cardputer can't take it: G5/G6 scan its keyboard.

<sub>The electrical schematic: power, the SPI bus shared with the microSD card, the LCD, the touch controller and what happens in standby.


Wire by wire, one colour per wire, with the EXT header seen from the top.</sub>

Before powering: wire with the Cardputer off, leave the module's jumper J1 open (closed, 5 V goes straight into the panel and the touch chip drives 5 V into G39), and find EXT pin 1 (G3) first — a reversed header swaps 5 V and GND.

Touch. Taps, drags and long presses act on what is under the finger: every screen has a finger-sized Back, lists scroll with a drag, games are played on the panel. Calibrate once from Settings ▸ Second screen ▸ Calibrate touch (four targets).

Power saving. When the Cardputer goes to standby (idle timeout, the Control Center, or display off from the web), G3 switches the panel's backlight off, both screens get the sleep command and the touch controller stays in power-down with its interrupt armed: a tap on the panel wakes everything. With the LED wire on 5VOUT instead of G3 the backlight can't switch off; the panel is only painted black.

Settings ▸ Second screen (ADV only): mode (both screens / Cardputer only / panel only), big home, big apps, speed (10–40 MHz), orientation, brightness, touch, calibration. Full reference, including other pinouts and troubleshooting: docs/external-display.md.

The Store is the second entry on Home, right after ANIMA. It asks first which channel to open:

• Safe by construction. Only the maintainer publishes, with an offline key. The device installs only what verifies against the keys compiled into the firmware, and a native module is checked again before every launch, so an edited card never runs code the Store did not sign. Every native app is rebuilt byte for byte from public NucleoOS source.
• Small firmware, more apps. Native apps live on the card, not in the firmware: the games alone freed about 480 KB, and new apps ship without a firmware release.
• Updates in one tap, from the Cardputer or from the web OS: the same store, the same signatures, checked by the browser too.

Store repository and catalog: indecenti/nucleoos-cardputer-store · format and rules: its docs/ · how native apps work: docs/native-apps.md.

ANIMA answers from a ladder of engines and shows which one answered:

• Facts and commands first, exactly. Device actions, battery, Wi‑Fi, storage, time, dates, unit conversions and arithmetic are answered exactly in all five languages. A model never makes these up.
• Your own PC's model. Ollama, LM Studio, llama.cpp or Jan on the computer you browse from is free, offline and needs no key. Set it up in Settings ▸ AI / Models ▸ Models on your PC.
• A cloud model, if you add a key: Claude, Groq, Grok (xAI) or Gemini.
• In the browser. A full LLM on WebGPU (Qwen3‑1.7B), or the Cardputer's own brain compiled to WebAssembly, offline and private.
• On the Cardputer, always. A real offline NL engine in C: a retrieval cascade, a knowledge graph, math and units. It is grounded by construction, so it never invents a fact it doesn't have.

There are two modes. Auto uses the best engine available. Private removes every Internet step, so nothing leaves your machine.

_{Settings ▸ AI / Models ▸ Models on your PC: what runs on this computer, a model per task, who answers first.}

ANIMA's agent works like a small OpenCode on your files. It gets a workspace folder on the SD and tools to read, search, edit (with a diff and your approval), create files and run JavaScript. It also has a Linux‑like shell (ls, cat, grep, sed, node FILE.js). It runs on your PC's model or a cloud key. The Cardputer only stores the files and never runs an inference.

🔊 Bilingual offline voice. ANIMA speaks — a concatenative TTS engine (IT/EN) that pre‑vocalizes a finite, grounded vocabulary on the PC and pastes the right clips at runtime: natural voice, ~zero RAM, completely offline. It reads the time to the exact minute, confirms launches ("Opening music"), states status — and politely says "read it on screen" for anything that shouldn't be spoken aloud. See docs/tts.md.

When you do want a frontier model, NucleoOS wires it in cleanly:

• OS‑wide copilot — summon AI from anywhere with Ctrl/⌘ + Space.

• Pluggable providers — Claude, Groq, Grok (xAI), Gemini. Configure one (or several, with automatic fallback). Keys are stored on the device SD, never logged, and the browser talks to the provider directly — the Cardputer isn't in the loop.

• AI Chat talks straight to the model you pick; ANIMA picks the best engine for each turn.

• ANIMA Code — a sandboxed JavaScript runtime in the browser with an os.* API (os.fs, os.http, os.anima, os.notify): write a script, hit Run, drive the OS.

• ANIMA Chat / Agents — multi‑turn chat and a browser‑hosted multi‑agent runtime for online work.

• On‑device transcription — speak into the Cardputer mic and watch text appear, on‑device, via a Vosk WASM model. IT/EN, summarize, screen‑off while listening to save battery.
• Record & transcribe in real time, remotely — start a recording on the Cardputer and stream it live to NucleoOS Web (/api/rec/stream) for real‑time transcription on the big screen.
• Mic Spectrum — a live FFT analyzer on the native screen.

Paint is a full image editor — layers, tools, adjustments, transforms — with an AI side (Atelier) that generates and manipulates images locally via WebGPU, no server: "create a cat icon", "remove the background", "brightness +20", "rotate right". Heavy pixels live in the browser GPU; the device just stores the result.

Costellazioni is the flagship: a space game with 6DOF combat in procedural star systems, a galaxy to cross (map, jumps, docking, beacons to relight) and worlds to land on — seamless descent from orbit, eight biomes, discoveries. It has 66 paintings and an original four‑track score. It plays in the browser; a native version runs on the Cardputer itself.

• Native console on the Cardputer, all with one console look, in five languages, with sound packs:

  • multiplayer over ESP‑NOW, with no router: Pong, Snake Duel and Tank Duel;
  • Brawl (a beat‑'em‑up), Hordes, Cardler (a mini‑RPG), Pinball, Reactor and Tanks (artillery);
  • Poker, Slots, Yahtzee and Dice;
  • the new Sand Garden, a merge game.

  Each game reboots into a fresh heap for maximum RAM.

• Native Game Boy & Game Gear emulation — our own cores (no PSRAM tricks, cartridge‑accurate, battery‑backed saves), running your own ROMs straight off the SD, zero browser needed.

• Arcade (web) — a second, browser‑side emulator (EmulatorJS: NES, SNES, Game Boy, GBA, Mega Drive, PC Engine) for when you'd rather play on the big screen.

• Game Center (web) — peer‑to‑peer over WebRTC with the Cardputer as signaling: Tic‑Tac‑Toe, Connect 4, Pong — 2‑player or vs ANIMA (offline brain, or an LLM brain when online).

• Film player (native) — plays .nfv v4 (whole-frame JPEG + IMA ADPCM sound in one file, ~15 fps) straight off the SD, on the external 320x240 panel too, with seek and resume.
• MP3 player (native) — dual‑mic aware, browses folders, reads duration from headers.
• Radio (native) — multi‑station internet radio with a twin web app.

A clean‑room offensive/defensive toolkit (native firmware apps):

• WiFi Sniffer — promiscuous capture → .pcap on SD, live breakdown, radiotap, radar view.
• Evil Portal — captive‑portal testing.
• WiFi Attacks — deauth/beacon/probe suite (clean‑room).
• BLE Suite — scan / spam / iBeacon.
• Ethernet (W5500) — raw L2/L3 MACRAW attacks over the SD bus.
• Payloads / BadUSB — DuckyScript runner with dry‑run.
• USB Keyboard PRO — HID injection, macros, IT/US layouts.

Turn the Cardputer into a Swiss‑army tool: Torch, Bubble Level, Protractor (goniometer), Alarm (siren armed by microphone + accelerometer + IMU), Pedometer (step counter), Mic Spectrum, plus Clock, Calendar, Weather, IR Remote, QR and PixelFix.

A real SSH terminal that reaches your hosts through a tiny self‑hosted bridge (no third party) — available as a native app on the Cardputer and as a full web terminal with saved hosts.

File Commander, Spreadsheet (SUMIFS/VLOOKUP/IF with an ANIMA copilot), a live System Monitor, Settings Control Center, Notepad, Calculator, DOSBox, and more — real windows, fullscreen, drag‑and‑drop, Start menu and search.

📸 More screenshots — web shell apps

The apps are the surface. These are the engineering bets that make them possible on a no‑PSRAM microcontroller — and several have no equivalent in other Cardputer firmwares.

ANIMA's offline brain is written once in C and runs in three places, certified to give the same answer in each:

1. On the ESP32‑S3 (the device firmware).
2. In your browser — the exact same C compiled to wasm32 (anima-local.wasm), so the web shell's assistant is offline and private, not a reimplementation.
3. On the PC host harness (anima.exe) for development and gates.

A parity gate runs every query through the WASM module and the native build and asserts byte‑identical replies — and refuses a WASM not rebuilt from the current firmware sources; a web‑contract gate pins every JSON field the chat UI reads. The "cascata WASM" isn't a port — it's literally the device's C (firmware/components/nucleo_anima), recompiled.

query → L0  intent/FAQ string match           (<1 ms, no SD, no model)   70–90% of use
        L1  binary Hamming (popcount) coarse  + int8 rerank, confidence‑gated
        L2  MOSAICO span‑stitch — verbatim, attributed (never fabricated)
        L3  optional cloud LLM — else an honest "I don't know"

• No‑FPU‑friendly: Matryoshka binary embeddings (~64 B), distance = popcount(a XOR b) — pure integer math, ideal for an MCU. int8 rerank only for the few survivors (~tens of KB/query).
• Matryoshka speculative prefetch: the 16‑dim embedding prefix prefetches the likely SD clusters on core 1 while core 0 finishes the full encode — compute overlaps slow storage.
• Evidential abstention (CRAG‑style gate): high → frozen answer, medium → stitch, low → refuse. It never hallucinates a fact it can't support. Live data (time/battery/files) always bypasses the cache.
• Neuro‑symbolic core: HDC/VSA hyperdimensional reasoning (XOR/popcount bind‑bundle) + a permutation‑KGE deductive engine (inverse/transitive/multi‑hop) + a math/physics/vector solver, with a proof‑carrying mode (NSPCG) in Forge.

The device never streams model weights. Anything heavy is offloaded to the browser: WebLLM (Qwen3‑1.7B, WebGPU) and wllama for real in‑browser LLM work (Forge), your own PC's Ollama / LM Studio for the agent and chat (reached from the browser — never through the Cardputer), ONNX Runtime Web for offline diffusion (Paint/Atelier), ffmpeg.wasm for Video Studio.

A clean‑room MACRAW Layer‑2/3 engine (nucleo_eth) over a self‑written W5500 driver — not lwIP, not Bruce source. It includes a hand‑rolled DHCP client that self‑configures with no TCP/IP stack, OUI vendor fingerprinting, and operations most firmwares lack:

Strict discipline: exactly one op at a time (start = stop‑heal‑free the previous), every active attack is consent‑gated, and the app declares NX_NET_APP so the OS reclaims ~70 KB while it runs.

Every demanding feature respects a tight set of RAM tricks, validated on hardware:

• Exclusive mode — apps reclaim ~47 KB by taking httpd + ANIMA L1 + mDNS down for their run.
• Heap‑on‑enter — big buffers allocate on entry, never in .bss (a .bss array once bricked the ADV).
• Solo boot — an RTC flag skips httpd/mDNS for a contiguous heap; each game reboots into a fresh one.
• Canvas‑free OTA — the framebuffer auto‑frees at idle so an update finds enough contiguous heap.
• Heavy‑work arbiter — one TLS session at a time (503 if busy); online ANIMA gated on block ≥ 18 KB AND free ≥ 40 KB. Plus FATFS WL‑sector‑512 (+33 KB), web‑focus screen‑off (+32 KB), and -Os/Lua‑strip size work (≈37 % flash free).

• Universal binary — one image auto‑detects the original Cardputer vs ADV (TCA8418 keymap + ES8311 codec HAL) at runtime: build once, ship to both.
• Event‑sourced bus — append‑only state deltas → observability, replay, undo; extends across ESP‑NOW peers (the swarm/CHORUS model) for shared clipboard, multiplayer and sensor mesh.
• Multi‑runtime apps — web (zero device RAM) · vm (sandboxed on‑device bytecode) · service (native C) · elf (PSRAM‑gated). Install/run without reflashing.
• OS services — capability‑scoped manifests, OTA A/B with rollback, PIN pairing + cookie auth, delta SD‑sync (never /MIR), OS‑wide live i18n in 5 languages (IT/EN/DE/ES/FR; ANIMA and its voice stay IT/EN) plus Simplified Chinese (简体中文) in the web OS, notifications, an OS‑wide mic gate and download gate (Web Locks), and a service‑worker update gate.
• Robustness gates run before any build ships:
  • a 129‑gate ANIMA regression suite that compiles the real firmware C on the PC — 0 fabrications across the hallucination stress, adversarial and metamorphic batteries;
  • about 850 unit tests;
  • about 300 browser end‑to‑end tests in real Chrome, in CI on every push;
  • a smoke run of every web app on a real Cardputer.
• Knowledge — a corpus deduplication and quality gate, and an auto‑evolving knowledge graph (Wikipedia + teacher LLM, AUG‑192 encoder).

The desktop shell is a real workstation: window snapping (drag‑to‑edge + Snap Layouts), Alt‑Tab, a global search that also asks ANIMA, an OS clipboard with history, a Notification Center (Do‑Not‑Disturb

• quiet hours), taskbar widgets (weather + device pulse + recents, all browser‑side), night light, a lock screen (Ctrl+Alt+L) and a keyboard‑shortcuts sheet — all in 6 languages (with 简体中文), all costing the Cardputer ~0 RAM.

Apps are capability‑scoped (each declares its permissions) and most cost ~0 device RAM — they are files on the SD, rendered by your browser. The registry is the single source of truth.

NucleoOS exists because the hardware is brutal. Every feature above respects these:

• RAM: ~512 KB SRAM, no PSRAM. Runtime heap ~18 KB; the real enemy is fragmentation (httpd + ANIMA L1 + workers), not CPU. Heavy data never loads on the device — it goes to the browser. Native apps allocate on‑enter and run exclusive. See docs/memory-budget.md.
• Battery: ~120 mAh — energy is a first‑class system resource; every service declares a budget.
• Storage: microSD (system in flash, content on SD).
• Recovery first: OTA updates fail without bricking (A/B partitions + rollback).

docs/              Engineering specs — one focused file each (the canonical knowledge base)
schemas/           JSON Schemas — shared contract for firmware / PC / Android
registry/          Live OS registry: installed apps, settings, file associations, app aliases
apps/<id>/www/     One folder per web app + manifest.json (.gz built alongside)
firmware/          ESP‑IDF firmware (boot, SD, registry, HTTP/WS, ANIMA C core, native apps)
  components/nucleo_app/      Native firmware apps (games, security, sensors, media, ANIMA…)
  components/nucleo_anima/    Offline NL engine (retrieval cascade, KG, reasoning)
  components/nucleo_tts/      Offline concatenative bilingual voice
  components/nucleo_*/        HAL + services: codec, httpd, ir, ble, smtp, …
web/shell/         Desktop shell PWA (windows, taskbar, Start, copilot, i18n)
tools/             Dev tooling: validators, the host harness, the device simulator, deploy/flash
tools/anima-host/  Host gates — compile the REAL firmware C and run it on the PC

Start every orientation from the relevant file under docs/*.md — it's the source of truth, one focused engineering spec per topic; prefer reading it over re‑deriving.

New here? Read the User Guide (end‑user manual), or browse the docs index for every spec grouped by topic.

Don't iterate by flashing. The host harness compiles the real ANIMA C and runs it on the PC:

npm run anima -- "what is nucleoos"   # one‑shot      npm run anima       # interactive REPL
npm run anima:gate                     # the ANIMA regression gate (must be green before any flash)
npm run validate                       # registry + manifest schema + cross‑reference check

For web/shell work, run the zero‑dependency device simulator — it mirrors the device API and serves every app, so you verify in a browser without touching hardware:

node tools/serve-shell.mjs             # http://localhost:5599

Verification matrix: npm run validate · i18n:gate · gz:check · icons:gate · gen:api:check · anima:gate · test:all · node tools/web-e2e/run.mjs (browser E2E). See docs/debugging.md.

All screenshots above are captured from this simulator running the real shell and apps.

tools/release.ps1                      # gate → build → assemble deploy/sd → SD delta‑sync → OTA
tools/release.ps1 -FirmwareOnly        # OTA the firmware only
tools/flash.ps1                        # gate → build → flash over USB (confirm only)

It's one universal binary — the same image auto‑detects the board (original Cardputer vs ADV) at runtime, so you build once and fan out. The ANIMA gate must be green before any flash (release.ps1/flash.ps1 enforce it). See docs/releasing.md.

Installed devices learn about new releases by themselves: the shell checks GitHub once a day (from the browser — the device never contacts the internet) and offers a verified one‑click update in Settings ▸ Updates. You can also Watch ▸ Custom ▸ Releases on this repo to get notified by GitHub. Design: docs/update-check.md.

NucleoOS ships tools that probe and transmit on radio and wired networks — Wi-Fi (scan, deauth, beacon, Evil Portal, PMKID / handshake capture), Bluetooth LE, Ethernet L2/L3, infrared, USB-HID (BadUSB / DuckyScript), and the FIDO security-key stack. These are provided for authorized security testing, research, and education only.

• Use them only on networks, devices, and systems you own or have explicit written permission to test.
• You alone are responsible for complying with every applicable law and regulation in your jurisdiction — including computer-misuse, unauthorized-access, interception / wiretap, privacy, and radio-spectrum rules. Active transmission (deauthentication frames, beacon / BLE floods, infrared, jamming) is restricted or outright illegal in many countries.
• Do not use NucleoOS against any network, device, or account without authorization. Unauthorized access, disruption, or interception can be a criminal offense.
• NucleoOS is provided "as is", without warranty of any kind. The authors and contributors accept no liability for any damage, loss, or legal consequence arising from its use or misuse.

By building, flashing, or running this software you accept these terms and agree to use it lawfully and ethically. If you do not agree, do not use it.

PRs welcome — see CONTRIBUTING.md (includes a short contributor agreement so the project can stay dual-licensed). Third-party components and their licenses are listed in THIRD_PARTY.md.

PolyForm Noncommercial License 1.0.0 — free for any noncommercial use (personal, study, research, hobby, non-profit, education, government).

Commercial or production use requires a paid commercial license — see COMMERCIAL.md. Want to ship NucleoOS in a product? Get in touch: [email protected].

© 2026 indecenti. All rights reserved. NucleoOS bundles third-party components under their own licenses (some copyleft) — see THIRD_PARTY.md.