Return to the Workbench – Building the Apple //e Replica. Phase 1.

I haven’t been able to spend time on my hobby for a while due to personal circumstances and life changes, but I’ve really wanted to get back to it. Now that I finally have some free time, I’ve decided to build an Apple //e replica using the existing NanoApple2 project as a refresher before diving back into heavy development work.

I don’t just want a messy prototype wired up on a desk. I want to build a highly accurate, fully functional Apple IIe replica for my collection. The brain is a Sipeed Tang Nano 20K FPGA doing hardware-level simulation, paired with a Sipeed M0S Dock acting as the system supervisor for the SD card and USB hosting.

Instead of a tangle of wires and separate modules, I am designing a single, custom-fabricated unified PCB that combines historical accuracy with modern conveniences. Here is a high-level look at what is going under the hood:

Keyboard: A custom 64-input matrix driven by an ATmega32U4 controller. I will be using Gateron Milky Yellow Pro linear switches to emulate the feel of vintage keyboards, topped with custom dye-sublimated DSA keycaps.
USB Routing: A passive USB 2.0 Hub integrated directly onto the board. This will wire up the internal keyboard while providing dual USB-A ports on the rear for custom external joysticks.
Audio: A PAM8302 audio amplifier driving an internal speaker and a rear headphone jack, controlled by a physical thumbwheel.
Case: 3D printed with a green power LED and red disk activity LEDs.

To keep this project manageable, I mapped out a phased roadmap to prove all the core technologies on the benchtop using off-the-shelf parts before I order the custom PCB.

Phase 1 was all about proving the core FPGA brain works. I got it done, but getting the Tang Nano 20K and the M0S Dock to talk to each other was an absolute nightmare. The goal was simple: get the FPGA running the Apple II core, use the M0S Dock to host the USB keyboard, and boot from an SD card. I triple-checked my wiring, verified the FAT32 SD card, and swapped keyboards. Nothing worked. The M0S Dock simply refused to initialise the USB port, leaving my keyboard completely dead.

My primary workstation runs Linux Mint. Because I was doing everything via a Linux VM with USB passthrough to handle the flashing, I started to suspect my toolchain was dropping packets. I decided to eliminate that variable completely. I jumped on eBay and bought a used Win 10 laptop for $130(AUD) delivered (i5, 8GB RAM, 128GB SSD). I figured having a dedicated bare-metal Windows machine is a good idea for situations like this anyway, and it’s going to make running my Cricut software much more reliable as well. I downloaded the official BL Dev Cube software recommended on the NanoApple2 repository and tried to flash the M0S Dock with it. Nothing changed. It was still completely dead.

When the official software failed, I started brute-forcing it. I tried flashing different files consecutively (like the bootloader plus the companion firmware). I tried all sorts of combinations. None of them worked. Then, I had a thought: maybe the latest repository release is just broken for this specific hardware combo.

I started scrolling down through the older releases on the project’s GitHub page. I noticed that one of the previous releases had a lot more assets attached to it. Looking closely at the file list, I spotted something – instead of just the fpga_companion_nano20k.bin file I had been fighting with, there was a file named fpga_companion_m0sdock.bin. I thought, “What? Let’s try it.”

I flashed the older bin file and applied power to the Tang Nano. Straight away, I noticed something different. An LED on the Tang Nano that had never been lit before suddenly started cycling through colours. That is something different! I pressed F12 on my attached USB keyboard, and the OSD appeared on the screen. I had done it.

I navigated the menu, mounted the Total Replay hard drive image, and booted Karateka. I just sat there enjoying the first few screens. There was no sound yet over the HDMI, but that is totally fine as I’m building a proper audio circuit with a dedicated amplifier later anyway. I turned the rig off and went to bed happy, knowing the core logic actually works and I can move to the next phase.

Because the official instructions are a bit vague, here is the exact sequence to get this hardware working together:

Prepare the SD Card: You must use a 32GB MicroSD card formatted strictly to FAT32.
Convert the Files: Download the “Total Replay” collection, which includes most of the famous games. If they are in .2MG format, you have to strip the 64-byte headers off them to turn them into raw .HDV files before the core can read them. Copy those .HDV files onto the SD card.
Flash the Correct Firmware: Do not use the latest companion release if you are using the M0S Dock. Scroll down to the older releases on the FPGA-Companion GitHub and download fpga_companion_m0sdock.bin. Flash this specific file.
Boot: Insert the SD card, plug your keyboard into the M0S Dock via a USB-C OTG adapter, and power the Tang Nano 20K. Press F12 to drop the OSD and mount the Total Replay HDD image before doing a Cold Reset. Done!

Next up is Phase 2: Keyboard Matrix Prototyping. The goal here is to wire up a small test matrix on a breadboard using an ATmega32U4 microUSB breakout board, a handful of 5-pin switches, and standard 1N4148 signal diodes. I will need to write and configure custom firmware to map these switches directly to Apple II keys, proving the M0S Dock recognizes the custom inputs before I commit to routing the PCB.

I feel excited and slightly intimidated by the coding side of it, as it has been a while since I’ve done it. I’m also ordering the PAM8302 audio amplifier module today, so it’s ready to go by the time I have the keyboard proof-of-concept finished.