It boots.

Hello, LED, splash

The entire first milestone was: print a greeting over USB, cycle the LED, show something on the screen. Zero emulator. It exposed two things immediately.

The board boot-looped on PSRAM — every guide, and our own spec, said it had 8 MB of octal PSRAM. It has none. Only the separate Plus variant does. And the greeting was losing a race: this dongle is USB-powered, so plugging it in is a cold boot, and the boot-time print happens before the host has finished enumerating. It now waits for a host and then says hello.

A filesystem, a network, a web server

LittleFS, WiFi credentials in NVS, an HTTP server answering on 8086tiny.local. Along the way, a bootloop that took real time to find: the system event task was overflowing its stack. And a lesson that shaped everything after — panic output on this board is invisible, because the panic handler writes into a USB FIFO that the reset then destroys. So we built a panic journal in no-init RAM that survives the reboot and replays into dmesg on the next boot. We would need it.

The keyboard, and a question that took nine days to answer

A WebSocket carrying video frames and XT scan codes. The user looked at the first colour test and asked: “no blue?”

No blue. CGA palette 1 is cyan, magenta and white, and the only blue a 320×200 screen can show is as the background colour. The instinct — every time — is to fix the palette until it looks nice. The rule we settled on instead: read the register, never hardcode what looks good. That rule caught a real bug five milestones later.

Forty-five instructions

The first time the 8086 core ran on hardware, it executed forty-five instructions of a bring-up ROM and halted with exactly the register values it should have. A very small number, and one of the best moments of the project.

FreeDOS — and a one-byte bug hiding behind 45,416 bytes

The PC's memory is not one flat block; it is chunks, scattered across whatever heap we could find. Which means a 16-bit write can straddle a chunk boundary. We wrote 38 host assertions for that seam, and they caught something we would never have found by running DOS:

An 8-bit write to the last byte of a chunk silently reverted the first byte of the next one. Harmless — unless something copies straight through the seam. FreeDOS relocates its own kernel with a single REP MOVSB of 45,416 bytes, right across it.

You cannot switch off memory you have already linked

FreeDOS needs 192 KB. We were 160 KB short. The obvious fix: a runtime flag to turn WiFi off and reclaim the RAM.

It cannot work, and the reason is worth internalising. net off disabled the radio, but esp_wifi, lwIP, mbedTLS and the HTTP server were still linked into the binary. Their static memory is spoken for before main() runs. A runtime flag cannot reclaim linked BSS.

And the real blocker was not free bytes at all — it was contiguity. There was enough memory; there was no single piece big enough. Dropping the chunk size from 32 KB to 8 KB is what actually booted DOS.

The idea that worked: boot the machine at build time

If DOS writes almost all of its memory, and none of it matches the disk — then stop trying to avoid the copy, and move it out of RAM entirely.

So: boot FreeDOS on a workstation, snapshot the 192 KB of memory the instant it reaches A:\>, and bake that image into the firmware's read-only data. On the dongle, the PC's RAM is memory-mapped flash. Pages become real RAM only when the guest writes to them — copy-on-write, at 1 KB granularity.

The machine now boots to a DOS prompt instantly, because it doesn't boot at all. It wakes up already booted.

Three quarters of every instruction fetch now comes from flash, and it costs nothing. The 8 KB hot working set simply lives in the CPU's instruction cache — even with WiFi competing for it. And it collapsed the project's two separate firmware builds into one: the DOS machine and the networked machine stopped being a trade-off.

CGA graphics — and the bottom three scanlines nobody could see

Two findings, and the brief was wrong about the first one. This BIOS never writes the CGA registers at all. It drives a Hercules mode register at port 0x3B8. We had been watching the wrong port.

The second was a real bug, and it had been hiding since M5. CGA video memory is 16,384 bytes, and we had mapped a 16,000-byte window — the obvious size, since the picture is 16,000 bytes. But CGA interleaves its scanlines into two banks, and scanline 199 begins at byte 16,191. Every graphics screen this machine had ever drawn was missing its bottom three odd scanlines, into open bus.

Alley Cat was never a video problem

The game had been on the floppy since before the emulator could execute a single instruction. It was the named acceptance test for a milestone about an exotic 160×100 video mode. It never ran, and we assumed the video mode was why.

It needed 54,555 bytes. DOS's free arena had 48,688. It had never loaded, not once, not for any reason to do with graphics. Trimming BUFFERS and FILES in CONFIG.SYS fixed it. And it turns out Alley Cat uses ordinary CGA mode 4 — the entire premise of the milestone was wrong.

(The 160×100 mode survived anyway, and got its revenge later. Keep reading.)

The dongle says its own name

It stopped enumerating as USB JTAG/serial debug unit and started introducing itself properly. Plug it into anything:

And then the genuinely silly part, which is also the best part. We wrote HOSTCFG.COM — a real DOS program, 1,192 bytes, sitting on the floppy — that reaches out of the emulator to configure the host it is running on.

The emulated 1981 PC can reconfigure the WiFi of the 2026 microcontroller that is dreaming it.

The cat was waiting at a menu

This one is our favourite, because the bug was never where anyone was looking.

The emulated machine has two displays, and always has — 8086tiny's own documentation says so. A text device, where the BIOS teletypes every character out through a hook (it carries no font at all, so text can never appear in the pixel framebuffer), and a pixel device, where programs write video memory. Two independent monitors, running at once.

Our browser page received the pixels. Our serial console received the text. Neither had ever received both.

So when Alley Cat started, switched to graphics, and drew nothing — we spent a long time debugging the graphics. The game was fine. It had printed this, to the monitor nobody was connected to, and was politely waiting for an answer:

The menu was never invisible. It was on the other monitor. Both streams now ride both transports, on one connection, and the cat is playable — over WiFi, or down a USB cable, with real XT scan codes, because an arrow key is not a character and never was.

The little screen joins in

And here is where that abandoned 160×100 mode gets its revenge. The dongle's LCD is 160×80. The CRTC tweak mode is 160×100. The width matches exactly — pixel for pixel, no scaling, no filtering.

The 160×100 tweak is the dongle's native resolution. It was never a curiosity. It is the mode this machine's own screen speaks.

In text mode the LCD is a front panel. The moment a program enters graphics, it becomes a monitor — automatically, driven by the mode register. The game plays on the stick itself.