Gb devcart

GB DEVCART r1 — open hardware

A simple, original Game Boy (DMG) / ModRetro Chromatic homebrew development cartridge. 512 KB of rewritable NOR flash, 8 KB of battery-free F-RAM, and an MBC5-subset mapper built from discrete 74HC logic. 2-layer, 56 x 49.5 mm, 32 edge fingers at 1.5 mm pitch, 5 V bus.

Status: fully routed (2 layers, Freerouting through fabdesk), DRC/ERC clean, in-stock JLCPCB parts with LCSC numbers, JLC gerbers/BOM/CPL in exports/jlcpcb/. Not yet built or tested on hardware.

Designed with fabPlane (fabdesk) driving Claude Code. Inspired by the ModRetro "Demo Cartridge", but an original, much simpler design: no FPGA, no level shifters, no regulators.

Quick start

# build the demo game (GBDK-2020)
make -C game GBDK_HOME=/path/to/gbdk
# test the programmer end to end against the cart simulator (no hardware needed)
programmer/test_e2e.sh
# flash a real cart through an Arduino Mega 2560 (see programmer/README.md for wiring)
python3 programmer/host/gbflash.py --port /dev/ttyACM0 flash game/dist/bitcatcher.gb

Top	Bit Catcher on the cart

Memory map

Notes:

• 0x3000–0x3FFF is deliberately not decoded, so MBC5 software that writes bit 8 there does not clobber the bank register.
• No RAM-enable register and no RAM bank latch. Upgrade path: use the FRAM's A13/A14 with a 2-bit latch.
• The bank register is undefined at power-up. Bank-0 code must write it before using 0x4000–0x7FFF.
• Writes to 0x4000–0x7FFF are the only ones that reach the flash /WE.

Logic

The flash sees A0–A13 from the bus and A14–A18 from the latch (D0–D4).

Flashing from the Game Boy

Run the flasher from WRAM/HRAM, because the flash returns status instead of data while busy. Interrupts off. All command cycles go through the switchable window, so bank-register writes at 0x2000 never reach the flash.

The SST39SF040 decodes commands on address bits A14–A0 only: 0x5555 and 0x2AAA.

• 0x5555 needs chip A14 = 1, so select an odd bank (e.g. 1) and write to GB 0x5555.
• 0x2AAA needs chip A14 = 0, so select an even bank (e.g. 0) and write to GB 0x6AAA.

Byte program of data to chip address X:

1. [0x2000]=1; [0x5555]=0xAA
2. [0x2000]=0; [0x6AAA]=0x55
3. [0x2000]=1; [0x5555]=0xA0
4. [0x2000]=X>>14; [0x4000 + (X & 0x3FFF)]=data
5. Poll the same address until DQ7 equals data bit 7 (or DQ6 stops toggling), about 20 µs.

Sector erase (4 KB) at SA: the same first two cycles, then [0x2000]=1; [0x5555]=0x80, [0x5555]=0xAA, [0x2000]=0; [0x6AAA]=0x55, then [0x2000]=SA>>14; [0x4000+(SA&0x3FFF)]=0x30. Chip erase: the same, with the last cycle [0x2000]=1; [0x5555]=0x10. Then poll as above.

Program a 16 KB bank only from a bank other than the one being written, or from RAM, and verify by read-back. Keep bank 0 (vectors, header, flasher stub) write-protected by software convention.

Hardware notes

• /RESET has a 10 kΩ pull-up (R1). AUDIO_IN is unconnected except for test pad TP6.
• Test pads: TP1 VCC, TP2 GND, TP3 CLK, TP4 /WR, TP5 /RD, TP6 AUDIO_IN.
• Edge fingers are on the component side, 0.5 mm back from the board edge; order the board with ENIG.
• Pin 1 (VCC) is at the left, looking at the component side. Order: VCC, CLK, /WR, /RD, /CS, A0–A15, D0–D7, /RESET, AUDIO_IN, GND.
• 3.5 mm boss hole at (28, 39) mm from the top-left; all parts are kept above y = 41.5 mm.
• Latch outputs are tri-stated and pulled down for bank 0, so the bank-0 address-to-data path depends on a ~2.2 kΩ RC settle (about 40–80 ns). Check the timing on a real console.
• The /CS decode assumes /CS is asserted for A15 = 1; verify on the target hardware.
• Bus is 5 V logic (HC family). Confirm that your target's cartridge port tolerates 5 V.

BOM

Programming over USB

The cart is programmed by an Arduino Mega 2560 (5 V I/O, so no level shifters) wired to a 32-pin Game Boy cartridge slot. The PC runs programmer/host/gbflash.py (info, flash, dump, erase, save-backup, save-restore). The flashing algorithm lives in programmer/firmware/gbflash/gbflash_core.h, which also compiles into a native simulator of this cart for hardware-free tests. See programmer/README.md for the wiring table.

3D models

Every component carries a 3D model, vendored in 3dmodels/ and referenced as ${KIPRJMOD}/3dmodels/…, so the project renders and exports (STEP/GLB) with no global KiCad 3D library. The passives and SOIC models come from the official KiCad 3D library (CC-BY-SA 4.0 with the KiCad library exception). KiCad ships no PLCC-32 model, so scripts/make_plcc32_model.py generates one with CadQuery (JEDEC MS-016 body, 32 J-leads) matching the KiCad footprint. Regenerate the renders with:

kicad-cli pcb export glb --include-pads --include-silkscreen --include-soldermask -o renders/board.glb board.kicad_pcb
kicad-cli pcb export step -o exports/board.step board.kicad_pcb
cd scripts/render3d && npm install && CHROMIUM_PATH=/path/to/chrome npm run render  # -> renders/3d-*.png

Ordering

See docs/jlcpcb-pricing.md for bare-PCB and assembled prices at JLCPCB with LCSC part numbers. Order ENIG (or hard-gold fingers with a 45° bevel) and 1.0 mm thickness so the board fits a standard DMG cartridge shell.

JLC order files (regenerate with KICAD_CLI=… python3 scripts/jlc_export.py):

Check the rotation preview on JLC's assembly page before confirming. SOIC and PLCC reels sometimes need a ±90° correction.

Routed top (F.Cu)	Routed bottom (B.Cu)

Snapshot from 2026-10-01 (USD, before shipping):

Before ordering:

• Stock. The design now uses the in-stock drop-ins: SST39SF040-55-4I-NHE-T (C632847, the same flash in a faster, industrial grade) and FM18W08-SGTR (C55945, the same F-RAM on tape and reel). Stock was 17 and 45 on 2026-10-01, so re-check it before ordering. The F-RAM is about 60% of the assembled cost.
• Gold-finger size rule. JLC's bevelled gold-finger option needs boards of at least 50 mm on both sides. This board is 49.5 mm tall, so widen it to 50 mm (r1.1) or order a panel. Plain ENIG needs no change.

Project files

• scripts/sync_fields.py copies MPN / Manufacturer / LCSC from the netlist into board.kicad_pcb and board.kicad_sch.
• scripts/jlc_export.py writes the JLC gerbers, BOM and CPL.
• scripts/gen.py generates lib/gbdev.kicad_sym, lib/gbdev.pretty/ and circuit.netlist.json. The netlist is the source of truth; board.kicad_* are built from it.
• Symbols and the edge footprint are custom (gbdev library) because the build environment has no KiCad symbol libraries.

Project status

• Netlist: 26 components, 46 nets. Custom gbdev symbols and edge footprint; placement inside the 56 x 49.5 mm outline, with all parts above y = 41.5 mm and the 3.5 mm boss hole at (28, 39).
• Routing: done with Freerouting 2.4.1 (Java 25) through fabdesk's route_run. All 134 connections are routed in one run.
  • Rules: 0.2 mm tracks, 0.15 mm clearance, 0.5/0.3 mm vias, all within JLCPCB's standard 2-layer process.
  • Keepouts: a copper keepout around the boss hole and rules for the finger zone.
  • Power: VCC/GND widened to 0.25–0.4 mm where neighbouring tracks allow. A GND pour on B.Cu would be a good r1.1 change.
• DRC: 0 errors, 0 warnings, 0 unconnected, 0 schematic-parity conflicts. ERC: 0 errors.
• What didn't work: fabdesk's built-in capacity router (fab_router) could not route this dense 2-layer bus. Its best result was 63 of 134 connections, and long runs block the bridge process until fabdesk times out. To get to the result above, parts were moved (U2, U3, C2, C3, C6, R2–R6), the rules were tightened as listed, and Freerouting was enabled.
• Board thickness: still the KiCad default (1.6 mm). Choose 1.0 mm in the fab order so the board fits a DMG shell.
• Hand edits: the silkscreen text and the J1 reference position were added to board.kicad_pcb by hand. A circuit_build with fresh: true will discard them, along with the routing.
• Not yet verified on hardware: bus timing (bank-0 pull-down settling), the /CS decode assumption, and the JLC rotation offsets.