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
Examples and commands
Check out more examples and commands here
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!