CardPuter86 is an 8086 PC emulator for the M5Stack Cardputer (ESP32-S3), based on the Fake86 emulator and the ESP32TinyFake86 port.

• M5Stack Cardputer keyboard support
• ST7789 LCD output with a DSx86-style 40x16 text viewport and full-screen scaled modes
• PC speaker output through a Core 0 audio task and the Cardputer I2S speaker
• Built-in BIOS, BASIC ROM and COM program support
• Independent writable IMG storage on internal Flash and microSD
• PlatformIO build and flash workflow

Requirements:

• M5Stack Cardputer
• Python 3
• PlatformIO Core

cd ESP32/CardPuter86
pio run

The generated firmware is written to:

ESP32/CardPuter86/.pio/build/cardputer86/firmware.bin

Connect the Cardputer over USB and run:

./flash.sh

For the first installation, initialize the internal IMG partition:

./flash.sh --with-images

--with-images erases the device and reinstalls the default image partition. Normal ./flash.sh updates only the firmware and preserves imported images.

Build a complete release package without flashing hardware:

./flash.sh --package

The version comes from VERSION and can be overridden with --version X.Y.Z. Output is written under release/M5Burner/ and includes a complete 8 MB merged image, offset-named component images, m5burner.json, the flash layout, SHA-256 checksums, and a ZIP bundle.

The package includes the default internal cardputer86.img, so installing the merged image replaces the complete device Flash.

The M5Burner submission cover is available as SVG and PNG; both files are copied into every release package.

• Fn + 1 through 0: F1 through F10
• Fn + -: F11
• Fn + =: F12
• Fn + `: Esc
• Fn + Backspace: Delete
• Aa: Shift. Aa + `1234567890-= sends ~!@#$%^&*()_+.
• Ctrl, Alt: corresponding PC modifier keys
• Fn + ;, ,, ., /: PC cursor Up, Left, Down, and Right, sent directly to the emulator.
• Fn + Space: pause the emulator and open Settings
• Opt+Space: switch between the default DSx86-style text mode and scaled mode. Text mode uses a readable 6x8 cell and supports viewport scrolling; scaled mode uses a 3x5 font for text screens and scales graphics screens to the full LCD. Opt+;, Opt+,, Opt+., and Opt+/ scroll the text viewport up, left, down, and right; Opt+' returns a FIXED viewport to its top-left starting position.
• G0: unused by the emulator power manager.

The default text view uses the BSD-licensed Adafruit Classic 5x7 glyphs in 6x8 cells. The scaled text view uses Tom Thumb by Robey Pointer, released under CC0.

Text mode starts in AUTO mode and follows the last content line while keeping up to two detected bottom status rows pinned. Manual scrolling switches to FIXED mode.

Fn combinations replace their base keys, so Fn+1 sends only F1 rather than both 1 and F1.

PC Speaker audio is generated by a FreeRTOS task pinned to Core 0, then written to I2S DMA in 128-frame batches. This keeps PIT channel 2 tones independent from the display refresh path and leaves the 8086 emulator loop on the Arduino core.

The default cardputer86.img is based on the original tinyfake86-compatible system disk with the bundled games removed. It now includes CP86TEST.COM, MININASM.COM, TERM.COM, TE.COM, and Shiru's SB.COM System Beeps PC speaker musicdisk. Run CP86TEST for the all-in-one RTC, BIOS clock, disk, keyboard, PC speaker, COM1 modem, Wi-Fi modem status, and USB-mode note tests. Run TERM for direct COM1 Hayes modem interaction, TE FILE.TXT for a 40x14 nano-like tiny editor, and SB for the System Beeps PC speaker demo. SB.TXT is included on the disk for the original attribution and CC BY 3.0 license notice.

CardPuter86 exposes a lightweight Hayes-compatible modem on the emulated PC's COM1 port (3F8h). This is separate from the USB CDC mode: COM1 is visible only to DOS software inside the emulator, while USB CDC is the Cardputer's external USB serial function for the host computer.

Configure Wi-Fi from Settings with WiFi modem; enter SSID and password manually, and the credentials are stored in NVS. The modem implements a small AT command set: AT, ATI, ATE0/ATE1, ATZ, AT+WIFI?, ATDT host:port, +++, and ATH. AT+WIFI? reports status; credentials are configured from Settings rather than typed through AT commands. CP86TEST.COM includes a direct COM1 AT probe.

Disk images are regular writable .img files stored independently from the firmware. The built-in Flash image partition initially contains cardputer86.img. Images in the microSD root are also detected; legacy .dsk files remain compatible.

When more than one image is available, startup shows a boot menu. Use W/S (or the printed arrow keys) and Enter; keys 1 through 9 select directly. Without input, cardputer86.img starts after four seconds. Floppy-sized images boot as A:, while images larger than 2.88 MB boot as hard drive C:.

To import images from a computer, wait for the optional SD check and hold Ctrl when it finishes. If SD was enabled with Alt and detected, select either Internal Flash or SD Card; otherwise the internal Flash is exported automatically as a USB drive. Copy .img files to its root, safely eject it, and reboot.

Press Fn+Space while the emulator is running to pause and open Settings. The first-level Settings menu keeps high-traffic items visible: disk/IMG mounting, Wi-Fi modem setup, USB interface mode, audio enable, network COM1 enable, and Continue. Less frequent options are under More settings. USB mode is persistent: Charge only, Serial CDC, or USB disk. Serial CDC and USB disk are mutually exclusive active modes. The 512 KB memory option is stored in NVS and remains selected after power-off; when disabled or unset, the emulated PC uses the default 128 KB. In 512 KB mode, a 128 KB SRAM page cache keeps active 4 KB pages in memory while cold dirty pages are written through ESP-IDF wear levelling to a dedicated Flash partition.

More settings provides persistent approximate 8086 CPU speed profiles: 4.77 MHz, 8 MHz, 10 MHz, 12 MHz, 16 MHz, 24 MHz, 33 MHz, and Unlimited. POST no longer plays a firmware tune; audio comes from the emulated PC speaker path. The firmware explicitly keeps the ESP32-S3 host CPU at its standard 240 MHz maximum. The CPU limiter models an average of four 8086 clock cycles per emulated instruction; actual software timing remains approximate because instruction costs vary.

Power settings can set automatic sleep to 30 seconds, 2 minutes, 5 minutes, 10 minutes, or Never. The default is 2 minutes. Sleep uses ESP32-S3 light sleep with the LCD panel and backlight disabled; the firmware briefly wakes every 100 ms to scan the Cardputer keyboard matrix, and any key restores the display. G0 is not used for sleep or wake. Settings also includes a simulated RTC clock; DOS reads it through BIOS INT 1Ah, BIOS Data Area clock ticks, and the standard CMOS RTC ports 70h/71h.

ESP32/CardPuter86/data/cardputer86.img is used only by --with-images. This option resets the internal image partition, so routine firmware updates intentionally do not run uploadfs.

• 简体中文
• English
• Español

CardPuter86 uses the Fake86 emulator by Mike Chambers and is derived from the ESP32TinyFake86 project by Ackerman. Original project material remains under its respective license and attribution.

CardPuter86 is distributed under the GNU General Public License v3.0 or later. Third-party components under compatible licenses, including BSD, CC0, and LGPL code and assets, retain their original notices and terms.