Skip to the content
4 layers81.7 × 61 mmPmod interface board, the printed circuit board in 3D

Pmod interface board

alpyen/zynq-gbcartreader3

Embedded Software Development project to read & write GameBoy cartridges.

Size
81.7 × 61 mm
Copper layers
4
Thickness
1.6 mm
Parts
31
Nets
65
Pads
208
Tracks, vias
325, 57
Pours
7
Routed
Yes
KiCad
KiCad 9.0 (file 20241229)
Created
22 Jul 2025
Updated
18 Jul 2026

Overview

Pmod interface board is an open-source printed circuit board by alpyen, from the alpyen/zynq-gbcartreader repository on GitHub. It is a 4-layer board of 81.7 × 61 mm with 31 parts on 65 nets, routed with 325 tracks and 57 vias.

It is built around the 74HCT541D, 74HC595 and 74HC597D. Its parts include 15 resistors, 6 capacitors, 6 ICs and 4 connectors. It belongs with the retro computing and games and fPGA and programmable logic boards and the FPGA and CPLD boards of this library.

Main components

3

README

README.md

ZYNQ GBCartReader - Read & Write GameBoy cartridges

This project is aimed to dive into FPGA SoCs and embedded software development by designing a system that's able to read and write to gameboy cartridges with a custom designed PCB which interfaces between the FPGA and the game cartridge.

Starting from a very basic bitbanging implementation solely running on the ARM core, the following design iterations will make use of a more sophisticated architecture by offloading the board communication to an IP core and moving commands and responses around with AXI interfaces.


A (badly) handsoldered demonstration of this project with a Pokémon Red cartridge.
Left is Top, Right is Bottom.

Navigation

  1. Supported Cartridge Types
  2. Reading and Writing Cartridges
    1. Reading ROM / RAM
    2. Writing RAM
  3. Setting up the FPGA-board
    1. Hardware Design with Vivado
    2. Software Application with Vitis
  4. Acknowledgements
  5. Todo-List

Supported Cartridge Types

There are a couple of different cartridge types that mostly distinguish between the type of mapper chip and additional periphery such as RAM, Real-Time-Clock, Battery and more. Here's a list of the ones that are available:

TypeStatusVerified On
No MBC✅Motocross Maniacs (DMG-MX-NOE)
Othello (DMG-OT-NOE)
MBC1✅ポケットモンスター 緑 (DMG-APBJ-JPN)
Super Mario Land (DMG-ML-NOE)
MBC2✅F-1 RACE (DMG-F1-NOE)
MBC3✅Pokémon Crystal (CGB-BYTD-NOE)
Pokémon Silver (DMG-AAXD-NOE)
MBC5✅Pokémon Red (DMG-APAD-NOE)
Pokémon Blue (DMG-APED-NOE)
Pokémon Yellow (DMG-APSD-NOE)
MBC30✅ポケットモンスター クリスタルバージョン (CGB-BXTJ-JPN)

Some exotic cartridges exist which are not supported. For an exhaustive list check the Pan Docs and GameBoy hardware database. Most games simply use No MBC, MBC1, 3 or 5. If I own any of the uncommon ones I'll implement them, otherwise I'll skip them as I cannot verify them.

This project supports reading the ROM, reading and writing to RAM allowing you to dump games, backup save files and also restore save files back to the cartridge. Reading and Writing RTC data is not supported.

I've noted that some games can underreport the number of ROM or RAM banks, for example ポケットモンスター 緑 or ポケットモンスター クリスタルバージョン. They only report half as many banks present, but manually fixing them in the software dumps these correctly too.

Reading and Writing Cartridges

This step assumes you have your FPGA-board configured with the application up and running.

Interfacing with the FPGA-board is done through python scripts by sending data over a serial port. Please refer to Setting up the virutal environment on how to create a virtual environment and install the pip packages (pyserial) to use the scripts.

The board communicates with a baudrate of 115200 and is plugged in to /dev/ttyUSB1 on my machine.

Check if your setup is healthy by runing the help command:

console
(.venv) zynq-gbcartreader/python$ python reader.py -b 115200 -p /dev/ttyUSB1 help
Sending command: help
Receiving data...482B/482B...done!
ZYNQ GBCartReader - Read & Write Gameboy cartridges
written by alpyen - visit the project on github.com/alpyen/zynq-gbcartreader

Available commands:
-------------------
help          Display this help page
parse header  Read cartridge header and parse into readable form
read rom      Read cartridge rom and echo it in binary
read ram      Read cartridge ram (if available) and echo it in binary
write ram     Write cartridge ram (if available) from binary terminal data

A help screen should be printed which is sent by the applicaton running on the FPGA-board. If you do not receive any text or the connection hangs, make sure to correctly flash the board, and check your access permissions on that serial port.

Reading ROM / RAM

Plugging in a Pokémon Crystal cartridge (CGB-BYTD-NOE) I can read out its header:

console
(.venv) zynq-gbcartreader/python$ python reader.py -b 115200 -p /dev/ttyUSB1 parse header
Sending command: parse header
Receiving data...858B/858B...done!
Overview:
  Entry Point:       00 C3 6E 01
  Nintendo Logo:     Good
  Title:             PM_CRYSTAL
  Manufac. Code (?): BYTD
  CGB Flag:          CGB exclusive
  New Licensee Code: Nintendo Research & Development 1
  SGB Flag:          No
  Type:              MBC3 + RTC + RAM + Battery
  ROM Size:          2048 KiB (128 banks)
  RAM Size:          32 KiB (4 banks)
  Destination Code:  Overseas
  Old Licensee Code: Check New Licensee Code
  Version:           00
  Header Checksum:   28 (Good)
  Global Checksum:   49 82

Full Header:
  0x0100:  00 C3 6E 01 CE ED 66 66 CC 0D 00 0B 03 73 00 83
  0x0110:  00 0C 00 0D 00 08 11 1F 88 89 00 0E DC CC 6E E6
  0x0120:  DD DD D9 99 BB BB 67 63 6E 0E EC CC DD DC 99 9F
  0x0130:  BB B9 33 3E 50 4D 5F 43 52 59 53 54 41 4C 00 42
  0x0140:  59 54 44 C0 30 31 00 10 06 03 01 33 00 28 49 82

Now all you have do to dump this cartridge is to use the read rom function. The python script will output the contents onto stdout while printing the current progress onto stderr. Pipe the result into a file like so:

console
(.venv) zynq-gbcartreader/python$ python reader.py -b 115200 -p /dev/ttyUSB1 read rom > cartridge.gb
Sending command: read rom
Receiving data...2048K/2048K...done!

The file extension does not really matter, it is recommended to simply use one that downstream tools like emulators or inspection tools can handle.

Dumping the cartridge RAM is as straightforward, simply replace read rom with read ram.

Writing RAM

Use write ram and either pipe in the RAM file or redirect stdin like so:

text
(.venv) zynq-gbcartreader/python$ python reader.py -b 115200 -p /dev/ttyUSB1 write ram < cartridge.sav
Sending command: write ram
Sending size...done!
Sending data...32K/32K...done!

Note: Since RTC reads/writes are not implemented some games may ask you to re-set the clock.

Setting up the FPGA-board

This project was developed with Vivado/Vitis 2025.1 and uses scripts for these versions. It should be possible to recreate the projects with minimal hassle on different versions.

Currently the PYNQ-Z2 with the software running on the ARM and the Basys3 with the software running on a MicroBlaze-V soft core processor are supported.

Hardware Design with Vivado

Note: This step can be skipped if a pre-built XSA is downloaded from the releases section. Place it in the vivado subfolder and continue with the Vitis section.

You can regenerate the project by starting Vivado and opening the tcl console. Navigate with cd into the vivado subfolder and either run source regenerate_pynq_z2.tcl or source regenerate_basys3.tcl.

Vivado will rebuild the project from the source files. Once that's done you can generate the wrappers for the different block design implementations, synthesize and export the XSA files for use in Vitis.

Note: The automatic wrapper generation is not implemented for now.

Software Application with Vitis

Vitis offers a python interface to dispatch commands from scripts to the application. In order to use this, you need to source the settings64.sh from the Vitis installation. If you've installed the Xilinx tools in the default location then open up a new terminal and load the settings by running these commands based on your operating system:

  • Windows: call C:/Xilinx/2025.1/Vitis/settings64.bat
  • Linux: source /opt/Xilinx/2025.1/Vitis/settings64.sh

In the same terminal navigate with cd into the vitis subfolder and either run vitis -s regenerate.py pynq-z2 or vitis -s regenerate.py basys3.

Note: This script has to be run from Vitis, it will not work with your local python installation.

Unfortunetaly only later versions of Vitis support compilation settings through the Python API so some entries have to be manually configured for the Basys3 build which the script will warn you about when creating the Vitis project.

The script takes care of several things:

  1. Performs sanity checks to see if the execution environment is correct and if the XSA files have been exported, otherwise the platform generation will fail.
  2. Delete everything except the regenerate.py inside the vitis subfolder to remove a potentionally old workspace.
  3. Regenerate the different platforms and applications used to run it on the board.
  4. Link sources located outside the vitis workspace to into the projects.

Once the regeneration is complete you can open the Vitis GUI and set the workspace to the vitis subfolder. Now you're ready to build the applications and deploy them.

Acknowledgements

This project heavily relies on the work of others who have reverse engineered and documented the inner workings of the Game Boy and its cartridges and/or compiled existing information:

Todo-List

  • Do the actual work in an IP-Core and communicate with PS instead of bitbanging

Parts

31
QtyValueFootprintReferences
1310KResistor_THT:R_Axial_DIN0204_L3.6mm_D1.6mm_P5.08mm_HorizontalR1, R2, R3, R4, R5, R6, R7, R8, R9, R10, R11, R12, R13
6100nFCapacitor_THT:C_Disc_D4.7mm_W2.5mm_P5.00mmC1, C2, C3, C4, C5, C6
374HC595Package_DIP:DIP-16_W7.62mmU3, U4, U5
274HCT541Package_DIP:DIP-20_W7.62mmU1, U2
1100RResistor_THT:R_Axial_DIN0204_L3.6mm_D1.6mm_P5.08mm_HorizontalR14
1200RResistor_THT:R_Axial_DIN0204_L3.6mm_D1.6mm_P5.08mm_HorizontalR15
174HC597Package_DIP:DIP-16_W7.62mmU6
1Gameboy Cart Connectorpmod-interface-board:GBCartConnectorJ4
1PMOD Connector 1Connector_PinHeader_2.54mm:PinHeader_2x06_P2.54mm_HorizontalJ1
1PMOD Connector 2Connector_PinHeader_2.54mm:PinHeader_2x06_P2.54mm_HorizontalJ2
1~Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_VerticalJ3

Similar boards

  • 2 layersControl, the printed circuit board in 3D

    Control

    Velko/8-bit-CPU

    Homebrew 8-bit CPU

    64 parts16MIT
  • 4 layers101.6 × 147.3 mmKarabas go, the printed circuit board in 3D

    Karabas go

    andykarpov/karabas-go-pcb

    Karabas-Go PCB

    311 parts3
  • 2 layers144 × 100 mmUrbanSteering, the printed circuit board in 3D

    UrbanSteering

    supermileage/UrbanSteeringPCB

    Kicad files for the urban steering PCB

    50 parts
  • 2 layers99.7 × 58.4 mmESP32Hardware, the printed circuit board in 3D

    ESP32Hardware

    bvenneker/CHAT64

    Chat64 for Commodore64

    21 parts
  • 2 layers99.6 × 100 mmGateometry, the printed circuit board in 3D

    Gateometry

    Desval27/Gateometry

    Gateometry is an Arduino-based, 8-channel Euclidean rhythm generator for Eurorack synthesizers, featuring programmable rhythms, individual gate outputs and mute switches, external clock synchronization, and an OLED…

    79 partsMIT
  • 2 layers118 × 87 mmCore32f4 V0.1, the printed circuit board in 3D

    Core32f4 V0.1

    papaya/Modulbox

    Midibox files PCB kicad

    40 parts2
  • 2 layers130 × 100 mmCore32V7, the printed circuit board in 3D

    Core32V7

    papaya/MB_ModulBox_NG

    MBModulBoxNG est une bibliothèque de cartes de contrôle physiques pour le système MIDIbox NG. Les sources, schémas, PCB et fichiers de fabrication ne sont pas tous disponibles pour chaque carte.

    37 parts
  • 4 layers110 × 110 mmSmoothiev2-prime, the printed circuit board in 3D

    Smoothiev2-prime

    Smoothieware/Smoothieboard2

    Hardware files for the Smoothieboard v2, and extension boards

    453 parts71

Questions

How big is the Pmod interface board PCB?

It measures 81.7 × 61 mm and has 4 copper layers, 1.6 mm thick.

What parts does the Pmod interface board use?

31 parts, built around the 74HCT541D, 74HC595 and 74HC597D. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Pmod interface board KiCad files?

From the alpyen/zynq-gbcartreader repository on GitHub, at the commit this page was made from: the board is kicad/pmod-interface-board.kicad_pcb and its schematic kicad/pmod-interface-board.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Pmod interface board design in my own project?

Its repository states no licence, so its author keeps all rights: ask alpyen before reusing the design.