BreezyBox for Cardputer & Cardputer ADV

BreezyBox for Cardputer

Cardputer, Cardputer ADV and StickS3 port of BreezyBox, a BusyBox-inspired shell and virtual terminal system for ESP32 with added features like Wi-Fi, Bluetooth keyboard support, bundled built-in apps, and an embedded Lua runtime.

Features

• Unix-like Shell: Familiar commands like ls, cat, echo, cd, pwd, cp, mv, rm, mkdir, sed, grep
• Virtual Terminals: Multiple independent terminals with hotkey switching (F1-F4)
• ANSI Colors: Full 16-color support with SGR escape sequences
• I/O Redirection: Support for >, >>, <, and pipes |
• Script Execution: Run shell scripts from files with sh
• Tab/Hint Completion: Command completion via linenoise and hint autocomplete for some command options
• History: Arrow key navigation through command history, saved to the SD card so it survives reflashing (history path, history off)
• WiFi Commands: wifi scan, wifi connect, wifi status, saved credentials
• Scrollback: Ctrl+arrow to view paged scrollback
• HTTP Server: Built-in file server with httpd
• SSH: SSH client with known-host persistence and saved host aliases
• Bluetooth keyboard support: Bluetooth keyboard scanning, pairing, reconnect, and saved target storage
• File storage: LittleFS and SD card support
• Lua: Embedded Lua runtime for scripting and lightweight GUI/TUI apps
• AI agent: claw runs an on-device agent that can read and write files, run shell commands, write Lua, and drive Grove accessories (see claw.md)
• Built-in apps: vi, plasma, termbench, wget, gzip, gunzip, ping

• Lots of extra shell utilities: See commands.md

Examples and commands

Check out more examples and commands here

• Commands
• Examples
• Lua
• claw, the AI agent

Filesystems

The shell exposes these roots:

• /root for internal LittleFS
• /sd for the SD card, when mounted

Build And Flash

Activate ESP-IDF first:

source ~/esp/esp-idf/export.sh

Cardputer and Cardputer ADV

The default cardputer build is a single auto-detecting firmware image for both Cardputer models. It detects the keyboard controller at startup, so do not build a separate cardputer-adv image.

make build
make flash PORT=/dev/cu.usbmodem1101
make monitor PORT=/dev/cu.usbmodem1101

This one image has everything: the shell, Bluetooth keyboard support, SSH, graphics, Lua, and the claw AI agent. There is no separate agent build.

To create the final install image, use:

make final-package

The resulting breezybox-firmware/build-cardputer/breezybox-cardputer.bin contains the bootloader, partition table, firmware, and LittleFS image. It is the same universal image for both Cardputer and Cardputer ADV, is compatible with Launcher, and may also be flashed directly at offset 0x0.

StickS3

make build BOARD=sticks3
make flash BOARD=sticks3 PORT=/dev/cu.usbmodemXXXX
make monitor BOARD=sticks3 PORT=/dev/cu.usbmodemXXXX

Serial Monitor

From the repo root:

make monitor PORT=/dev/cu.usbmodem1101

If idf.py monitor is running, exit with:

Ctrl-]

Lua Scripts

Starter scripts and examples for GUI and TUI based applications along with APIs are located in lua-apps. You can copy these to your SD card and run them using lua in BreezyBox.

Keyboard Notes

Cardputer modifier behavior:

• Shift: hold for uppercase
• Ctrl: control modifier
• Alt: ESC-prefix/meta
• Opt: ESC-prefix/meta

Fn navigation:

• Fn + ; = Up
• Fn + . = Down
• Fn + , = Left
• Fn + / = Right
• Fn + Backspace = Delete
• `Fn + `` = Escape

Scrollback:

• Ctrl + ; = scroll up
• Ctrl + . = scroll down

Virtual terminals:

• Ctrl + 1 = VT0
• Ctrl + 2 = VT1
• Ctrl + 3 = VT2
• Ctrl + 4 = VT3
• vt shows the active VT
• vt 0 to vt 3 switches directly

Pager controls in help and more:

• Space = next page
• Enter = next line
• q = quit

ESPClaw

claw
claw> what files are on the sd card?
claw> read /sd/claw/config.json and tell me which backend I'm using
claw> write a haiku about pocket computers to /sd/haiku.txt
claw> how much free memory does this device have?
claw> run df and summarise it
write a lua script that shows the battery percentage, save it as battery

StickS3 Input

StickS3 uses an on-screen keyboard for text entry.

• first button press opens the keyboard
• short A = previous key
• short B = next key
• short A+B = select key
• long A = previous row
• long B = next row
• long A+B = accept/send line

Special keys in the on-screen keyboard:

• ^ toggle caps
• _ space
• < backspace
• > cancel/close
• ! accept/send

Thanks

Thank you valdanylchuk for the great work on BreezyBox!

• BreezyBox
• Original inspiration BreezyDemo