NucleoOS
ENITDEESFR
Install

A microcontroller that thinks it’s a workstation.

NucleoOS is an operating system for the M5Stack Cardputer. One ESP32-S3 with 512 KB of RAM and no PSRAM runs real apps on its own 240 × 135 screen — and serves a full desktop to any browser on your Wi-Fi.

Install from your browser Source on GitHub

Latest release v0.4.0Cardputer and Cardputer ADV · one universal firmware · free for noncommercial use

An M5Stack Cardputer running NucleoOS An M5Stack Cardputer running NucleoOS
Home — ANIMA always comes firstGames — 17 native titlesOffice — clock, files, notesSystem toolsSearch as you typeControl CenterSettingsSound and offline voice
Home — ANIMA always comes firstReal renders of the native interface. Browse with ← → — or with , and / as on the device.Device photo © M5Stack; the screen is a real NucleoOS render.

240 × 135 in your hand. A whole desktop in your browser.

On the Cardputer

The native interface is always there, no phone or PC needed: a smartwatch-style launcher, large type, search as you type, 1–9 row jumps in lists, games, media, sensors and the security lab.

In any browser on your Wi-Fi

Open the address the Cardputer shows and you get NucleoOS Web: real windows, a Start menu, snap layouts, Alt-Tab, drag-and-drop, a lock screen and global search.

The native launcher on the Cardputer’s 240 × 135 screen

The device serves the files. Your browser does the heavy work — never the Cardputer’s 18 KB heap.

ANIMA answers offline. When it doesn’t know, it says so.

ANIMA is the assistant built into NucleoOS. It opens apps, does math and conversions, sets reminders and answers from its own knowledge pack — with no cloud and no language model. It is built to answer only from what it knows, and to say so when it doesn’t.

  1. Youwhat is 12% of 80

    ANIMA12% of 80 = 9.6.

    L0 · percent · 95%

  2. Youconvert 10 km to miles

    ANIMA10 km = 6.21371 miles.

    L0 · convert · 96%

  3. Youopen the calculator

    ANIMAOpening calculator.

    L0 · open app · 75%

  4. Youremind me to call john tomorrow at 9

    ANIMAReminder “call john” tomorrow at 09:00.

    L0 · add event · 86%

  5. Youwhat is the capital of mars

    ANIMAI don’t know.

    no match · abstains

Real replies from the ANIMA host build (v0.4.0), with the tier and confidence it reports.

Cheap first, honest always

  1. L0

    Intent and FAQ match

    Under 1 ms, no SD access, no model. Covers 70–90% of everyday requests.

  2. L1

    Binary retrieval

    64-byte embeddings compared with popcount, then an int8 rerank — only answers above a confidence gate.

  3. L2

    Stitched, never invented

    Passages taken verbatim from the knowledge pack, with their source.

  4. L3

    Cloud, only if you allow it

    An optional online model. Otherwise ANIMA says “I don’t know.”

One brain, three runtimes, the same answer

ANIMA’s engine is written once in C. A parity test runs every query on each build and requires byte-identical replies.

  • ESP32-S3On the Cardputer, fully offline
  • Your browserThe same C, compiled to WebAssembly
  • PCThe host build the test gates run

Want a frontier model too? AI Chat and the OS-wide copilot (Ctrl/⌘ + Space) connect to Claude, Groq, Grok or Gemini straight from your browser. Your keys stay on the Cardputer’s SD card.

512 KB. No PSRAM. Every byte planned.

The Cardputer’s ESP32-S3 has 512 KB of SRAM and no external RAM. NucleoOS keeps a fixed core and gives the rest to one transport profile at a time, so only the radio you are using holds memory.

  • 80 KBBoot ROM and system data
  • 40 KBFreeRTOS and service stacks
  • 16 KBEvent bus
  • 16 KBSD card buffers
  • 14 KBDisplay (partial framebuffers)
  • 20 KBApp runtime and automation VM

Apps allocate memory when they open and free it when they close. Games reboot into a fresh heap. The web desktop costs the device almost nothing.

Design budget from docs/memory-budget.md. Figures are approximate.

Cover of 512 KILOBYTE — Storia e regole di un sistema operativo impossibile, by Nicola Sabaini

The book: 512 kilobytes

by Nicola Sabaini

Two months, told by the only witness who saw all of it: the machine that wrote the code. Nights, dead ends, devices bricked in stereo, three-kilobyte victories celebrated like championships — and the beautiful ideas someone had to kill at the right moment.

Underneath runs a second story: what happens when you can no longer buy solutions and can only think them. Seventeen rules, a graveyard of dead ideas, and a small manual on asking a machine to help you build something too big for you.

Innovation isn’t adding. It’s deciding.

Get it on Amazon

Paperback and Kindle · in Italian · ISBN 979-8171345747

What’s on it

46 web apps served from the SD card, and a native catalog that runs on the device itself. Every app declares the permissions it needs.

  • Start menu and search
    Start menu and search
  • ANIMA, answering offline in the browser
    ANIMA, answering offline in the browser
  • Paint with on-device image generation (WebGPU)
    Paint with on-device image generation (WebGPU)
  • File Commander for the SD card
    File Commander for the SD card
  • Settings Control Center with live device pulse
    Settings Control Center with live device pulse
  • Weather, fetched by your browser — never by the Cardputer
    Weather, fetched by your browser — never by the Cardputer
  • Internet radio, with a twin native app
    Internet radio, with a twin native app
  • Calendar
    Calendar
  • Code Runner with an os.* scripting API
    Code Runner with an os.* scripting API
  • Device terminal with Tab completion and history search
    Device terminal with Tab completion and history search
  • Offline transcription from the Cardputer’s microphone
    Offline transcription from the Cardputer’s microphone
  • SSH through a self-hosted bridge
    SSH through a self-hosted bridge
  • Video Studio converts films for the device
    Video Studio converts films for the device
  • Arcade — 14 retro systems, your own ROMs
    Arcade — 14 retro systems, your own ROMs

Scroll sideways for more

On the Cardputer

Assistant and voice
ANIMA chat · offline voice in Italian and English · recorder with live transcription · mic spectrum · push-to-talk keywords
Games
Pong · Snake Duel · Tank Duel · Tanks · Scorribanda · Pinball · Poker · Slots · Dice · Yahtzee · Constellations · Reactor · Sand Garden — multiplayer over ESP-NOW, no router
Emulation
Game Boy and Game Gear on our own cores, with battery-backed saves, from your own ROMs on the SD card
Media
Film player · MP3 player · internet radio · photos
Pocket instruments
Torch · bubble level · protractor · alarm · pedometer · weather · IR remote · QR · PixelFix
System
Wi-Fi · settings and themes · clock · calendar · notes · calculator · system monitor · mail · SSH terminal
Security lab
Wi-Fi, Bluetooth LE, wired Ethernet (W5500), IR and USB-HID tools — for authorized testing only

In your browser

AI
ANIMA (offline, WebAssembly) · AI Chat · ANIMA Code · Agents · OS-wide copilot
Create
Paint + Atelier · Video Studio · video and media players · radio · QR
Work
File Commander · Spreadsheet · Notepad · Calculator · Calendar · Tasks · Archive Manager · Mail · Contacts
Build
Code Runner · Terminal · SSH · System Monitor · Log Viewer · Updates
Tools
Weather · Authenticator (TOTP/HOTP) · Unit Converter · Passkeys · IR Remote
Voice
Transcription · Recorder · Voice Manager · Dictation
Play
Game Center (WebRTC) · Arcade (NES, SNES, Game Boy, GBA, Mega Drive, PC Engine) · DOSBox · Nearby

One firmware, both boards

A single universal binary detects the original Cardputer or the Cardputer ADV at boot and loads the right keyboard and audio drivers. Build once, flash either.

Cardputer
Cardputer ADV
Both boards run the same NucleoOS image. Product photos © M5Stack; the screens are real NucleoOS renders.
ChipESP32-S3FN8, dual-core Xtensa LX7 at 240 MHz
Memory512 KB SRAM, no PSRAM · 8 MB flash with two OTA slots
Screen240 × 135 TFT (ST7789V2)
Keyboard56 keys
RadiosWi-Fi 2.4 GHz · Bluetooth LE 5 · ESP-NOW
I/OMicrophone · speaker · IR transmitter · Grove port · microSD
Battery120 + 1400 mAh (original) · 1750 mAh (ADV)
ADV addsIMU (BMI270) · 3.5 mm audio out · ES8311 audio codec

Have an ESP32-P4 board with a 7″ touchscreen? That’s NucleoOS-P4, a sister edition with its own repository.

Install in three steps

You need a USB-C cable, a microSD card and Chrome or Edge on a desktop computer.

  • USB-C cable
  • microSD card, FAT32
  • Chrome or Edge, desktop

  1. Flash the firmware

    Open the web installer, plug in the Cardputer and pick its serial port. When it finishes, press reset. If anything goes wrong, you can usually just flash again. Installing a custom firmware is at your own risk.

    Open the web installer

  2. Prepare the microSD card

    Format a card as FAT32 and extract the SD package to its root — you should see /apps, /www, /system and /data. Insert it before powering on. The SD package is not firmware: it never goes into the installer.

    Download the SD package (.zip)

  3. Boot and connect

    Pick a language, join your Wi-Fi and name the device. The screen then shows an address: open it in a browser on the same network and pair with the 6-digit PIN shown on the Cardputer. No Wi-Fi? The Cardputer starts its own network, NucleoOS-xxxx, with the password on screen.

    Read the user guide

Updates

Once a day the web desktop checks GitHub from your browser — the Cardputer itself never goes online for it — and offers a verified one-click update in Settings ▸ Updates. Updates install to a second slot and roll back automatically if the new version fails to boot.

Release notes →

Manual and documentation

The manual lives on GitHub next to the code, so it always matches the release you run. It is written in English.

Frequently asked questions

Does NucleoOS work on the Cardputer ADV?

Yes. One universal firmware runs on both the original M5Stack Cardputer and the Cardputer ADV: it detects the board at boot and loads the right keyboard and audio drivers.

Is NucleoOS free?

It is free for personal use, study, research, hobby projects, education and non-profits under the PolyForm Noncommercial License 1.0.0. Commercial use needs the author’s permission.

How do I install NucleoOS on a Cardputer?

Use the web installer in Chrome or Edge on a desktop computer with a USB-C cable, then copy the SD package onto a FAT32 microSD card. There is nothing to install on your PC.

Do I need a phone, a PC or the internet to use it?

No. The native interface runs on the Cardputer by itself, and ANIMA answers offline. A browser on the same Wi-Fi adds the full desktop; the internet is only needed for online features you choose.

Which languages does NucleoOS support?

The interface is available in English, Italian, German, Spanish and French, and you can switch at any time. The offline assistant ANIMA and its voice understand Italian and English.

Where is the manual?

The user guide is on GitHub, next to the source code, so it always matches the current release. Read the user guide.

Free for noncommercial use

NucleoOS is source-available under the PolyForm Noncommercial License 1.0.0: free for personal use, study, research, hobby projects, education and non-profits.

Commercial use — in a product, a paid service or a for-profit organisation — is not covered by the free license. If that is what you have in mind, write to niki070585@gmail.com before you start.

Read the license → Legal information →

Responsible use

The security lab is for authorized testing, research and education only — on networks and devices you own or have written permission to test. Active tools ask for consent before they run, and you are responsible for complying with the law.

Read the rules →