TinyComputers.io (Posts about hardware)

What Routing 314 Nets Taught Me About AI-Assisted PCB Design

A.C. Jokela — Sun, 19 Apr 2026 23:00:00 GMT

This is the fourth post in a running series about designing a level-shifter shield for the Arduino Giga R1 using Claude Code and open-source command-line EDA tools. A brief map of what's come before, since the series grew past its original planned scope:

Fiverr PCB Design (\$468) — the first GigaShield, designed by a freelance contractor in KiCad. It worked for most things but broke against the Z80's tri-state bus because the auto-sensing level shifters couldn't cope with floating signals.
Redesigning a PCB with Claude Code and Open-Source EDA Tools (Part 1) — the v0.2 redesign. Replaced the TXB0108 auto-sensing shifters with SN74LVC8T245 driven shifters, generated the PCB programmatically from a Python script, autorouted, and shipped Gerbers to fabrication. (The "Part 1" in its title was meant to lead directly into a Part 2 about assembly and bring-up — but a bug derailed that plan.)
How a Pin Numbering Bug Killed a PCB — the unplanned post-mortem on why the v0.3 board didn't work. A pin-numbering convention mismatch on the dual-row headers put every signal at the wrong physical position. The fabricated board was perfect; the design was wrong.

This post is about the v0.4 respin. It is also an honest accounting of what AI-assisted PCB design actually looks like in practice: the places where the workflow is miraculous, the places where it is agonizing, and the hour-long arguments between Freerouting and pcb-rnd about whether two pieces of copper were three tenths of a millimeter apart.

If you came here looking for a triumphant "I built a PCB with AI and it just worked" story, this is not that post. If you came here looking for a nuanced report from someone who spent days on this and now has calibrated opinions about where it's worth doing, welcome.

The Setup, Briefly

For readers who haven't read the earlier posts: the GigaShield is a 155mm x 90mm PCB that sits between an Arduino Giga R1 (3.3V logic) and a RetroShield Z80 (5V logic). It has ten SN74LVC8T245PW level-shifter ICs translating 72 channels between the two voltage domains. The Giga plugs into the bottom (3.3V headers), the RetroShield plugs into the top (5V headers), and the shifters bridge the two. Our first design used TXB0108 level-shifter ICs but the autosensing signal direction did not play nicely with the Z80's tri-state signals.

The entire PCB is generated by a Python script. Not the schematic — there is no schematic. Not the layout — there is no graphical layout. The script emits a pcb-rnd board file directly: component placements, pad definitions, netlist, board outline, silkscreen text, all in text format. Running python3 build_giga_shield.py produces giga_shield.pcb in a fraction of a second. The board is then routed by Freerouting and exported to Gerbers via pcb-rnd's command-line tools.

Everything happens in the terminal. No GUIs, no mouse clicks, no "did I save the layout?" anxiety.

The v0.3 board — subject of the previous post — failed because of a subtle bug in this pipeline. The v0.4 board fixes that bug and several others I didn't know about. This post covers what it took to find and fix them.

Bug Class #1: The Kind AI Caught Easily

Before refabricating, I asked Claude Code to audit the Python generator for any additional bugs. I framed it as a careful code review with specific checkpoints: pin numbering in both the pcb-rnd and KiCad generators, SN74LVC8T245 pin mapping against the TI datasheet, critical Z80 signal routing, and component placement validation.

The audit took maybe fifteen minutes of wall-clock time — during which Claude Code read the entire codebase, cross-referenced it against the datasheet, and produced a severity-graded report. Most findings were cosmetic (stale comments, a print statement that said "1x10 header" for an 11-pin connector, harmless inconsistencies between the two build scripts). One finding was genuinely important:

H1 — Comment "default A→B" is factually wrong, and U10's pulldown produces incorrect default behavior without user intervention.

DIR=LOW per the SN74LVC8T245 datasheet means B→A (B-side drives A-side). The comment states the opposite. More importantly, U10 uses DIR for CLK, RESET, INT, NMI — signals that must flow A→B (Giga→Z80). With R10 pulling DIR_U10 to GND, U10 powers up in the B→A direction, which means the 5V Z80 side would drive the 3.3V Giga side on these control pins. Backwards and potentially damaging if the Z80 is outputting signals while the Giga is also driving those pins.

This bug is worth dwelling on, because it highlights something important about how I've been working on this project. I didn't write that code. Claude Code did, three weeks earlier, as part of the initial generator script. The wrong comment and the wrong pulldown direction were both introduced by the same LLM that later caught the mistake on audit.

That sounds like it should be embarrassing for the workflow — the tool that generates bugs is also the tool that reviews them — but I think it's actually the right shape of the argument. A single LLM pass is fallible. A single human pass is also fallible. What matters is whether the combined system catches bugs reliably before they ship. In this case, the first pass (generation) introduced a subtle error, the second pass (audit, explicitly framed as a datasheet-cross-referencing review) caught it. The human's job was to know that the second pass was worth requesting — and to recognize, when the audit report came back, which findings mattered and which were cosmetic.

This is exactly the kind of bug that a human engineer might catch on a good day and miss on a bad day. The comment and the circuit were internally consistent but both wrong. The datasheet was authoritative but three hundred pages away. Claude Code's audit didn't find it by being clever — it found it by mechanically cross-referencing every pin mapping against the datasheet, every comment against the actual behavior, with the patience of a machine that doesn't get bored.

The fix was a one-line change: swap R10 from a pulldown-to-GND to a pullup-to-+3V3. U10 now powers up in the correct direction without any firmware intervention.

I'll be transparent: the wrong direction would not have destroyed the boards immediately. The 5V CMOS outputs driving a 3.3V CMOS input is within the chips' absolute maximum ratings for short periods, especially if the Giga's pins are configured as inputs during that window. But in the steady state, with the Arduino trying to drive those pins as outputs, you'd have a lot of current flowing through ESD diodes, probably latch-up, almost certainly failure. A bug that would have cooked several \$70 Arduino Giga R1s over the life of the project.

Fifteen minutes of LLM review. One avoided burn-up. A comfortable argument for the workflow.

Bug Class #2: The Kind AI Didn't Help With At All

Then came the Freerouting clearance saga.

After the v0.4 build script was fixed, regenerated, and re-routed with Freerouting at the familiar 0.254mm trace width and 0.254mm clearance rule, I packaged up the Gerbers and uploaded them to PCBWay. Their automated DFM check failed almost immediately with a message I'd never seen before:

Failed reason: The spacing between copper traces and pads should be larger than 0.1mm.

A few hours later, a QA engineer at PCBWay followed up with a screenshot from their internal Gerber inspection tool. They had loaded the top-copper layer, zoomed into the crowded region around the level-shifter ICs, and drawn yellow arrows at eight or ten spots where traces were running uncomfortably close to pads. At one spot they'd highlighted in cyan, their measurement tool showed D=0 — literal zero distance between a trace and a pad.

The screenshot PCBWay's QA engineer sent back. Yellow arrows mark the violations. Cyan highlight shows their measurement tool reporting D=0 — a trace touching a pad that it shouldn't be touching.

This should not have been possible. Freerouting had been told to maintain 0.254mm clearance between all copper. 0.254mm is 10 mil, which is more than double PCBWay's 0.1mm minimum. If the router respected its rules, PCBWay's automated check should have sailed through.

But it hadn't.

I went through the usual debugging motions. Ran pcb-rnd's DRC on the routed board: 121 clearance violations. Opened the board in a gerber viewer: confirmed the violations were real, not artifacts. Tightened Freerouting's clearance to 0.3mm, narrowed traces to 0.2mm to give more room, added explicit clearance rules for every object-pair type (wire-pin, wire-via, smd-pin, pin-pin, and so on):

(rule
  (width 0.2)
  (clearance 0.3)
  (clearance 0.3 (type smd_smd))
  (clearance 0.3 (type smd_via))
  (clearance 0.3 (type smd_pin))
  (clearance 0.3 (type pin_pin))
  (clearance 0.3 (type pin_via))
  (clearance 0.3 (type via_via))
  (clearance 0.3 (type wire_wire))
  (clearance 0.3 (type wire_via))
  (clearance 0.3 (type wire_pin))
  (clearance 0.3 (type wire_smd))
)

Re-ran Freerouting. Ninety minutes of autorouting and optimization later, pcb-rnd's DRC still reported 121 clearance violations. Identical count. As if the clearance setting had been ignored entirely.

This went on for several iterations. I tried 0.35mm clearance. 0.4mm clearance. I made the trace narrower. I made it wider. I added explicit rules for each layer. The violation count remained 121. Freerouting's optimization phase consistently took ninety minutes and improved the design by "about 52%" each time. The DRC report was unmoved.

Claude Code was with me through all of this. It read the Freerouting log. It parsed the DRC output. It spotted the p_shape is not bounded warnings (only three occurrences, probably unrelated). It suggested hypotheses — maybe Freerouting measured clearance from via hole centers rather than copper rings, maybe the padstack path shapes were confusing the bounds calculation, maybe pcb-rnd's DRC was using a threshold different from what Freerouting was told. Each hypothesis was plausible. None of them panned out. The violation count stayed at 121.

The breakthrough came not from any clever insight but from a dumb experiment: run the DRC on the unrouted board. Zero violations. Run it after Freerouting: 121 violations. Same 121, every time. Re-route with completely different settings: still 121 violations at roughly the same coordinates.

The coordinates were the tell. The 121 "violations" weren't scattered — they were clustered at specific, consistent locations. And those locations, when I finally examined them carefully, were pin-to-trace junctions. Where a trace ended at a pad on its own net. Where the copper legitimately overlapped because they were the same electrical node.

pcb-rnd's DRC was flagging every legitimate trace-pad connection as a "shorted nets: net too close to other net" violation. Not because the nets were shorted, but because pcb-rnd's DRC algorithm didn't properly account for the fact that two pieces of copper on the same net are supposed to touch. They're supposed to be connected. That's the whole point.

All 121 "violations" were false positives. Freerouting had been maintaining 0.3mm clearance the whole time. pcb-rnd had been lying about it the whole time. And PCBWay's automated DFM had been flagging the real issue — spots where same-net connections appeared to violate clearance under their algorithm — except their tool was smart enough to usually recognize same-net connections, so it flagged only the ones where the overlap happened to look particularly bad in the Gerber rendering.

The fix, once I understood this, was to increase clearance (which I'd been doing) until the visual overlap was conservative enough that PCBWay's tool stopped complaining, and stop trusting pcb-rnd's DRC entirely. The winning configuration was 0.254mm traces with 0.3mm clearance and the explicit per-type clearance rules. PCBWay's DFM passed on that submission.

Total time spent on this: maybe six hours across two days, counting the autorouting time, the iteration loops, and the eventual diagnosis. Nothing Claude Code did made this faster. Claude Code could parse logs and suggest hypotheses as quickly as I could read them, but it couldn't see what I couldn't see. The problem wasn't in any file — it was in the interaction between three tools' different assumptions about what "clearance" means. That kind of bug lives in the interfaces, not in any single artifact. LLMs are not good at debugging interfaces they can't run.

I don't think this is a damning critique of AI-assisted workflows. But it is a calibrating one. If you're choosing between "write a Python script and fight Freerouting and pcb-rnd and PCBWay's DFM" versus "click around in KiCad for four hours," the second path has fewer interfaces to break. Graphical tools eat their own complexity internally. The CLI workflow exposes every seam.

Bug Class #3: The Kind AI Made Worse

At some point during the clearance debugging, I decided to reduce the board from 6 layers to 4 layers. Freerouting had been routing successfully on four, so paying for six was wasteful. I updated the pcb-rnd build script to emit a 4-layer stack, changed the Groups() directive to "1,c:2:3:4,s:5:6:7", regenerated, exported DSN, routed, imported, exported Gerbers.

The resulting Gerber package had five copper layers.

Not six. Not four. Five. With traces scattered across them in a way that suggested pcb-rnd, on SaveTo, had rewritten my Groups() string into something of its own invention — "6:8:1,c:2:3:5:10:11:4,s:9:7" — that created phantom layers and assigned them roles my build script hadn't intended. The gerber named intern.copper.none.12.gbr had 1,406 traces. This was not a layer I had defined.

I asked Claude Code to help me understand pcb-rnd's Groups() syntax. It gamely tried to parse the string. It offered three different interpretations, each of which would have produced a different layer stack than what pcb-rnd actually did. It couldn't fix the problem because it couldn't run pcb-rnd and observe the behavior. I couldn't fix it either, for the same reason with more forgivable excuses.

After maybe two hours of going in circles, I reverted to the original 6-layer Groups() string, re-routed, exported Gerbers (getting six copper gerbers — four with traces, two with only padstack pads), and deleted the two empty ones before zipping. PCBWay doesn't care what my source PCB file says. They fabricate what's in the Gerber bundle. If I submit four copper layers, I get a 4-layer board.

This is a pattern worth noting. Sometimes the right solution to a tool-chain problem isn't to fix the tool chain. It's to work around it. Claude Code is good at helping you solve problems correctly; it's not as good at helping you recognize that the correct solution is to stop trying to solve the problem. That's a uniquely human skill: knowing when to quit.

The Component Placement Lesson

One more story worth telling. The v0.3 design had the ten level-shifter ICs arranged as U1-U5 across the top of the board and U6-U10 stacked in a single vertical column on the right side. It looked tidy. It routed successfully on six layers. It also concentrated an enormous amount of signal traffic into a narrow vertical channel between the shifter cluster and the 2x18 headers — so narrow that Freerouting couldn't route all 308 nets on four layers without leaving some unrouted.

Claude Code flagged this the first time I tried the 4-layer route. Not by proposing a new placement — it didn't. By noting that the unrouted nets all terminated in the same congested region, and asking whether I'd considered spreading U6 through U10 into a staggered two-column layout between J9 and J10. I hadn't. The suggestion was obvious in hindsight, which is the clearest sign that it was useful. A lot of engineering is exactly this: you know the answer once someone mentions it, but no one mentions it and you don't think to ask yourself.

The new placement — U6, U8, U9 in one column closer to J9, U7 and U10 offset in another column closer to J10 — routed cleanly on four layers with 314/314 nets connected. The LLM didn't solve a geometric problem I couldn't solve. It pointed at a geometric problem I hadn't recognized as a problem. That's a different and narrower contribution than "AI designed my board," but it's also real and repeatable.

For the curious: my mental model for why the original layout was bad had been "I want them in a tidy column near the connector." The LLM's implicit mental model, derived from having read every PCB design textbook ever digitized, was "signal traffic wants to spread, not concentrate." Both are defensible. The second is more useful.

What Actually Works

Stepping back from the debugging, here is my honest breakdown of where Claude Code earned its keep on this project versus where it didn't.

Where it was essentially indispensable:

Parsing hierarchical S-expression formats. The original KiCad design from the Fiverr engineer was a .kicad_sch file with nested sheets, positional net labels, and implicit connections across hierarchical boundaries. Extracting the 72-channel signal mapping from that file would have taken me half a day by hand and maybe an hour of Python if I were patient. Claude Code did it in about twenty minutes of interactive conversation.
Generating boilerplate code with domain-specific constraints. The tssop24_element() function that produces the SN74LVC8T245PW footprint is three dozen lines of boring arithmetic — pad positions, coordinate transforms, string formatting. I asked for a pcb-rnd Element that matched the SN74LVC8T245PW footprint and got working code on the first try — Claude Code fetched the TI datasheet, read the pcb-rnd format reference, and produced the correct geometry without me having to hand it either document. I would have gotten it wrong on the first try if I'd written it by hand, because I would have flipped the B-side pin order (pins 13-24 run bottom-to-top on this package, which is easy to miss).
Cross-referencing mechanical information against specifications. The audit I mentioned earlier — reading my entire codebase and checking it against the TI datasheet — would have been tedious and error-prone to do manually. Claude Code did it reliably and caught a bug I would have shipped.
File format debugging. pcb-rnd's error messages are unhelpful by the standards of modern software. The Specctra DSN format has undocumented quirks. Gerber apertures have version-specific formatting differences. Every time I hit an error I didn't understand, Claude Code could read the file, diff it against a working example, and tell me what was different. This is LLM work at its best — bulk pattern-matching across reference material I don't have memorized.
Bridging the SSH workflow. pcb-rnd runs on Linux and I work on a Mac. Half of the pipeline was shell commands to upload files, run pcb-rnd on a remote machine, download results, and iterate. Claude Code managed that SSH shuffle cleanly across hundreds of invocations. Not a hard problem, but a tedious one. Delegating it was valuable.

Where it didn't help:

Diagnosing cross-tool interaction bugs. The 121-false-positive clearance saga was a problem that lived between three tools' different mental models. Claude Code could read each tool's output but couldn't run experiments to validate hypotheses. I had to do that myself, slowly.
Making placement decisions involving physical intuition. Claude Code helped with the U6-U10 restacking only after I'd ruled out other options. It didn't lead the design choice. For pure physical intuition — "this will be too dense," "this trace will pick up noise from this inductor," "this via is a mechanical weakness" — the LLM was helpful as a second opinion but not a primary source.
Knowing when to stop debugging and accept a workaround. When pcb-rnd's SaveTo mangled my layer stack, Claude Code happily kept trying to fix it. It took me longer than it should have to realize the fix was to not use SaveTo. LLMs are optimized for "helpfully continue the task." Human judgment is needed for "recognize the task is wrong."

The Economics

It's fair to ask whether any of this is worth it. I'll try to be honest.

Time invested in the v0.4 respin, from identifying the pin-numbering bug through submitting the second Gerber package:

Designing the fix: 2 hours (including the code audit that caught R10)
Regenerating and re-routing: ~4 hours of wall-clock time, mostly Freerouting optimization
The clearance debugging saga: ~6 hours
The layer-stack misadventure: ~2 hours
Documentation, git commits, this blog post: ~4 hours

Total: ~18 hours of my engineering time, plus a lot of Freerouting CPU-hours.

If I had paid a Fiverr freelancer to redo the design in KiCad from scratch, it would have cost about \$400 and taken about a week of wall-clock time. If I had learned KiCad properly and done the layout myself, it would have taken probably 20 to 30 hours for a 314-net 4-layer board, given I've never used KiCad's layout editor seriously. If I had used a commercial autorouter (Altium's, say), I would have paid thousands of dollars in licensing and probably spent 10 hours on the project.

The Python-and-Claude-Code workflow cost me 18 hours of engineering time and the frustration of debugging interactions between three different CLI tools. PCBWay sponsored the fabrication, so the direct cash outlay was zero on this project — but that's an artifact of the sponsorship, not the workflow. A non-sponsored hobbyist running the same pipeline would spend roughly \$50 per prototype fabrication run at PCBWay's standard rates, so two runs (v0.3 plus v0.4) would be in the ballpark of \$100 total. The boards will arrive next week.

Is that a good trade? It depends on what you value. For me, the workflow is repeatable — the next board I design will take a fraction of this effort because the tool chain is now debugged. For someone doing one PCB in their lifetime, this would be a terrible trade. For someone who plans to iterate on a design family over months or years, it's probably a good one. The upfront cost amortizes.

I don't think the right question is "AI-assisted PCB workflow yes or no." I think it's "what kind of PCB work are you doing, and does your workflow compound?" If your boards are one-offs, use KiCad. If your boards are a family that evolves over time, scripted workflows start paying for themselves around the third iteration. Add AI assistance on top and the break-even point moves earlier.

What I'd Do Differently

A few hard-won principles from this project, in case anyone tries something similar:

Validate the pipeline on a dead-simple board before using it for a real one. If I had generated a toy two-net board first, routed it, exported Gerbers, and submitted the files to PCBWay's online DFM check as a dry run, I would have caught the pin-numbering convention bug without wasting a fabrication run on v0.3. The total time for the dry run would have been maybe two hours. It would have saved a two-week turnaround — and, more importantly, not burned a sponsored fabrication run on a design that was never going to work.

Run DRC with multiple tools and compare. pcb-rnd's DRC was actively misleading on this board. If I had also run the Gerbers through a third-party tool like Gerber Viewer or through KiCad's DRC after importing, I'd have noticed the disagreement and dug into it earlier. Never trust a single tool's DRC as authoritative.

Keep PCBWay's DFM as the source of truth. Their automated check has seen more boards than any open-source DRC. It's tuned for actual manufacturability. When the open-source tools say "clean" and PCBWay says "fail," believe PCBWay.

Write test fixtures for the scripted generator. A few unit tests that verify "net X has pins Y and Z" would have caught the pin-numbering bug in the build step rather than the fabrication step. For a scripted PCB workflow, the Python code needs the same test discipline as any other production code.

Budget for LLM's failure modes. The LLM is fast and confident but can spiral into unproductive debugging loops. When a fix doesn't work on the second or third try, that's the signal to stop and think rather than let the LLM keep trying variations. Six hours on the clearance bug should have been two.

The Broader Question

There's a cultural current in software circles right now that frames AI coding assistants as either revolutionary or fraudulent. Neither frame captures what I experienced on this project.

Claude Code didn't replace my expertise. I still had to know what a level shifter is, why the Z80 tri-states its bus during IO cycles, why the annular ring on a via matters for fab yield, when a pull-up is safer than a pull-down. Without that domain knowledge, I couldn't have directed Claude Code at the right problems, and I couldn't have recognized when its suggestions were wrong.

Claude Code also didn't slow me down. The audit that caught the R10 bug was pure leverage. The file-format debugging was pure leverage. The SSH shuffle was pure leverage. The CLI workflow I'm using would not be tractable without an LLM assistant — too many file formats, too many tools, too much boilerplate. Claude Code didn't enable the workflow, but it made it something I could actually use instead of abandoning it for KiCad's GUI after the first pcb-rnd error message.

What Claude Code is, for PCB design, is a competent junior collaborator with encyclopedic memory, infinite patience, and no physical intuition. It won't design your board for you. It'll help you design your board, if you know what you're doing. That's a different and less exciting claim than the marketing suggests, but it's also a more durable one.

What's Next

The v0.4 boards are scheduled to arrive from PCBWay in a few weeks. If they work — if the Z80 actually responds to its clock, if the data bus reads are clean, if /IORQ is no longer stuck at ground — I'll write a Part 4 covering the bring-up and the test results. If they don't work, I'll write a Part 4 about whatever new bug I've introduced.

In the meantime, the Python build script, pcb-rnd source files, Gerber outputs, Arduino test sketch, and every piece of infrastructure discussed in these posts is open source:

giga-shield — Complete design files, build pipeline, and test firmware

If you're interested in scripted PCB design workflows, I'd genuinely like to hear from people who've tried similar approaches — or, more interestingly, tried and given up. The body of public literature on "I attempted this and it didn't work for me" is much smaller than on "I succeeded, here's how," and I think the former is more useful.

*Previous posts in this series: Redesigning with Claude Code (Part 1) · How a Pin Numbering Bug Killed a PCB · Fiverr PCB Design (\$468)

How a Pin Numbering Bug Killed a PCB

A.C. Jokela — Sat, 18 Apr 2026 15:00:00 GMT

The boards arrived from PCBWay in perfect condition. Black solder mask, clean silkscreen, precise drill hits. The fabrication quality was excellent — 6-layer board, 6/6 mil trace/space, HASL finish, delivered in about two weeks from order to doorstep. PCBWay's online Gerber viewer had flagged one component overlap before manufacturing (a decoupling capacitor crowding a level shifter IC), their team asked about it, and we resolved it in a single email exchange. Everything about the fabrication was smooth.

Then I plugged in the RetroShield Z80, uploaded a test sketch to the Arduino Giga R1, and nothing worked.

Not "mostly worked with some issues." Nothing. The Z80 didn't respond to its clock. The data bus read all zeros. One control signal — /IORQ — was stuck permanently LOW while the others sat HIGH. Sixteen bus cycles of silence where there should have been a Z80 booting up and fetching instructions from address 0x0000.

The board wasn't defective. PCBWay had fabricated exactly what I asked them to fabricate. The problem was that what I asked them to fabricate was wrong.

The GigaShield v0.3

For context: the GigaShield is a level-shifter shield that sits between an Arduino Giga R1 (3.3V logic) and a RetroShield Z80 (5V logic). It has ten SN74LVC8T245PW 8-channel bidirectional level translators, translating 72 signal channels between the two voltage domains. The design was covered in detail in Part 1 of this series — the short version is that the entire PCB was generated programmatically from a Python script, exported to pcb-rnd format, autorouted with Quilter.ai, and sent to PCBWay as Gerber files.

The board has twelve connectors. Ten are single-row pin headers (1xN) for the standard Arduino shield headers, the analog breakout, and a direction-control header. Two are dual-row headers (2x18) that carry the high-pin-count digital signals — Arduino digital pins 22 through 53 on one side, level-shifted to 5V on the other.

Those two dual-row headers are where the bug lives.

First Contact

The first test was simple: read the Z80's control lines with no clock running. The SN74LVC8T245 level shifters have explicit direction control (that's why I chose them over the TXB0108), so with the direction defaulting to B-to-A (5V side drives, Arduino reads), I should see the Z80's active-low control outputs all sitting HIGH — their idle state.

=== Test 3: Control inputs (active-low Z80 signals) ===
  /M1=1  /RD=1  /WR=1  /MREQ=1  /IORQ=0
  With no Z80 clock, all should read HIGH (inactive)

Four out of five correct. /IORQ reading LOW was the first clue that something was wrong, but I initially dismissed it as a possible floating pin or a pull-down issue on the RetroShield side.

The real alarm came when I tried to boot the Z80. The test sketch drives CLK, releases RESET, and captures the first 16 bus cycles:

=== Test 5: Z80 boot — first 16 bus cycles ===
  RESET released
  T00: /M1=1 /RD=1 /MREQ=1 DATA=0x00
  T01: /M1=1 /RD=1 /MREQ=1 DATA=0x00
  T02: /M1=1 /RD=1 /MREQ=1 DATA=0x00
  ...
  T15: /M1=1 /RD=1 /MREQ=1 DATA=0x00
  RESET asserted — Z80 halted

Sixteen clock cycles, and the Z80 never responded. No /M1 going low for an opcode fetch. No /MREQ for a memory request. No /RD for a read cycle. The Z80 was either not getting a clock signal, or not getting a valid RESET sequence, or both.

I checked the obvious things first. Is the 3.3V rail powered? Yes. Is the 5V rail powered? Yes. Is the direction control for U10 (the control-output shifter carrying CLK) set correctly? Yes — J11 pin 10 tied to 3.3V, which sets DIR HIGH for A-to-B (Giga drives Z80). Is the RetroShield seated properly? Yes.

Looking at the Schematic

With solder bridges ruled out and the electrical fundamentals verified, I went back to the Python build script — the single source of truth for the entire PCB design.

The board's ten single-row headers all worked. The level shifters were passing signals correctly (the control input test proved that U9 was translating). The problem was specific to the Z80 not receiving CLK and RESET, and /IORQ being stuck at ground.

All three of those signals route through the 2x18 dual-row headers: J9 (3.3V side) and J10 (5V side). I started tracing nets.

The build script generates pin headers with a function called pin_header_element. For a 2x18 header, it iterates:

for col in range(ncols):      # 0, then 1
    for row in range(rows):   # 0 through 17
        pin_num += 1

This produces column-first numbering: pins 1–18 run down column 0, pins 19–36 run down column 1.

Col 0         Col 1
Pin 1         Pin 19
Pin 2         Pin 20
Pin 3         Pin 21
...           ...
Pin 18        Pin 36

But the net arrays that assign signals to pin numbers were written in zigzag order — the standard convention for dual-row pin headers, where pin numbers alternate between columns:

Col 0         Col 1
Pin 1         Pin 2
Pin 3         Pin 4
Pin 5         Pin 6
...           ...
Pin 35        Pin 36

The J9 net array:

j9 = ['+5V', '+5V',
      'D22', 'D23', 'D24', 'D25', ...
      'D52', 'D53',
      'GND', 'GND']

This assumes zigzag: pin 3 = D22 at (col 0, row 1), pin 4 = D23 at (col 1, row 1). But the footprint generator puts pin 3 at (col 0, row 2) and pin 4 at (col 0, row 3) — same column, two rows apart instead of across from each other.

Every signal on J9 and J10 was at the wrong physical position.

The Geometry of the Bug

To understand why this specific mismatch is catastrophic, consider what happens to a few critical signals.

D52 (CLK): In the net array, D52 is at index 32 (pin 33). In zigzag, pin 33 is at (col 0, row 16) — left column, second-to-last row. In column-first, pin 33 is at (col 1, row 14) — right column, six rows higher. The RetroShield's CLK pin physically touches the pad at zigzag position (col 0, row 16), but the GigaShield routed CLK to column-first position (col 1, row 14). Different column, different row. The Z80 never sees a clock.

D53 (/IORQ): Pin 34 in zigzag is at (col 1, row 16). In column-first, pin 34 is at (col 1, row 15) — one row off. But at the zigzag (col 1, row 16) position, the column-first numbering places pin 35, which the net array assigns to GND. The RetroShield's /IORQ pin is physically sitting on a ground pad. That's why it reads LOW — it's hard-wired to ground through the PCB trace.

D38 (RESET): Pin 19 in zigzag is at (col 1, row 9). In column-first, pin 19 is at (col 1, row 0) — the very first row of the second column instead of the middle. RESET goes to a completely unrelated position.

The pattern holds for every signal on the 36-pin header. The first two pins (+5V, +5V) happen to be at matching positions for both conventions (pin 1 is always col 0 row 0, and pin 2's mismatch doesn't matter since both are power). After that, every signal diverges.

Why Nothing Caught It

This bug is invisible to every standard verification step in the PCB pipeline.

DRC (Design Rule Check): All traces meet clearance and width rules. The traces connect the correct logical pin numbers — the netlist is internally consistent. DRC validates geometry, not pin-numbering conventions.

Visual inspection: The board renders look correct. Traces run from shifter pads to header pads in clean, routed paths. You can't tell from a PNG rendering that a header pad at row 14 should be at row 16. The footprint silkscreen shows pin 1, and the rest are just a grid of identical-looking through-holes.

Quilter.ai: The autorouter takes a netlist and routes traces between named pads. It has no concept of "this pad should be at this physical position" — it just connects pad A to pad B using copper. If the pad positions are wrong in the input file, the router dutifully routes to the wrong positions.

Gerber review: PCBWay's Gerber viewer (and any standard Gerber viewer) shows copper layers, drill hits, and silkscreen. It doesn't cross-reference pad positions against any external standard. The Gerbers were valid files describing a valid board — just not the board I intended.

pcb-rnd: The PCB editor displays the board as defined. It doesn't know that a 2x18 header should use zigzag numbering. It renders what the file says.

The bug exists in the gap between two conventions: the net array assumes zigzag ordering (which is the industry standard for dual-row headers and what KiCad uses in its standard footprint library), while the footprint generator implements column-first ordering (a natural but incorrect choice when iterating for col... for row...). Both halves are internally consistent. The error is in their interaction.

The One-Line Fix

The fix is almost comically small relative to the damage:

# Before (column-first — WRONG for standard dual-row headers):
for col in range(ncols):
    for row in range(rows):
        pin_num += 1

# After (zigzag — correct):
for row in range(rows):
    for col in range(ncols):
        pin_num += 1

Swap the loop order. That's it. Row-first iteration produces zigzag numbering: pin 1 at (col 0, row 0), pin 2 at (col 1, row 0), pin 3 at (col 0, row 1), pin 4 at (col 1, row 1), and so on. This matches the KiCad convention, the IPC convention, and what every dual-row connector in the world expects.

Single-row headers (J1 through J8, J11) are unaffected because column-first and zigzag are identical when there's only one column. Only J9 and J10 — the two 2x18 headers — had the wrong pinout.

Can Software Fix It?

My first instinct was to work around the bug in firmware — remap which Arduino GPIO pins the sketch uses so that signals arrive at the correct physical positions despite the wrong traces. If the board routes D36 to where D52 should be, just use D36 for CLK in the sketch.

It doesn't work, for two reasons.

First, some signals map to power pins. D53 (/IORQ) physically sits on a GND pad. You can't drive a signal through a ground trace in software. The pad is connected to the ground plane. It's not a GPIO — it's copper bonded to zero volts.

Second, the level shifters have shared direction control. Each SN74LVC8T245 has eight channels and one DIR pin. All eight channels shift in the same direction. If you remap CLK (which needs Giga-to-Z80 direction) to go through a shifter that also carries address bus signals (which need Z80-to-Giga direction), you can't set both directions simultaneously. The shared DIR creates an unsolvable constraint when signals that need opposite directions land on the same shifter.

The board needs a respin.

The Respin

With the bug identified and the fix trivial, the path forward is straightforward:

Fix the loop order in pin_header_element
Regenerate giga_shield.pcb from the Python script
Export to DSN format via pcb-rnd
Re-route the traces
Export new Gerbers
Send to PCBWay for fabrication

The entire pipeline — from fix to fabrication-ready Gerbers — takes about twenty minutes. That's the advantage of the text-based, scriptable workflow described in Part 1. Change one line of Python, re-run the pipeline, get a new board. No GUI interactions, no manual routing, no "did I remember to update the footprint" anxiety.

The v0.3 board was originally routed on six layers because the autorouter couldn't find paths for every net with the components packed tightly together. For v0.4, we rearranged the level shifter ICs into a staggered two-column layout between the dual-row headers, giving the router more room to work with. The result: all 313 nets routed cleanly on just four layers. We're also using Freerouting for the v0.4 routing — we had initially planned to use Quilter.ai, but their recent release introduced some parsing issues that made it unreliable for our KiCad files. Freerouting's v1.9 codepath, while older, has been rock-solid for this board.

PCBWay's turnaround on prototype boards is fast — I've consistently gotten boards in under two weeks from order placement to delivery, including the original v0.1 boards from the Fiverr design. For the v0.4 respin, I'm using slighly different specs: 4-layer, 1.6mm FR-4, black solder mask, HASL finish, standard 6/6 mil trace/space. PCBWay's pricing for prototype quantities (5-10 boards) is genuinely hard to beat — and the quality has been consistently good across every order.

One thing I appreciate about PCBWay's process: the pre-production review. Before they start cutting boards, their engineering team reviews the Gerbers and flags potential issues. They caught the C29/U10 overlap on the v0.3 boards — a decoupling capacitor footprint that crowded a TSSOP-24 IC. We agreed to leave C29 unpopulated (it was one of 29 bypass caps, not critical), and PCBWay proceeded with fabrication. That kind of proactive communication saves real time and money. If I'd caught the pin numbering bug at that stage, the whole issue would have been avoided. But pin numbering convention mismatches aren't the kind of thing that shows up in a Gerber review — the files were technically correct.

What PCBWay Offers

For readers who haven't used PCBWay before, a brief overview of what they provide beyond basic PCB fabrication:

PCB Prototyping: 1 to 8 layers, multiple surface finishes (HASL, ENIG, OSP, immersion silver/tin), controlled impedance, blind/buried vias, flex and rigid-flex boards. Minimum trace/space of 3.5/3.5 mil for standard process. They handle both small prototype runs (5 boards) and production quantities.

PCB Assembly (PCBA): Full turnkey assembly with component sourcing, SMT and through-hole placement, and testing. For a board like the GigaShield with thirty-six SMD components (ten TSSOP-24 ICs, twenty-seven 0603 caps, nine 0603 resistors), assembly service eliminates the most tedious part of the build. TSSOP-24 packages are hand-solderable with a fine-tip iron and flux, but doing ten of them with twenty-four 0.65mm-pitch pins each is several hours of careful work. PCBWay's pick-and-place machines do it in minutes.

3D Printing and CNC Machining: Useful for enclosures, mounting brackets, and custom mechanical parts. Multiple materials available — PLA, resin, nylon, aluminum, steel. I haven't used these services for this project, but for projects that need a custom case or mounting hardware, having it from the same vendor simplifies ordering.

Stencil Service: Solder paste stencils for reflow soldering. If you're doing your own assembly with a hot plate or reflow oven, a properly cut stencil makes paste application dramatically faster and more consistent than syringe application.

Design-for-Manufacturing (DFM) Review: As mentioned above, PCBWay reviews your files before production and flags potential issues. This caught the C29 overlap on my boards. For someone iterating on a design — especially a design generated programmatically where visual review of the physical layout is less intuitive — this review is valuable.

The pricing model scales well: prototype quantities are cheap enough to iterate without stress (important when you're, say, debugging a pin numbering convention), and production quantities get volume discounts. The online quoting system gives you a price instantly when you upload Gerbers, so you know the cost before committing.

Lessons

Every post-mortem needs a "what did we learn" section. Here's mine.

Test with hardware before ordering quantity. If I'd breadboarded the 2x18 connection with jumper wires before committing to fabrication, I'd have caught the mismatch immediately. The single-row headers all work — I could have validated those and assumed the dual-row headers were fine. Testing the full signal path end-to-end, from Giga GPIO through the level shifter to the RetroShield's Z80, would have caught it in an hour. One of the reasons I did not breadbroad the design first is I was unable to find breadboardable SN74LVC8T245PW level shifters. I have TXB0104 Bi-Directional Level Shifters but no driven level shifter breakouts.

Convention mismatches are the hardest bugs. The code was correct by its own logic. The net arrays were correct by the KiCad convention. The footprint was correct by its own convention. The bug was in the assumption that both sides used the same convention. No single piece of code was wrong — the error was in the interface between two correct pieces. This is the class of bug that code review, static analysis, and automated testing all miss, because each component passes its own tests.

Text-based PCB design cuts both ways. The scriptable pipeline that let me generate and route a board in twenty minutes also let me ship a subtle pin-numbering bug to fabrication in twenty minutes. A graphical PCB editor would have forced me to visually place the header footprint and see the pin numbers on screen, which might have triggered a "wait, that doesn't look right" moment. The speed of automation is a liability when the automation is wrong. The counterargument is that graphical editors have their own class of invisible bugs — accidentally moved components, stray traces from mis-clicks, forgotten net connections. Text-based design doesn't eliminate bugs; it changes which bugs are likely.

Pin numbering standards exist for a reason. The IPC standard for dual-row connector numbering is zigzag. KiCad follows it. Every 2xN header footprint in every major footprint library follows it. When you write your own footprint generator, you need to follow it too. The column-first iteration (for col... for row...) is a natural coding pattern — it's how you'd iterate a 2D array in most languages. It's also wrong for connector pin numbering. Convention over intuition.

The fabrication was perfect. I want to emphasize this because it's easy to conflate "the board doesn't work" with "the board was made badly." PCBWay manufactured exactly what the Gerber files specified, with excellent quality. Every trace, via, drill hit, and solder mask opening matched the design files. The bug was in my design files, not their manufacturing process. The distinction matters: when a board comes back dead, the first question should be "is my design correct?" not "did the fab house make an error?"

The Fix in Context

This is the second failure mode for this project, and both have been instructive. The v0.1 board failed because the TXB0108 auto-sensing level shifters couldn't handle Z80 tri-state bus conditions — a component selection problem. The v0.3 board failed because of a pin numbering convention mismatch in the software that generates the PCB — a toolchain problem. Neither was a manufacturing defect. Both were design errors that passed every automated check and only surfaced when physical hardware was connected.

The v0.4 respin will fix the pin numbering and go back to PCBWay for fabrication. The turnaround time from fix to new boards is probably ten days — twenty minutes for the software pipeline, a few days for PCBWay's production, and a few days for shipping. In the meantime, the v0.3 boards are useful as physical references for component placement and as evidence that the level shifters themselves work correctly (the single-row header signals all translate properly through the SN74LVC8T245s).

The Python build script, pcb-rnd source files, Gerber outputs, and the test sketch are all open source:

giga-shield — Complete design files, build pipeline, and test firmware

What's Next

Part 2 of this series was supposed to cover assembled boards and Z80 bus captures. It will — just with v0.4 boards instead of v0.3. In the meantime, the v0.4 Gerbers are being generated and will be sent to PCBWay for the respin. The fix is one line. The lesson was worth more.

The Thing and the Endpoint: Why a Z80 Gathers a World and an API Doesn't

A.C. Jokela — Thu, 16 Apr 2026 13:00:00 GMT

A Z80 DIP-40 weighs 5.7 grams. Run Zork on it, or run Zork in a browser emulator. The bytes execute the same way. One of these is a thing. The other isn't.

That distinction has a name. Heidegger called it Das Ding, the thing. He meant it in a specific sense that has nothing to do with how we normally use the word. A thing, for him, is something that gathers a world. A wine jug gathers earth (the clay, the grape), sky (the rain that watered the vines, the sun that ripened them), the mortals who drink from it and made it, and the occasion of its use. The jug is not a container that happens to have history. The gathering is the jug's being a jug.

That sounds mystical on first read. On second read it describes something you already know. A Z80 RetroShield running CP/M and Zork at 2 a.m. on a workbench gathers a world in this specific sense. A request to an OpenAI endpoint does not, and cannot, and was deliberately designed not to. This essay is about why that difference matters, and why the people who build home labs and retro computing setups feel it even when they can't name it.

What the RetroShield Gathers

Start with the chip. The Z80 on my bench was fabricated by Zilog sometime in the late 1990s, which I know because the date code stamped on the plastic reads 9734. The silicon die underneath that plastic implements an instruction set designed in 1975 by Masatoshi Shima, the engineer who had already co-designed the Intel 4004 and 8080, and Federico Faggin, who had defected from Intel in 1974 to found Zilog. The Z80's register set inherits the 8080's. The opcode encoding is backwards-compatible with 8080 binaries. The chip in my hand is a physical artifact of a specific engineering defection.

The plastic package is a DIP-40. Two rows of twenty pins, 0.6 inches between rows, 0.1 inches pin-to-pin. When you drop it into a machined socket, the pins bind slightly before seating. That's not sloppy tolerance, it's designed in: the socket contacts have to wipe against the pin to break through the oxide layer that forms on the tin plating. Every retro computer from the TRS-80 to the ZX Spectrum to the MSX used this package.

The RetroShield is an Arduino shield. Erturk Kocalar published the original design on GitLab as open hardware. His version fits one Z80 on a 2x18 Arduino Mega bus header. Mine is a revision that fits two Z80s on the same shield, shared address and data buses, separate control signals on a supplementary header. The Gerbers were exported from pcb-rnd, a fork of the original gEDA PCB program maintained by Tibor Palinkas. The traces were placed by Freerouting, which Alfons Wirtz originally wrote on Oracle's dime, then re-released as MIT-licensed after Oracle lost interest. The board was fabricated by PCBWay in Shenzhen with a four-week turnaround. I soldered the DIP-40 sockets myself and discovered on the first power-up that every bus line was shorted to ground because the ground fill polygon's clearance cutouts hadn't fully encircled the pins in the Gerber export. Part 2 of this series is the story of finding that out.

When the chip executes, it reads an opcode. 0xDB is IN A, (n), read a byte from an I/O port. The Arduino Mega firmware intercepts that read, treats the Z80 as if it were a CPU attached to a memory-mapped terminal, and feeds bytes back. The bytes are a Z3 storyfile: Zork I, compiled in 1980 by the Dynamic Modeling Group at MIT's Laboratory for Computer Science using a language called ZIL, originally written in MDL on a PDP-10 and ported into a virtual machine that could run on any 8-bit or 16-bit home computer of the era. Infocom ported it to CP/M. CP/M ran on the Z80. The chain closes on itself.

Typing "GO NORTH" into the serial terminal produces, after a pause, the text "You are in an open field west of a big white house, with a boarded front door." That pause is not latency in any network sense. It is the Z80, at 4 MHz, running the Z-machine interpreter through thirty or so thousand clock cycles, each of which is a real transition of real silicon on real power.

That is the gathering. It is not decoration. Zilog is present. MIT is present. Kocalar is present. PCBWay is present. pcb-rnd is present. The engineers who decided in 1975 that the return instruction should be one byte are present, because the silicon they designed is still decoding that byte at 4 MHz on my bench. My own ground-fill debugging is present, because the fill polygon is gone from this revision and that absence has a history. The thing gathers.

What the Cloud Endpoint Gathers

You can play Zork in a browser. archive.org hosts a Frotz build compiled to WebAssembly. You click a link, a Z3 interpreter materializes in a JavaScript sandbox, a virtual screen renders a virtual terminal, and "GO NORTH" produces "You are in an open field west of a big white house." Bit for bit, the same bytes of output. The game is the same. The Z-machine is the same. The story file is the same.

But nothing gathers.

The browser tab is not a thing in Heidegger's sense. It is a runtime. Runtimes are designed to be interchangeable. Run the same Frotz build in Chrome, in Firefox, in Safari. Run it on a phone, on a desktop, on a Chromebook in a school. Each one produces identical output from identical input. That interchangeability is not an accident or a failure. It is the entire engineering accomplishment of the web stack. A Z-machine interpreter that only ran on one specific browser on one specific machine would be a lesser piece of software, not a greater one.

This is even clearer if the emulator is on a cloud-hosted runtime. You click a link to play-zork.com, it spawns a container in some datacenter, the container runs Frotz, the output streams back to you over HTTPS. Where is Zork running right now? Physically, electrically, in which building? You do not know. You are not meant to know. The service's value proposition depends on you not knowing. If US-East-1 fails over to US-East-2, your session survives with at most a reconnect. If Vercel goes under and the operator moves to Cloudflare Workers, your experience is identical. The gathering is suppressed by design.

The same is true at a higher level of abstraction. A call to api.openai.com/v1/chat/completions hits some cluster of H100s somewhere. Maybe in Texas. Maybe in Iowa. Maybe in Norway. The model behind the endpoint has weights, trained on hardware you will never see by engineers you will never meet. Tomorrow OpenAI might swap the backing model. Or add a 403 quota limit. Or migrate the inference stack to Blackwell. Your code does not change. That is the contract. The contract is the endpoint. The thing behind the endpoint is deliberately, structurally, invisible.

This is not a complaint. The contract is useful. A company running a Rails app wants exactly this: stable interface, invisible infrastructure, someone else's problem. But the cost of that abstraction, the thing you pay with, is the gathering. The endpoint cannot gather a world because the world behind it is required to be interchangeable with any other world that can satisfy the contract.

Heidegger's Jug

In 1950 Heidegger gave a lecture called Das Ding. He spent most of it talking about a wine jug. The essay is notoriously hard to read and almost comically literal. He describes the jug's sides, its base, its void. He distinguishes the jug from a cup and from a bottle. He asks what it means for a jug to be a jug.

His answer is that a jug is not defined by its shape, its material, or its containing function. A jug is defined by what it gathers. When wine is poured from the jug, there gathers in that pouring: the earth (the grape that grew in soil, the clay fired into the vessel), the sky (the rain, the sun), the mortals (the drinker, the potter, the host), and what he calls the divinities (the toast, the libation, the occasion that makes this pouring different from running tap water into a glass). The fourfold, he called it. Earth, sky, mortals, divinities.

The fourfold is the part of the essay that reads as mystical. Ignore the specific terminology if it grates. The structural claim underneath is simpler: a thing is a thing to the extent that it is a node in a web of presence. The jug is not just a container. The jug is a place where a whole world becomes, briefly and locally, present.

Heidegger's counter-example in a later essay is the bridge. The old bridge at Heidelberg is a thing in his sense. It gathers the two banks, the river underneath, the road that runs across it, the people who cross. The bridge is what makes those things into a coherent place. The hydroelectric plant on the Rhine, which he treats in The Question Concerning Technology, is not a thing. It is a piece of what he called the standing-reserve, Bestand. The plant converts the river into potential electrical output, on demand, interchangeable with any other kilowatt on the grid. The plant does not gather. It extracts.

This is the same distinction that separates the Z80 on my bench from the cloud-hosted Frotz emulator. The Z80 is a bridge. The cloud emulator is a power plant.

What's Actually Different

The functional output is the same. That is the central puzzle. The bytes of Zork's output are identical. The game is playable in either location. The player's subjective experience of "GO NORTH" producing a description of the open field is the same to within the tolerance of noticing.

What is different is what each running copy means, in a sense of meaning that is not about semantics but about presence.

The Z80 running Zork on my bench means: Zilog's 1975 design decisions, Infocom's 1980 implementation, Kocalar's open hardware, my four-week wait for PCBWay, my ground-fill debugging session, the specific 4 MHz crystal that drives this specific chip tonight. The game is the surface. The gathering is what makes the game this game and not an abstract instance of gameplay.

The cloud-hosted Zork means: the game. That's the whole content. The infrastructure is interchangeable by contract, the hardware is invisible by design, the history is irrelevant to the service. You play Zork. That is the product. The product is the endpoint. The endpoint is the product.

This is why people who run home labs can tell you war stories and people who use APIs cannot. "Remember the fan seizing on the P40 in July." "Remember when the ground fill shorted every bus line." "Remember the first time Forth actually loaded and we watched OK appear on the terminal." These stories are possible because the thing is specific, present, and has its own biography. "Remember that 503 from OpenAI last Tuesday" is not a story. It is a status page entry. The difference is not nostalgia or sentimentality. The difference is that one event happened to a thing and the other event happened to a contract.

The Enframing Connection

I wrote earlier about Enframing, Heidegger's term for the mode of revealing that dominates the modern technological era. Enframing, Gestell, is the stance that frames everything in advance as standing-reserve: resources on call, available on demand, interchangeable for the purpose at hand. The hydroelectric plant enframes the river as kilowatts. The modern timber industry enframes the forest as board-feet. The cloud endpoint enframes computation as a billable unit.

Enframing is not a villain in Heidegger's telling. It is not a mistake. It is a stance that reveals certain truths about things, specifically their exchangeability as resources, at the cost of concealing other truths, specifically their being as things.

The cloud endpoint is what Enframing looks like at the level of infrastructure. The GPU cluster is enframed as tokens-per-second, which are enframed as dollars-per-million-tokens, which are enframed as a line item on an invoice. That enframing is what makes the cloud economically tractable. It is also what makes the cloud unable to gather.

The Z80 on my bench resists Enframing. Not because it's old or small or personal, but because I haven't framed it that way. I haven't asked it to be interchangeable. I haven't said "give me CP/M compute on demand at the lowest price." I have said "here is this specific chip, running this specific program, in this specific session." That's not a resource request. That's a relationship with a thing.

This essay is not a sequel to Enframing the Code. It is a companion piece, addressing what Enframing costs. Enframing names the stance. This one names what falls out of view when the stance becomes total.

Why People Build

The retro computing and home lab communities do something that looks, from an economic standpoint, irrational. They spend four-week lead times and hundreds of dollars to produce hardware that they could replace with a five-minute browser session for free. They run LLMs on Tesla P40s pulled out of eBay auction lots when the equivalent API call would cost fractions of a cent. They solder DIP-40 sockets in their basements when the emulator is a click away.

You can explain this as nostalgia, and people sometimes do. You can explain it as hobby, and that's also partly right. You can explain it as skill acquisition, which is closer but still not the reason. The economic irrationality goes away the moment you stop assuming that the only value of running Zork is playing Zork.

People build because the thing gathers. The RetroShield is not just a way to run Zork. It is a way to make Infocom's 1980 engineering present in the room tonight. It is a way to put Faggin's chip design decisions into active service at 4 MHz. It is a way to hold the physical object that descends from Zilog's break with Intel, from MIT's Dynamic Modeling Group, from the whole genealogy of 8-bit personal computing, and to use that object for its intended purpose on a Tuesday evening fifty years after the design was finalized.

None of that is available through the endpoint. The endpoint is a contract for Zork. It is not a gathering of Zork's world.

The feeling that people describe when they say "running Zork on a real Z80 feels different" is not aesthetic preference. It is the presence of the gathering. Something is actually there that is not there when you run the emulator in a browser tab, and that something is not information. It is a specific thing's being a thing.

What This Predicts

A test of the claim: this framework predicts that communities will form around specific hardware and not around cloud providers, and it predicts which specific hardware will gather the most.

Communities form around the Tesla P40. Around the Raspberry Pi. Around the RetroShield. Around specific FPGA boards like the ULX3S and the Tang Nano 9K. Around the PDP-11 (still). Around the Apple IIe. Around the Amiga. Around AMD's Strix Halo in my own recent posts. The common feature: these are things with specific histories, specific constraints, specific failure modes, specific communities of use.

Communities do not form around "the API endpoint for a frontier LLM." They do not form around "managed Postgres." They do not form around "us-east-1." There are users of those things, and there are engineers who get very good at using them, but the thing itself is not a gathering point because the thing is structurally interchangeable. You can run managed Postgres on AWS or GCP or Azure. It doesn't matter. That's the value. That's also why no one has a tattoo of managed Postgres.

Within the cloud, communities do sometimes form, but they form around thing-like artifacts: specific open-source projects like Kubernetes or Postgres itself, specific hardware generations like the original A100 launch or the H200 launch, specific incidents like the us-east-1 outage of December 2021. The gathering happens when the abstraction fails or when a specific thing peeks through.

This is not a prediction that cloud computing will fail or that people will abandon it. They won't. The endpoint is too useful. The prediction is narrower: the cloud will never gather the way things gather, and people will keep building physical hardware in their basements even when it is economically irrational, because the gathering is not available any other way.

The Chip on the Bench

I started with the weight of a Z80, 5.7 grams. End there. The chip is still on my bench. It is in a socket. The socket is on a PCB. The PCB is in a Mega header. The Mega is connected to my laptop by USB. The laptop is rendering a serial terminal. The terminal is showing the Zork prompt. The prompt is waiting.

The physical object in front of me is small. It fits under my thumb. It was designed fifty years ago by an engineer who had just quit Intel. It has been sitting in a drawer for some years. Tonight it is running. Tonight a specific piece of silicon, fabricated in 1997, is decoding instructions written in 1980 by people in Cambridge, Massachusetts, to produce text that was designed to be read by someone sitting at a CRT terminal in a dorm room in 1982. That whole world is present on my bench, gathered by this chip, for as long as I keep the 4 MHz crystal running.

When I type "GO NORTH" and the text appears, I am not receiving a service. I am participating in a thing that is thinging, in Heidegger's awkward verb form. I am one of the mortals in the fourfold. Faggin is one. Shima is one. The Infocom implementers are some. Kocalar is one. PCBWay's fabrication technicians are some. We are all gathered around the chip for the duration of this session.

The API endpoint offers me none of this. The API endpoint offers me Zork. That's a different thing entirely, and most of the time it's what I want. But sometimes, on a Tuesday evening in 2026, it isn't, and the reason why has a name.

Designing a Dual Z80 RetroShield: Ground Planes, Ghost Shorts, and the Fix (Part 2)

A.C. Jokela — Mon, 06 Apr 2026 22:00:00 GMT

The assembled dual Z80 RetroShield on the bench. Two Z80 CPUs socketed, jumper wires from J2 to the Arduino Mega's free pins, ready for testing.

In Part 1, I designed a dual-Z80 RetroShield PCB entirely from the command line: two Z80 CPUs sharing an address and data bus, with independent control signals on a supplementary header. The Gerber files went to PCBWay. The boards arrived. I soldered everything up, plugged the shield into an Arduino Mega, wired jumpers from the J2 control header to the Mega's free pins, loaded a test sketch, and...

Nothing. Both Z80s appeared to be alive (the diagnostic showed bus activity after reset), but they couldn't execute a single instruction. The data bus was completely unresponsive. The SMP kernel I'd written—a 52-byte symmetric multiprocessing demo where both CPUs boot the same code, pull tasks from a shared scheduler, and sum arrays in parallel—hit its cycle limit and returned zeroes.

What followed was a multi-day debugging session that taught me more about PCB design than the entire design phase did. The root cause turned out to be a subtle interaction between pcb-rnd's ground fill polygon and its Gerber exporter. This is the story of finding it.

The Hardware

The boards came back from PCBWay with the usual four week turn around time. Clean fabrication, good silkscreen, no obvious defects on visual inspection. I soldered DIP-40 sockets for both Z80s, the 2×18 J1 bus header, the 2×6 J2 control header, and the bus activity LED. The Z80 chips dropped into their sockets with satisfying precision.

The J2 header needed jumper wires to the Arduino Mega's free pins (D0–D21). I chose a deliberate mapping based on the pin functions: D9 for CPU2's clock (Timer1 OC1A, which can generate a hardware PWM signal for a stable 4 MHz clock), D4 for RESET, D5–D6 for INT/NMI, D7–D8 for MREQ/IORQ, D10–D11 for RD/WR, and D12–D13 for BUSRQ/BUSAK. Twelve jumper wires total, plus +5V and GND.

The plan was to run a five-test validation suite: each Z80 solo (write a signature byte to a known address), shared RAM persistence (both CPUs write to different locations, verify both persist), a relay test (CPU1 computes a value, CPU2 picks it up and continues), and a loop counter (DJNZ loop to verify branch instructions work). After that, the SMP kernel.

None of it worked.

Routing traces with Freerouting.

First Contact: The Diagnostic Sketch

I backed off to a simpler diagnostic sketch to test each connection individually. It checked four things: idle state of control pins, bus activity after releasing reset, address bus bit toggling, and the BUSRQ/BUSAK handshake on CPU2.

The results were a mix of encouraging and confusing:

=== Test 1: Control Pin Idle State ===
  [FAIL] U1 MREQ (D41) idle HIGH
  [FAIL] U1 IORQ (D39) idle HIGH
  [FAIL] U1 RD   (D53) idle HIGH
  [FAIL] U1 WR   (D40) idle HIGH

=== U1: Bus Activity ===
  [PASS] MREQ went LOW (Z80 is alive)
  [PASS] RD went LOW (Z80 fetching)
  [PASS] Address bus active — first fetch address = 0x0000

Both Z80s were "alive" in the sense that they responded to clock pulses and attempted to fetch from address 0x0000 after reset. But every control signal (MREQ, IORQ, RD, WR) read LOW regardless of what the Z80 was doing. They should have been toggling between HIGH and LOW during bus cycles. LOW all the time meant either the Z80 wasn't actually driving these pins, or something else was pulling them down.

I filed this under "weird but not fatal" and pushed ahead to the SMP test. That's when things got serious.

The Bus Trace That Went Nowhere

The SMP kernel loaded into emulated memory at address 0x0000. After releasing reset, the Z80 should have fetched its first instruction (0xDB, the opcode for IN A, (n)), executed it, and proceeded through the scheduler loop. Instead, a 150-cycle bus trace showed this:

Cyc  MREQ IORQ RD WR  Addr    Data  Action
  0  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  1  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  2  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  ...
149  LOW   LOW   L  L  0x0000  0xDB  MEM RD

Every single cycle: same address, same data, same control signals. The Z80 was stuck at its reset vector, endlessly attempting to fetch the first byte and never advancing. MREQ and IORQ were LOW simultaneously on every cycle, which should never happen during normal Z80 operation—they're mutually exclusive signals.

The Z80 was putting 0x0000 on the address bus (correct for a reset vector fetch), and I was driving 0xDB on the data bus (the correct opcode). But the Z80 wasn't reading it. Or rather, it was reading something else.

The Data Bus Loopback Test

I added a simple test: with the Z80 held in reset (outputs tri-stated), drive patterns on the data bus and read them back. If the Arduino writes 0xFF to PORTL and reads back 0xFF from PINL, the data bus is clean. If it reads back something else, there's a short or broken trace.

--- Data Bus Drive Test ---
  bit0(D49)  wrote 0x01 read 0x01 OK
  bit1(D48)  wrote 0x02 read 0x02 OK
  bit2(D47)  wrote 0x04 read 0x04 OK
  bit3(D46)  wrote 0x08 read 0x08 OK
  bit4(D45)  wrote 0x10 read 0x10 OK
  bit5(D44)  wrote 0x20 read 0x00 FAIL
  bit6(D43)  wrote 0x40 read 0x00 FAIL
  bit7(D42)  wrote 0x80 read 0x80 OK

Bits 5 and 6 were stuck LOW. The Arduino's GPIO pins couldn't drive them HIGH—something on the board was pulling those lines to ground with enough strength to overpower the Mega's output drivers.

This explained why the Z80 couldn't execute. When I drove 0xDB (IN A, (n)) on the data bus, the Z80 actually saw 0x9B (bits 5 and 6 forced low), which decodes as SBC A, E—a completely different instruction. The Z80 was faithfully executing garbage.

Isolating the Short

Systematic isolation. First question: is it the Arduino or the board?

I pulled the RetroShield off the Mega and ran the same loopback test with the shield disconnected. Every bit passed perfectly. The Arduino's PORTL pins (D42–D49) could drive any pattern and read it back correctly. The problem was definitively on the board.

Second question: is it CPU1 or CPU2? The two Z80s share the address and data bus, so a fault on either side would affect both. I disconnected J2's +5V jumper to deprive CPU2 of power, leaving its outputs floating. Same result—bits 5 and 6 still stuck LOW. So CPU2 wasn't the culprit. The short was in CPU1's territory.

Third question: is it the Z80 chip or the PCB? I pulled U1 from its socket. Bits 5 and 6 still stuck. Pulled U2 as well (since it shares the bus traces even without power). Both chips out, empty sockets, and the shorts persisted.

Then I ran a comprehensive pin test with both Z80 chips removed—just the bare PCB with sockets:

--- Data Bus (PORTL) ---
  [SHORT] D0/bit0 (D49/PL0)
  [SHORT] D1/bit1 (D48/PL1)
  [SHORT] D2/bit2 (D47/PL2)
  [SHORT] D3/bit3 (D46/PL3)
  [SHORT] D4/bit4 (D45/PL4)
  [SHORT] D5/bit5 (D44/PL5)
  [SHORT] D6/bit6 (D43/PL6)
  [SHORT] D7/bit7 (D42/PL7)

--- Address Bus ---
  [SHORT] A0 through A15 — all 16 lines

--- U1 Control Pins ---
  [OK] MREQ, IORQ, RD, WR, RESET, INT, NMI, CLK — all 8 fine

Every single data line. Every single address line. All 24 shorted to ground. But all 8 control signals were clean.

This wasn't random solder bridges. The pattern was too systematic: every line that belonged to the shared bus (connected to both U1 and U2) was shorted, while every line that connected to only one Z80 was fine. Something structural was wrong with the PCB.

The Ground Fill

I went back to the PCB design files. The original RetroShield design included a copper fill polygon on the bottom layer—a ground plane covering roughly the left half of the board (x = 0.3mm to 55.6mm, y = 0.3mm to 53.1mm). This is standard practice: ground planes reduce noise, improve signal integrity, and provide a low-impedance return path for high-frequency signals.

The polygon had a clearpoly flag, which tells pcb-rnd to maintain clearance around pins that aren't connected to the fill. Each Z80 through-hole pin specified 0.762mm clearance. The fill should have maintained that gap around every signal pin, connecting only to GND pins (via thermal relief pads) and leaving all data and address pins isolated.

I also found some design-level flag errors. U1 pin 1 (A11, an address line) had a thermal(0X) flag—explicitly telling pcb-rnd to connect this signal pin to a copper fill on the top layer. Several +5V pins had connected flags. These were wrong, though in pcb-rnd's net-aware polygon system, they turned out to be harmless (a connected flag only connects a pin to a fill on the same net, so +5V pins wouldn't connect to a GND fill). I fixed them anyway.

But fixing the flags didn't solve the short. The 24 bus lines were still shorted to ground with both chips removed. The problem was deeper.

The Gerber Analysis

I dug into the actual Gerber output for the bottom copper layer. In Gerber format, ground fill clearances are typically achieved either through layer polarity commands (%LPC*% to switch to "clear" mode and punch out holes) or by drawing the fill as a region with the clearance areas built into its outline.

pcb-rnd uses the region approach. The fill polygon gets exported as a complex region (G36/G37 block) whose boundary weaves around each pin, creating clearance cutouts. Or at least, that's what it's supposed to do.

I wrote a script to analyze the region vertices near U1's pins. For pin 9 (D5, a signal pin that should have full clearance), this is what the Gerber contained:

# U1-9(D5) SIGNAL at Gerber(120000,120000)
# Region 20: 5 vertices within 2.54mm
#   (120000,116587) dist=0.87mm angle=-90°
#   (121413,128587) dist=2.21mm angle=81°

Five vertices. Two distinct positions. A proper circular clearance cutout around a through-hole pin needs 8 to 16 vertices distributed at various angles to approximate the circle. This had vertices at just two angles: -90° and 81°. The polygon boundary was making a shallow notch past the pin, not encircling it.

Even worse: the closest vertex was only 0.87mm from the pin center. The pad edge is at 0.762mm (half of the 1.524mm pad diameter). That left 0.108mm of clearance—about 4.3 mil—on the side where the boundary came closest. Manufacturing tolerance at PCBWay is typically 4-6 mil. The clearance was right at the edge, and on other sides of the pin, there was no clearance at all because the polygon boundary didn't go around.

For comparison, U1 pin 29 (GND, which should connect to the fill) had a vertex at exactly 0.00mm distance. The fill went right through it. Correct.

The Root Cause

pcb-rnd's Gerber exporter was generating incomplete clearance cutouts in the ground fill polygon around through-hole pins. Instead of tracing a complete circle around each pin (maintaining the specified 0.762mm clearance on all sides), it was generating partial notches that only cleared the pin on one or two sides. On the remaining sides, the ground fill copper made direct contact with the pin pad.

This affected every through-hole pin inside the polygon's boundary: all of U1's pins, all of J1's pins, and most of the vias. The pattern now made sense. The ground fill polygon covered x = 0.3mm to 55.6mm—the left side of the board. U1 (at x = 30.48mm) was squarely inside. U2 (at x = 66.0mm) was outside. All 24 bus lines pass through U1's footprint. All 8 control lines connect only to one Z80 and route through traces, not through-hole pads, in the fill area.

The reason the initial diagnostic showed control signals as "OK" while bus lines were "SHORT" was purely geometric: the control signal traces exited the fill area quickly and reached the Arduino pins via the top copper layer, while the bus lines had through-hole pads sitting directly in the fill.

It's worth noting that this bug is specific to the combination of pcb-rnd's polygon fill, through-hole pins, and Gerber export. SMD pads weren't affected (no SMD components were inside the fill area). The clearance math in pcb-rnd's internal representation appeared correct, but the translation to Gerber region vertices lost fidelity, producing polygon outlines that didn't fully encircle the pins.

The Fix

I removed the ground fill polygon entirely.

# Find and remove the Polygon block in Layer 2 (bottom)
# Strategy: parse through the file, skip everything
# between 'Polygon("clearpoly")' and its closing ')'

The board's GND connectivity doesn't depend on the fill. The autorouter (Freerouting) had already placed explicit copper traces connecting all GND pins. The fill was adding copper density and potentially improving signal integrity, but neither matters for a board running Z80s at 4 MHz. At these speeds, the electrical benefit of a ground plane is negligible, and the manufacturing risk (as we discovered) is real.

I also cleaned up the erroneous flags while I was in there:

Removed thermal(0X) from U1 pin 1 (A11 should not connect to any fill)
Removed connected from all +5V pins (J1-1, J1-36, U1-11, U1-24, U1-25, U2-11, U2-24, U2-25)
Removed thermal/connected from all 11 vias (signal vias should get clearance, not connection)
Left thermal flags only on GND pins: J1-18, J1-19, and U1-29

The bottom copper Gerber went from 46KB (fill + traces) to 16KB (traces only). The region block count dropped from 26 to 5. Regenerated the Excellon drill file, rebuilt the production zip with BOM and centroid, and pushed everything to the repository.

Was This Always Broken?

A natural question: is this a flaw in the original RetroShield Z80 design, or something we introduced? The ground fill polygon, the thermal(0X) flag on U1 pin 1, and all the connected flags exist in Erturk Kocalar's upstream design — identical to our initial commit. We didn't add any of them. So why does the original RetroShield work?

To find out, I ran the original, unmodified kz80.pcb through the same pcb-rnd Gerber exporter and performed the same vertex analysis on the output. The results were revealing:

Pin	Our Board (re-routed)	Original Board (original traces)
U1-9 (D5, signal)	5 vertices, closest 0.87mm from center	75 vertices, closest 1.14mm from center
U1-10 (D6, signal)	similar	169 vertices, closest 1.14mm
U1-29 (GND)	vertex at 0.00mm (correct)	vertices at 0.76mm (thermal spokes, correct)

The original board, exported through the same pcb-rnd Gerber exporter, gets proper circular clearance cutouts with 75+ vertices distributed around each signal pin at a safe 1.14mm from center (0.38mm clearance from pad edge). Our re-routed board gets 5 vertices at only 0.87mm from center (0.11mm clearance — below manufacturing tolerance).

The difference is the trace geometry. The original RetroShield's traces were routed with classic gEDA/pcb. When we added the second Z80, we stripped all traces and autorouted from scratch with Freerouting. The new trace layout changed how pcb-rnd's polygon fill algorithm tessellated the clearance boundaries. With different traces running through the fill area, the polygon's outline took different paths around the pins — and those paths didn't maintain adequate clearance.

So the design flaw (wrong flags, a ground fill with tight clearance margins) was always latent in the original design. But it only manifested as physical shorts when the trace geometry changed. The original routing happened to produce geometry that pcb-rnd's exporter handled gracefully. Our autorouted traces didn't. It's the kind of bug that lies dormant until you touch something seemingly unrelated.

This is why removing the polygon entirely was the right fix. It doesn't matter how the traces are routed if there's no fill to create clearance problems against. The GND connectivity is fully handled by explicit routed traces.

Verification

To confirm the fix, I verified the new Gerber output:

No layer polarity commands (no fill, no clearance needed)
No large region blocks (no polygon fill)
Only trace geometry and pad flashes remain on the bottom copper layer
Bottom copper file size reduced by 65% (46KB → 16KB)

The new production files have been submitted to PCBWay for a second fabrication run. The fix is structural: without the fill polygon, there's nothing to short to. Every GND connection is an explicit routed trace, visible in the Gerber, and verifiable by inspection.

The corrected Rev C board: 553 traces, 25 vias, no ground fill polygon. Clean explicit routing for all 48 nets.

What I Learned

Ground fills aren't free. They improve signal integrity on high-speed boards, but on a 4 MHz Z80, the benefit is marginal. The cost is an additional failure mode: if the clearance generation is buggy, incomplete, or at the edge of manufacturing tolerance, the fill becomes a liability. For simple retro computing boards, explicit GND traces are more predictable.

Autorouting can break things you didn't touch. The ground fill polygon wasn't something we modified. But by re-routing the traces (which we had to do after adding the second Z80), we changed the geometry that the polygon fill algorithm used to compute clearances. A latent design flaw became an active one. When you re-route a board with copper fills, you need to re-verify the fills, not just the traces.

Test the bare PCB before populating it. If I'd run a continuity test between the Z80 socket pads and GND before soldering anything, I'd have caught this immediately. Instead, I spent time debugging firmware, suspecting timing issues, and questioning my understanding of Z80 bus cycles. The problem was never software.

The Gerber is the contract. The PCB design tool's internal representation doesn't matter; only the Gerber output does. Even if pcb-rnd's polygon clearance looks correct on screen, the Gerber export is what the fab house uses. Verify the Gerber, not the design file. A Gerber viewer would have shown the incomplete clearances immediately.

Diagnostic sketches are invaluable. Writing targeted Arduino sketches that tested individual pins, drove patterns, and reported results over serial turned a "nothing works" situation into a systematic narrowing process. The data bus loopback test (drive a byte, read it back, compare) is trivially simple and would have caught this on day one.

AI-assisted debugging works the same way AI-assisted design works. I brought the domain knowledge (how Z80 bus signals work, what the control signal timing should look like, what "stuck LOW" means electrically) and the AI handled the tedious parts: writing diagnostic firmware, parsing Gerber files, analyzing polygon vertices, checking coordinate math. The same division of labor that made the design possible also made the debugging possible.

Solder bridges are a red herring when the pattern is systematic. Early on, I found and fixed a solder bridge between two adjacent pins. It didn't help. When two pins are bridged, you get two bad signals. When 24 pins are all shorted to the same rail, the cause is structural, not incidental. I should have recognized the pattern sooner and stopped looking at individual joints.

Open-source hardware needs open-source verification. The entire reason I could diagnose this was that every file in the chain—PCB source, Gerber output, Excellon drill files—was text-based, parseable, and inspectable. I wrote Python scripts to analyze the Gerber's region vertices and measure distances to pin centers. Try doing that with a proprietary board file. The text-based EDA workflow that made the design possible also made the debugging possible.

What's Next

The corrected boards are in fabrication. When they arrive, Part 3 will cover what this project was always about: bringing up the SMP kernel, watching two Z80 processors boot the same code, identify themselves, and divide work across a shared memory bus. The kernel is 52 bytes. The scheduler is in the Arduino. The demo sums an array split across both CPUs and measures the speedup.

Both Z80s are confirmed alive. They just need a board that doesn't short their bus to ground.

The complete source—PCB files, Gerber production package, diagnostic sketches, SMP kernel, and wiring guide—is on GitHub.

The Split Isn't Between People, It's Between Tasks

A.C. Jokela — Thu, 19 Mar 2026 13:00:00 GMT

Les Orchard's "Grief and the AI Split" identifies something real. AI tools have revealed a division among developers that was previously invisible, because before these tools existed, everyone followed the same workflow regardless of motivation. Now the motivations are exposed. Some developers grieve the loss of hand-crafted code as a practice with inherent value. Others see the same tools and feel relief: the tedious parts are handled, the interesting parts remain. Orchard frames this as a split between people. Craft-oriented developers on one side, results-oriented developers on the other.

He's right that the split exists, and the piece clearly resonated with software creators because it names something people have been feeling but couldn't articulate. The observation is sharp. Where I think it can be extended is in where the line falls.

Orchard draws the line between people. I think it falls between tasks. The same person crosses that line dozens of times a day, moving between work that demands human judgment and work that doesn't, between moments where the craft concentrates and moments where it was never present in the first place. The split is real. It's just not an identity.

The Kernel I Didn't Write

JokelaOS is a bare-metal x86 kernel: 2,000 lines of C and NASM assembly, booting from a Multiboot header through GDT (Global Descriptor Table, which defines memory segments and access rights) and IDT (Interrupt Descriptor Table, which maps interrupt vectors to service routines) setup, paging, preemptive multitasking with Ring 3 isolation, a network stack that responds to pings, and an interactive shell. No forks. No libc. Every memcpy, every printf, every byte-order conversion written from scratch.

I didn't write most of it. Claude did.

In Orchard's framework, this should place me firmly in the "results" camp. I used AI to produce 2,000 lines of systems code; clearly I care about the outcome, not the process. But that framing misses what actually happened during the project.

The decisions that made JokelaOS work were not typing decisions. They were sequencing decisions: bring up serial output first, because without it you have no diagnostics for anything that follows. Initialize the GDT before the IDT, because interrupt handlers need valid segment selectors. Get the bump allocator working before the PMM (Physical Memory Manager), because page tables need permanent allocations before you can manage dynamic ones. These choices come from understanding how x86 protected mode actually works, which subsystems depend on which, and what the failure modes look like when you get the order wrong.

Claude generated the GDT setup code. I decided what the GDT entries should be, caught the access byte errors, and debugged the triple faults when segment selectors were wrong. Claude wrote the process scheduler. I determined that the TSS (Task State Segment, which tells the CPU where to find the kernel stack when switching privilege levels) needed updating on every context switch and diagnosed the General Protection Faults that occurred when it wasn't. Claude produced the RTL8139 network driver. I decided to bring up ARP before ICMP, caught a byte-order bug in the IP checksum, and validated that the packets leaving QEMU were actually well-formed.

The typing was delegated. The architecture, the sequencing, the diagnosis, the validation: those were mine. If you asked me whether JokelaOS involved craft, I would say yes, more than most projects I've done. If you asked me where the craft was, I would not point at any line of code.

The Board That Failed Twice

The Giga Shield tells a longer version of the same story, and it's messier, because hardware involves the physical world in a way that software doesn't.

The project started with a $468 Fiverr commission. I gave a designer in Kenya the spec documents, the components I thought should be used, and the form factor requirements: an Arduino Giga R1 shield with bidirectional level shifters, 72 channels of 3.3V-to-5V translation, KiCad deliverables. He produced a clean design. Nine TXB0108PW auto-sensing translators on a two-layer board. PCBWay fabricated it. Professional work, quick turnaround, and PCBWay sponsored the fabrication.

Then I plugged in the RetroShield Z80 and the board was blind.

The TXB0108 detects signal direction automatically by sensing which side is driving. For most applications, that's a feature. For a Z80 bus interface, it's fatal. During bus cycles, the Z80 tri-states its address and data lines. The pins go high-impedance: not high, not low, floating. The TXB0108 can't determine direction from a floating signal. It guesses wrong, and the Arduino reads garbage. I'd paid $468 for a board that couldn't see half of what the processor was doing.

Nobody caught this in the design phase. Not the Fiverr designer, who was working from the spec I gave him. Not me, when I reviewed the schematic. The TXB0108 datasheet doesn't scream "incompatible with tri-state buses"; you have to understand what tri-stating means in practice and recognize that auto-sensing can't handle it. That understanding came from plugging the board in and watching it fail.

The redesign used Claude to replace all nine auto-sensing translators with SN74LVC8T245 driven level shifters. Driven shifters have an explicit direction pin: you tell them which way to translate, and they do it regardless of whether the signal is being actively driven. Claude wrote Python scripts that pulled apart the KiCad schematic files, extracted all 72 signal mappings across 9 ICs, and generated new board files with the correct components and pin assignments.

I was about to submit the revised design to PCBWay when I realized we needed a tenth level shifter. The original nine covered not just the digital pins that map to the Z80 RetroShield but all of the analog pins on the Giga, giving complete 3.3V-to-5V coverage across the board. But with driven shifters, each IC has a single direction pin controlling all eight channels. Signals that need to travel in opposite directions at different times can't share an IC without creating bus contention. Some of the channel assignments had conflicting direction requirements, and the only fix was a tenth IC to separate them.

Adding one more TSSOP-24 package to an already dense two-layer board broke the trace routing. The board that had been routable with nine ICs was unroutable with ten. Moving to four layers helped but still left two to four traces with no viable path. The solution was a six-layer stackup, which needed a copper pour layer to act as a common ground plane. The open-source autorouter Freerouting couldn't handle a full copper pour; its architecture has no concept of flood-fill connectivity. So I used Quilter.ai, an AI trace router, to route the six-layer board with the ground plane that the open-source tooling couldn't represent.

Count the layers of delegation and intervention in this project. I delegated the initial design to a human professional. Physics revealed the flaw. I delegated the redesign to an AI. I caught the missing tenth shifter before it went to fabrication. I delegated the trace routing to another AI. PCBWay is currently manufacturing these boards. At every stage, the work alternated between labor that could be delegated and judgment that couldn't. The Fiverr designer did skilled labor. Claude did skilled labor. Quilter.ai did skilled labor. The craft was never in the labor. It was in knowing when the labor was wrong.

Where the Craft Actually Lives

Both of these projects point at the same thing. The craft isn't in the typing, the routing, or the code generation. It's in a layer that sits above and around all of that: the judgment layer.

The judgment layer is where you decide what to build next. Where you recognize that the output is wrong before you can articulate why. Where you sequence subsystems based on dependency chains that aren't documented anywhere. Where you plug a board in and notice that the readings don't make sense. Where you catch a missing component that the AI, the designer, and the autorouter all missed because none of them were thinking about the problem at that level.

This layer has specific properties. It requires contact with the problem domain, not just the code or the schematic but the actual behavior of the system under real conditions. It depends on accumulated experience: understanding what tri-stating means in practice, knowing that x86 protected mode has forty years of backward-compatible traps waiting for you. And it's the part that AI is worst at, precisely because it requires grounding in physical or logical reality that language models don't have access to.

The TXB0108 failure is the clearest example. The information needed to predict this failure existed in the datasheets. But recognizing its relevance required understanding what a Z80 bus cycle actually looks like at the electrical level, which required either experience with the hardware or a simulation environment that nobody had set up. No amount of language model capability substitutes for plugging in the board and watching it fail.

The Same Person in Both Modes

Orchard describes himself as results-oriented. He learned programming languages as "a means to an end" and gravitated toward AI tools because they let him focus on the outcome. He acknowledges that craft-oriented developers experience genuine loss. His framing is empathetic, but it still draws the line between people.

The line doesn't hold, because I'm both of his archetypes depending on the hour.

On Tuesday I might use Claude to generate a hundred lines of systemd service configuration because I need Ollama running on a machine and I don't care about the elegance of the unit file. On Wednesday I might spend three hours hand-debugging why rocm-smi reports GPU utilization at zero percent: reading kernel logs, checking DKMS module versions, testing HSA_OVERRIDE_GFX_VERSION values, loading the amdgpu module manually because it didn't auto-load at boot. The first task is pure delegation. The second is pure craft. Both are mine. Both happened this week.

When I wrote the economics piece, I used Claude to draft sections and I measured real power draw with nvidia-smi and rocm-smi at 500-millisecond intervals. I let AI handle the prose scaffolding and I personally caught that Ollama on the Strix Halo had been running entirely on CPU because the systemd service file was missing an environment variable. Every benchmark I'd trusted before finding that bug was wrong. No AI caught it. I caught it because the numbers felt off.

These aren't different people. They're different tasks. The identity framing ("I'm a craft developer" or "I'm a results developer") obscures what's actually a task-level decision that experienced people make constantly: this piece of work benefits from my full attention; this piece doesn't.

What the Grief Is About

The craft-grief that Orchard describes is real and worth taking seriously. Part of it targets the wrong thing. Part of it doesn't.

What's being mourned is typing as the bottleneck. For forty years, the primary constraint on software projects was the speed at which a human could produce correct code. Design mattered, architecture mattered, but someone still had to sit down and type it. The typing was slow enough that it forced a certain kind of attention. You couldn't write a function without thinking about it, because writing it took long enough that thinking was unavoidable. The bottleneck created the conditions for craft, and it felt like the craft itself.

AI removes the bottleneck. Code appears in seconds. The thinking isn't forced by the typing anymore; it has to be deliberate. And that shift feels like a loss, because the rhythm of the work has changed. The long, meditative stretches of writing code, where your understanding deepened as your fingers moved, are replaced by short bursts of generation followed by review. The texture is different.

But the craft didn't live in the texture. It lived in the judgment that the texture incidentally supported. The experienced developer who hand-writes a function isn't doing craft because the typing is slow. The typing is slow, and the craft happens during the slowness, but the craft is the decisions: what to name things, what to abstract, what edge cases to handle, when to stop. Those decisions haven't gotten easier. If anything, they've gotten harder, because AI lets you attempt projects that would have been too large to type by hand, which means you hit the judgment bottleneck more often and at higher stakes.

JokelaOS would have taken me months to type by hand. I probably wouldn't have attempted it. With AI handling the code generation, I attempted it in days and spent the entire time making architecture and debugging decisions. The project had more craft in it than most things I've built, precisely because the typing wasn't the bottleneck. The judgment was.

The Biological Ceiling

I wrote in the AI Vampire piece that human judgment is the binding constraint in a Jevons cycle operating on cognitive output. AI makes the labor cheaper; demand expands; the expansion concentrates on the one input that can't scale: human attention and judgment. The three-to-four-hour ceiling on deep work is biological, not cultural, and no amount of productivity tooling changes it.

The task-level split is where this plays out in practice. AI compresses the labor side of every project: the code generation, the trace routing, the prose drafting, the schematic extraction. What remains is denser, harder, and more consequential. Every hour of work has a higher ratio of judgment to labor than it did before AI. That's why Yegge's developers feel burned out, not because they're working more hours, but because every hour is now a judgment hour.

The craft isn't disappearing. It's being compressed into a smaller, denser layer. The typing is gone. The design reviews are shorter. The code appears instantly. What's left is the part that was always the actual craft: deciding what to build, recognizing when it's wrong, knowing what to test, catching the missing tenth level shifter. That layer is entirely human, it's harder than it used to be because the projects are bigger, and it's the only part that matters.

Orchard identified the split correctly. The grief is real, the division is real, and the piece resonated because it named something that software creators recognized immediately. The refinement I'd offer is that the line doesn't separate two kinds of people; it separates two kinds of tasks. The craft was never in the code. It was in the decisions that surrounded the code. Those decisions haven't gone anywhere. They've just lost the slow, meditative typing that used to accompany them. What remains is craft at higher concentration, with no filler.

There was something cathartic about the old way. The hours of typing weren't just production; they were a complete experience. You conceived the idea, worked through the logic, typed every character, fought the compiler, and watched it run. The whole arc from intention to execution passed through your hands. That totality had a satisfaction to it that reviewing AI-generated output doesn't replicate, even when the output is correct.

And there was something else: the syntax was a sacred tongue. Not everyone could read it. Not everyone could write it. The curly braces, the pointer arithmetic, the register mnemonics formed a language that belonged to the people who had invested years learning to speak it. That exclusivity wasn't gatekeeping for its own sake; it was the mark of hard-won fluency, and it meant something to the people who had it. Now anyone can describe what they want in English and get working code back. The priesthood dissolved overnight.

I feel that loss. I still create. I still orchestrate. I still catch the errors that the tools miss. But I no longer speak a language that most people can't. The judgment layer is real, and it's where the work that matters happens. But it doesn't carry the same weight as mastery of a difficult notation. Orchestrating a process is not the same as performing it, even if the orchestration requires more skill.

The grief is real. It's not about the wrong thing. It's about something that actually disappeared.

The Mathematics of PCB Trace Routing

A.C. Jokela — Sun, 15 Mar 2026 16:00:00 GMT

Every PCB design eventually arrives at the same moment. Components are placed. Nets are defined. The ratsnest of thin lines connecting pad to pad looks like a plate of spaghetti dropped on a cutting board. Now someone, or something, has to turn that mess into real copper traces that don't cross, don't short, and fit within the design rules. That's the routing problem.

For hobbyists and professionals alike, autorouters do this work. You press a button, wait, and traces appear. But what actually happens during that wait? The answer turns out to involve some of the most elegant mathematics in computer science, and some surprisingly hard geometric constraints that no algorithm can finesse.

I've been using Freerouting, the open-source Specctra autorouter, for two PCB projects now: a dual Z80 RetroShield and a level-shifter shield for the Arduino Giga R1. The second project pushed Freerouting to its limits in ways that forced me to understand how it works internally. This is what I found when I read the source code.

Not a Grid, Not a Maze

Giga Shield routed by Freerouting in 45-degree mode. Top layer, rendered in pcb-rnd.

Most descriptions of PCB autorouting start with Lee's maze algorithm from 1961. Place the board on a grid. Flood-fill from the source pad. When the wave hits the destination, backtrack along the shortest path. It's intuitive, easy to implement, and used in introductory EDA courses everywhere.

Freerouting doesn't do this.

Instead of discretizing the board into a grid of cells, Freerouting operates on a continuous geometric plane. The routing space is partitioned into convex polygonal regions called expansion rooms. Each room is a chunk of free space on one layer of the board, bounded by the edges of existing obstacles (traces, vias, pads) plus their clearance halos. The rooms aren't precomputed. They're generated lazily during the search, grown on demand as the router explores new areas.

This is a shape-based router, sometimes called a free-space router. The distinction matters. A grid-based router's resolution is fixed: if your grid is 0.1mm, you can't route a trace at 0.05mm offset from an obstacle, even if the design rules would allow it. A shape-based router has no such limitation. It works with exact geometry (integer-valued coordinates for precision), and the routing channels it discovers are as wide or narrow as the physical clearances actually allow.

Three geometry modes control the shape of the rooms:

Mode	Room Shape	Allowed Trace Angles
90-degree	Axis-aligned rectangles	Horizontal, vertical
45-degree	Octagons	Plus 45-degree diagonals
Any-angle	General convex polygons	Unrestricted

The choice affects both routing quality and performance. Axis-aligned rectangles are fastest to compute and intersect. Octagons allow the 45-degree traces common in modern PCBs. General polygons give the router maximum freedom but at a computational cost.

Same board in any-angle mode. Traces follow direct paths instead of 45-degree snapping.

The image to the left shows the same board routed in any-angle mode. Notice how traces leave pads at arbitrary angles, following straight-line paths toward their destinations rather than snapping to a 45-degree grid. Compare this with the image above, which used the standard 45-degree octagon mode. The any-angle result has shorter total trace length but can be harder to manufacture cleanly at tight tolerances.

The A* Core

At its heart, Freerouting's search algorithm is A*, the same algorithm that drives pathfinding in video games, robot navigation, GPS routing, and network packet delivery. A* was published by Peter Hart, Nils Nilsson, and Bertram Raphael at the Stanford Research Institute in 1968. Nearly sixty years later, it remains the standard algorithm for finding shortest paths in weighted graphs where a heuristic estimate of remaining distance is available.

The mathematical foundation is straightforward. A* maintains a priority queue of candidate states, each with a cost value:

$$f(n) = g(n) + h(n)$$

Where:

g(n) is the actual accumulated cost from the start to state n. In PCB routing, this includes trace length, layer changes (vias), preferred-direction penalties, and any ripped-up obstacle costs.
h(n) is a heuristic estimate of the remaining cost from n to the destination. This must be admissible: it must never overestimate the true remaining cost.
f(n) is the total estimated cost of the best path through n.

At each step, A* pops the state with the lowest f(n) from the queue, expands its neighbors, and adds them back with updated costs. When the destination is popped, the algorithm has found the optimal path (given an admissible heuristic).

The key insight is the heuristic. Without it, A* degenerates into Dijkstra's algorithm, which explores in all directions equally. A good heuristic focuses the search toward the destination. In Freerouting's case, DestinationDistance.calculate() estimates the minimum cost to reach the target, accounting for both planar distance and any required layer transitions. The sorting value in the priority queue is computed as:

double sorting_value = expansion_value
    + this.destination_distance.calculate(shape_entry_middle, layer);

Where expansion_value is the g(n) accumulated cost, and the distance calculation is h(n). This is textbook A*.

Why A* Works So Well

A* has a remarkable optimality guarantee. If the heuristic h(n) is admissible (never overestimates), A* is guaranteed to find the shortest path. If h(n) is also consistent (satisfying the triangle inequality: h(n) <= cost(n, n') + h(n') for every neighbor n'), then A* never needs to re-expand a state it has already visited. This makes it both optimal and efficient.

For PCB routing, the Euclidean distance between the current position and the destination pad is a natural admissible heuristic: a straight line is always shorter than any actual route that must navigate around obstacles. Freerouting's heuristic is somewhat more sophisticated, incorporating via costs for layer transitions, but the principle is the same.

The efficiency gain over brute-force search is dramatic. Dijkstra's algorithm (A* with h(n) = 0) explores states in concentric rings outward from the source. On a board with N searchable regions, it visits O(N) states. A* with a good heuristic carves a narrow corridor from source to destination, visiting far fewer states. In practice, on a moderately complex board, this is the difference between milliseconds and minutes per connection.

A* Is Everywhere

The same algorithm, with different cost functions and heuristics, solves an astonishing range of problems:

Game pathfinding. Every real-time strategy game since the 1990s uses A* to move units around obstacles. The grid cells are the states, movement cost is g(n), and Manhattan or Euclidean distance to the target is h(n).

GPS navigation. Road networks are weighted graphs. Edge weights are travel times. A* with geographic distance as the heuristic finds near-optimal routes across millions of road segments.

Robot motion planning. A robot's configuration space (position, orientation, joint angles) is the state space. A* finds collision-free paths from one configuration to another.

Natural language processing. Viterbi decoding, which finds the most likely sequence of hidden states in a Hidden Markov Model, is structurally similar to A* over a trellis graph.

Puzzle solving. The 15-puzzle, Rubik's Cube, Sokoban. A* with an appropriate heuristic solves them all optimally, and the heuristic is what makes the search tractable rather than exponential.

What makes A* general is the abstraction. It doesn't care whether the "states" are grid squares, road intersections, robot poses, or polygonal rooms on a PCB layer. It only needs a cost function, a heuristic, and a neighbor-expansion rule. Freerouting provides all three, with the unusual twist that its states are dynamically-computed convex polygons rather than fixed graph nodes.

But A* Only Routes One Net

Here's the catch. A* finds the optimal path for a single source-destination pair. A PCB has hundreds of nets, all competing for the same physical space. Route net A first, and it might block the optimal path for net B. Route net B first, and net A suffers instead. The quality of the overall routing depends heavily on the order in which nets are processed.

Freerouting handles this with rip-up-and-reroute, a strategy from the 1970s that remains the standard approach. The idea is simple: route all nets in some initial order. When a net fails (no path exists without violating design rules), rip up one or more blocking traces and add them to a retry queue. Then try again with different priorities.

The implementation in BatchAutorouter.java runs multiple passes over the board. On each pass, every unrouted connection is attempted. The critical detail is how ripup decisions are made. Each existing trace has a ripup cost, and the cost increases linearly with the pass number:

ripup_cost = start_ripup_costs * passNumber

Early passes are conservative: the router avoids tearing up existing routes. Later passes become progressively more aggressive, willing to rip up more traces to find solutions. This is a controlled escalation that prevents the router from thrashing (endlessly ripping and re-routing the same nets) while still allowing it to escape local minima.

The scheduler also implements a limited form of backtracking. Every few passes, the router checks whether the board score (total unrouted connections, via count, trace length) has improved. If not, it restores a previously saved board snapshot and continues from that earlier state. This is a coarse approximation of simulated annealing: occasionally accepting a worse intermediate state to explore a different region of the solution space.

Net Ordering: The Hidden Variable

The order in which nets are routed has an outsized effect on the result. By default, Freerouting routes nets in the order they appear in the DSN file, which is typically the order they were defined in the schematic. There's no sorting by airline length, fan-out degree, or criticality. The router's source code contains a commented-out sort-by-distance that was disabled in v2.3 because it "negatively impacts convergence."

This means the same board can produce different routing results depending on how the DSN file was generated. I exploited this during the Giga Shield project by writing a script (shuffle_dsn.py) that generates dozens of copies of the same DSN file with randomized net ordering:

for i in range(n_copies):
    shuffled = nets.copy()
    random.seed(i * 31337 + 42)
    random.shuffle(shuffled)
    # write shuffled DSN...

Each copy routes nets in a different sequence, converging to a different local optimum. Running 128 parallel Freerouting instances across three machines (a local Mac, a 64-core server, and a 32-core workstation) explored 128 different regions of the solution space simultaneously. The best result was measurably better than any single run. This is an embarrassingly parallel optimization: each job is independent, and you keep the best answer.

The takeaway: if your autorouter isn't finding a clean solution, the problem might not be the algorithm. It might be the ordering. Changing the input order is cheaper than changing the router.

The Optimization Phase

After the initial routing passes, Freerouting enters an optimization phase controlled by the -mp flag. This phase iterates over every existing via and trace in the design, processing them in a left-to-right spatial scan.

For each item, the optimizer:

Rips up the item's entire connection (all traces and vias for that net segment)
Re-runs up to 6 passes of the A*-based autorouter on just that connection
Accepts the result only if it reduces via count or total trace length
Restores the previous state if the re-route was no better

Vias are visited before traces, reflecting the priority of via reduction. Each unnecessary via adds manufacturing cost, signal integrity degradation, and parasitic capacitance. The optimizer also alternates between preferred and non-preferred trace directions on successive passes, preventing the solution from getting stuck in a directional rut.

Via positions themselves are fine-tuned by a separate algorithm (OptViaAlgo). For vias connecting exactly two traces, the optimizer searches for the position that minimizes the combined weighted trace length on both layers, iteratively nudging the via toward the geometric optimum.

The result of the optimization phase is typically a 15-30% reduction in via count and a 10-20% reduction in total trace length compared to the initial routing. On the Giga Shield, 60 optimization passes ran for about 45 minutes and brought the via count from ~220 down to ~158.

Why Freerouting Can't Do Copper Pours

This is where the elegance of the algorithm runs headfirst into a hard architectural limit.

Every non-trivial PCB has a ground net that connects to dozens or hundreds of pads. The standard solution in commercial EDA tools is a copper pour: a filled polygon that covers an entire layer (or most of it), with clearance cutouts around non-ground features and thermal relief connections to ground pads. You don't route GND with traces. You flood-fill it.

Freerouting cannot do this.

The limitation isn't a missing feature that could be added with a few hundred lines of code. It's structural. Freerouting's entire architecture is built around point-to-point trace routing. The maze search, the rip-up scheduler, the optimizer: they all operate on individual connections between pairs of pads. A copper pour is a fundamentally different object. It's not a path from A to B. It's a region that grows to fill available space, adapting its shape around every obstacle on the layer.

In the source code, copper pours are represented as ConductionArea objects with a fixed shape set at import time. When the autorouter encounters a net that already has a ConductionArea, it simply returns CONNECTED_TO_PLANE and considers the job done. There's no flood-fill algorithm. There's no thermal relief generation. The router expects that the EDA tool (KiCad, pcb-rnd, etc.) has already computed the pour geometry before the DSN file was exported.

For foreign nets (anything that isn't the pour's net), the ConductionArea is treated as a hard obstacle. Traces can't cross it. Vias can't be placed inside it. The router routes around it as if it were a solid wall. This is exactly right from a clearance perspective, but it means the router has no ability to create, modify, or extend a pour during the routing process.

The practical impact is severe for boards with fine-pitch surface-mount parts. On the Giga Shield, each SN74LVC8T245PW (TSSOP-24) has three GND pins at 0.65mm pitch. The gap between adjacent pads is roughly 0.25mm. A via needs approximately 0.9mm of space (drill diameter plus annular ring plus clearance). There is physically no room to place a via next to a TSSOP-24 GND pad and connect it to a GND trace on another layer. The router can see the GND pad, it can see that it needs to be connected to other GND pads, but it cannot find a valid path because there is no valid path using its vocabulary of traces and vias.

A copper pour solves this trivially. The pad sits directly on (or thermally connects to) the pour polygon. No via needed. No trace routing needed. The connectivity is implied by physical overlap. But this is a concept that simply doesn't exist in Freerouting's model of the world.

On the Giga Shield project, this limitation manifested as a hard floor of 5-6 unrouted GND connections that no amount of optimization could resolve. I threw 128 parallel instances at the problem across three machines. I tried 2-layer, 4-layer, and 6-layer board configurations. I wrote custom post-processing scripts to add GND vias and MST-based bottom-layer routing. None of it worked within DRC constraints. The geometry was simply too tight. We ended up solving it with a different tool entirely, which is a story for the next article in this series.

The Shove Machine

Bottom layer. The shove algorithm packs traces tightly between through-hole pin rows.

One of Freerouting's more sophisticated subsystems is its forced insertion with shove mechanism. When the A* search finds that the optimal path for a new trace passes through space occupied by an existing trace, the router doesn't immediately give up or rip up the obstacle. Instead, it tries to push the obstacle aside.

The ForcedPadAlgo and ShoveTraceAlgo classes implement this recursively. When a new trace needs to go where an existing trace is, the existing trace is nudged perpendicular to the new trace's path. If that nudge collides with a third trace, the third trace is nudged too, and so on, up to a configurable recursion depth (default: 20 levels for traces, 5 for vias). Only if the shove cascade exceeds this depth does the router fall back to ripping up the blocking item.

This is the routing equivalent of parallel parking in a tight spot. Instead of abandoning the space, you bump the neighboring cars just enough to fit. It produces much denser routing than a pure rip-up approach, especially on boards with tight clearances and many competing nets.

After every trace insertion, a pull-tight pass (PullTightAlgo) smooths and shortens all traces in the affected area. This is a local optimization that removes unnecessary corners, straightens diagonal segments, and reduces total trace length. The combination of global A* search, local shove, and pull-tight smoothing produces routing quality that is competitive with commercial autorouters.

Clearance Compensation: Geometry Trick

One implementation detail worth highlighting is how Freerouting handles clearance checking. Rather than testing "does this trace violate clearance with that via?" as a separate geometric predicate, Freerouting inflates every item's shape by its clearance value when storing it in the search tree. A trace with 0.254mm clearance is stored as a shape 0.254mm wider on each side. A via with 0.127mm clearance is stored as a circle 0.127mm larger in radius.

This transforms all clearance checks into simple overlap tests. If two inflated shapes overlap in the search tree, there's a clearance violation. If they don't, there isn't. No separate clearance computation is needed during routing. The free-space rooms computed by the maze search are automatically clearance-legal by construction, because they're defined as the gaps between pre-inflated obstacles.

This is an instance of the Minkowski sum from computational geometry. The inflated obstacle shape is the Minkowski sum of the original shape and a disc of radius equal to the clearance. The free space is the complement of the union of all inflated obstacles. It's mathematically clean and computationally efficient.

Strengths and Weaknesses

After reading through the source and pushing the router to its limits, here's my honest assessment.

Strengths:

Gridless geometry. The shape-based approach produces routing that uses space optimally, without the artifacts of grid snapping. Traces can be placed at any position and any angle (in the selected mode), not just on grid points.
Mathematically sound core. The A* search with admissible heuristic guarantees optimal single-net routing. The rip-up-and-reroute scheduler provides a practical framework for multi-net optimization. These are well-understood algorithms with decades of theoretical backing.
Shove + pull-tight. The forced insertion mechanism and post-routing optimization produce dense, clean routing that competes with commercial tools for signal traces.
Reproducibility. Deterministic algorithm, text-based input/output, command-line interface. Same input always produces the same output. You can script it, parallelize it, and integrate it into CI pipelines.
Open source. You can read the code, modify the cost functions, change the heuristics, rebuild for different Java versions, and understand exactly what the tool is doing. That's rare in EDA.

Weaknesses:

No copper pour support. The most significant limitation. Any board with a meaningful ground net requires manual post-processing or a different tool for GND connectivity. This eliminates Freerouting from the running for most production boards with fine-pitch ICs.
Single-threaded core. The maze search is inherently sequential. Multi-threading exists in the codebase but only at the item level (different connections routed by different threads), not within the search itself. On modern multi-core machines, this leaves most of the CPU idle.
Net ordering sensitivity. The same board produces meaningfully different results depending on input order, with no built-in intelligence about which order is likely to be best. The disabled sort-by-distance suggests the developers tried and found it counterproductive.
GUI initialization in batch mode. Freerouting's Swing UI code initializes even when running headless with -de/-do flags. On servers without X11, this requires xvfb or a virtual framebuffer, adding deployment complexity to what should be a pure command-line tool.
Version regression. Freerouting v2.1.0 produced dramatically worse results than v1.9.0 on the same board (152 unrouted vs 6). The newer version isn't always better.

What's Next

The board you see in the images above was v0.2: nine SN74LVC8T245PW shifters, 72 channels, fully routed by Freerouting on two layers. I was ready to submit it to PCBWay for fabrication. Then I counted the GPIO pins one more time.

The Arduino Giga R1 has 76 digital I/O pins that need level shifting, plus a handful of analog and control lines. Nine 8-channel shifters give you 72 channels. That's not enough. I was four signals short. The board needed a tenth IC, which meant reworking the layout, adding more decoupling caps, and re-routing everything. The v0.2 design that Freerouting had spent hours optimizing was going in the bin.

With ten shifters instead of nine, the board got denser. The GND problem got worse. And the copper pour limitation that was already a hard floor at 5-6 unrouted connections on the 9-IC board became completely impassable on the 10-IC version. I threw 128 parallel Freerouting instances at it across three machines. I tried 2-layer, 4-layer, and 6-layer configurations. I wrote custom post-processing scripts for MST-based ground routing and copper pour stitching. None of it produced a clean board within DRC constraints.

The solution came from an unexpected direction: Quilter.ai, an AI-powered PCB router that understands copper zones. It routed the 10-IC, 6-layer board with zero unrouted nets on the first attempt. The full story of that journey, from massively parallel Freerouting across a home lab cluster to the moment Quilter solved it in one shot, is coming in Part 2 of the Giga Shield redesign series. If the mathematics of A* is the beauty of PCB routing, the GND problem is where theory meets the physical constraints of 0.65mm-pitch IC packages, and the theory blinks first.

The source code for all of this, including the board generator, the net shuffler, the parallel routing scripts, and the post-processing tools, is available in the giga-shield repository.

Redesigning a PCB with Claude Code and Open-Source EDA Tools (Part 1)

A.C. Jokela — Fri, 13 Mar 2026 16:00:00 GMT

In January, I spent $468 on Fiverr to have a professional design an Arduino Giga R1 shield with level shifters. It was a good design. Nine TXB0108PW bidirectional level translators, 72 channels of 3.3V-to-5V shifting, a clean two-layer board ready for fabrication. And then I started testing it with the RetroShield Z80, and the auto-sensing level shifters fell apart.

The TXB0108 is a clever chip. It detects signal direction automatically, so you don't need to tell it whether a pin is input or output. For most applications, that's a feature. For a Z80 bus interface, it's a fatal flaw. During bus cycles, the Z80 tri-states its address and data lines. The outputs go high-impedance. They're not driving high or low, they're floating. The TXB0108 can't determine drive direction from a floating signal. It guesses wrong, or it doesn't drive at all, and the Arduino on the other side sees garbage. The board was blind to half of what the Z80 was doing.

The fix was clear: replace the TXB0108s with SN74LVC8T245PW driven level shifters. The SN74LVC8T245 has an explicit DIR pin: you tell it which direction to translate, and it does exactly that, regardless of whether the signals are being actively driven. No guessing, no ambiguity, deterministic behavior during tri-state periods. The trade-off is that you need a direction control signal for each shifter IC, but that's a small price for reliability.

What wasn't clear was how to execute the redesign. I could go back to Fiverr for another $400-500. I could spend weeks learning KiCad properly. Or I could try something that had worked surprisingly well on a previous project: use AI and open-source command-line EDA tools to design the board from a terminal, without ever opening a graphical PCB editor.

This is part one of a two-part series. This piece covers the design and toolchain: how I used Claude Code, the gEDA ecosystem, pcb-rnd, and Freerouting to go from a failed design to production-ready Gerber files. Part two will cover the physical boards, assembly, and testing against the Z80.

The Toolchain Problem

The original Fiverr design was done in KiCad 9.0. My first instinct was to modify it directly: swap the TXB0108 footprints for SN74LVC8T245, update the pin mappings, add the DIR control header, and re-route. But there was a problem. My preferred command-line PCB tool, pcb-rnd, is version 3.1.4 on Ubuntu. KiCad 9.0 uses a file format version (20241229) that pcb-rnd's io_kicad plugin doesn't support. When I tried to open the KiCad PCB:

unexpected layout version number (perhaps too new)

Hard stop. No conversion path exists from KiCad 9.0 to pcb-rnd. The formats aren't just different versions. KiCad's S-expression format and pcb-rnd's text-based format are fundamentally different syntaxes.

I could have started KiCad and used its GUI. But I'd already proven to myself with the dual Z80 RetroShield project that text-based, AI-assisted PCB workflows are not only possible but sometimes preferable. The gEDA/pcb-rnd file format is human-readable. AI can parse it, reason about it, and generate it. A Python script can manipulate it. You can diff two boards and see exactly what changed. None of that is true for a graphical-only workflow.

So the plan became: extract everything useful from the KiCad source files, then rebuild the board from scratch in pcb-rnd's native format using Python. Sound insane? It kind of is. But it worked.

Extracting the DNA

Even though pcb-rnd couldn't read the KiCad files directly, the KiCad files contained all the design intelligence I needed. Component positions, net assignments, pin mappings, board dimensions. It was all there, just in a format I couldn't import.

KiCad's CLI tools (kicad-cli) could export what I needed:

# Component positions (X, Y, rotation for each part)
kicad-cli pcb export pos AlexJ_bz_ArduinoGigaShield.kicad_pcb -o giga_pos.csv

# Netlist connectivity
kicad-cli pcb export ipc2581 AlexJ_bz_ArduinoGigaShield.kicad_pcb -o giga_netlist.d356

The schematic file (AlexJ_bz_ArduinoGigaShield.kicad_sch) was an S-expression text file I could parse to extract the signal mappings: which Giga pin connects to which 5V header pin through which level shifter channel. This was the most critical piece: getting the net assignments wrong would mean the board physically connects but logically doesn't work.

This is where Claude Code earned its keep. I described the KiCad schematic structure and asked it to help me parse out the signal mappings. The KiCad schematic uses hierarchical sheets with positional net connections, which isn't the simplest format to work with manually, but straightforward for an AI that can read S-expressions and track net names across sheets. Within an hour, I had a complete mapping of all 72 signal channels across the 9 shifter ICs.

Generating the Board with Python

With positions and nets extracted, I wrote build_giga_shield.py, a single Python script that generates the entire pcb-rnd board from scratch. No GUI involved. Every component footprint, every pin, every net connection is defined programmatically.

The script is structured around four generator functions:

tssop24_element() generates the SN74LVC8T245PW footprint. TSSOP-24 is a precise geometry: 0.65mm pin pitch, 6.4mm pad-to-pad span, 24 pins. The function calculates pad positions mathematically: 12 pins on the left, 12 on the right, with pin 1 marked as square per convention. Getting the pin numbering right was critical. The SN74LVC8T245's datasheet shows pins 1-12 on the left (DIR, A1-A4, GND, A5-A8, OE#, GND) and pins 13-24 on the right counting bottom-to-top (B8-B5, VCCB, B4-B1, VCCA, VCCA, VCCB).

pin_header_element() handles through-hole pin headers with rotation support. The Arduino Giga R1 has an unusual form factor: the long pin headers run along the board edges horizontally, not vertically. In the original KiCad design, these were placed with 90-degree or -90-degree rotation. Without matching that rotation, a 26-pin header at y=84mm would extend 63.5mm downward to y=148mm, well past the 90mm board edge. The rotation transform was simple once identified:

def rotate(px, py):
    if rot == 90:
        return (py, -px)
    elif rot == -90:
        return (-py, px)
    return (px, py)

smd_0603_element() creates the 0603 footprint shared by all 27 decoupling capacitors and 9 pull-down resistors. Small SMD parts, simple geometry.

mounting_hole_element() places the four 3.2mm mounting holes that align with the Arduino Giga's standoff positions.

The coordinate system was the trickiest part. KiCad uses an arbitrary origin; in this design, x=106mm, y=30.5mm. pcb-rnd uses (0,0). Every KiCad coordinate had to be translated:

KX, KY = 106.0, 30.5
def kpos(kx, ky):
    return (mm(kx - KX), mm(ky - KY))

The build_pcb() function ties everything together: place components, assign nets, build the symbol table, generate the layer stack, and write out a valid pcb-rnd .pcb file. Running the script produces a complete, unrouted board: components placed, netlist defined, silkscreen text positioned, board outline drawn. Ready for routing.

$ python3 build_giga_shield.py
Generated giga_shield.pcb
Board: 155mm x 90mm
9x SN74LVC8T245PW (TSSOP-24) level shifters
DIR control via J11 (1x10 header)

The Format Wars

Getting pcb-rnd to actually accept the generated file was its own adventure. pcb-rnd's parser is strict about things that look optional in the documentation, and its error messages are sometimes misleading. An error in an Element definition might be reported as a syntax error in the Layer section fifty lines later.

Three format issues bit me hardest:

The "smd" flag. I initially generated elements with Element["smd" "TSSOP24" "U1" ...], which seemed logical for surface-mount parts. pcb-rnd rejected it with "Unknown flag: smd ignored," which cascaded into a complete parse failure. The fix: use an empty string Element["" "TSSOP24" "U1" ...]. The SMD-ness is implicit from using Pad[] entries instead of Pin[] entries.

Bare zeros. pcb-rnd is inconsistent about whether 0 and 0nm are interchangeable. In some contexts, bare 0 works fine. In others, it causes a silent parse error that manifests as a syntax error dozens of lines later. The defensive fix: always use 0nm, never bare 0, everywhere.

Missing flags on Layer lines. The Line[] entry inside Layer blocks needs 7 fields, not 6. The seventh is a flags string like "clearline". My generator omitted it, producing Line[x1 y1 x2 y2 thickness clearance]. The parser's error message: syntax error, unexpected ']', expecting INTEGER or STRING, reported at the layer definition, not at the malformed line.

I found these bugs using a binary search approach, truncating the file with head -N and testing each truncation point until I isolated which section introduced the failure. It's crude but effective when error reporting is unhelpful. Claude Code helped enormously here. I'd paste the error and the surrounding file content, and it would spot the structural issue faster than I could.

The pcb-rnd Ecosystem

For anyone unfamiliar with the tools involved, a brief orientation.

gEDA (GNU Electronic Design Automation) is a suite of open-source tools for electronic design. The original project dates to the late 1990s and includes gschem (schematic capture), pcb (PCB layout), and various utilities. The file formats are text-based and human-readable, a deliberate design choice that makes them scriptable and version-control-friendly. The original pcb program is now deprecated.

pcb-rnd is the actively maintained successor to gEDA's pcb program. It reads and writes the same text-based PCB format, but adds modern features: more export formats, better plugin support, and critically for this project, command-line export of Gerber files, PNG renderings, and Specctra DSN files. It runs on Linux (packaged for Ubuntu) but not macOS, which is why I ran it over SSH on a remote machine throughout this project.

Freerouting is a Java-based autorouter that speaks the Specctra DSN/SES interchange format. You feed it a board definition with components and nets but no traces, and it computes the copper routing, finding paths for every net while respecting design rules for trace width, clearance, and via placement. It's the open-source standard for PCB autorouting and has been used in production for decades.

The workflow chains these tools together:

build_giga_shield.py → giga_shield.pcb
                            ↓
                    [pcb-rnd DSN export]
                            ↓
                     giga_shield.dsn
                            ↓
                   [Freerouting autorouter]
                            ↓
                     giga_shield.ses
                            ↓
              [pcb-rnd SES import + Gerber export]
                            ↓
                    Production files

Every step is a command-line operation. Every intermediate file is text. Every transformation is reproducible. Change a component position in the Python script, re-run the pipeline, get new Gerber files. This is the power of text-based EDA: the entire design is version-controlled, diffable, and automatable.

Autorouting: The Machine Does the Tedious Part

With the board generated and validated in pcb-rnd, the next step was routing: connecting all 308 nets with actual copper traces across a two-layer board. This is where Freerouting comes in.

The pipeline starts with exporting the unrouted board to Specctra DSN format. pcb-rnd handles this in batch mode on the remote Linux machine:

pcb-rnd -x dsn giga_shield.pcb

The DSN file contains the board geometry, component placements, pad definitions, and netlist, everything the autorouter needs to compute a routing solution. One subtlety I learned the hard way: the DSN's (structure) section needs explicit (rule) and (via) definitions. pcb-rnd's DSN exporter puts the design rules inside the net class section, but Freerouting also expects them in the structure section. Without them, the router can see the nets but can't figure out what trace widths and via sizes are legal, and it silently fails to route most connections. A two-line addition fixed this:

(via pstk_1)
(rule
  (width 0.254)
  (clearance 0.254)
)

Freerouting itself is a Java application with both GUI and command-line modes. On my machine, I'm running a custom build from source. The current main branch had a few issues I had to fix (a missing static on the main method, a null pointer on maxThreads in the GUI initialization, and a Gradle build compatibility issue). The v1.9 codepath was more reliable for headless routing:

java -jar freerouting-1.9.0-executable.jar \
  -de giga_shield.dsn \
  -do giga_shield.ses

The autorouter loaded the 308-net board, ran through its passes, and produced a Specctra Session file containing 2911 wire segments and 172 vias. Every net connected. Every design rule satisfied. The routing took about 10 seconds for initial placement followed by optimization passes.

Importing the routes back into pcb-rnd was the final step. pcb-rnd can import SES files through its batch mode:

pcb-rnd --gui hid_batch giga_shield.pcb <<EOF
ImportSes(giga_shield.ses)
SaveTo(LayoutAs, giga_shield_routed.pcb)
EOF

The result: a fully routed PCB with 2911 traces and 172 vias, ready for Gerber export.

Running pcb-rnd Over SSH

One of the more unusual aspects of this project is that all pcb-rnd operations happened on a remote Ubuntu 24.04 machine accessed over SSH. pcb-rnd isn't available on macOS via Homebrew (I tried; there's a deprecated pcb package but no pcb-rnd), and building from source on macOS looked like a rabbit hole I didn't want to enter.

The remote workflow was straightforward:

# Upload the PCB
scp giga_shield.pcb alex@10.1.1.27:/tmp/

# Export DSN for routing
ssh alex@10.1.1.27 "pcb-rnd -x dsn /tmp/giga_shield.pcb"

# Import SES and export gerbers
ssh alex@10.1.1.27 'pcb-rnd --gui hid_batch /tmp/giga_shield.pcb <<EOF
ImportSes(/tmp/giga_shield.ses)
SaveTo(LayoutAs, /tmp/giga_shield_routed.pcb)
EOF'

# Export production files
ssh alex@10.1.1.27 "pcb-rnd -x gerber --gerberfile /tmp/giga_shield /tmp/giga_shield_routed.pcb"
ssh alex@10.1.1.27 "pcb-rnd -x png --dpi 600 --photo-mode --outfile /tmp/top.png /tmp/giga_shield_routed.pcb"

# Download results
scp alex@10.1.1.27:/tmp/giga_shield.*.gbr .
scp alex@10.1.1.27:/tmp/top.png giga_shield_top.png

It's more keystrokes than clicking Export in a GUI. But it's scriptable, repeatable, and fits into the same terminal where Claude Code is running. When I needed to iterate (move a component, re-route, re-export) I could do it in a single pipeline without switching contexts.

Claude Code as a Hardware Design Partner

I should be explicit about what Claude Code did and didn't do in this project, because the AI angle is the part people will either find most interesting or most suspicious.

What Claude Code did:

Parsed the KiCad schematic to extract the 72-channel signal mapping across 9 level shifter ICs
Wrote the initial build_giga_shield.py generator script, including all four footprint generators and the net assignment logic
Debugged pcb-rnd format issues by analyzing error messages and file structure
Managed the remote SSH workflow: uploading files, running pcb-rnd commands, downloading results
Fixed bugs in the Freerouting build (the static main issue, the null maxThreads, the Gradle fileMode API change)
Handled iterative changes: "move tinycomputers.io down by a millimeter" became an edit to the Python script, a regeneration, a re-import, and a re-export, all executed as a single flow

What Claude Code didn't do:

Make architectural decisions. The choice to use SN74LVC8T245 over TXB0108, the DIR control header design, the decision to use pull-down resistors defaulting to A-to-B direction. Those were my decisions based on understanding the Z80 bus protocol; it is also on me for selecting the TXB0108 in the first place
Verify electrical correctness. I checked the SN74LVC8T245 datasheet pin mapping myself. I verified that OE# tied to GND means always-enabled. I confirmed the 10K pull-down value was appropriate for the DIR pin
Replace domain knowledge. I knew why the TXB0108 failed during tri-state periods because I understand Z80 bus cycles. Claude Code could have looked up the TXB0108 datasheet, but it couldn't have diagnosed the real-world failure mode from first principles

The pattern that emerged was: I made design decisions, Claude Code implemented them. I said "the DIR pins need pull-down resistors to default A-to-B direction," Claude Code generated the pcb-rnd Element entries with the correct footprint, position, and net assignments. I said "export gerbers at 600 DPI with photo mode," Claude Code ran the right pcb-rnd command on the remote machine.

This is the same division of labor I described in the dual Z80 post: I bring the domain knowledge, the AI handles the format translation. The text-based nature of gEDA files makes this work. If the design lived in a binary format or required mouse interactions, the AI would have been far less useful.

The New Design

Here's what the redesigned board looks like:

Parameter	v0.1 (Fiverr/TXB0108)	v0.2 (Claude Code/SN74LVC8T245)
Level Shifter IC	TXB0108PW (TSSOP-20)	SN74LVC8T245PW (TSSOP-24)
Direction Control	Auto-sensing	Explicit DIR pin
Channels	72	72
Shifter ICs	9	9
Decoupling Caps	27	27
Pull-down Resistors	9 (OE)	9 (DIR)
DIR Control Header	None	J11 (1x10)
Board Dimensions	155mm x 90mm	155mm x 90mm
Layers	2	2
Design Tool	KiCad 9.0 (GUI)	Python + pcb-rnd (CLI)
Design Cost	$468.63	$0 (open source tools)
Design Time	~10 days (outsourced)	~2 days (with AI)

The J11 header is the key addition. It's a 1x10 pin header with 9 direction control pins (one per shifter IC) and a ground reference. Each DIR pin has a 10K pull-down resistor that defaults the direction to A-to-B (3.3V to 5V). To reverse a shifter's direction (for example, when the Arduino needs to read from the Z80's data bus) you drive the corresponding J11 pin high. The Arduino firmware manages this dynamically during bus cycles.

The board carries "tinycomputers.io" and "v0.2" on the silkscreen, placed near the bottom edge. Version tracking on the physical board, a lesson learned from the Fiverr experience, where I had to pay $57 for a revision just to add version text to the silkscreen.

Generating Production Files

With the routed board in hand, the final step was generating files suitable for manufacturing. pcb-rnd handles this with command-line exporters:

# Gerber files (9 layers: top/bottom copper, mask, silk, paste, outline, drill, fab)
pcb-rnd -x gerber --gerberfile giga_shield giga_shield_routed.pcb

# Photo-realistic renderings
pcb-rnd -x png --dpi 600 --photo-mode --outfile top.png giga_shield_routed.pcb
pcb-rnd -x png --dpi 600 --photo-mode --photo-flip-x --outfile bottom.png giga_shield_routed.pcb

The Gerber output includes everything a fab house needs: top and bottom copper, solder mask, silkscreen, paste stencil, board outline, and drill locations. The photo-realistic PNG renderings use pcb-rnd's built-in renderer: green solder mask, gold-plated pads, white silkscreen text. They're useful for documentation and for sanity-checking the layout before sending it to fabrication.

The BOM and centroid files were generated separately from the Python script's component data. The centroid file lists every SMD component's X/Y position and rotation, which is essential if you're having the boards assembled by a service rather than hand-soldering.

What's Different About This Approach

The standard way to design a PCB in 2026 is: open KiCad or Altium, draw a schematic, assign footprints, lay out the board, route traces (manually or with the built-in autorouter), and export Gerbers. It's a visual, interactive process that works well for most people and most projects.

What I did is different in a few ways that I think are worth noting, even if they're not universally applicable:

The entire design is a Python script. build_giga_shield.py is the single source of truth. Want to move a component? Change a coordinate in the script. Want to add a net? Add it to the dictionary. Want to change every decoupling cap from 0.1uF to 0.22uF? Change a string. Then re-run the pipeline. There's no "did I save the layout?" ambiguity, no undo history to worry about, no risk of accidentally moving something with a stray mouse click.

Every intermediate file is text. The .pcb file, the .dsn file, the .ses file. All text, all diffable, all version-controllable. When I moved a component and re-routed, I could git diff the PCB file and see exactly what changed. Try that with a binary PCB format.

AI can participate meaningfully. Because the files are text, Claude Code could read them, modify them, and verify them. It could grep for a component reference in the PCB file, find its coordinates, suggest a new position, and make the edit. It could read the Freerouting log and diagnose why routing failed. This level of AI participation simply isn't possible with graphical-only workflows.

The workflow is reproducible. I can hand someone the Python script and the Freerouting JAR and they can regenerate the entire board from scratch, on any machine with Python and Java. No KiCad version compatibility issues, no plugin dependencies, no "works on my machine" problems.

The trade-off is obvious: this approach requires understanding file formats at a level that graphical tools abstract away. If pcb-rnd's parser rejects your file with a misleading error message, you need to debug the file format, not just re-click a button. It's a power-user workflow. But for someone comfortable with text editors and command lines (which describes most of the audience reading a blog called tinycomputers.io), it's a viable alternative.

What's Next

The Gerber files are ready for fabrication. In part two, I'll cover ordering the boards from PCBWay, sourcing the SN74LVC8T245PW and passive components, and the moment of truth: plugging the RetroShield Z80 into the new shield and seeing if the Arduino can finally see the Z80's bus cycles clearly.

I'll also compare the v0.2 board side-by-side with the original Fiverr v0.1 board: the TXB0108 auto-sensing design versus the SN74LVC8T245 driven design. Same board dimensions, same connector layout, fundamentally different level-shifting approach. The comparison should be instructive for anyone choosing between auto-sensing and driven level translators for bus interfaces.

The Python build script, pcb-rnd source files, Gerber outputs, and all helper scripts are open source:

giga-shield: Complete design files, build pipeline, and production outputs

This is part one of a two-part series. Part two will cover fabrication, assembly, and testing.

Previous posts in this series: Fiverr PCB Design ($468) · Dual Z80 RetroShield · CP/M on the Giga R1 · Zork on the Giga

Designing a Dual Z80 RetroShield: Two CPUs, One Bus, Zero GUI (Part 1)

A.C. Jokela — Fri, 06 Mar 2026 14:00:00 GMT

The RetroShield Z80 by Erturk Kocalar at 8bitforce.com is one of my favorite pieces of hardware. A real Zilog Z80 CPU on a shield that plugs into an Arduino Mega. The Arduino emulates memory and I/O while the Z80 executes real instructions on real silicon. I've used it to boot CP/M, play Zork over WiFi, port it to the Arduino Giga R1, and even commission a custom level-converter shield to bridge the voltage gap.

But a single Z80 is, well, a single Z80. Real multi-processor Z80 systems existed in the 1980s. Machines like the Cromemco System Three and some S-100 configurations ran multiple Z80s on a shared bus, with bus arbitration mediating access. The question that kept nagging at me: could I fit a second Z80 onto the RetroShield?

I should be honest about something: PCB design is one of my least knowledgeable areas of computing. I'm comfortable with firmware, with compilers, with operating systems, but the physical layer, the world of copper traces and drill files and design rule checks, is territory I've mostly avoided. I can read a schematic, but I've never designed a board from scratch. What I wanted to find out was whether modern AI tools could bridge that gap, whether I could use AI to help me understand, alter, and extend Erturk Kocalar's existing RetroShield design into something new without becoming a PCB design expert first.

This is part one of a two-part series. This piece covers the design: architecture decisions, schematic work, PCB layout, autorouting, and Gerber generation. Part two will cover the physical boards arriving from the fab, assembly, bring-up, and the firmware that makes two Z80s cooperate.

One more thing worth mentioning up front: every step of this design was done without a GUI. That was intentional. I wanted to see how far I could get with just a terminal, command-line EDA tools, AI assistance, and Python scripts that modify PCB files directly. Partly because I think text-based workflows compose better with AI; it's much easier for an AI to generate a Python script that manipulates a text-based PCB file than to drive a graphical EDA tool. And partly because I wanted the entire process to be reproducible and scriptable, not trapped in a series of mouse clicks I'd never remember.

The Original Design

The stock RetroShield Z80 is a clean, simple board. A 55.88mm × 53.34mm two-layer PCB carrying:

U1: A Z80 CPU in a DIP-40 package
J1: A 2×18 pin header (36 pins) that plugs into Arduino Mega 2560 pins 22–53
A handful of passives: decoupling caps (C1, C2), a clock cap (C3), a clock series resistor (R1), an LED current-limiting resistor (R3), and a bus activity LED

The J1 header carries everything the Z80 needs: 16 address lines (A0–A15), 8 data lines (D0–D7), and control signals (CLK, RESET, INT, NMI, MREQ, IORQ, RD, WR). The Arduino drives the clock, provides the data when the Z80 reads, captures the data when the Z80 writes, and emulates whatever memory and I/O map you define in firmware. It's elegant in its simplicity; the Z80 thinks it's talking to a real computer, and in a sense, it is.

The schematic and PCB files use the gEDA format, text-based files that are human-readable and, crucially, scriptable. The schematic (.sch) defines the logical connections. The PCB (.pcb) defines the physical layout: component footprints, copper traces, vias, and board outline. Both are just text. This matters a lot for what comes next.

Why Two Z80s?

The honest answer is that I wanted to see if it could be done. But there are genuinely interesting things you can do with two processors sharing a bus:

Asymmetric multiprocessing. One Z80 runs CP/M as the primary CPU. The second handles I/O (serial communication, disk access, network operations), freeing the primary CPU from waiting on slow peripherals. This mirrors how some S-100 systems used coprocessor boards.

Cooperative multitasking. Both CPUs execute independent programs, taking turns on the shared bus. The Arduino arbitrates access using the Z80's built-in BUSRQ/BUSACK mechanism, a hardware handshake designed exactly for this purpose. One CPU gets the bus, executes for a while, then yields so the other can run.

Debugging and instrumentation. The second CPU can monitor the first. Watch the address bus to trace execution. Compare outputs. Run the same code on both CPUs and verify they produce identical results, which is useful for testing Z80 clones or FPGA implementations against real silicon.

The Z80 was designed for multiprocessor operation. As Rodnay Zaks details in Programming the Z80, it has dedicated bus request (BUSRQ) and bus acknowledge (BUSAK) pins specifically for multi-master bus sharing. Steve Ciarcia's Build Your Own Z80 Computer covers the hardware side of these signals in practical detail. Most hobbyist projects never use them. This one does.

Architecture: Shared Bus with Independent Control

The first design I considered (and quickly rejected) gave each Z80 its own independent header. Two 36-pin headers, two complete sets of address, data, and control lines. This would have worked electrically, but it was wrong for several reasons. It would have required either two Arduino Megas or consumed all the I/O on one Mega with nothing left for bus arbitration. The board would have been enormous. And it wouldn't have reflected how real multi-processor Z80 systems actually worked.

The right approach is a shared bus. Both Z80s connect to the same address and data lines through J1. They take turns driving the bus, just like in a real S-100 system. What each CPU needs independently is its own set of control signals: its own clock, its own reset, its own interrupt lines, and its own bus request/acknowledge pair.

I checked the Arduino Mega's pin budget. J1 uses pins 22–53 (32 I/O pins). The Mega still has pins 2–21 (20 pins) plus analog pins A0–A15 (16 more, usable as digital I/O), leaving 36 pins sitting idle. A second CPU's control signals only need about 10 pins. There was plenty of room.

The solution: a small supplementary 2×6 header (J2, 12 pins) carrying CPU2's independent control signals to the Arduino's remaining pins:

Pin 1:  +5V         Pin 2:  GND
Pin 3:  CLK_2       Pin 4:  RESET_2
Pin 5:  INT_2       Pin 6:  NMI_2
Pin 7:  MREQ_2      Pin 8:  IORQ_2
Pin 9:  RD_2        Pin 10: WR_2
Pin 11: BUSRQ_2     Pin 12: BUSAK_2

BUSRQ and BUSAK are the key pins. The Arduino firmware pulls BUSRQ low on whichever CPU should yield the bus. That CPU finishes its current machine cycle, tristates its outputs, and asserts BUSAK to signal it's off the bus. The other CPU can then drive the bus freely. It's the same mechanism Zilog designed in 1976; I'm just finally using it.

Building the Schematic, Without a Schematic Editor

The original project used classic gEDA tools (gschem, pcb), which are no longer packaged for Ubuntu 24.04. The modern replacement is lepton-eda, a maintained fork that reads the same file formats. But since the whole point was to avoid a GUI, even lepton-schematic's graphical mode was off the table.

This is where AI earned its keep. I don't have the gEDA file format memorized; I've never needed to. But AI can work through the format specification and generate correct output. I described what I wanted (a second Z80 sharing the existing bus, with independent control signals on a new header), and the AI helped me produce the schematic files, the symbol definitions, and eventually the PCB modifications. I still had to understand the architecture and make the design decisions, but the AI handled the translation from intent to file format.

gEDA schematic files are text. A component placement looks like this:

C 44300 47700 1 0 0 z80-1.sym
{
T 44400 59000 5 10 1 1 0 0 1
refdes=U2
}

That's a Z80 symbol placed at coordinates (44300, 47700), with reference designator U2. Net connections are similarly textual. N entries define wire segments, U entries define bus rippers. You can write an entire schematic in a text editor if you understand the coordinate system.

I created a new schematic page, kz80_cpu2.sch, for the second CPU. In gEDA's multi-page scheme, nets with the same name on different pages are automatically connected. So CPU2's address pins connect to nets named A0, A1, ..., A15 (the same net names used on page 1), and the netlister merges them into shared nets. The shared bus happens at the netlist level without any explicit cross-page wiring.

The one component that didn't exist yet was the 2×6 control header. I wrote a new gEDA symbol file (ctrlhdr2x6-1.sym) from scratch, a rectangular body with 12 pins, labeled with the control signal names, specifying the HEADER12_1 footprint. It's about 30 lines of text, all hand-written.

CPU2's schematic connections break down cleanly:

Shared with CPU1 (same net names, auto-merged): A0–A15, D0–D7, +5V, GND

Independent to CPU2 (new nets with _2 suffix): CLK_2, RESET_2, INT_2, NMI_2, MREQ_2, IORQ_2, RD_2, WR_2, BUSRQ_2, BUSAK_2

The total net count went from 37 to 48, only 11 new nets for an entirely new processor. That's the elegance of the shared-bus approach.

Modifying the PCB With Python

Here's where the CLI-only constraint got interesting. The normal workflow would be: run lepton-sch2pcb to update the PCB with new components from the schematic, then open the PCB in a graphical editor to place and route them. But lepton-sch2pcb had trouble finding footprints in pcb-rnd's library paths, and I didn't have a graphical editor anyway.

So I had AI write a Python script (add_cpu2_shared.py) to modify the PCB file directly. The pcb-rnd file format is text-based, with clearly delimited blocks for each component (Element), each copper trace (Line), each via (Via), and the netlist (NetList). The script:

Widened the board from 55.88mm to 86.36mm, an extra 30.48mm to accommodate the second Z80 and control header, placed on the right half of the board.

Inserted five new Element blocks: U2 (Z80, DIP-40), J2 (2×6 header), C4 and C5 (decoupling and clock caps), and R2 (clock series resistor). Each Element block is essentially a footprint definition: pin positions, pad dimensions, drill sizes, silkscreen outlines. I copied the dimensional parameters from the existing components to maintain consistency.

Updated the netlist in two ways. For shared nets (A0–A15, D0–D7, +5V, GND), the script found each existing net block and appended Connect("U2-xx") entries. For CPU2's independent control signals, it created 11 entirely new net blocks. The +5V net picked up four new connections: U2's VCC pin, U2's WAIT pin (tied high, since WAIT is active low, so high means "not waiting"), C4, and J2.

The result was a valid PCB file with all components placed and all nets defined, but no copper traces connecting anything.

Autorouting: Let the Machine Do the Tedious Part

With components placed and nets defined, the board needed routing: actual copper traces connecting all those pins. Doing this by hand over SSH would have been masochistic. This is exactly what autorouters exist for.

The workflow: export the PCB to Specctra DSN format (an industry-standard interchange format for autorouters), run Freerouting, then import the results back.

First Attempt (Failed)

The first attempt exported the PCB with the original CPU1 traces still in place, hoping Freerouting would preserve them and only route the new nets. Instead, Freerouting spent 50+ seconds per pass trying to work around traces it couldn't associate with its own net encoding. After 48 passes and 40 minutes, it was still failing to route several nets.

Second Attempt (Clean Slate)

Another AI-generated Python script (strip_traces.py) removed all existing copper traces from the PCB file. This was a careful operation. The script had to remove Line[...] entries inside Layer blocks (copper traces) while preserving ElementLine[...] entries (component silkscreen outlines that look syntactically similar).

With a clean board, Freerouting ran in headless mode:

java -jar /tmp/freerouting.jar -de kz80.dsn -do kz80.ses -mp 20

It completed the initial routing in 10 passes, then spent another 49 passes optimizing trace length, converging at pass 59 with the message: "There were only 10.60 track length increase in the last 5 passes, so it's very likely that autorouter can't improve the result further."

Total routing time: about three minutes. The result: 191 wires decomposed into 897 individual trace segments, plus 82 vias for layer transitions. Every net connected. Every design rule satisfied.

Importing Routes Back

One more headless problem: pcb-rnd's SES import requires the GUI. I tried xvfb-run with action commands, but it hung waiting for GTK widget interactions that couldn't happen without a display.

The solution was yet another AI-generated Python script (ses_to_pcb.py) that parsed the Freerouting SES output and injected the routes directly into the PCB file as copper Line entries. The main complication was coordinate system conversion: the SES file uses a bottom-left origin (y increases upward) while pcb-rnd uses a top-left origin (y increases downward). The script also handled via translation, mapping Freerouting's via definitions to pcb-rnd's format with appropriate pad sizes, drill diameters, and clearances.

897 trace segments and 82 vias injected. The PCB was fully routed.

The top copper layer after Freerouting: 897 trace segments connecting 48 nets across both Z80s, the J1 bus header, and the J2 control header. Every trace was placed by the autorouter; none were drawn by hand.

Generating Production Files

The final step was generating Gerber files, the industry-standard format that PCB fabrication houses use to manufacture boards. pcb-rnd's command-line exporter handled this cleanly:

pcb-rnd -x gerber --all-layers kz80.pcb

This produced 11 files covering top and bottom copper, solder mask, silkscreen, paste stencil, board outline, and drill locations. pcb-rnd uses verbose filenames (kz80.top.copper.none.3.gbr), so a renaming script converted them to the standard extensions (.gtl, .gbl, .gts, etc.) that fabrication houses expect.

I also added tinycomputers.io to the top silkscreen layer, placed directly below the existing www.8bitforce.com text, a small nod to both projects.

The final Gerber package: 35KB zipped, ready for fabrication.

The Final Board

The top silkscreen: U1 (left) and U2 (right) with the J1 bus header on the far left and the J2 control header between the two CPUs. The silkscreen includes the original 8bitforce.com credit alongside tinycomputers.io.

Here's what changed from the original RetroShield to the dual-CPU version:

Parameter	Original	Dual CPU
Board dimensions	55.88 × 53.34mm	86.36 × 53.34mm
Layers	2	2
Z80 CPUs	1	2
Headers	J1 (36 pins)	J1 (36) + J2 (12) = 48 pins
Nets	37	48
Through-hole components	2	4
SMD components	6	9
Trace segments	-	897
Vias	-	82

The board is wider but not taller. The second Z80 sits to the right of the first, with the J2 control header between them. Both CPUs share the J1 bus connection, and the Arduino firmware will manage who drives the bus at any given moment.

The Toolchain Nobody Uses

It's worth stepping back to note what just happened. An entire PCB was designed (schematic capture, component placement, autorouting, Gerber generation) without opening a single graphical application. Every step was either a command-line tool invocation or an AI-generated Python script manipulating text files. And it was done by someone who, at the start of the project, couldn't have told you the difference between a Gerber file and a drill file.

That was the whole point. I chose to avoid a GUI specifically because I wanted to test a hypothesis: that AI-assisted, text-based workflows could let someone with domain knowledge in adjacent areas (firmware, systems programming) operate effectively in an unfamiliar domain (PCB design). The text-based EDA formats made this possible; they gave the AI something it could read, reason about, and generate. A graphical tool would have put me back to square one, clicking through menus I didn't understand.

I'm not claiming this is better than using KiCad or Altium with a mouse. For complex boards with hundreds of components, graphical tools and experienced designers are indispensable. But for a modification like this (adding a known set of components to an existing, well-documented open-source design), AI plus text-based tools was surprisingly effective. I brought the architectural understanding (how Z80 bus arbitration works, which signals need to be shared versus independent) and the AI handled the translation into file formats I'd never touched before. Most of the time was spent understanding the design, not fighting tools.

What's Next

The Gerber files are at the fab now. In part two, I'll cover what happens when the physical boards arrive: inspection, assembly, first power-on, and the Arduino firmware that orchestrates two Z80s on a shared bus. The firmware is where the real complexity lives: bus arbitration timing, memory mapping for two independent address spaces, and the question of what to actually run on a dual-Z80 system in 2026.

Here's a preview of what the bus arbitration core looks like. The Arduino manages which CPU owns the shared bus at any given moment using the Z80's hardware BUSRQ/BUSAK handshake:

// --- Pin definitions (active low) ---
// CPU1 control (directly from J1 via existing RetroShield mapping)
#define CPU1_CLK      A5
#define CPU1_BUSRQ    A4    // directly from Arduino to CPU1 BUSRQ pin
#define CPU1_BUSAK    A3    // directly from CPU1 BUSAK pin to Arduino

// CPU2 control (directly from J2 header)
#define CPU2_CLK      2
#define CPU2_BUSRQ    3
#define CPU2_BUSAK    4

// Bus state
volatile uint8_t active_cpu = 1;

void setup() {
  // BUSRQ is output (Arduino tells CPU to release bus)
  pinMode(CPU1_BUSRQ, OUTPUT);
  pinMode(CPU2_BUSRQ, OUTPUT);

  // BUSAK is input (CPU tells Arduino it released bus)
  pinMode(CPU1_BUSAK, INPUT_PULLUP);
  pinMode(CPU2_BUSAK, INPUT_PULLUP);

  // Start with CPU1 active, CPU2 off the bus
  digitalWrite(CPU1_BUSRQ, HIGH);   // HIGH = don't request bus release
  digitalWrite(CPU2_BUSRQ, LOW);    // LOW  = request CPU2 to release bus
  active_cpu = 1;

  // Wait for CPU2 to acknowledge it's off the bus
  while (digitalRead(CPU2_BUSAK) == HIGH);
}

bool switch_to_cpu(uint8_t cpu) {
  if (cpu == active_cpu) return true;

  uint8_t old_busrq = (active_cpu == 1) ? CPU1_BUSRQ : CPU2_BUSRQ;
  uint8_t old_busak = (active_cpu == 1) ? CPU1_BUSAK : CPU2_BUSAK;
  uint8_t new_busrq = (cpu == 1) ? CPU1_BUSRQ : CPU2_BUSRQ;

  // Ask the active CPU to release the bus
  digitalWrite(old_busrq, LOW);

  // Wait for acknowledgment (CPU finishes current machine cycle first)
  unsigned long timeout = micros() + 1000;
  while (digitalRead(old_busak) == HIGH) {
    if (micros() > timeout) return false;   // hung CPU — shouldn't happen
  }

  // Bus is free. Release the new CPU onto it.
  digitalWrite(new_busrq, HIGH);
  active_cpu = cpu;
  return true;
}

The critical detail is timing. When the Arduino pulls BUSRQ low, the Z80 doesn't stop immediately; it finishes its current machine cycle, which can take 3–6 clock periods depending on the instruction. Only then does it tristate its address, data, and control outputs and assert BUSAK. The while loop waits for that handshake to complete. During the transition, neither CPU is driving the bus, and the Arduino must not attempt any bus operations.

This is a simplified version. The full firmware in part two will handle clock generation for both CPUs, memory mapping, I/O dispatch, and the arbitration policy (round-robin, priority-based, or cooperative yield). But the handshake above is the foundation everything else builds on. It's the same protocol that made multi-Z80 S-100 systems work in the early 1980s.

The hardware design is the easy part. Making two 50-year-old processors cooperate is the challenge.

Source Files

All schematics, PCB files, Gerber outputs, and helper scripts for this project are open source:

dual-z80: KiCad/gEDA source files, Gerber package, Python scripts for PCB manipulation, and build log

This is part one of a two-part series. Part two will cover board assembly, bring-up, and dual-CPU firmware.

Previous RetroShield posts: CP/M on the RetroShield · Fiverr PCB Design · CP/M on the Giga R1 · Zork on the Giga

Part 4: 132 Tests, Zero Failures - Verifying the Sampo CPU on Real Hardware

A.C. Jokela — Sun, 15 Feb 2026 20:00:00 GMT

In Part 1, we designed the Sampo 16-bit RISC architecture. In Part 2, we synthesized it to an ECP5 FPGA on the ULX3S board. In Part 3, we built an LLVM backend so Rust could compile for it. But there was a glaring gap in the project: we'd never systematically verified that the hardware actually implements the ISA correctly.

The "Hello, Sampo!" demo program exercises maybe 10 of the CPU's 66 instructions. The LLVM backend generates code that assumes the hardware matches the spec. If a single instruction is subtly wrong - a carry flag not set, a branch offset miscalculated, a byte load sign-extending when it shouldn't - the entire toolchain is built on sand.

This post documents the process of building a comprehensive test suite, running it in simulation, finding a real pipeline hazard bug in the CPU, and then the surprisingly treacherous journey of getting those tests running on real FPGA hardware.

The Test Strategy

The approach is straightforward: write assembly programs that exercise every instruction in the ISA, compare results against known-good values, and report PASS or FAIL over UART. The testbench monitors the serial output, and if it sees "FAIL" anywhere, the test run fails.

Each test follows the same pattern:

; Load known inputs
LIX  R8, 0x1234
LIX  R9, 0x5678

; Execute the instruction under test
ADD  R10, R8, R9

; Check the result
MOV  R4, R10          ; actual value
LIX  R5, 0x68AC       ; expected value
JALX check_eq         ; prints PASS or FAIL

The check_eq subroutine compares R4 (actual) against R5 (expected) and prints the result over the UART. This makes the test output human-readable and machine-parseable:

=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
ADD overflow: PASS
SUB basic: PASS
...
Done.

The Test Framework

Every test program begins with a block of helper subroutines that handle UART communication and result reporting. The core is a busy-wait loop that polls the MC6850-compatible UART status register:

.equ ACIA_STATUS 0x80
.equ ACIA_DATA   0x81

print_char:
    ; R5 = character to output
.wait:
    INI  R6, ACIA_STATUS    ; Read status register
    AND  R7, R6, R6         ; Copy to R7
    ADDI R7, -2             ; Check if TX ready (bit 1)
    BNE  .wait              ; Loop until ready
    OUTI ACIA_DATA, R5      ; Send character
    JR   RA                 ; Return

The check_eq helper prints "PASS" or "FAIL" based on a register comparison, and the print_str helper walks a null-terminated string byte by byte. These routines are duplicated in each test file rather than linked - there's no linker in this toolchain, just a single-file assembler.

Test Coverage

We organized the tests into 10 programs, each targeting a specific area of the instruction set:

Test Program	Instructions Tested	Test Count
test_alu	ADD, SUB, AND, OR, XOR, NEG + flags	20
test_addi	ADDI with signed immediates + flags	10
test_shift	SLL, SRL, SRA, ROL, ROR, SWAP (1/4/8-bit variants)	17
test_muldiv	MUL, MULH, DIV, DIVU, REM, REMU	12
test_loadstore	LW, LB, LBU, SW, SB + offset variants	11
test_branch	All 16 branch conditions (taken + not taken)	24
test_jump	J, JR, JALR, JX, JALX	6
test_stack	PUSH, POP, CMP, TEST, MOV	12
test_misc	EXX, GETF, SETF, SCF, CCF, NOP	9
test_extended	ADDIX, SUBIX, ANDIX, ORIX, XORIX, SLLX, SRLX, SRAX	11
Total		132

The branch tests are particularly thorough - each of the 16 conditions (BEQ, BNE, BLT, BGE, BLTU, BGEU, BMI, BPL, BVS, BVC, BCS, BCC, BGT, BLE, BHI, BLS) gets tested both for the taken and not-taken case. We set up flags with arithmetic, then verify the branch goes the right way.

Finding a Real Bug: The Pipeline Hazard

The first time we ran the full test suite in simulation, 130 of 132 tests passed. Two tests in test_loadstore were failing: the multi-word store/load test and a load with offset test.

The failing pattern was consistent: any test that performed a store followed immediately by a load from a different address would read stale data. The load would return the value from the previous memory operation instead of the current one.

The root cause was a pipeline hazard between the MEMORY and FETCH states. Here's what was happening:

Cycle N:   MEMORY state - store completes, mem_ready asserts
Cycle N+1: FETCH state  - new instruction fetch begins

The problem: mem_ready is a one-cycle delayed version of mem_valid (because the RAM is synchronous). When the CPU transitions from MEMORY to WRITEBACK to FETCH, the mem_ready signal from the store was still asserted during the first cycle of the next FETCH. The CPU latched the stale mem_rdata from the previous store operation as if it were the new instruction.

The fix was to add a WRITEBACK state after every MEMORY operation - not just loads, but stores too. This gives mem_ready a cycle to deassert before the next FETCH begins:

Before: MEMORY → FETCH          (mem_ready still high from store)
After:  MEMORY → WRITEBACK → FETCH  (mem_ready deasserts during WRITEBACK)

A one-line change to the next-state logic:

`ST_MEMORY: begin
    if (mem_ready) begin
        // Always go through WRITEBACK after MEMORY.
        // For stores: allows mem_ready to deassert before
        // next FETCH (prevents stale rdata latch).
        next_state = `ST_WRITEBACK;
    end
end

This is exactly the kind of bug that simulation catches and manual inspection misses. The instruction executes correctly in isolation - it's only the interaction between consecutive memory operations that triggers the hazard. After the fix, all 132 tests passed in simulation.

Taking It to the FPGA

With simulation clean, the next step was running the tests on real hardware. The ULX3S board has an FTDI FT231X USB-serial chip connected to the FPGA, so UART output appears on a serial port at 115200 baud.

There was an immediate practical problem: the test programs run fast. At 12.5 MHz, the entire 20-test ALU suite completes in about 30 milliseconds. By the time openFPGALoader finishes programming the FPGA and releases the USB port, the test output is long gone. The FTDI chip has a small receive buffer, but 364 characters of test output overflows it before you can open the serial port.

The solution: patch the hex files to loop instead of halting. Replace the HALT instruction with a delay loop followed by a jump back to the reset vector. The test runs, outputs its results, waits about half a second, and starts over. You can open the serial port at any time and catch a complete iteration.

The Delay Loop Patch

The hex_loop_patch.py script performs binary patching on the assembled hex files. It finds the HALT instruction (encoded as 0xE100) and replaces it with a delay loop:

; Delay ~0.38 seconds at 12.5 MHz
    LIX  R8, 0x0008       ; outer counter
outer:
    LIX  R9, 0xFFFF       ; inner counter = 65535
inner:
    ADDI R9, -1
    BNE  inner
    ADDI R8, -1
    BNE  outer
    JX   0x0100            ; jump back to reset vector

The first version of this script inserted these 10 words at the HALT position. This seemed obviously correct. The tests ran on FPGA. Characters appeared on the serial port.

They were the wrong characters.

The Address Shift Bug

The FPGA output for the "Hello, Sampo!" test program was \x08\x08\x08\x08 - four backspace characters, repeating forever. The ALU test suite showed truncated output with roughly 45% of characters missing. Same pattern at 12.5 MHz and 6.25 MHz, ruling out timing violations. Simulation with realistic UART timing (1,080 cycles per byte, matching the hardware baud rate) passed perfectly.

I spent considerable time investigating the wrong theories. Was the UART transmitter dropping bytes? Was there a clock domain crossing issue? Was $readmemh in Yosys interpreting the hex file differently from Icarus Verilog? None of these panned out.

The breakthrough came from staring at \x08. That's the byte value 8. Where would 8 come from? The "Hello, Sampo!" program loads its message pointer with LIX R4, message where message is the label for the string data. In the assembled hex, message resolves to address 0x011E - the byte immediately after the HALT instruction.

And there it was. Look at the assembly structure:

done:
    HALT                    ; address 0x011C
message:
    .asciz "Hello, Sampo!\n" ; address 0x011E

The string data lives immediately after HALT. When hex_loop_patch.py inserts 10 words of delay loop code at the HALT position, it pushes the string data down by 20 bytes. But the LIX R4, 0x011E instruction still points to the original address. At 0x011E there's now the second word of LIX R8, 0x0008 - which contains the value 0x0008. The low byte is 0x08.

The CPU faithfully reads byte 0x08 from the patched address, outputs it via UART, advances the pointer to 0x011F where the high byte is 0x00 (the null terminator), and stops. One \x08 per iteration, four iterations captured. Mystery solved.

This same address shift corrupted every test program. The test strings ("ADD basic: ", "PASS\n", etc.) all live after HALT and all got displaced. The CPU was reading from locations that now contained delay loop machine code instead of ASCII text. Some fragments of text survived because adjacent strings partially overlapped with their shifted locations, producing the truncated output we saw.

The Fix

The correct approach: don't shift any data. Place the delay loop at address 0x0000 - the 256 bytes of unused memory before the 0x0100 reset vector - and replace the single-word HALT with a single-word relative J (jump) instruction that jumps backward to the loop code. One word replaces one word. No data moves.

# Place delay loop at address 0x0000 (unused space)
for i, w in enumerate(LOOP_PATCH):
    words[loop_base + i] = w

# Replace HALT with J instruction to address 0x0000
# J encoding: opcode 0x9, 12-bit signed offset
# target = PC + 2 + (sign_extend(offset) << 1)
offset = (target_addr - halt_addr - 2) // 2
j_word = 0x9000 | (offset & 0xFFF)
words[halt_idx] = j_word

There's a subtle complication: the J instruction shares opcode 0x9 with JR (register indirect jump) and JALR (jump and link register). The decoder distinguishes them by specific bit patterns in the offset field. If the calculated offset happens to have bits[3:0] == 0x1 and bits[11:8] != 0xF, the decoder interprets it as JALR instead of J. The script tries successive target addresses (0x0000, 0x0002, 0x0004, ...) until it finds one that doesn't collide with the JR/JALR encoding space.

After the fix, the patched hex files have exactly the same number of words as the originals. The only changes are the delay loop code written to the zero page and the HALT word replaced with a backward jump.

With the corrected patcher, the "Hello, Sampo!" program finally works on the FPGA - looping cleanly with zero character loss:

The Testbench: Trusting but Verifying

One important discovery during this process: the simulation testbench had tx_ready = 1 permanently. The simulated UART never pushed back on the CPU - it accepted every byte instantly. This meant the CPU's busy-wait loop (INI R6, ACIA_STATUS / ADDI R7, -2 / BNE wait) was never actually tested in simulation. The status register always returned "ready," so the loop body executed zero times.

On real hardware, the UART transmitter takes about 87 microseconds per byte at 115200 baud. The busy-wait loop runs hundreds of times per character, exercising the INI instruction, the AND/ADDI flag-setting sequence, and the BNE branch in a tight loop. If any of those instructions had a subtle bug, it would only manifest on hardware.

We added realistic UART timing to the testbench:

parameter TX_BYTE_CYCLES = 108 * 10;  // ~1080 cycles per byte
reg [15:0] tx_delay_cnt;

always @(posedge clk) begin
    if (tx_valid && tx_ready) begin
        tx_ready <= 0;
        tx_delay_cnt <= TX_BYTE_CYCLES;
    end else if (tx_delay_cnt > 0) begin
        tx_delay_cnt <= tx_delay_cnt - 1;
        if (tx_delay_cnt == 1)
            tx_ready <= 1;
    end
end

With this change, simulation exercises the same code paths as the hardware. All 132 tests still pass - the UART flow control logic was correct all along, it just wasn't being tested.

Running All Tests on the FPGA

Your browser does not support the video tag.

With the patch bug fixed, we ran the complete suite. Each test requires a separate FPGA build (Yosys synthesis, nextpnr place-and-route, ecppack bitstream generation), programming via JTAG, and serial capture. The Makefile automates the entire pipeline:

fpga-%: $(BUILD_DIR)/sampo_%.bit
    openFPGALoader -b ulx3s $<
    sleep 1
    python3 fpga_capture.py $(SERIAL_PORT) $(SERIAL_BAUD) 5

The fpga_capture.py script opens the serial port, discards the first partial iteration (we might join mid-stream), waits for the === ... === header line that starts each test, captures everything until the header repeats, and outputs one clean iteration.

The results:

========================================
=== FPGA: test_alu ===
========================================
=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
...
AND clr C/V: PASS
All tests passed!

========================================
=== FPGA: test_addi ===
========================================
...
All tests passed!

...

========================================
FPGA Test Summary: 10 passed, 0 failed
========================================

All 10 test suites pass. All 132 individual tests pass. Zero failures on real hardware.

Test Suite	Tests	FPGA Result
ALU (ADD, SUB, AND, OR, XOR)	20	All PASS
ADDI (immediate arithmetic)	10	All PASS
Shift (SLL, SRL, SRA, ROL, SWAP)	17	All PASS
MulDiv (MUL, DIV, REM variants)	12	All PASS
Load/Store (LW, LB, LBU, SW, SB)	11	All PASS
Branch (all 16 conditions)	24	All PASS
Jump (J, JR, JALR, JX, JALX)	6	All PASS
Stack (PUSH, POP, CMP, TEST, MOV)	12	All PASS
Misc (EXX, GETF, SETF, SCF, CCF, NOP)	9	All PASS
Extended (ADDIX, SUBIX, SLLX, etc.)	11	All PASS
Total	132	All PASS

What This Means

Having all 132 ISA tests pass on hardware is a significant milestone for the project. It means:

The Verilog RTL is correct. Every instruction in the Sampo ISA produces the right result, sets the right flags, and handles edge cases (zero, overflow, carry, sign extension) correctly. Not just in behavioral simulation, but in synthesized logic on a real FPGA running at 12.5 MHz.

The assembler is correct. All 66 instructions encode properly. Branch offsets calculate correctly. Extended instructions (LIX, JALX, OUTX) with their 32-bit encoding work. The sasm Rust assembler and the Verilog decoder agree on every instruction format.

The LLVM backend has a solid foundation. When the Rust compiler generates a ADD or BNE or JALX, the hardware will execute it correctly. The test suite doesn't exercise every possible code generation pattern, but it validates every primitive instruction that the compiler builds upon.

The UART subsystem works end-to-end. Status register polling, TX busy-wait, byte transmission, baud rate generation - all verified on hardware. The MC6850-compatible interface works exactly as specified.

Lessons Learned

Test your assumptions. The testbench had tx_ready = 1. It went unnoticed because simulation "worked." The real hardware exercises code paths that simulation shortcuts. Add realistic peripheral timing to your testbenches from day one.

Binary patching is fragile. Inserting bytes into a binary without updating references is a classic relocation bug - the same class of problem that linkers exist to solve. If your patch changes the size of anything, every address reference past the patch point is wrong. The fix - placing the patch in unused address space and using a same-size replacement instruction - avoids the problem entirely.

Simulation is necessary but not sufficient. The pipeline hazard bug was caught by simulation. The address shift bug was invisible to simulation (both used the same patching script, and the original programs - without patching - worked fine). You need both simulation and hardware testing, exercising different code paths and different failure modes.

Systematic testing finds bugs that demos don't. "Hello, Sampo!" worked on the FPGA from day one. It exercises LIX, LBU, CMP, BEQ, INI, OUTI, ADDI, and J - about 8 instructions. The pipeline hazard only manifested when a store was followed by a load to a different address, a pattern that doesn't occur in a simple print loop. You need tests specifically designed to exercise corner cases.

What's Next

The entire Sampo project - assembler, emulator, Verilog RTL, FPGA build scripts, test suite, and LLVM backend - is open source on GitHub. With hardware verification complete, the next steps might be:

Running Rust-compiled code on the FPGA. The LLVM backend generates assembly, the assembler produces hex files, and we now know the hardware executes them correctly. Closing this loop - cargo build to blinking LEDs - is the obvious next milestone.
Adding more peripherals. The ULX3S has 32MB of SDRAM, an HDMI output, a microSD slot, and an ESP32 co-processor. Each of these opens up interesting possibilities for a working 16-bit computer.
Performance optimization. The CPU currently runs at 12.5 MHz with a multi-cycle FSM (5-8 cycles per instruction). Pipelining could push this significantly higher on the ECP5.

But first: 132 tests, zero failures. The Sampo CPU works.

This is Part 4 of the Sampo series. Part 1 covers architecture design, Part 2 covers FPGA implementation, and Part 3 covers the LLVM backend.

Recommended Resources

OrangeCrab ECP5 FPGA Board - A compact Lattice ECP5 board with DDR3 and USB-C, available on Amazon
ECP5 FPGA Development Boards - Other ECP5 boards available on Amazon
Getting Started with FPGAs by Russell Merrick - Beginner-friendly introduction with Verilog and VHDL examples
FTDI USB Serial Adapters - Useful for UART debugging with FPGAs
USB Logic Analyzers - Essential for debugging digital signals

Source Code

github.com/ajokela/sampo - CPU architecture, assembler, emulator, Verilog RTL, test suite, and FPGA build scripts
github.com/ajokela/llvm-sampo - LLVM backend and Rust target specification

Playing Zork on a Real Z80: From CP/M Boot to the Great Underground Empire

A.C. Jokela — Sun, 15 Feb 2026 12:00:00 GMT

This is the third post in a series about running CP/M 2.2 on a real Z80 processor connected to an Arduino Giga R1 WiFi. The first post covered getting the custom level converter shield designed and manufactured. The second post documented the hardware stack, the catastrophic TXB0108 level converter failures, the shadow register workaround, and the Rust sector server that provides disk I/O over WiFi. That post ended with a promise: CP/M was close to booting, and all the pieces were in place.

This post is about keeping that promise. It covers the final debugging push from "almost boots" to a fully interactive game of Zork I running on real Z80 hardware, and the performance crisis that nearly made the whole thing unusable.

The Story So Far

The hardware is straightforward: a RetroShield Z80 (a real Zilog Z80 CPU on a shield board) plugged into an Arduino Giga R1 WiFi through a custom level converter PCB. The Giga's STM32H747 (480MHz Cortex-M7) provides 64KB of Z80 RAM as a byte array in its internal SRAM, clocks the Z80, and serves memory read/write requests. Disk I/O goes over WiFi to a Rust TCP sector server instead of an SD card.

The level converter uses nine TXB0108 bidirectional level shifters to bridge the Giga's 3.3V logic and the RetroShield's 5V. And those TXB0108s are the source of almost every interesting engineering decision in the project. Their auto-direction sensing fails for several Z80 bus signals: IORQ_N and RD_N are permanently stuck, WR_N only works during memory cycles, and the data bus is invisible from Z80-to-Arduino during I/O operations. The address bus works but lags by 1-3 clock ticks through the converter.

These failures forced a fundamentally different approach to interfacing with the Z80. Instead of passively watching bus signals, the Arduino actively decodes the Z80's instruction stream and maintains software copies of the CPU's internal state:

Guard-only M1 detection: a timing table (tStates[256]) tells us how many clock cycles each instruction takes; the next memory read after the guard expires is the next opcode fetch
Software PC (softPC): a software copy of the Z80's program counter, immune to address bus lag
Shadow registers: software copies of A, B, C, D, E, H, L, F, and SP, updated by decoding each opcode from z80RAM[softPC]
Pre-writes: memory store instructions write their values directly to z80RAM at opcode detection time, using shadow register values and softPC-derived addresses, because the Z80's physical bus writes go to wrong addresses due to the propagation delay
Deferred writes: for read-modify-write instructions like INC (HL), where pre-writing would cause the Z80 to read an already-modified value and double-apply the operation

The full technical details of this architecture are in the previous post. What matters here is where that post left off: the shadow register system was working, the sector server was serving disk images over WiFi, and partial serial output confirmed that the Z80 was executing real code. What remained was completeness testing, making sure every instruction the Z80 actually executed was tracked correctly in the shadows.

CP/M Boots

The first milestone came faster than expected. After expanding the shadow register switch statement to cover more of the Z80 instruction set (POP instructions, ADD HL with register pairs, DAA (decimal adjust), EX (SP),HL), CP/M booted.

The boot loader loaded all 53 sectors of CPM.SYS from the sector server over WiFi. The BIOS cold boot initialized correctly. And the console printed:

RetroShield CP/M 2.2
56K TPA

a>

A real Z80, running real CP/M 2.2, with 56KB of Transient Program Area, booting from a disk image served over WiFi from a Rust TCP server. The DIR command worked and showed the contents of drive A:

a>dir
A: ZORK1    COM : ZORK1    DAT : ZORK2    COM : ZORK2    DAT

Zork was right there, waiting.

The "Bad Load" Bug

Running ZORK1.COM produced a single line of output and then nothing:

a>zork1
Bad load

"Bad load" is a CP/M CCP (Console Command Processor) error. It means the CCP tried to load the .COM file into the TPA and something went wrong: either a disk read failed, or the CCP's internal logic decided the load was corrupt.

Finding the Root Cause

The CCP loads .COM files by repeatedly calling BDOS function 20 (Read Sequential), advancing the DMA address by 128 bytes after each successful sector read, until the file is fully loaded. The load loop lives in the CCP code at address 0xE6DE. After each BDOS call, it checks whether the DMA address has exceeded the TPA boundary at 0xE000:

E6F5: LD E,A         ; save BDOS return code
E6F6: LD A,H         ; get current DMA high byte
E6F7: SUB E           ; compare against...
E6F8: LD A,H          ; (for SBC below)
E6F9: SBC A,D         ; ...TPA boundary
E6FB: JP NC,E771      ; if past TPA, stop loading

The SBC A,D instruction at E6F9 (opcode 0x9A) subtracts the D register and the carry flag from A. This is a 16-bit comparison implemented as a high-byte subtract-with-borrow after the low-byte subtract at E6F7.

The problem: opcode 0x9A was not in the shadow register tracking. The switch statement had SBC A,A (0x9F), SBC A,B (0x98), and SBC A,C (0x99), but not SBC A,D.

Without tracking, the SBC A,D instruction didn't update shadowF. The carry flag in the shadow still reflected the preceding SUB E instruction, which had set carry=0 (no borrow, since 0x80 - 0x00 = 0x80). But the real Z80 computed SBC A,D with the actual register values and got carry=1 (borrow). When the JP NC,E771 branch came, our shadow said NC=true (carry clear, branch taken) while the Z80 said NC=false (carry set, branch not taken).

SoftPC jumped to the "Bad load" error handler. The real Z80 continued the load loop. From that point on, softPC and the Z80's actual program counter were desynchronized; every subsequent opcode decode was wrong, and the system was effectively running blind.

The Fix

Add the missing instructions. All of them:

// SBC A,r — subtract with carry
case 0x98: { uint16_t r = shadowA - shadowB - (shadowF & FLAG_C ? 1 : 0);
             shadowF = flagsSub8(shadowA, shadowB, r, true);
             shadowA = r & 0xFF; break; }
case 0x99: { /* SBC A,C */ ... }
case 0x9A: { /* SBC A,D */ ... }
case 0x9B: { /* SBC A,E */ ... }
case 0x9C: { /* SBC A,H */ ... }
case 0x9D: { /* SBC A,L */ ... }
case 0x9E: { /* SBC A,(HL) */ ... }

// ADC A,r — add with carry (same gap)
case 0x8A: { /* ADC A,D */ ... }
case 0x8B: { /* ADC A,E */ ... }
case 0x8C: { /* ADC A,H */ ... }
case 0x8D: { /* ADC A,L */ ... }
case 0x8E: { /* ADC A,(HL) */ ... }

After this fix, ZORK1.COM loaded all 68 sectors successfully: 8,704 bytes from DMA address 0x0100 to 0x2300, with every BDOS read returning success.

Zork Starts, Barely

With the load fixed, Zork launched. It read its .DAT file from disk. The copyright text appeared:

ZORK I: The Great Underground Empire
Copyright (c) 1981, 1982, 1983 Infocom, Inc. All rights
reserved.
ZORK is a registered trademark of Infocom, Inc.
Revision 88 / Serial number 840726

And then... nothing. Or rather, something, but at glacial speed. At approximately 18,000 Z80 clock cycles per second, the text took minutes to render. The game was technically running but practically frozen. Typing a command and waiting for a response meant staring at a blank terminal for an eternity.

On a 480MHz Cortex-M7, 18,000 Z80 cycles per second means the Arduino was spending roughly 26,000 of its own CPU cycles on every single Z80 clock tick. Something was catastrophically wrong with the hot loop.

The Performance Crisis

I added a performance counter that measured actual Z80 cycles per second. The numbers were dire: 9,000–18,000 cycles/sec depending on what the Z80 was doing. A real Z80 runs at 2.5–8 MHz. We were three orders of magnitude too slow.

Five bottlenecks were hiding in the hot loop, each one multiplying the others.

Bottleneck 1: A Two-Millisecond Nap on Every Tick

Every clock tick included delayMicroseconds(2), a 2,000-nanosecond delay to let signals settle through the TXB0108 after toggling the clock. The TXB0108's actual propagation delay is about 4–12 nanoseconds. This was a 200x safety margin I'd added early in debugging and never removed.

Fix: Replace with 24 inline NOP instructions. At 480MHz, each NOP is ~2ns, giving roughly 50ns of settle time, still 4x more than the TXB0108 needs, but 40x faster than the delay.

inline void __attribute__((always_inline)) busSettle() {
    __asm volatile("nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n"
                   "nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n"
                   "nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n");
}

Bottleneck 2: Flipping 8 Pins on Every Single Tick

This was the real killer. At the end of every cpu_tick() call, setDataBusInput() was called to tri-state the data bus pins, switching all 8 data lines from output to input mode. Then at the start of the next memory read, setDataBusOutput() switched them all back. Each direction change went through the Arduino HAL pinMode() function 8 times.

On the STM32H747 with the mbed-based Arduino core, each pinMode() call involves HAL abstraction layers, pin table lookups, and clock configuration checks. Eight calls took approximately 16–32 microseconds. This was happening on every single clock tick, both directions, 16 pinMode() calls per tick.

The irony: this direction switching was completely unnecessary. Since all Z80 bus writes are suppressed (pre-writes handle memory stores in software), the data bus never needs to read anything from the Z80 during normal operation. The bus can stay in output mode permanently.

Fix: Remove the per-tick setDataBusInput() call entirely. For the rare cases where direction changes are still needed (certain IO operations), replace pinMode() with direct GPIO MODER register writes:

#define GPIO_SET_OUTPUT(port, pin) \
    ((port)->MODER = ((port)->MODER & ~(3U << ((pin)*2))) \
                     | (1U << ((pin)*2)))
#define GPIO_SET_INPUT(port, pin) \
    ((port)->MODER = ((port)->MODER & ~(3U << ((pin)*2))))

One register write per pin instead of a full HAL function call.

Bottleneck 3: Arduino HAL in the Hot Loop

The Arduino digitalRead() and digitalWrite() functions are convenient abstractions, but on the STM32H747 they carry significant overhead: pin number lookups, port mapping tables, multiple function calls per operation. The original RetroShield code for the Mega 2560 used direct AVR port registers (PORTA, PORTL) for fast parallel I/O. On the Giga, the pins are scattered across GPIO ports B, E, G, H, I, J, and K (no single-register solution), but direct register access is still orders of magnitude faster than the HAL.

Fix: Map every Arduino pin to its STM32H747 GPIO port and pin number, then replace all hot-path I/O with direct register access.

The clock signal (toggled every tick) went from ~200ns per call through HAL to ~4ns via the BSRR (Bit Set/Reset Register):

// Before
#define CLK_HIGH  digitalWrite(uP_CLK, HIGH)

// After — single atomic register write
#define CLK_HIGH  (GPIOK->BSRR = (1U << 2))    // PK2
#define CLK_LOW   (GPIOK->BSRR = (1U << 18))   // PK2 reset

The BSRR register is an elegant STM32 feature: bits [15:0] set outputs high, bits [31:16] set outputs low, and the entire operation is atomic, so no read-modify-write cycle is needed.

For the address bus (16 pins read every memory cycle), three GPIO IDR (Input Data Register) reads replace sixteen individual digitalRead() calls:

inline uint16_t readAddress() {
    uint32_t jIDR = GPIOJ->IDR;
    uint32_t kIDR = GPIOK->IDR;
    uint32_t gIDR = GPIOG->IDR;

    uint16_t addr = 0;
    if (jIDR & (1U << 12)) addr |= (1 << 0);   // A0 = PJ12
    if (gIDR & (1U << 13)) addr |= (1 << 1);   // A1 = PG13
    // ... 14 more bit extractions
    return addr;
}

For the data bus (8 pins written every memory read cycle), pins sharing the same GPIO port are combined into a single BSRR write. Port I has three data bus pins, so they get folded into one register operation:

inline void writeDataBus(byte val) {
    GPIOE->BSRR = (val & 0x01) ? (1U << 4) : (1U << 20);
    GPIOK->BSRR = (val & 0x02) ? (1U << 0) : (1U << 16);
    GPIOB->BSRR = (val & 0x04) ? (1U << 2) : (1U << 18);
    GPIOH->BSRR = (val & 0x08) ? (1U << 15) : (1U << 31);

    // Port I: combine 3 data bus pins into one write
    uint32_t iBSRR = 0;
    iBSRR |= (val & 0x10) ? (1U << 13) : (1U << 29);  // PI13
    iBSRR |= (val & 0x40) ? (1U << 10) : (1U << 26);  // PI10
    iBSRR |= (val & 0x80) ? (1U << 15) : (1U << 31);  // PI15
    GPIOI->BSRR = iBSRR;

    GPIOG->BSRR = (val & 0x20) ? (1U << 10) : (1U << 26);
}

Bottleneck 4: USB Serial Polling Every Tick

The MC6850 ACIA emulation checked Serial.available() on every clock tick to detect incoming keystrokes. On the Giga, USB CDC serial operations are expensive; each call may involve USB stack processing. At 700K ticks/sec, checking every tick means 700,000 USB stack queries per second.

Fix: Check every 256 ticks. That's still a 2,700 Hz polling rate, more than fast enough for interactive typing, and it eliminates 99.6% of the USB overhead.

if ((clock_cycle_count & 0xFF) == 0) {
    if (!CONTROL_RTS_STATE && Serial.available()) {
        reg6850_STATUS |= 0b00000001;   // RDRF set
        if (CONTROL_RX_INT_ENABLE) { INT_N_LOW; }
    }
}

Bottleneck 5: I-Cache Thrashing from Forced Inlining

The cpu_tick() function is around 1,200 lines of code, dominated by the shadow register tracking switch statement with hundreds of cases. It was marked inline __attribute__((always_inline)), which forces the compiler to inline the entire function body into loop().

The STM32H747's instruction cache is 16KB. Inlining a 1,200-line function creates a binary blob that doesn't fit, causing constant cache misses. Every iteration of the main loop refills the I-cache from flash.

Fix: Change to __attribute__((noinline)). The function call overhead (a few nanoseconds for the branch and return) is negligible compared to the cache thrashing cost. This change also reduced the compiled binary by ~9KB, from 284KB to 276KB.

void __attribute__((noinline)) cpu_tick() {
    // ... 1,200 lines of bus interface and shadow tracking
}

The Result

Metric	Before	After
Z80 cycles/sec	~9,000	~690,000
Effective Z80 clock	~0.009 MHz	~0.69 MHz
Binary size	284 KB	276 KB
Time per Z80 tick	~111 µs	~1.4 µs

A 75x speedup. The system went from roughly 50,000 Cortex-M7 cycles per Z80 tick down to about 700. Enough for Zork to be fully interactive.

Network Reconnection

With the performance problem solved, a new issue appeared: the TCP connection to the sector server dropped during long idle periods. Zork is a text adventure; the player types a command, the game responds, and then nothing happens until the next command. During that idle time (which could be minutes while you think about whether to go north or east), the WiFi TCP socket would quietly die. The next disk operation would fail with "Bad Sector."

The fix was automatic reconnection logic. Before each disk operation, ensureServerConnection() checks if the TCP socket is still alive. If not, it reconnects to the sector server, re-opens the disk image file that was previously open, and re-seeks to the last position, all transparently, so the Z80 never knows the connection dropped.

bool ensureServerConnection() {
    if (server.connected()) return true;

    Serial.println("[NET] Connection lost, reconnecting...");
    server.stop();

    for (int attempt = 0; attempt < 3; attempt++) {
        if (server.connect(SERVER_IP, SERVER_PORT)) {
            Serial.println("[NET] Reconnected to server");
            if (diskFileOpen && diskActiveFile.length() > 0) {
                netSendFileCommand(DISK_CMD_OPEN_RW, diskActiveFile);
                uint8_t status = netReadStatus();
                if (status != 0) { diskFileOpen = false; return false; }
                // Re-seek to last known position
                uint8_t seekCmd[4];
                seekCmd[0] = DISK_CMD_SEEK;
                seekCmd[1] = diskSeekPos & 0xFF;
                seekCmd[2] = (diskSeekPos >> 8) & 0xFF;
                seekCmd[3] = (diskSeekPos >> 16) & 0xFF;
                server.write(seekCmd, 4);
                netReadStatus();
            }
            return true;
        }
        delay(500);
    }
    return false;
}

Your browser does not support the video tag.

Playing Zork

With all the pieces in place (shadow registers covering every instruction CP/M and Zork use, GPIO registers replacing Arduino HAL calls, network reconnection handling idle timeouts), it was time to play.

Here's a complete boot-to-gameplay session, captured from the serial terminal:

OK (192.168.0.75)
Server:     OK (192.168.0.248:9000)
Boot:       OK (512 bytes loaded)

Starting Z80...

RetroShield Z80 Boot Loader
Copyright (c) 2025 Alex Jokela, tinycomputers.io

Loading CPM.SYS.....................................................
Boot complete.

RetroShield CP/M 2.2
56K TPA

a>zork1
ZORK I: The Great Underground Empire
Copyright (c) 1981, 1982, 1983 Infocom, Inc. All rights
reserved.
ZORK is a registered trademark of Infocom, Inc.
Revision 88 / Serial number 840726

West of House
You are standing in an open field west of a white house, with
a boarded front door.
There is a small mailbox here.

>open mailbox
Opening the small mailbox reveals a leaflet.

>take leaflet
Taken.

>go south
South of House
You are facing the south side of a white house. There is no
door here, and all the windows are boarded.

>go east
Behind House
You are behind the white house. A path leads into the forest
to the east. In one corner of the house there is a small
window which is slightly ajar.

>open window
With great effort, you open the window far enough to allow
entry.

>enter
Kitchen
You are in the kitchen of the white house. A table seems to
have been used recently for the preparation of food. A passage
leads to the west and a dark staircase can be seen leading
upward. A dark chimney leads down and to the east is a small
window which is open.
On the table is an elongated brown sack, smelling of hot
peppers.
A bottle is sitting on the table.
The glass bottle contains:
  A quantity of water

Every command produces the correct response, at interactive speed. The text appears as fast as you'd expect from a terminal session, with no perceptible delay between pressing Enter and seeing the game's response.

How It All Fits Together

Here's what happens when you type open mailbox at the Zork prompt, end to end:

Each keystroke arrives over USB serial. Every 256 Z80 clock ticks, the Arduino checks Serial.available(), finds a character, and sets the MC6850 ACIA status register's RDRF bit.
The Z80 is spinning in the BIOS console input loop, repeatedly executing IN A,(0x80) to check the ACIA status register. Our shadow register system detects each IN instruction at M1 time, calls handle_io_read(0x80), and drives the status byte onto the data bus during the IO cycle.
When RDRF is set, the Z80 executes IN A,(0x81) to read the character. We return the byte from Serial.read(), and shadowA gets updated to match.
The BIOS echoes the character by executing OUT (0x81),A. We detect this at M1 time, use shadowA for the data value, and call Serial.write().
When the user presses Enter, the CCP passes the command to Zork. Zork parses it and starts executing game logic, hundreds of thousands of Z80 instructions manipulating its internal data structures.
When Zork needs to read from its .DAT file, the BIOS executes a sequence of OUT instructions to set up the disk operation: filename characters to port 0x13, seek position to ports 0x14/0x15/0x19, DMA address to ports 0x16/0x17, and a block read command to port 0x18. Each OUT is intercepted by the shadow register system and forwarded to the sector server over WiFi.
The sector server reads 128 bytes from the disk image file, sends them back over TCP. The Arduino writes them directly into z80RAM at the DMA address.
Zork processes the data, generates response text, and prints it character by character through the ACIA, each character going through the same OUT (0x81),A → shadowA → Serial.write() path.

Every single one of these operations relies on the shadow register system. The Z80 has no idea the Arduino can't see half its bus signals. It thinks it's talking to normal memory and I/O ports. The Arduino, meanwhile, is running a parallel simulation of the Z80's register state, intercepting every instruction, and making the illusion seamless.

The Full Architecture

For reference, here's the complete technical stack:

Hardware: - Arduino Giga R1 WiFi (STM32H747, 480MHz Cortex-M7, 1MB SRAM, WiFi) - RetroShield Z80 (real Zilog Z80 CPU, 5V logic) - Custom level converter PCB (nine TXB0108PW, design details here)

Z80 Memory: - 64KB byte array in Giga's internal SRAM (uint8_t z80RAM[65536])

Bus Interface (direct STM32 GPIO registers): - Clock: GPIOK pin 2 (BSRR for set/clear) - Address: 3 IDR reads (GPIOJ, GPIOK, GPIOG) → 16-bit extraction - Data: 6 BSRR writes (GPIOE, GPIOK, GPIOB, GPIOH, GPIOI combined, GPIOG) - Control: MREQ via GPIOK pin 7, WR via GPIOE pin 6

Software Architecture: - Guard-only M1 detection with tStates[256] timing table - Software PC tracking (softPC) for all branch types including conditional - Shadow registers (A, B, C, D, E, H, L, F, SP) with full ALU flag computation - Pre-writes for all memory store instructions - Deferred writes for read-modify-write instructions (INC/DEC (HL), CB prefix on (HL)) - IO handling at M1 time using shadow register values

Disk I/O: - Rust TCP sector server on local network (192.168.0.248:9000) - 128-byte CP/M sector transfers over WiFi - Automatic reconnection with file re-open and seek restore

Console I/O: - Emulated MC6850 ACIA on ports 0x80/0x81 - USB CDC serial at 115200 baud - Interrupt-driven receive with throttled polling (every 256 ticks)

Pin Mapping Reference

For anyone attempting a similar project, here's the complete mapping from Arduino digital pins to STM32H747 GPIO ports. This is essential for the direct register access that makes the performance optimization possible:

Function	Arduino Pin	STM32 Port/Pin
CLK	D52	PK2
MREQ_N	D41	PK7
WR_N	D40	PE6
IORQ_N	D39	PI14
INT_N	D50	PI11
RESET_N	D38	PJ7
Data bit 0	D49	PE4
Data bit 1	D48	PK0
Data bit 2	D47	PB2
Data bit 3	D46	PH15
Data bit 4	D45	PI13
Data bit 5	D44	PG10
Data bit 6	D43	PI10
Data bit 7	D42	PI15
Addr A0	D22	PJ12
Addr A1	D23	PG13
Addr A2	D24	PG12
Addr A3	D25	PJ0
Addr A4	D26	PJ14
Addr A5	D27	PJ1
Addr A6	D28	PJ15
Addr A7	D29	PJ2
Addr A8	D37	PJ6
Addr A9	D36	PK6
Addr A10	D35	PJ5
Addr A11	D34	PK5
Addr A12	D33	PJ4
Addr A13	D32	PK4
Addr A14	D31	PJ3
Addr A15	D30	PK3

The address bus pins are spread across three GPIO ports (J, G, K), so a 16-bit address read requires three IDR register reads and individual bit extraction. Not ideal, but still orders of magnitude faster than sixteen digitalRead() calls.

What's Next

The immediate win would be using the Giga's 8MB SDRAM as a disk cache. Download entire disk images over WiFi at boot, then serve all disk I/O from memory. No network latency, no TCP overhead, no reconnection logic needed. CP/M running at SRAM speed on a RAM disk, faster than any physical media the Z80 ever had access to.

There's also the question of the TXB0108 itself. The level converter PCB works, but three of its nine ICs are essentially decorative; the signals they're supposed to translate (IORQ_N, RD_N, and data bus Z80→Arduino during IO) are broken, and the software works around them. A v0.2 of the board replaces 5 of the 9 TXB0108s with purpose-matched ICs that don't rely on auto-direction sensing:

74LVC541 (U1–U3): Unidirectional buffers for the address bus and control inputs (MREQ_N, IORQ_N, RD_N, WR_N). VCC at 3.3V with 5V-tolerant inputs. They simply translate 5V→3.3V with no direction ambiguity. This eliminates the stuck-HIGH failures on IORQ_N and RD_N entirely.
74AHCT541 (U4): Unidirectional buffer for control outputs (CLK, RESET_N, INT_N, NMI_N). VCC at 5V with TTL-compatible inputs that accept 3.3V drive levels, providing clean 3.3V→5V translation.
SN74LVC4245A (U5): Bidirectional transceiver for the data bus, with an explicit DIR pin controlled by a Giga GPIO. No more auto-sensing guesswork; the firmware tells the chip which side is driving, so Z80→Arduino data is visible during IO writes for the first time.
TXB0108 (U6–U9): Retained for the remaining 40 channels of pass-through GPIO, where auto-direction sensing works fine.

The firmware payoff is substantial: the entire shadow register architecture (roughly 1,300 lines of opcode tracking, softPC maintenance, pre-writes, and deferred write logic) could be replaced by a single digitalWrite() to flip the data bus direction pin. That's a lot of complexity removed for one additional GPIO wire.

But there's something satisfying about the current approach. The shadow register system transforms a passive bus controller into something that understands the Z80's instruction stream at a semantic level. The Arduino doesn't just shuttle bytes; it knows what the Z80 is thinking. And if the goal is to play Zork in the Great Underground Empire on real 1980s hardware controlled by a modern microcontroller over WiFi, well, we're there.

A note on tooling: this project would have taken considerably longer without Claude Code. The debugging cycle for a project like this (where you're staring at Z80 opcode tables, cross-referencing flag behavior across hundreds of instructions, and hunting for one wrong carry bit in a 2,600-line Arduino sketch) is brutal. Claude Code served as a tireless pair programmer throughout the process, helping trace through instruction semantics, spotting missing opcodes in the shadow register implementation, working through the GPIO register mappings for the STM32H747, and iterating on performance optimizations. The feedback loop that would normally stretch across days of manual datasheet cross-referencing compressed into hours.

Source Code

All source code, firmware, and hardware design files for this project are open source:

retroshield-z80-cpm-giga: Arduino Giga R1 firmware, CP/M system files, and disk image (BSD 3-Clause)
retroshield-sector-server: Rust TCP sector server for WiFi-based disk I/O (BSD 3-Clause)
retroshield-level-shifter-pcb: KiCad design files, Gerber files, BOM, and schematic for the level converter shield (CC BY-SA 4.0)

This is the third post in the Arduino Giga R1 + RetroShield Z80 series:

My Experience Using Fiverr for Custom PCB Design: A $468 Arduino Giga Shield, designing the level converter
Porting CP/M to the Arduino Giga R1: When Level Converters Fight Back, the hardware stack, TXB0108 failures, shadow registers, and sector server
Playing Zork on a Real Z80 (this post), getting CP/M to boot, the "Bad load" bug, 75x performance optimization, and interactive Zork gameplay

Porting CP/M to the Arduino Giga R1: When Level Converters Fight Back

A.C. Jokela — Sat, 14 Feb 2026 21:00:00 GMT

My previous CP/M build runs great. A real Z80 on a RetroShield, DRAM shield for 64KB, SD card for disk images, all sitting on an Arduino Mega 2560. It boots CP/M, runs Zork, the works. So naturally I decided to make my life harder.

The Arduino Giga R1 WiFi is a significantly more powerful board: a dual-core STM32H747 running at 480MHz, 1MB of internal SRAM, 8MB of SDRAM, and built-in WiFi. Where the Mega's 16MHz AVR crawled through bus cycles, the Giga could theoretically fly. And all that internal RAM means we can ditch the KDRAM2560 DRAM shield entirely, leaving just a 64KB byte array in SRAM.

There was just one problem. The Giga runs at 3.3V logic. The Z80 runs at 5V. And as I'd learn the hard way, bridging that gap would consume more debugging hours than everything else combined.

This post documents the port: the hardware stack, the architectural pivot to WiFi-based disk I/O, the level converter nightmare, the shadow register workaround that saved the project, and the Rust sector server that ties it all together. If you want the backstory on the custom level converter PCB, designed by Elijah on Fiverr, that's a separate post.

The Hardware Stack

The upgraded system has fewer physical components than the Mega version, but more going on under the hood.

Component	Mega Version	Giga Version
Processor	ATmega2560, 16MHz	STM32H747, 480MHz Cortex-M7
Logic Level	5V native	3.3V (needs level converter)
Z80 RAM	KDRAM2560 DRAM shield	64KB byte array in SRAM
Bus I/O	AVR port registers (parallel)	digitalRead/Write (per-pin)
Disk Storage	SD card (software SPI)	WiFi to sector server
Extra Hardware	DRAM shield + SD adapter	Level converter board only

The RetroShield Z80 plugs in the same way; it uses the same physical pin positions. The level converter board sits between the Giga and the RetroShield, translating all bus signals between 3.3V and 5V. The board uses TXB0108 bidirectional level converters, which sense the drive direction automatically.

At least, that's what they're supposed to do.

CP/M Memory Map

The Z80 sees the same 64KB address space as on the Mega:

0000-00FF   Page Zero (jump vectors, FCBs, command buffer)
0100-DFFF   TPA (Transient Program Area) — 56KB
E000-E7FF   CCP (Console Command Processor)
E800-F5FF   BDOS (Basic Disk Operating System)
F600-FFFF   BIOS (Basic I/O System)

On the Mega, this lived in the KDRAM2560's dynamic RAM with its complex refresh timing. On the Giga, it's just:

byte z80RAM[65536];

One line. The Giga's 1MB of internal SRAM makes the entire DRAM shield unnecessary.

WiFi Instead of SD

The original plan was to keep the SD card. The Mega version used software SPI on pins 4-7 since the RetroShield claims the hardware SPI pins. On the Giga, the RetroShield still claims all 76 digital pins, but this time there are no spare analog pins conveniently routed for software SPI either.

The initial idea was to wire a MicroSD adapter to the analog pins. But that meant more custom wiring on top of the already-custom level converter board. And anyone trying to replicate this project would need to solder yet another adapter.

Then it hit me: the Giga has WiFi built in. Why not serve disk images over the network?

The more I thought about it, the more sense it made:

No additional hardware. WiFi is built into the Giga. Zero extra wiring.
Better reproducibility. The project already requires a custom level converter. Adding another custom wiring job makes it harder for others to build.
The sector server is just software. Anyone can download and run a binary. Compare that to soldering an SD adapter to analog pins.
It plays to the Giga's strengths. If you're upgrading from a Mega, you might as well use what makes the Giga special: WiFi and RAM.
Future potential. The 8MB SDRAM could cache entire disk images downloaded over WiFi at boot. CP/M on a RAM disk, faster than any physical media the Z80 ever had access to.

The tradeoff is that the system is no longer self-contained. It needs a WiFi network and a computer running the sector server. For a project that already requires a custom level converter PCB, this felt acceptable.

The Level Converter Problem

This is where the project nearly died.

The TXB0108 is a popular bidirectional level converter. It uses auto-direction sensing: whichever side drives a signal stronger "wins," and the converter translates accordingly. This works well for simple I2C and SPI signals where direction is clear.

It does not work well for a Z80 bus.

Signal-by-Signal Breakdown

I built a pin diagnostic sketch to test each signal through the level converter. Here's what I found:

Signal	Pin	Expected	Actual	Status
MREQ_N	41	Toggles on memory access	Toggles correctly	Working
WR_N	40	Toggles on writes	Memory writes only	Partial
RD_N	53	Toggles on reads	Stuck HIGH always	Broken
IORQ_N	39	Toggles on I/O access	Stuck HIGH always	Broken
Address Bus	22-37	16-bit address	All bits correct	Working
Data Bus (A→Z80)	42-49	Arduino drives data	Works	Working
Data Bus (Z80→A)	42-49	Z80 drives data	Memory writes only	Partial

Two signals completely stuck. Two signals working only half the time. The auto-direction sensing that makes the TXB0108 convenient is exactly what makes it unreliable here; the Z80's bus signals have complex timing relationships where drive strength varies throughout the cycle.

RD_N: Permanently Stuck

RD_N on pin 53 never toggles. It reads HIGH regardless of what the Z80 is doing. Pin 53 is the hardware SPI SCK pin on the Mega, and may have internal pull-ups or other conflicts on the Giga's STM32. Combined with the TXB0108's direction sensing, the signal simply can't get through.

The fix is trivial once you realize it: during any bus cycle, the Z80 is either reading or writing. They're mutually exclusive. So:

#define STATE_RD_N (!STATE_WR_N)

If WR_N isn't asserted, it must be a read. This works for all standard Z80 bus operations.

IORQ_N: The Big One

IORQ_N on pin 39 is also stuck HIGH. This is the signal that tells us the Z80 wants to talk to a peripheral: console I/O, disk I/O, everything. Without it, we have no way to detect I/O operations through the bus.

But we have something the bus doesn't know about: we control the Z80's memory. Every byte the Z80 fetches comes from z80RAM[], which we serve. We can read the opcode stream and know exactly what instruction the Z80 is executing, including OUT (n), A (opcode 0xD3) and IN A, (n) (opcode 0xDB).

So instead of watching for IORQ_N to go low, we watch for the Z80 to fetch an I/O instruction from memory.

Data Bus: Invisible During I/O OUT

This was the subtlest failure. During OUT (n), A, the Z80 puts the A register value on the data bus. We should be able to read it. But we can't.

The TXB0108 latches the last strongly-driven value. Since the Arduino drives the data bus during memory reads (pushing 3.3V through the converter to the Z80's 5V side), the converter's direction gets stuck. When the Z80 tries to drive data back during an I/O write, its 5V output can't overcome the converter's latched direction.

I confirmed this by sampling the data bus at every clock tick during an OUT cycle. It showed 0x80 (the last value the Arduino had driven, a port number) at every single tick. Zero variation. The Z80's output was completely invisible.

WR_N: Only Works Sometimes

WR_N toggles correctly during memory write cycles but never during I/O write cycles. The timing or drive strength during I/O is just different enough that the converter can't track it.

This meant we couldn't use WR_N to detect when an I/O write was complete either. Every signal we'd normally use for I/O detection was either stuck or unreliable.

Shadow Register Tracking

The solution to the data bus problem is to never read the data bus during I/O at all. Instead, we maintain a shadow copy of the Z80's A register by watching the opcode stream.

Since we serve every byte the Z80 reads from z80RAM[], we can decode the instruction stream in real time. When we see LD A, 0x03 (opcode 0x3E 0x03), we set shadowA = 0x03. When we later see OUT (0x10), A (opcode 0xD3 0x10), we already know A contains 0x03, so there's no need to read the bus.

M1 Detection

The first challenge is knowing when the Z80 is fetching an opcode (M1 cycle) versus reading data. We detect M1 by watching for the first MREQ-active read after a MREQ-inactive cycle, the rising-to-falling edge of MREQ activity:

bool mreq_active = !digitalRead(uP_MREQ_N);

if (mreq_active && !prevMREQ_active && opcodeSkip == 0) {
    uint8_t opcode = z80RAM[uP_ADDR];
    // This is an M1 fetch — decode the instruction
}

The opcodeSkip Counter

After M1, the Z80 runs a refresh cycle (which reuses the address bus; when the I register is 0 after reset, refresh addresses overlap with boot code at 0x0000+). If we mistook a refresh cycle for another M1, we'd corrupt the shadow registers by "decoding" whatever data happened to be at the refresh address.

The fix is a 256-entry lookup table that tells us how many MREQ-active read cycles to skip after each opcode:

static const uint8_t skipCount[256] = {
    // 0x00-0x0F: NOP=1, LD BC,nn=3, ...
    1, 3, 1, 1, 1, 1, 2, 1, 1, 1, 2, 1, 1, 1, 2, 1,
    // ... 256 entries covering every Z80 opcode
};

A 1-byte instruction like NOP gets skip=1 (refresh only). A 3-byte instruction like LD HL, nn gets skip=3 (refresh + 2 operand reads). I/O instructions get skip=0 because their skipping is handled by the I/O state machine. After each M1, we set opcodeSkip = skipCount[opcode] and decrement it on each subsequent MREQ-active read cycle.

Register Tracking

We don't need to track every Z80 register, just enough to know what value A holds when an OUT happens. The BIOS uses a relatively small set of instructions to load registers before I/O:

switch (opcode) {
    // === IO Instructions ===
    case 0xD3: {  // OUT (n), A
        uint8_t port = z80RAM[uP_ADDR + 1];
        handle_io_write(port, shadowA);
        break;
    }
    case 0xDB: {  // IN A, (n)
        uint8_t port = z80RAM[uP_ADDR + 1];
        ioResponse = handle_io_read(port);
        shadowA = ioResponse;  // IN updates A
        break;
    }

    // === A register tracking ===
    case 0x3E: shadowA = z80RAM[uP_ADDR + 1]; break; // LD A, n
    case 0xAF: shadowA = 0; break;                     // XOR A
    case 0x79: shadowA = shadowC; break;                // LD A, C
    case 0x78: shadowA = shadowB; break;                // LD A, B
    case 0x7C: shadowA = shadowH; break;                // LD A, H
    case 0x7D: shadowA = shadowL; break;                // LD A, L
    case 0x7E: shadowA = z80RAM[(shadowH << 8) | shadowL]; break;
    case 0xE6: shadowA &= z80RAM[uP_ADDR + 1]; break;  // AND n
    case 0xF6: shadowA |= z80RAM[uP_ADDR + 1]; break;  // OR n
    case 0x2F: shadowA = ~shadowA; break;                // CPL
    case 0x3C: shadowA++; break;                         // INC A
    case 0x3D: shadowA--; break;                         // DEC A

    // === B, C, H, L tracking (needed because A loads from them) ===
    case 0x06: shadowB = z80RAM[uP_ADDR + 1]; break;  // LD B, n
    case 0x0E: shadowC = z80RAM[uP_ADDR + 1]; break;  // LD C, n
    case 0x21: {  // LD HL, nn
        shadowL = z80RAM[uP_ADDR + 1];
        shadowH = z80RAM[uP_ADDR + 2];
        break;
    }
    // ... plus INC/DEC HL, LD between registers, etc.
}

This isn't a full Z80 emulator; it's just enough to track register flow from loads to I/O instructions. If the BIOS uses an instruction we don't track, shadowA will be wrong and the I/O operation will get bad data. But the CP/M BIOS is a known codebase, so we can enumerate exactly which instructions it uses and make sure they're covered.

IO State Machine

For OUT, we handle the write immediately when we detect 0xD3 at M1, since we already know the port (from RAM) and the data (from shadowA). Then we let the skip counter consume the remaining machine cycles.

For IN, it's trickier because the Z80 needs to actually read our response off the data bus. We use a small state machine:

IO_IDLE → detect 0xDB → IO_IN_PENDING (call handle_io_read, get response)
IO_IN_PENDING → opcodeSkip reaches 0 → IO_IN_DRIVING (drive response on data bus)
IO_IN_DRIVING → next MREQ goes active → IO_IDLE (release bus, resume normal)

During IO_IN_DRIVING, we keep the response byte on the data bus and ignore other processing until the Z80's next M1 fetch (signaled by MREQ going active again).

The Sector Server

With the Arduino side handling bus-level I/O through shadow registers, the disk I/O ports translate to network messages. The Z80 BIOS writes a filename character-by-character to port 0x13, writes seek bytes to ports 0x14/0x15/0x19, sets the DMA address via ports 0x16/0x17, then triggers a block read/write on port 0x18. The Arduino accumulates this state, then forwards the operation to the sector server over TCP.

Protocol

The server speaks a simple binary protocol that mirrors the BIOS port commands:

Command	Byte	Payload	Response
OPEN_READ	0x01	filename\0	status
CREATE	0x02	filename\0	status
OPEN_APPEND	0x03	filename\0	status
SEEK_START	0x04	(none)	status
CLOSE	0x05	(none)	status
DIR	0x06	(none)	status + listing\0
OPEN_RW	0x07	filename\0	status
SEEK	0x08	3 bytes LE offset	status
READ_BLOCK	0x10	(none)	status + 128 bytes
WRITE_BLOCK	0x11	128 bytes	status

Status is a single byte: 0x00 for OK, 0x01 for error. Block size is 128 bytes, a CP/M sector.

Implementation

The server is written in Rust with minimal dependencies (just socket2 for SO_REUSEADDR). It started single-threaded, which worked fine until the Giga crashed and rebooted. The old TCP connection would hang in the server's blocking read_exact(), and the Giga's new connection attempt would queue indefinitely. Classic deadlock.

The fix was threaded connections with timeouts:

for stream in listener.incoming() {
    match stream {
        Ok(stream) => {
            let base_dir = Arc::clone(&base_dir);
            thread::spawn(move || {
                handle_client(stream, &base_dir);
            });
        }
        Err(e) => eprintln!("[!] Accept error: {}", e),
    }
}

Each client gets its own thread. The accept loop never blocks. Read timeouts (30s mid-command, 300s idle) automatically drop dead connections. SO_REUSEADDR lets the server restart instantly without port conflicts.

The server also sanitizes filenames (rejecting path traversal and special characters) and tracks session metrics:

Session Summary
---------------
Duration:        00:00:00
Commands:        11
Files opened:    2
Seeks:           1
Sectors read:    5
Sectors written: 1
Bytes read:      640 (640 B)
Bytes written:   128 (128 B)
Errors:          0

Running It

# Build
cd sector_server && cargo build --release

# Serve CP/M files on port 9000
./sector_server/target/release/sector_server ./kz80_cpm 9000

The directory needs boot.bin, CPM.SYS, and the disk images (A.DSK, B.DSK, etc.).

Proof of Concept

Before wiring up the full shadow register machinery, I wrote a minimal POC sketch that tests just the WiFi + sector server communication. It connects, opens files, reads blocks, seeks, and closes, verifying the network layer end-to-end without any Z80 involvement.

All 8 tests passed:

=== Sector Server POC ===

WiFi: connecting to TP-Link_A8A8 ... OK (192.168.0.75)
Server: connecting to 192.168.0.248:9000 ... OK

--- Test 1: OPEN_READ boot.bin ---
  Status: OK
--- Test 2: READ_BLOCK (128 bytes) ---
  Status: OK
  Data:
F3 31 00 04 3E 03 D3 80 3E 15 D3 80 21 83 00 CD
7B 00 21 43 01 CD 70 00 3E 01 D3 10 DB 11 E6 02
--- Test 3: READ_BLOCK (next 128 bytes) ---
  Status: OK
  Data:
23 18 F8 0D 0A 52 65 74 72 6F 53 68 69 65 6C 64
20 5A 38 30 20 42 6F 6F 74 20 4C 6F 61 64 65 72
--- Test 4: CLOSE ---
  Status: OK
--- Test 5: OPEN_RW A.DSK ---
  Status: OK
--- Test 6: SEEK offset=6656 ---
  Status: OK
--- Test 7: READ_BLOCK (directory sector) ---
  Status: OK
  Data:
00 5A 4F 52 4B 31 20 20 20 43 4F 4D 00 00 00 44
--- Test 8: CLOSE ---
  Status: OK

=== All tests complete ===

Some things to note: the first bytes of boot.bin are F3 31 00 04, which disassembles to DI; LD SP, 0x0400, the boot loader's first instructions, correct. The second block contains the ASCII string "RetroShield Z80 Boot Loader." And the directory sector from A.DSK shows ZORK1 COM. Zork is on the disk, waiting.

Boot Sequence

When the full sketch runs, the expected boot sequence is:

======================================
RetroShield Z80 CP/M 2.2
Arduino Giga R1 WiFi
======================================

Z80 RAM:    OK (64KB in SRAM)
WiFi:       OK (192.168.0.75)
Server:     OK (192.168.0.248:9000)
Boot:       OK (384 bytes loaded)

Starting Z80...

After "Starting Z80...", the Z80 boot loader runs. It opens CPM.SYS via the sector server, loads the CCP and BDOS into memory at 0xE000, jumps to the BIOS cold boot at 0xF600, and if everything works, prints a banner and the A> prompt.

What's Next

The WiFi communication works. The shadow register tracking mechanism works; I've confirmed partial serial output from the Z80 (the ACIA console I/O goes through the same shadow register path). The instruction skip counter prevents refresh cycle confusion. All the pieces are in place.

What remains is completeness testing. The shadow register tracking needs to cover every instruction the BIOS and CCP actually use. If the Z80 executes an instruction that modifies A through a path we don't track (say, a POP AF or EX AF, AF'), the shadow will be wrong and the next OUT will send garbage. The fix is straightforward (add more cases to the switch statement) but requires methodical testing.

There's also the 8MB SDRAM sitting unused on the Giga. Once CP/M boots reliably, the obvious next step is downloading entire disk images into SDRAM over WiFi at startup. At that point, all disk I/O becomes memory-mapped, with no network latency and no TCP overhead. CP/M running at memory speed on a RAM disk, served from a real Z80 that thinks it's talking to a floppy drive.

Once the project is stable and CP/M boots reliably, I plan to open-source the full KiCad PCB design files for the level converter shield, along with the Arduino sketch and sector server. The level converter board uses nine TXB0108PW ICs in TSSOP-20 packages to translate all 72 signals between the Giga's 3.3V and the RetroShield's 5V. It's a straightforward two-layer design that anyone could get fabricated.

The debugging journey from "IORQ_N is stuck" to "let's just decode the entire instruction stream in software" was not the path I expected to take. But it turned a level converter limitation into something arguably more interesting: a system where the Arduino doesn't just babysit the Z80's bus signals, but understands what the Z80 is thinking.

Part 2: Implementing Sampo on the ULX3S FPGA

A.C. Jokela — Mon, 02 Feb 2026 18:00:00 GMT

After designing the Sampo RISC architecture on paper (complete with a working assembler and emulator) it's time to bring it to life in silicon. Or at least, in programmable logic. This post documents the hardware selection and implementation planning for synthesizing Sampo on an FPGA.

The Story So Far

If you haven't read Part 1 of this series, here's the quick version: Sampo is a 16-bit RISC CPU designed to bridge the gap between clean RISC design principles and Z80-friendly features. It has 16 general-purpose registers, ~66 instructions, port-based I/O, block operations (LDIR, LDDR), alternate registers for fast interrupt handling, and hardware multiply/divide.

The project already includes working tools written in Rust:

sasm - A full assembler
semu - An emulator with TUI debugger (step, breakpoints, memory inspection)

And for hardware implementation, we now have two complete RTL implementations:

Amaranth HDL (/rtl/):

cpu.py, alu.py, decode.py, regfile.py, soc.py
Python-based, excellent for rapid iteration
Generates Verilog for synthesis

AI Assisted Hand-written Verilog (/verilog/rtl/):

cpu.v, alu.v, decode.v, regfile.v, shifter.v, uart.v, ram.v, soc.v
Readable, portable, works with any toolchain
Includes testbenches for Icarus Verilog and Verilator

Now it's time to synthesize it to real hardware.

Choosing an FPGA Platform

The FPGA world is split between proprietary toolchains (Xilinx Vivado, Intel Quartus) and the growing open source ecosystem. For a project like Sampo, where understanding every layer of the stack matters, open source tooling is the clear choice.

Open Source FPGA Options

FPGA Family	Capacity	Toolchain	Maturity
Gowin GW1N/GW2A	1K-55K LUTs	Project Apicula	Good
Lattice iCE40	1K-8K LUTs	Project IceStorm	Excellent
Lattice ECP5	12K-85K LUTs	Project Trellis	Excellent
Xilinx 7-series	10K-200K+ LUTs	Project X-Ray (partial)	Experimental

For Sampo, which estimates at ~1,500-2,500 LUTs for the basic CPU, even the smaller FPGAs have more than enough capacity. But if we want room to grow (adding caches, more peripherals, maybe even multi-core experiments) a larger device makes sense.

The ULX3S Board

The ULX3S is an open hardware development board built around the ECP5 FPGA. It's designed by Radiona.org and has become the de facto standard for open source FPGA development.

Specifications

Component	Specification
FPGA	Lattice ECP5 (LFE5U-85F/45F/12F-6BG381C)
LUTs	12K / 44K / 84K (depending on variant)
USB	FTDI FT231XS (500 kbit JTAG, 3 Mbit serial)
GPIO	56 pins (28 differential pairs), PMOD-compatible
RAM	32 MB SDRAM @ 166 MHz
Flash	4-16 MB Quad-SPI
Storage	microSD slot
LEDs	11 total (8 user, 2 USB, 1 WiFi)
Buttons	7 (4 direction, 2 fire, 1 power)
Audio	3.5mm jack (stereo + digital/composite)
Video	GPDI (HDMI-compatible) with level shifter
Display	Header for 0.96" SPI OLED (SSD1331)
Wireless	ESP32-WROOM-32 (WiFi/Bluetooth, standalone JTAG)
ADC	8 channels, 12-bit, 1 MS/s (MAX11125)
Clock	25 MHz onboard, differential input available
Power	3 switching regulators (1.1V, 2.5V, 3.3V)
Sleep	5 µA standby, RTC wake-up with battery backup
Dimensions	94mm × 51mm

Why ULX3S for Sampo

The ULX3S isn't just an FPGA breakout board; it's a complete system:

32MB SDRAM: Real memory, not just block RAM. Essential for running actual programs.
HDMI output: Video terminal without external hardware.
microSD slot: Load programs, implement a filesystem.
ESP32 co-processor: WiFi-based JTAG debugging from any device.
Buttons and LEDs: Instant I/O for testing without wiring anything.
Audio output: Even supports composite video through the audio jack.

Budget Alternative: Tang Nano 9K

Before we dive into the ULX3S, it's worth mentioning a much cheaper option. The Tang Nano 9K (~$15 on AliExpress) uses a Gowin GW1NR-9 FPGA with 8,640 LUTs, more than enough for Sampo:

8,640 LUTs
64Mbit PSRAM (can serve as the full 64KB address space and then some)
HDMI output for a video terminal
USB-C programming
Fully supported by open-source toolchain (Yosys + nextpnr-gowin)

For initial development and testing, the Tang Nano 9K is hard to beat on price. But the ULX3S offers more I/O, more RAM, and a richer peripheral set, making it the better choice for a more complete Sampo system.

LUT Budget Planning

The Sampo RTL implementation is designed to be compact. Here's the resource breakdown:

Component	Estimated LUTs
16 × 16-bit registers	~256 FFs
ALU (16-bit)	200 - 400
Control logic	500 - 1,000
Instruction decode	300 - 500
Sampo CPU core	~1,500 - 2,500
UART (115200 baud)	200 - 300
SPI controller (SD card)	300 - 500
GPIO controller	200 - 400
Basic system	~2,500 - 4,000
SDRAM controller	500 - 1,000
Instruction cache	1,000 - 2,000
Data cache	1,000 - 2,000
Full system	~6,000 - 10,000

These estimates are based on typical RISC CPU implementations. The actual numbers will depend on optimization choices and synthesis settings.

Variant Recommendations

12K LUTs (ULX3S-12F): Plenty for basic Sampo + peripherals, tight for caches.
45K LUTs (ULX3S-45F): Comfortable. Full CPU with cache, room for experiments.
85K LUTs (ULX3S-85F): Luxurious. Multi-core experiments, extensive peripherals.

Toolchain Setup

The ECP5 toolchain is fully open source:

# macOS (Homebrew)
brew install yosys nextpnr-ecp5 ecpprog fujprog

# Ubuntu/Debian
apt install yosys nextpnr-ecp5 ecpprog

# Amaranth HDL (for our existing RTL)
pip install amaranth amaranth-boards

# Or build FPGA tools from source for latest features
git clone https://github.com/YosysHQ/yosys
git clone https://github.com/YosysHQ/nextpnr
git clone https://github.com/YosysHQ/prjtrellis

Tool Roles

Tool	Purpose
Amaranth	Python-based HDL (generates Verilog)
Yosys	Verilog synthesis (RTL → netlist)
nextpnr-ecp5	Place and route (netlist → bitstream)
Project Trellis	ECP5 bitstream documentation
ecpprog/fujprog	Upload bitstream to board

Amaranth Build Flow

Since Sampo's RTL is written in Amaranth, the build flow starts with Python:

# Generate Verilog from Amaranth
cd rtl/
python -m amaranth generate soc.py > sampo.v

# Then synthesize with standard tools
yosys -p "synth_ecp5 -top sampo_soc -json sampo.json" sampo.v
nextpnr-ecp5 --85k --package CABGA381 \
    --lpf ulx3s.lpf --json sampo.json --textcfg sampo.config
ecppack sampo.config sampo.bit

# Program the board
fujprog sampo.bit

Hand-Written Verilog Implementation

In addition to the Amaranth RTL, we now have a complete ai-assisted hand-written Verilog implementation at /verilog/. While Amaranth can generate Verilog, the auto-generated output isn't particularly readable. The hand-written version is designed for clarity and portability:

verilog/
├── rtl/
│   ├── sampo_pkg.vh   # Opcodes, constants, state definitions
│   ├── alu.v          # 16-bit ALU with all operations
│   ├── shifter.v      # Barrel shifter (1/4/8-bit shifts, rotates)
│   ├── regfile.v      # 16 registers + alternate set (EXX)
│   ├── decode.v       # Instruction decoder
│   ├── cpu.v          # FSM-based CPU core (8 states)
│   ├── ram.v          # 64KB synchronous RAM
│   ├── uart.v         # Simple UART for serial I/O
│   └── soc.v          # Top-level SoC integration
├── tb/
│   ├── alu_tb.v       # ALU unit tests
│   ├── regfile_tb.v   # Register file tests
│   └── sampo_tb.v     # Full system testbench
├── programs/
│   └── hello.hex      # Test program in Verilog hex format
├── Makefile           # Build automation
└── bin2hex.py         # Convert sasm output to Verilog $readmemh format

The Verilog implementation uses an 8-state FSM for the CPU: RESET → FETCH → FETCH_EXT → DECODE → EXECUTE → MEMORY → WRITEBACK → HALTED. This makes timing predictable and debugging straightforward.

Simulation with Icarus Verilog

The Verilog implementation includes a complete Makefile for testing:

cd verilog/

# Run the main simulation (hello world)
make test

# Run ALU unit tests
make test-alu

# Run register file tests
make test-regfile

# Build with Verilator (faster simulation)
make verilate

# View waveforms in GTKWave
make wave

Sample output from make test:

=== Sampo CPU Testbench ===
RAM init file: ../programs/hello.hex

CPU started at PC=0x0100
UART output:
----------------------------------------
Hello, Sampo!
----------------------------------------

Simulation complete:
  Final PC:    0x011E
  Cycles:      847
  UART chars:  14
  Status:      HALTED

The Verilog version is portable to any FPGA toolchain (Xilinx, Intel, Lattice, Gowin) without requiring Amaranth or Python in the build chain.

Implementation Roadmap

With both Amaranth and Verilog implementations complete and tested in simulation, the roadmap is now about bringing them up on hardware.

Phase 1: Core Bring-up ✓ (Complete)

✓ Instruction fetch and decode
✓ ALU operations (all 16 operations)
✓ Barrel shifter (1/4/8-bit shifts, rotates, RCL/RCR)
✓ Register file with alternate set (EXX)
✓ FSM-based CPU core (8 states)
✓ RAM interface (64KB)
✓ UART for serial I/O
✓ SoC integration
✓ Testbenches passing (ALU, regfile, full system)
✓ Hello World runs in simulation

Phase 1.5: FPGA Bring-up (Current)

○ ULX3S pin constraints (.lpf file)
○ Clock setup (PLL from 25MHz)
○ Map UART to FTDI
○ LED heartbeat / debug outputs

Phase 2: Memory System

SDRAM controller for 32MB RAM
Instruction cache (optional but helps timing)
Basic interrupt handling

Phase 3: Peripherals

SPI controller for SD card boot
GPIO controller (buttons, LEDs)
Timer/counter module

Phase 4: Advanced Features

Data cache
MMU for memory protection
HDMI text console (VGA timing → GPDI)
ESP32 WiFi integration for wireless debugging

Recommended Tools & Books

Hardware

Tang Nano 9K FPGA - Budget-friendly FPGA board (~$25 on Amazon, ~$15 on AliExpress)
USB Logic Analyzer - Essential for debugging signals (24MHz, 8 channels)

Books

If you're new to Verilog or FPGA development, these are excellent starting points:

Getting Started with FPGAs by Russell Merrick - Beginner-friendly with Verilog and VHDL examples
Programming FPGAs: Getting Started with Verilog by Simon Monk - Practical hands-on guide
Verilog by Example by Blaine Readler - Concise reference for working engineers

Resources

Sampo on GitHub - Full source including assembler, emulator, and RTL
ULX3S GitHub - Schematics, examples, documentation
Project Trellis - ECP5 bitstream documentation
Amaranth HDL - Python-based hardware description
nextpnr - Place and route tool
Yosys - Verilog synthesis

Where to Buy

ULX3S: - AliExpress - ~$100-150 depending on variant - Mouser - Official distribution - CrowdSupply - Original campaign page

Tang Nano 9K (budget alternative): - Amazon - ~$25, faster shipping - AliExpress - ~$15, slower shipping

Next up: Getting our first instructions executing on real hardware. Both the Amaranth and Verilog implementations are ready and tested; Hello World runs in simulation and the testbenches pass. Now it's a matter of pin constraints, clock domains, and debugging the inevitable timing issues.

How We Learned Hardware in 1983

A.C. Jokela — Sat, 31 Jan 2026 16:00:00 GMT

I recently spent an afternoon with a scanned PDF of Z80 Applications by James W. Coffron, published by SYBEX in 1983. It's a 306-page guide to building microprocessor systems from discrete components. Reading it felt like archaeology, not because the technology is obsolete (the Z80 is still manufactured today), but because the way it teaches is so foreign to how we learn hardware now.

The book assumes you want to build a computer from chips. Not program one. Not configure one. Build one, with a soldering iron, from a CPU, some RAM, some ROM, and a handful of 74LS-series logic gates. The gap between this and a modern "Getting Started with Arduino" tutorial is so vast it's almost difficult to articulate. But I'll try.

The Starting Point: What You're Expected to Know

Coffron's introduction sets the tone:

"Have you ever imagined a new application for a microprocessor-controlled system, only to have the idea vanish under a torrent of technical details found in the data sheets? If so, you're not alone."

This is a book for people who have already read the datasheets and gotten lost. The assumed baseline is that you understand what a microprocessor is, what buses are, what memory addressing means. The book's job is to bridge the gap between "I understand the theory" and "I have a working system on my bench."

Compare this to the Arduino "Blink" tutorial, which assumes you know how to plug in a USB cable. The entire hardware abstraction layer (the thing that makes digitalWrite(13, HIGH) turn on an LED) is invisible. You don't need to know that pin 13 maps to PORTB bit 5 on the ATmega328P, or that setting that bit high puts 5V on the physical pin, or that there's a 220-ohm current-limiting resistor already on the board. You just call a function.

Chapter 1: Connecting a CPU to ROM

The first real chapter of Coffron's book is titled "Using the Z80 with ROM." Not programming the Z80. Not using an existing Z80 system. Literally: how do you wire a Z80 CPU chip to a 2716 EPROM so that the CPU can fetch instructions?

Figure 1.9 from the book: A complete schematic showing the connection between a 2716 EPROM and the Z80 microprocessor, including the logic used for enabling the memory device according to the memory map.

This single diagram requires understanding:

Address buses: The Z80 has 16 address lines (A0-A15). The 2716 EPROM has 11 address inputs. How do you connect them? Which lines go where?
Data buses: The Z80 has 8 data lines. The 2716 has 8 data outputs. These connect directly, but only when the chip is selected.
Chip select logic: The 74LS138 is a 3-to-8 decoder. The book explains how to use the upper address lines (A11-A15) to generate chip select signals, so that different memory chips respond to different address ranges. This is memory mapping, implemented in hardware.
Control signal generation: The Z80 outputs MREQ (memory request) and RD (read). These must be combined with OR gates to generate MEMR, which enables the ROM's output buffers at the correct moment.

The timing diagram that accompanies this schematic shows exactly when each signal transitions:

Figure 1.10: A timing diagram showing the important signal relationships. Address lines stabilize, MREQ goes low, RD goes low, data becomes valid, then everything releases.

This is page 12 of the book. We haven't written a single line of code yet. We're just trying to make the CPU able to read instructions from a ROM chip.

The Modern Equivalent: There Isn't One

On a Raspberry Pi, you don't connect the CPU to RAM. The RAM is soldered to the board. On an Arduino, the flash memory that holds your program is inside the microcontroller chip. There's no schematic to draw because there's no external connection to make.

When a modern tutorial says "upload your sketch," it's hiding:

The USB-to-serial converter that talks to the bootloader
The bootloader that receives bytes and writes them to flash
The flash memory controller that handles page erasure and programming
The reset circuit that starts execution at the right address

All of this exists. It's just not something you're expected to understand, or even know about, to get started.

Dynamic RAM: Where It Gets Serious

Chapter 4 of Coffron's book covers dynamic RAM. This is where the real complexity lives.

Static RAM is simple: you put an address on the bus, assert the chip select, and the data appears. Dynamic RAM is different. It stores bits in tiny capacitors that leak charge, so you have to refresh them periodically. It uses multiplexed addressing to reduce pin count. You send the row address, strobe RAS (Row Address Strobe), then send the column address and strobe CAS (Column Address Strobe).

The book dedicates an entire chapter to building a 16K x 8-bit dynamic RAM system using 4116 chips. This involves:

Address multiplexing hardware: You need logic to switch between presenting the low address bits and the high address bits to the RAM chips at the right times.
RAS/CAS timing generation: The sequence of RAS and CAS signals must meet strict timing requirements. Too fast and the chips don't respond. Too slow and you waste cycles.
Refresh logic: The Z80 has a built-in refresh counter (one of its innovations over the 8080), but you still need to understand when refresh cycles occur and how they interleave with normal memory access.

Figure 2.6: A partial data sheet and block diagram for the 2114, a 1K x 4 static RAM. The book walks through every pin and its function.

Here's the key insight: in 1983, if you wanted more than a few kilobytes of RAM, you had to use dynamic RAM. Static RAM was expensive. The 4116 gave you 16K bits for the same cost as 1K bits of static RAM. But you paid for it in complexity.

Today? The Raspberry Pi 5 has 8 gigabytes of DDR4 RAM. The timing controller, refresh logic, and address multiplexing are all handled by a dedicated memory controller inside the Broadcom SoC. You don't configure it. You don't even see it. It just works.

Interrupts: Where Software Meets Hardware

Chapter 5 covers interrupts, and this is where Coffron's book becomes genuinely fascinating. The Z80 has three interrupt modes, and the book explains not just what they do, but how to wire the hardware to use them.

The book explains the electrical characteristics of the INT input, how to mask interrupts in software, and the three interrupt modes.

Mode 2 interrupts are particularly elegant. When an interrupt occurs:

The interrupting device places a byte on the data bus
The CPU reads this byte and combines it with the I register to form a 16-bit pointer
This pointer addresses a table in memory containing the actual interrupt service routine address
The CPU jumps to that address

This means you can have up to 128 different interrupt vectors, each pointing to a different handler, with the interrupting device choosing which one. The book shows how to set up the vector table in memory and how to wire multiple devices in a "daisy chain" priority scheme.

In Arduino-land, you write attachInterrupt(digitalPinToInterrupt(2), myFunction, RISING) and you're done. The hardware abstraction layer handles vector table management, priority, and dispatch. This is convenient. But you have no idea why pin 2 can trigger an interrupt and pin 4 can't (on an Uno), or what happens inside the CPU when an interrupt fires.

The Peripheral Chips: A Complete Ecosystem

The Z80 wasn't just a CPU; it was the center of a chip family. Zilog made matching peripheral chips designed to work together:

Z80 PIO: Parallel I/O controller with handshaking
Z80 CTC: Counter/Timer circuit for generating timing or counting events
Z80 SIO: Serial I/O for RS-232 communication
Z80 DMA: Direct Memory Access controller for fast block transfers

Coffron's book covers all of these, plus Intel's 8255 PIO and 8253 timer (which work with the Z80 despite being designed for the 8080).

Figure 11.12: A Z80 program for initializing the Z80-SIO in an interrupt application. Every register must be programmed in the correct sequence.

Look at that initialization code. To set up a serial port, you have to:

Write to the control port to select which internal register you want to access
Write the actual configuration byte
Repeat for each register (WR0 through WR7)
Set up the interrupt vector
Enable the receiver and transmitter separately

The SIO has eight write registers and three read registers per channel, each with specific bit-level meanings. The book includes an appendix that's just register descriptions, twelve pages of bit definitions.

Compare this to Arduino: Serial.begin(9600). One line. Done.

The Static Stimulus Tester: Debugging from First Principles

Chapter 12 is unlike anything you'll find in a modern tutorial. It describes building a "Static Stimulus Tester," a tool for debugging Z80 hardware by manually single-stepping the CPU.

The idea is simple but radical: disconnect the crystal oscillator and replace it with a push-button. Each press advances the CPU by one clock cycle. Add LED displays for the address bus, data bus, and control signals. Now you can literally watch the CPU execute, one clock tick at a time.

The book includes assembly language examples throughout, always tied to specific hardware configurations.

This is how engineers debugged hardware in 1983. No logic analyzer (those cost more than cars). No JTAG. No printf debugging. You built a tool that let you see electricity moving through your circuit, and you traced the problem by hand.

Modern development boards have LEDs. They blink to show activity. But they're diagnostic indicators, not debugging tools. If your Arduino doesn't work, you use the serial monitor to print messages. If that doesn't work, you post on Stack Overflow. The idea of building a hardware tool to watch your CPU execute instruction-by-instruction is genuinely alien to modern practice.

The Economics of Learning

It's worth considering what it actually cost to learn hardware in 1983.

The book itself was probably \$15-20. But to actually use it, you needed:

A Z80 CPU: about \$10-15 in 1983 dollars
2716 EPROMs: \$5-10 each, and you'd need several
2114 static RAM chips: \$3-5 each, eight for a basic system
74LS-series logic chips: \$0.50-2 each, dozens needed
Sockets, capacitors, resistors, wire: another \$20-30
A prototype board or wirewrap supplies: \$10-50
An EPROM programmer: \$100-300 for a basic unit
An oscilloscope: \$300-1000 for something usable
A power supply: \$30-50

A minimal setup to follow along with Coffron's book would run \$200-400 in 1983 dollars, roughly \$600-1200 in 2026 money. A serious hobbyist setup with a decent scope and programmer could easily hit \$1000-2000 (1983), or \$3000-6000 adjusted.

Compare that to an Arduino Uno: \$25. A Raspberry Pi: \$35-75. A USB cable you probably already own. Free software. Free tutorials. Free community support on forums and Discord.

The democratization isn't just about abstraction; it's about cost. In 1983, learning hardware was expensive enough that it filtered for a certain kind of person: someone with disposable income, access to electronics suppliers, and enough space for a workbench. Today, a teenager with a part-time job can afford to experiment.

This matters. The people who learned hardware in 1983 were a self-selected group. The people who learn today are everyone.

What We Gained and What We Lost

I want to be clear: I'm not arguing that the 1983 approach is better. The barriers to entry were enormous. Building a working Z80 system from Coffron's book required:

Understanding digital logic (AND, OR, NAND gates)
Reading timing diagrams
Calculating address decoding logic
Soldering dozens of chips onto a board
Having access to an EPROM programmer
Writing assembly language

This took months of study and significant equipment investment. The number of people who could do it was small.

Today, a complete beginner can have an LED blinking on an Arduino within an hour of opening the box. They can connect sensors, motors, and displays without understanding the underlying protocols. They can build genuinely useful things (home automation, art installations, scientific instruments) without ever reading a timing diagram.

This democratization is valuable. More people building more things is good.

But something is lost.

The modern approach creates a gap between "user" and "understander." You can use an Arduino without understanding it. You can use a Raspberry Pi as a Linux computer without knowing it has GPIO pins. You can run machine learning models without understanding matrix multiplication.

In 1983, there was no such gap. If you were using a microprocessor, you understood microprocessors. You had to. The abstraction layers didn't exist yet.

The Pedagogical Difference

Coffron's book teaches hardware by building it. Each chapter adds another subsystem: ROM, then RAM, then I/O ports, then interrupts, then timers, then serial communication. By the end, you understand how all the pieces connect because you connected them yourself.

Modern tutorials teach by doing. "Make this LED blink. Now make it blink faster. Now add a button. Now read a temperature sensor." The complexity is hidden, revealed only when you hit the limits of the abstraction.

Both approaches work. But they produce different kinds of understanding.

Someone who learned from Coffron's book can troubleshoot hardware. They can look at an oscilloscope trace and identify a timing problem. They can read a datasheet for a new chip and understand how to integrate it. They have a mental model of what the electricity is doing.

Someone who learned from Arduino tutorials can build things. They can iterate quickly, trying different sensors and actuators until something works. They can find libraries that solve their problems and examples they can modify. They have a mental model of what the software is doing.

Neither is wrong. But they're not the same thing.

What Would 1983 Make of 2026?

If you dropped a Raspberry Pi 5 on James Coffron's desk in 1983, what would he see?

A computer with four 64-bit CPU cores running at 2.4 GHz. Eight gigabytes of RAM. Gigabit Ethernet. Bluetooth. WiFi. USB. HDMI. A GPU capable of 4K video. Storage measured in terabytes.

And no way to understand any of it from first principles.

The SoC at the heart of a Raspberry Pi contains billions of transistors. The memory controller alone is more complex than every computer that existed in 1983 combined. The protocols (USB 3.0, HDMI 2.0, PCIe) are specified in documents thousands of pages long.

You can't build a Raspberry Pi from discrete components. You can't even build the chips that go into it without a billion-dollar fab. The abstraction isn't just convenient; it's necessary. The complexity has exceeded human ability to hold it in one head.

This is progress. But it's also a kind of loss.

Closing Thoughts

I keep Coffron's book on my shelf not because I'm going to build a Z80 system (though I might, someday), but because it represents a way of thinking about computers that's worth preserving.

The Z80 is comprehensible. One person can understand all of it: every instruction, every pin, every timing requirement. The peripheral chips are comprehensible too. A moderately determined person can read the datasheets and know exactly what the hardware is doing.

Modern computers are not comprehensible in this way. They're usable, powerful, and democratized. But they're also opaque, their complexity hidden behind layers of abstraction that most users will never penetrate.

Both things can be true. We can celebrate Arduino for making electronics accessible while acknowledging that something is different (not worse, but different) about a world where understanding and using have become separate activities.

If you want to experience what hardware education was like in 1983, find a copy of Coffron's book. It's out of print, but scanned PDFs exist. Read chapter 1. Draw the schematic on paper. Trace the signals with your finger. Try to understand not just what the circuit does, but why it works.

Then open the Arduino IDE and type digitalWrite(13, HIGH).

Both are valid. But they're not the same thing.

Resources

The Books

Z80 Applications by James W. Coffron: The 1983 SYBEX book discussed in this article. Used copies occasionally appear.
Build Your Own Z80 Computer by Steve Ciarcia: Another classic from 1981, showing how to construct a complete Z80 system from scratch.
The Best of Ciarcia's Circuit Cellar: A collection of Steve Ciarcia's legendary BYTE magazine projects.

The Modern Approach

Arduino Uno R3: The official board. Plug it in, upload a sketch, blink an LED.
ELEGOO UNO R3 Most Complete Starter Kit: 200+ components with tutorials. Everything you need to get started.
Raspberry Pi 5 (8GB): The computer that would have seemed like science fiction in 1983.

The 1983 Toolkit

Hakko FX888D Soldering Station: A quality soldering station for building hardware the old-fashioned way.
Rigol DS1054Z Oscilloscope: A 4-channel 50MHz scope. In 1983, this capability would have cost thousands.
T48 Universal Programmer: Programs EPROMs, EEPROMs, and microcontrollers. Supports the vintage 27Cxxx series with high-voltage programming.

My Experience Using Fiverr for Custom PCB Design: A $468 Arduino Giga Shield

A.C. Jokela — Sat, 24 Jan 2026 20:00:00 GMT

When I decided to run vintage Z80 code on a modern Arduino Giga R1, I hit an immediate roadblock: voltage incompatibility. The RetroShield Z80 by 8-Bit Force is a fantastic piece of hardware that lets you run a real Zilog Z80 processor on an Arduino, but it's designed for the 5V-tolerant Arduino Mega 2560. The Arduino Giga R1, with its powerful STM32H747 dual-core processor and 76 GPIO pins, operates at 3.3V logic levels and can be permanently damaged by 5V signals.

The solution? A custom shield with level shifters that could translate between the Giga's 3.3V world and the Z80's 5V domain. Rather than spend weeks learning PCB design software and risking amateur mistakes, I decided to outsource the work to a professional on Fiverr. Here's what that experience was like, including the full cost breakdown and everything I received.

The Project Requirements

My requirements were relatively straightforward on the surface:

Design an Arduino Giga R1-compatible shield (matching the Giga's unique form factor)
Include bidirectional level shifting from 3.3V to 5V on all relevant GPIO pins
Provide pass-through headers so the RetroShield Z80 could plug in on top
Use KiCad for the design (my preferred EDA tool for future modifications)

The Arduino Giga R1 is essentially a larger, more powerful cousin of the Arduino Mega 2560. It shares some pin compatibility but has a different physical layout with additional headers. The shield needed to accommodate all of this while providing level shifting for approximately 70+ digital I/O lines.

Why the Arduino Giga R1?

You might wonder why I chose the Arduino Giga R1 over other options. The Arduino Due, which I mentioned in my initial message to the designer, was my original consideration. It's also 3.3V logic and has a powerful ARM processor. However, the Giga R1 offers several compelling advantages:

Processing Power: The Giga R1's STM32H747 is a dual-core Cortex-M7/M4 running at 480MHz and 240MHz respectively. This dwarfs the Due's 84MHz Cortex-M3. For running Z80 code, this extra headroom means I could potentially implement cycle-accurate emulation or run multiple virtual Z80s simultaneously.

Memory: The Giga R1 has 2MB of internal flash and 1MB of RAM, plus it supports external memory. The Due has 512KB flash and 96KB RAM. More memory means I can load larger Z80 programs and implement more sophisticated peripherals.

Connectivity: The Giga R1 includes WiFi and Bluetooth out of the box. Imagine running a Z80 BBS that's actually accessible over the internet, or wireless file transfers to a CP/M system. The possibilities are intriguing.

Camera Support: The Giga R1 has a camera connector. While seemingly unrelated to Z80 computing, it opens doors for interesting projects like OCR input devices or barcode reading peripherals.

The trade-off is that the Giga R1's 3.3V logic requires level shifting for any 5V hardware, hence this project. The Mega 2560's 5V tolerance made the RetroShield plug-and-play, but I felt the Giga's advantages were worth the additional complexity.

Finding a Designer on Fiverr

Fiverr's PCB design category has hundreds of sellers ranging from hobbyists charging \$20 to professional engineers charging \$500+. After reviewing portfolios and reading reviews, I found a designer named Elijah (username: ekeziah) whose work looked professional and who specifically mentioned KiCad experience. He does PCB design, CAD, and firmware work.

His base gig was priced reasonably, but I knew custom work like this would require negotiation. I reached out with my requirements:

"I have a relatively straightforward project. I need an Arduino Due/Giga form factor shield that can use level shifters to go from 3.3V to 5V. I have this: [RetroShield link] which is 5V, and instead of using an Arduino Mega 2560, which is 5V tolerant, I want to use either an Arduino Due or Giga which is not tolerant of 5V."

The designer responded quickly and we began negotiating scope and pricing.

The Cost Reality Check

Let me be transparent about the costs because this is often glossed over in "I made a thing" posts:

Initial Order (January 4, 2026)

Base price: \$75
Custom extras negotiated: \$200
Fiverr service fees: \$108.67
Subtotal: \$383.67

The designer initially quoted \$175, then corrected himself saying it was a typo and meant \$275. We settled on a \$275 total for the custom work with a 7-10 day timeline. Fiverr's fees added roughly 28% on top.

Revision Order (January 20, 2026)

After receiving the initial files, I realized I wanted to add version numbering and my website URL to the silkscreen. Since the designer hadn't included the KiCad source files in the first delivery (only Gerber files), I needed him to make the changes and regenerate everything.

Revision price negotiated: \$57
Fiverr service fees: \$27.96
Subtotal: \$84.96

Total Project Cost: \$468.63

Is this expensive? It depends on your perspective. A professional PCB design service might charge \$100-200 per hour, and this project involved creating a schematic from scratch, laying out a moderately complex board, and generating production files. Doing it myself would have taken 20-40 hours of learning and work. At that rate, the \$468 represents reasonable value, but it's definitely not pocket change for a hobby project.

The Design Process

Communication happened entirely through Fiverr's messaging system. Here's how the project unfolded:

January 4-8: Requirements Gathering

The designer studied the Arduino Giga R1 documentation and the RetroShield Z80 pinout. He asked clarifying questions about whether I needed level shifting on pins 22-53 (the additional digital pins on the Giga's side headers). I confirmed that yes, all pins needed level shifting to ensure full compatibility.

January 9: Schematic Complete

Elijah sent the first schematic PDF showing the circuit design. The approach was clean: nine TXB0108PW 8-bit bidirectional level shifter ICs, providing 72 channels of voltage translation. Each level shifter had proper decoupling capacitors and pull-up resistors on the output enable pins.

The TXB0108 is a popular choice for this application because it's bidirectional; you don't need to specify which direction each pin will operate, making it ideal for GPIO that might be configured as either input or output.

This is a key design decision worth understanding. Alternative level shifter approaches include:

74LVC245 bus transceivers: These require a direction control pin, which adds complexity when GPIO pins change direction dynamically
Simple resistor dividers: Work for unidirectional high-to-low shifting, but not bidirectional
MOSFETs with pull-ups: The classic BSS138 approach works well but requires one MOSFET per channel and can be slow
Dedicated level shifter ICs: The TXB0108 auto-detects direction and handles both directions at high speed

The designer's choice of TXB0108 was sound; it simplifies the design and ensures the shield will work regardless of how the software configures each GPIO pin.

January 10: Layout and Routing

The physical layout came together quickly. The board dimensions are 155mm x 90mm, matching the Arduino Giga R1's footprint with additional space for the level shifter circuitry. The routing was done on a two-layer board, keeping things manufacturable at low-cost PCB fabs.

The designer sent progress images showing the component placement with the level shifter ICs arranged along the edges of the board, close to their respective pin headers.

January 10: First Delivery

The initial delivery included:

Gerber files (ready for PCB manufacturing)
BOM (Bill of Materials) in CSV and Excel formats
3D rendered images of the board
Schematic PDF
Component placement (CPL) file for assembly

What was missing from this first delivery: the KiCad source files. This became important later.

The Revision Request

After examining the delivered files, I noticed two things I wanted to change:

Add "v0.1" to the board silkscreen for version tracking
Add my website URL (https://tinycomputers.io/) for attribution

These are simple text changes, but without the KiCad source files, I couldn't make them myself. The Gerber files are essentially "compiled" output; you can view them and send them to a fab, but you can't easily edit them.

I reached out to the designer:

"Is it possible for you to add something to the silkscreen? I would like to add 'v0.1' to the 'ARDUINO GIGA R1 SHIELD', so that line would be 'ARDUINO GIGA R1 SHIELD v0.1'. And then in a smaller font, directly to the right of that above text, I would like 'https://tinycomputers.io/'. I would add these things myself but I am not seeing any KiCAD source files, the only things that open in KiCAD are the Gerber files."

We negotiated \$57 for the revision, which also included finally receiving the full KiCad source files. The revision took about two days, with a quick back-and-forth to remove quotation marks from around the URL that the designer had initially added.

What I Received: The Complete Deliverables

The final delivery package was comprehensive. Here's everything included:

Source Files (SRC_FILES/)

The complete KiCad project including:

AlexJ_bz_ArduinoGigaShield.kicad_pcb - PCB layout file
AlexJ_bz_ArduinoGigaShield.kicad_sch - Schematic file
AlexJ_bz_ArduinoGigaShield.kicad_pro - Project file
Multiple backup ZIPs showing the design evolution

Having the source files means I can make future modifications myself: adding features, fixing issues, or creating derivative designs.

Gerber Files (GERBER_FILES/)

Production-ready files for PCB manufacturing:

Front and back copper layers (F_Cu.gbr, B_Cu.gbr)
Solder mask layers (F_Mask.gbr, B_Mask.gbr)
Silkscreen layers (F_Silkscreen.gbr, B_Silkscreen.gbr)
Paste layers for SMD assembly (F_Paste.gbr, B_Paste.gbr)
Board outline (Edge_Cuts.gbr)
Drill files (PTH.drl, NPTH.drl)
Gerber job file for fab house compatibility

These files can be uploaded directly to JLCPCB, PCBWay, OSH Park, or any other PCB fabrication service.

Bill of Materials (BOM/)

Component lists in both CSV and Excel formats:

Reference	Qty	Value	Part Number
C1-C27	27	0.1uF	CC0603KRX7R9BB104
R1-R9	9	10K	RC0603FR-0710KL
U1-U9	9	TXB0108PW	TXB0108PWR
J1-J10	Various	Pin Headers	DNP

The "DNP" (Do Not Populate) entries for connectors indicate these would typically be hand-soldered rather than machine-placed, or sourced separately.

3D Renders (IMAGES/)

Professional-looking 3D renders showing:

Top view with the Arduino Giga R1 mounted
Bottom view showing the routing
Angled perspective view

These are great for documentation and for visualizing how the final assembly will look.

3D render showing the shield PCB with Arduino Giga R1 mounted (top view)

Bottom view showing the PCB routing and through-hole connections

Schematic PDF (SCH_PDF/)

A beautifully laid out schematic showing:

All nine TXB0108PW level shifters with their connections
Pin mapping from Arduino Giga headers to 5V output headers
Power distribution (3.3V and 5V rails)
Decoupling capacitor placement
Four mounting holes for secure attachment

You can download the full schematic PDF here.

Reference Assets (ASSETS/)

The designer included reference materials used during the design:

Arduino Giga R1 datasheet (2MB PDF)
CAD files for the Arduino Giga R1 (ABX00063)
STEP files for 3D modeling
DXF file of the Giga R1 outline

These are helpful for understanding the design decisions and for future reference.

Component Placement File (CPL_FILE/)

A CSV file with X/Y coordinates and rotation for each component, useful if you're having the boards assembled by a fab house rather than hand-soldering.

The Circuit Design

Looking at the schematic, the design is elegant in its simplicity. Each TXB0108PW provides 8 channels of bidirectional level shifting. With nine of these ICs, the design provides 72 channels, more than enough for all the Arduino Giga's GPIO pins.

Key design elements:

Level Shifters: The TXB0108PW is an 8-bit bidirectional voltage-level translator. It automatically detects the signal direction, making it perfect for GPIO that might be configured as either input or output at runtime. The A-side connects to the 3.3V Arduino Giga pins, and the B-side connects to the 5V RetroShield pins.

Decoupling Capacitors: Each level shifter has a 0.1µF ceramic capacitor on both the 3.3V (VCCA) and 5V (VCCB) power pins. This is standard practice to filter high-frequency noise and ensure stable operation. With 27 capacitors total, the power rails should be rock-solid.

Output Enable Pull-ups: Each TXB0108 has a 10K pull-up resistor on the OE (Output Enable) pin, tying it to 3.3V. This ensures the level shifters are always active when the Arduino is powered.

Pass-Through Headers: The design includes matching pin headers on both the 3.3V and 5V sides. The Arduino Giga plugs into female headers on the bottom, while the RetroShield (or other 5V shields) can plug into male headers on top.

Lessons Learned

After going through this process, here's what I'd do differently or recommend to others:

1. Specify Source Files Upfront

Make it explicit in your initial requirements that you need the original design files (KiCad, Altium, Eagle, etc.), not just Gerber output files. This saves the cost and hassle of a revision later. Many designers consider source files an "extra" unless you ask for them.

2. Include Silkscreen Details Early

Think about what text you want on the board before the design starts. Version numbers, URLs, logos, regulatory markings: all of these are easy to add during initial design but require regenerating all files if added later.

3. Budget for Fiverr's Fees

Fiverr's service fees add roughly 25-30% to the listed price. When negotiating with a designer, account for this in your mental budget. A \$275 job becomes \$350+ after fees.

4. Communicate Frequently

Don't disappear for days at a time. Quick responses keep the project moving and help catch misunderstandings early. The designer asked good clarifying questions; make sure you answer them thoroughly.

5. Review Carefully Before Approving

Take time to review delivered files carefully. Open the Gerbers in a viewer (KiCad has a built-in Gerber viewer, or use an online tool), check the schematic for obvious errors, verify the BOM has the right components. It's much cheaper to catch issues before ordering PCBs.

Alternatives to Fiverr

Before deciding on Fiverr, I considered several alternatives:

DIY with KiCad: The open-source route. KiCad is free, powerful, and has excellent documentation. However, PCB design has a steep learning curve. Understanding design rules, proper trace widths, via sizes, clearances, and manufacturing constraints takes time. For a one-off project, the learning investment didn't seem justified.

Upwork or Other Freelance Platforms: Similar to Fiverr but often with higher prices and a more traditional freelancer relationship. Upwork tends to attract more experienced (and expensive) engineers. For a small project like this, Fiverr's fixed-price gig format seemed more appropriate.

Local EE Students/Engineers: Universities often have engineering students looking for small projects. This can be cheaper, but finding someone and managing the relationship takes effort. You also don't have the platform protections that Fiverr offers.

PCB Design Services: Companies like PCBWay and JLCPCB offer design services alongside manufacturing. These can be convenient but pricing varies widely and communication can be challenging across language barriers.

Open Source Existing Designs: Sometimes you can find an existing design that's close to what you need. I looked for Arduino Giga shields with level shifting but found nothing. The Giga R1 is relatively new and its unique form factor means fewer compatible shields exist.

Fiverr won because of its accessibility, fixed pricing model, and the portfolio/review system that let me evaluate designers before committing.

Was It Worth It?

For my situation, absolutely. I have a professional-quality PCB design that I can manufacture, modify, and iterate on. The alternative was spending 20-40 hours learning PCB design from scratch and likely making beginner mistakes that could damage expensive hardware.

The \$468 total is significant for a hobby project, but context matters:

The Arduino Giga R1 costs \$90
The RetroShield Z80 costs \$65
PCB manufacturing will add another \$20-50 depending on quantity

The total investment for this Z80-on-Giga project will be around \$650-700 including the shield design. That's real money, but for a unique piece of hardware that lets me run authentic Z80 code on a modern microcontroller with WiFi, Bluetooth, and a camera interface, it feels worthwhile.

A Note on Maker Culture

I'm aware that hiring someone to design a circuit board runs counter to the ethos of Maker Culture. There's something deeply satisfying about designing, building, and debugging your own hardware, learning from mistakes, understanding every trace and component choice, and earning that sense of accomplishment that comes from true DIY.

Outsourcing the design felt like a shortcut, and in some ways it was. I traded the learning experience for speed and convenience.

That said, I didn't stop there. After receiving the Fiverr design, I also created an alternative version of the shield myself. I used Claude Code to help work through the component connections and pin mappings, and Quilter.ai to handle the PCB routing, an AI-powered tool that automates trace layout while respecting design rules. The result is a second design that I understand more intimately, having been involved in every decision.

Once PCBWay manufactures both versions, I'll post a comparison of the two approaches: the professionally designed Fiverr board versus the AI-assisted DIY version. It should be an interesting look at how modern AI tools are changing what's possible for makers who want to learn by doing but also want a safety net of intelligent assistance.

Next Steps

With the design files in hand, my next steps are:

Order prototype PCBs from JLCPCB or PCBWay
Source components from LCSC or DigiKey (the BOM helps here)
Assemble and test the prototype
Document any issues and potentially order a v0.2 revision
Write about running Z80 code on the Arduino Giga R1

The beauty of having the KiCad source files is that if I find issues during testing, I can fix them myself and generate new Gerber files. The \$57 revision cost to get those source files has already paid for itself in peace of mind.

Conclusion

Fiverr can be a viable option for custom PCB design, especially for projects that are well-defined and don't require extensive back-and-forth iteration. The key is finding a competent designer, communicating clearly, and budgeting realistically for both the designer's fee and Fiverr's platform fees.

My Arduino Giga R1 shield project cost \$468.63 total across two orders, more than I initially hoped to spend, but less than I would have paid for my own time learning PCB design. The deliverables were comprehensive, professional, and gave me everything I need to manufacture, modify, and document the design.

If you're considering using Fiverr for PCB design, go in with realistic expectations about cost and timeline, and make sure to specify exactly what deliverables you need upfront. It might not be the cheapest option, but for a one-off custom project, it can be a reasonable trade-off between time and money.

Now, if you'll excuse me, I have some prototype PCBs to order and a Z80 to make talk to an STM32.

Coming Soon: Thanks to an upcoming sponsorship from PCBWay, I'll be able to bring this design from KiCad files and Gerber renders into the physical world. Stay tuned for a follow-up post where I'll document the manufacturing process, assembly, and first power-on of the Arduino Giga R1 Level Shifter Shield. Will it work on the first try? Will the Z80 finally talk to the STM32? Check back to find out!

The files discussed in this post, including the schematic and 3D renders, are from the actual delivered project. The Arduino Giga R1 is a product of Arduino. The RetroShield Z80 is designed by 8-Bit Force and available on Tindie.

CP/M 2.2 on Physical Hardware: RetroShield Z80 with 1MB DRAM and SD Card Storage

A.C. Jokela — Wed, 07 Jan 2026 22:00:00 GMT

There's a profound difference between emulation and the real thing. While my previous post covered running CP/M on a software-based Z80 emulator, this post documents the journey of bringing CP/M 2.2 to life on actual Z80 silicon - a real Zilog Z80 CPU executing real machine code, with 1MB of DRAM and SD card storage for disk images.

The result? A fully functional CP/M system running Zork, all on an Arduino Mega 2560 acting as the glue between vintage and modern technology.

The Hardware Stack

Building a working CP/M system requires three essential components: a CPU, memory, and storage. Here's what I used:

The RetroShield Z80

The RetroShield from 8bitforce is a clever piece of engineering. It's a shield that holds a real Z80 CPU and lets an Arduino Mega control it cycle-by-cycle. The Arduino provides the clock, handles bus transactions, and emulates peripherals - but the Z80 is doing the actual computation.

The RetroShield uses nearly every pin on the Arduino Mega:

Function	Arduino Pins
Address Bus (A0-A15)	Pins 22-37
Data Bus (D0-D7)	Pins 42-49
Control Signals	Pins 38-41, 50-53

This pin-hungry design means we need to be creative about adding peripherals.

KDRAM2560: 1MB of Dynamic RAM

The KDRAM2560 is another 8bitforce product - a DRAM shield that provides a full megabyte of memory to the Arduino Mega. It uses the analog pins (A0-A15) for its interface, leaving digital pins available for other uses.

Why DRAM instead of SRAM? Cost and density. A megabyte of SRAM would be expensive and physically large. DRAM is cheap but requires periodic refresh to maintain data integrity. The KDRAM2560 library handles this automatically using one of the Arduino's hardware timers.

For CP/M, we only need 64KB of the available 1MB, but having extra memory opens possibilities for RAM disks or bank switching in future projects.

#define DRAM_REFRESH_USE_TIMER_1
#include <kdram2560.h>

void setup() {
    // Initialize DRAM - this also starts the refresh interrupt
    if (DRAM.begin(&Serial)) {
        Serial.println("KDRAM2560: OK (1MB DRAM)");
    } else {
        Serial.println("KDRAM2560: FAILED!");
        while (1) {}  // Halt
    }
}

The API is beautifully simple:

// Read a byte from any address in the 1MB space
byte data = DRAM.read8(address);

// Write a byte
DRAM.write8(address, data);

Internally, the library handles the complex multiplexed addressing that DRAM requires - splitting the 20-bit address into row and column components, managing RAS/CAS timing, and ensuring refresh cycles happen frequently enough to prevent data loss.

Software SPI SD Card

Here's where things get interesting. The obvious choice for SD card storage would be the Arduino's hardware SPI on pins 50-53. But look back at that pin table - the RetroShield uses pins 50-53 for Z80 control signals!

The solution is software SPI - bit-banging the SPI protocol on different pins. I chose pins 4-7, safely away from both the RetroShield and KDRAM2560:

SD Card Pin	Arduino Pin
MISO	Pin 4
MOSI	Pin 5
SCK	Pin 6
CS	Pin 7

The SdFat library supports software SPI through its SoftSpiDriver template class. One important note: you must set SPI_DRIVER_SELECT to 2 in SdFatConfig.h to enable this:

// In SdFat/src/SdFatConfig.h
#define SPI_DRIVER_SELECT 2  // Enable software SPI

Then in your sketch:

#include "SdFat.h"

const uint8_t SOFT_MISO_PIN = 4;
const uint8_t SOFT_MOSI_PIN = 5;
const uint8_t SOFT_SCK_PIN  = 6;
const uint8_t SD_CS_PIN     = 7;

SoftSpiDriver<SOFT_MISO_PIN, SOFT_MOSI_PIN, SOFT_SCK_PIN> softSpi;
#define SD_CONFIG SdSpiConfig(SD_CS_PIN, DEDICATED_SPI, SD_SCK_MHZ(0), &softSpi)

SdFs sd;

void setup() {
    if (sd.begin(SD_CONFIG)) {
        Serial.println("SD Card: OK (Software SPI)");
    }
}

Software SPI is slower than hardware SPI - roughly 20-50 KB/s compared to 1-2 MB/s. For loading programs at boot and occasional disk access, this is perfectly acceptable. You won't notice the difference playing Zork.

The Complete System Architecture

Here's how all the pieces fit together:

┌─────────────────────────────────────────────────────────────┐
│                      Arduino Mega 2560                      │
├─────────────────────────────────────────────────────────────┤
│  Z80 RetroShield (top layer)                                │
│    Real Zilog Z80 CPU @ ~100kHz                             │
│    Address: pins 22-37 (directly mapped)                    │
│    Data: pins 42-49 (directly mapped)                       │
│    Control: pins 38-41, 50-53                               │
├─────────────────────────────────────────────────────────────┤
│  KDRAM2560 (middle layer)                                   │
│    1MB DRAM via analog pins A0-A15                          │
│    Timer 1 interrupt for automatic refresh                  │
│    Only 64KB used for Z80 address space                     │
├─────────────────────────────────────────────────────────────┤
│  MicroSD Card (external, via jumper wires)                  │
│    Software SPI on pins 4-7                                 │
│    FAT32 formatted, ≤32GB                                   │
│    Contains: boot.bin, CPM.SYS, A.DSK, B.DSK                │
└─────────────────────────────────────────────────────────────┘

Peripheral Emulation: The Arduino's Role

While the Z80 executes code, the Arduino handles peripheral I/O. When the Z80 performs an IN or OUT instruction, the Arduino intercepts it and provides the appropriate response.

MC6850 ACIA (Serial Console)

The console uses a virtual MC6850 ACIA on I/O ports 0x80 (control/status) and 0x81 (data). This connects to the Arduino's Serial interface, which in turn connects to your terminal:

#define ADDR_6850_CONTROL     0x80
#define ADDR_6850_DATA        0x81

// In the I/O read handler:
if (ADDR_L == ADDR_6850_DATA) {
    // Z80 is reading from serial
    prevDATA = Serial.read();
}
else if (ADDR_L == ADDR_6850_CONTROL) {
    // Z80 is checking status
    // Bit 0: Receive data ready
    // Bit 1: Transmit buffer empty
    prevDATA = reg6850_STATUS;
}

// In the I/O write handler:
if (ADDR_L == ADDR_6850_DATA) {
    // Z80 is writing to serial
    Serial.write(DATA_IN);
}

SD Card Interface

The SD card interface uses ports 0x10-0x19, providing commands for file operations and DMA block transfers:

Port	Function
0x10	Command register
0x11	Status register
0x12	Data byte (single-byte I/O)
0x13	Filename character input
0x14-0x15, 0x19	Seek position (24-bit)
0x16-0x17	DMA address (16-bit)
0x18	Block command (0=read, 1=write)

The key innovation is the DMA block transfer. Instead of the Z80 reading 128 bytes one at a time through port 0x12 (which would require 128 IN instructions), it sets a DMA address and issues a single block command. The Arduino then copies 128 bytes directly between the SD card and DRAM:

void sd_do_block_read() {
    uint8_t buffer[128];
    sdFile.read(buffer, 128);

    // Copy directly to DRAM
    for (int i = 0; i < 128; i++) {
        DRAM.write8((unsigned long)(sdDmaAddr + i), buffer[i]);
    }
    sdBlockStatus = 0;  // Success
}

This makes disk operations reasonably fast despite the software SPI limitation.

The Boot Process

When the Arduino powers up, here's what happens:

Arduino Setup
Initialize Serial at 115200 baud
Initialize KDRAM2560 (starts refresh interrupt)
Initialize SD card via software SPI
Load boot.bin from SD card into DRAM at address 0x0000
Release Z80 from reset
Z80 Boot Loader (boot.bin)
Initialize the MC6850 ACIA
Print boot banner
Open CPM.SYS from SD card
Load it into DRAM at 0xE000 (53 sectors = 6,784 bytes)
Jump to BIOS cold start at 0xF600
CP/M BIOS Cold Start
Initialize disk variables
Set up page zero jump vectors
Print the welcome message
Jump to CCP (Console Command Processor)
You see the A> prompt!

The boot loader is about 330 bytes of Z80 assembly:

;========================================================================
; CP/M Boot Loader for RetroShield Z80
;========================================================================

CCP_BASE:       equ     0xE000
BIOS_BASE:      equ     0xF600
LOAD_SIZE:      equ     53              ; Sectors to load

                org     0x0000

BOOT:
                di
                ld      sp, 0x0400

                ; Print boot message
                ld      hl, MSG_BOOT
                call    PRINT_STR

                ; Open CPM.SYS
                ld      hl, FILENAME
                call    SD_SEND_NAME
                ld      a, CMD_OPEN_READ
                out     (SD_CMD), a

                ; Load CP/M system to memory
                ld      hl, CCP_BASE
                ld      b, LOAD_SIZE

LOAD_LOOP:
                push    bc
                push    hl

                ; Set DMA address
                ld      a, l
                out     (SD_DMA_LO), a
                ld      a, h
                out     (SD_DMA_HI), a

                ; Read 128-byte block via DMA
                xor     a
                out     (SD_BLOCK), a

                ; Print progress dot
                ld      a, '.'
                call    PRINT_CHAR

                pop     hl
                ld      de, 128
                add     hl, de
                pop     bc
                djnz    LOAD_LOOP

                ; Jump to BIOS
                jp      BIOS_BASE

CP/M Disk Images

CP/M uses a specific disk format based on the 8-inch floppy standard:

77 tracks
26 sectors per track
128 bytes per sector
256KB total capacity

The first two tracks are reserved for the system (though we load from CPM.SYS instead). The directory starts at track 2, sector 0 (byte offset 6,656 or 0x1A00).

I wrote a Python tool to create and manage these disk images:

# Create an empty disk image
python3 cpm_disk.py create A.DSK

# Add a file
python3 cpm_disk.py add A.DSK ZORK1.COM

# List files
python3 cpm_disk.py list A.DSK

The directory entry format is straightforward - 32 bytes per entry:

Offset	Size	Description
0	1	User number (0xE5 = empty/deleted)
1-8	8	Filename (space-padded)
9-11	3	Extension (space-padded)
12-15	4	Extent info and record count
16-31	16	Block allocation map

One gotcha: empty directory entries must be marked with 0xE5, not 0x00. A disk full of zeros will confuse CP/M into thinking it has files with blank names!

Loading Classic Software: Zork on Real Hardware

With the infrastructure in place, loading classic software is straightforward. I grabbed Zork I, II, and III from the cpm-dist repository:

# Add Zork to the A: drive
python3 cpm_disk.py add A.DSK ZORK1.COM
python3 cpm_disk.py add A.DSK ZORK1.DAT
python3 cpm_disk.py add A.DSK ZORK2.COM
python3 cpm_disk.py add A.DSK ZORK2.DAT

# Hitchhiker's Guide goes on B:
python3 cpm_disk.py add B.DSK HITCH.COM
python3 cpm_disk.py add B.DSK HITCHHIK.DAT

Copy the disk images to the SD card, insert it into the module, and reset the Arduino:

======================================
RetroShield Z80 CP/M 2.2
======================================

KDRAM2560:  OK (1MB DRAM)
SD Card:    OK (Software SPI)
Loading boot.bin...
Loaded 331 bytes to DRAM at 0x0000
Starting Z80...

RetroShield Z80 Boot Loader
Copyright (c) 2025 Alex Jokela, tinycomputers.io

Loading CPM.SYS.....................................................
Boot complete.


RetroShield CP/M 2.2
56K TPA

A>DIR
A: ZORK1    COM : ZORK1    DAT : ZORK2    COM : ZORK2    DAT
A>ZORK1

ZORK I: The Great Underground Empire
Copyright (c) 1981, 1982, 1983 Infocom, Inc. All rights reserved.
ZORK is a registered trademark of Infocom, Inc.
Revision 88 / Serial number 840726

West of House
You are standing in an open field west of a white house, with a boarded
front door.
There is a small mailbox here.

>

There's something deeply satisfying about this. The Z80 CPU running this game is the same architecture that ran it in 1981. The actual opcodes being executed are identical. We've just swapped floppy drives for SD cards and CRT terminals for USB serial.

The CPU Tick Loop: Where It All Comes Together

The heart of the system is the cpu_tick() function - called continuously in loop(), it handles one Z80 clock cycle:

inline __attribute__((always_inline))
void cpu_tick() {
    // Check for serial input
    if (Serial.available()) {
        reg6850_STATUS |= 0x01;  // Set RDRF
    }

    CLK_HIGH;  // Rising clock edge
    uP_ADDR = ADDR;  // Capture address bus

    // Memory access?
    if (!STATE_MREQ_N) {
        if (!STATE_RD_N) {
            // Memory read - get byte from DRAM
            DATA_DIR = DIR_OUT;
            DATA_OUT = DRAM.read8((unsigned long)uP_ADDR);
        }
        else if (!STATE_WR_N) {
            // Memory write - store byte to DRAM
            DRAM.write8((unsigned long)uP_ADDR, DATA_IN);
        }
    }
    // I/O access?
    else if (!STATE_IORQ_N) {
        if (!STATE_RD_N && prevIORQ) {
            // I/O read
            DATA_DIR = DIR_OUT;
            if (sd_handles_port(ADDR_L)) {
                prevDATA = sd_read_port(ADDR_L);
            }
            else if (ADDR_L == ADDR_6850_DATA) {
                prevDATA = Serial.read();
            }
            else if (ADDR_L == ADDR_6850_CONTROL) {
                prevDATA = reg6850_STATUS;
            }
            DATA_OUT = prevDATA;
        }
        else if (!STATE_WR_N && prevIORQ) {
            // I/O write
            DATA_DIR = DIR_IN;
            if (sd_handles_port(ADDR_L)) {
                sd_write_port(ADDR_L, DATA_IN);
            }
            else if (ADDR_L == ADDR_6850_DATA) {
                Serial.write(DATA_IN);
            }
        }
    }

    prevIORQ = STATE_IORQ_N;
    CLK_LOW;  // Falling clock edge
    DATA_DIR = DIR_IN;
}

This runs at roughly 100kHz - slow by modern standards, but plenty fast for interactive programs. The Z80 was designed for clock speeds of 2-4MHz, so we're running at about 3-5% of original speed. Text adventures don't mind.

The BIOS: Hardware Abstraction in 1KB

The CP/M BIOS is where the magic happens. It's the only part of CP/M that needs to be written for each new hardware platform. The BDOS and CCP are universal - they work on any machine with a conforming BIOS.

Our BIOS implements 17 entry points:

                org     BIOS_BASE       ; 0xF600

                jp      BOOT            ; 00 - Cold boot
WBOOTE:         jp      WBOOT           ; 03 - Warm boot
                jp      CONST           ; 06 - Console status
                jp      CONIN           ; 09 - Console input
                jp      CONOUT          ; 0C - Console output
                jp      LIST            ; 0F - List output
                jp      PUNCH           ; 12 - Punch output
                jp      READER          ; 15 - Reader input
                jp      HOME            ; 18 - Home disk
                jp      SELDSK          ; 1B - Select disk
                jp      SETTRK          ; 1E - Set track
                jp      SETSEC          ; 21 - Set sector
                jp      SETDMA          ; 24 - Set DMA address
                jp      READ            ; 27 - Read sector
                jp      WRITE           ; 2A - Write sector
                jp      LISTST          ; 2D - List status
                jp      SECTRAN         ; 30 - Sector translate

The most complex routines are the disk operations. READ and WRITE must calculate the byte offset within the disk image from track and sector numbers:

CALC_OFFSET:
        ; offset = (track * 26 + sector) * 128
        ld      hl, (TRACK)
        ld      de, 26          ; Sectors per track
        call    MULT16          ; HL = track * 26
        ld      de, (SECTOR)
        add     hl, de          ; HL = track * 26 + sector

        ; Multiply by 128 (shift left 7 times)
        xor     a               ; Clear carry byte
        add     hl, hl          ; *2
        adc     a, 0
        add     hl, hl          ; *4
        adc     a, a
        ; ... continue shifting ...

        ld      (SEEKPOS), hl
        ld      (SEEKPOS+2), a  ; 24-bit result
        ret

The Disk Parameter Block (DPB) tells CP/M about our disk geometry:

DPB:
        defw    26              ; SPT - sectors per track
        defb    3               ; BSH - block shift (1K blocks)
        defb    7               ; BLM - block mask
        defb    0               ; EXM - extent mask
        defw    242             ; DSM - total blocks - 1
        defw    63              ; DRM - directory entries - 1
        defb    0xC0            ; AL0 - allocation bitmap
        defb    0x00            ; AL1
        defw    16              ; CKS - checksum size
        defw    2               ; OFF - reserved tracks

These parameters define a standard 256KB 8-inch floppy format - the same format used by countless CP/M machines in the late 1970s.

Understanding CP/M's Memory Model

CP/M's memory layout is elegantly simple. The entire operating system fits in the top 8KB of the 64KB address space:

┌───────────────────────────────────────┐ 0xFFFF
│              BIOS                     │ ~1KB - Hardware abstraction
├───────────────────────────────────────┤ 0xF600
│              BDOS                     │ ~3.5KB - File system, I/O
├───────────────────────────────────────┤ 0xE800
│              CCP                      │ ~2KB - Command processor
├───────────────────────────────────────┤ 0xE000
│                                       │
│                                       │
│              TPA                      │ ~56KB - Your programs!
│     (Transient Program Area)          │
│                                       │
│                                       │
├───────────────────────────────────────┤ 0x0100
│          Page Zero                    │ 256 bytes - System variables
└───────────────────────────────────────┘ 0x0000

Page Zero contains crucial system information:

0x0000-0x0002: Jump to warm boot
0x0005-0x0007: Jump to BDOS entry
0x005C: Default FCB (File Control Block)
0x0080: Default DMA buffer / command tail

When you type ZORK1 at the command prompt, CP/M loads ZORK1.COM at address 0x0100 and jumps there. The program has nearly 56KB to work with - a luxurious amount of memory for 1970s software.

Debugging Tips

Getting CP/M running required extensive debugging. Here are some tips if you're attempting something similar:

Enable Debug Output

Set outputDEBUG to 1 in the Arduino sketch to see every I/O operation:

#define outputDEBUG     1

This prints every port read/write, which is invaluable for tracking down why the BIOS isn't finding files or why sectors are being read from wrong locations.

Check Your Directory Format

The most common issue I encountered was improperly formatted disk images. Use a hex editor to verify:

Directory starts at offset 0x1A00 (6656 bytes)
Empty entries have 0xE5 in byte 0, not 0x00
Filenames are space-padded to 8 characters, extensions to 3

Verify DMA Addresses

If programs load but crash immediately, check that the DMA address is being set correctly. The BIOS must output both low and high bytes:

ld      a, l
out     (SD_DMA_LO), a
ld      a, h
out     (SD_DMA_HI), a

Watch for Register Clobbering

Z80 subroutine calls don't preserve registers by default. If your SELDSK routine returns garbage, check whether the OPENDISK helper is destroying HL before the return.

Performance Considerations

The system runs at approximately 100kHz - about 3% of the Z80's original 4MHz speed. This is limited by:

Arduino loop overhead: Each cpu_tick() call has function call overhead
DRAM access time: Software-controlled DRAM is slower than dedicated hardware
Software SPI: Bit-banging SPI adds latency to disk operations

For interactive programs like text adventures, this is imperceptible. For computation-heavy tasks, you'd notice the slowdown. WordStar feels sluggish but usable; compiling code would test your patience.

Future optimizations could include:

Assembly-optimized cpu_tick() routine
Hardware SPI with a different pin arrangement
Overclocking the Arduino (at your own risk)

Challenges and Solutions

Challenge 1: Pin Conflicts

The RetroShield claims the hardware SPI pins (50-53). Solution: software SPI on alternate pins. The SdFat library's SoftSpiDriver template makes this painless.

Challenge 2: Memory Refresh

DRAM needs refresh every few milliseconds or it loses data. Solution: the KDRAM2560 library uses Timer 1 interrupts to handle this transparently. The refresh happens in the background - you never need to think about it.

Challenge 3: Disk Image Format

CP/M expects 0xE5 (not 0x00) for empty directory entries. A disk image initialized to all zeros will confuse CP/M into displaying phantom files. Solution: the cpm_disk.py tool properly initializes the directory.

Challenge 4: 24-bit Seek Positions

Disk images are 256KB, requiring 18 bits to fully address. My initial 16-bit seek implementation couldn't access sectors past track 51. Solution: added a third seek port (0x19) for bits 16-23.

Challenge 5: SELDSK Return Value Bug

CP/M's BDOS expects SELDSK to return a pointer to the Disk Parameter Header in HL. My initial code calculated this pointer, then called OPENDISK which clobbered HL. Solution: push/pop HL around the OPENDISK call.

Getting Started: Bill of Materials

To build your own CP/M machine, you'll need:

Item	Approximate Cost
Arduino Mega 2560	$15-40
Z80 RetroShield	$35
KDRAM2560	$20
MicroSD Card Module	$5
MicroSD Card (≤32GB FAT32)	$5-10
Jumper wires	$5
Total	~$100-130

Files and Resources

The complete Arduino sketch and supporting files are available on GitHub:

Arduino Sketch: kz80_cpm.ino
Boot Loader Source: boot.asm
BIOS Source: bios.asm
Disk Image Tool: cpm_disk.py

Required libraries: - KDRAM2560 - 1MB DRAM library - SdFat - SD card with software SPI support

Conclusion

Building this system was a journey through computing history. CP/M's clean architecture - the separation of BIOS, BDOS, and CCP - made it possible to port a 45-year-old operating system to completely alien hardware in a matter of days. For a fascinating look at CP/M in its heyday, check out the Computer Chronicles episode on CP/M from 1984.

The Z80 doesn't know it's being fed clock pulses by an Arduino, that its memory is dynamic RAM on a shield, or that its "floppy drives" are files on an SD card. It just executes its opcodes, one after another, exactly as it did in 1978.

And somewhere in that stream of opcodes, a small mailbox waits west of a white house, just as it has for over four and a half decades.

>open mailbox
Opening the small mailbox reveals a leaflet.

>read leaflet
"WELCOME TO ZORK!

ZORK is a game of adventure, danger, and low cunning. In it you will
explore some of the most amazing territory ever seen by mortals..."

Welcome to the underground empire. The password is nostalgia, and the treasure is understanding how elegantly simple these early systems really were.