# PUMPBOY physical cartridge kit

This is a hardware prototype, not a hardware-validated product. The Game Boy ROM and Pico firmware are built; protocol and ROM tests run in software. No real Game Boy, adapter, wallet transaction or IPFS upload has been tested. Begin with practice mode.

## Parts

- Original Nintendo Game Boy (DMG) with a working link port.
- A DMG-compatible flash cartridge that can load a 128 KB MBC1 Game Boy `.gb` image (no cartridge RAM or battery is used). A normal retail game cartridge cannot be rewritten. Follow the flash cartridge manufacturer's copying/flashing instructions; practically every flash cartridge supports MBC1.
- Raspberry Pi Pico **RP2040** (the original Pico, not Pico 2), preferably with soldered headers, plus a USB data cable.
- A DMG link plug/cable breakout. The original DMG connector differs from the smaller Pocket/Color connector. Cable wire colors are not reliable: identify contacts with continuity testing.
- A 5 V/3.3 V logic interface: two channels from Game Boy to Pico, one from Pico to Game Boy, plus common ground. A suitable professionally assembled Game Boy/Pico level-shifter board is preferable to loose wiring, but its GPIO mapping must match or the firmware must be rebuilt. This firmware is not a drop-in replacement for arbitrary commercial USB adapters.
- Desktop Chrome or Edge with Web Serial and Phantom/Solflare for live mode. The Codex preview browser may not expose serial devices. USB approval is required once in the companion page.

## Electrical mapping

Power off and unplug both devices before wiring. **Never connect the Game Boy's 5 V signals directly to Pico GPIO.** Pico GPIO operates at 3.3 V. Do not power the Game Boy from USB or join the Game Boy power pin to Pico's 3V3 pin. Power the Game Boy normally and the Pico via USB.

The pin numbers below are **Game Boy port signal names/numbers**, not the far end of an arbitrary link cable. Standard cables cross data lines; verify the path back to the Game Boy's actual port. Connector-view orientation must be checked against Pan Docs.

| Game Boy link port | Direction at Game Boy | Interface | Pico |
| --- | --- | --- | --- |
| Pin 2, SOUT | Output | 5 V → 3.3 V input translation | GP0, physical pin 1 |
| Pin 3, SIN | Input | 3.3 V → 5 V output translation | GP1, physical pin 2 |
| Pin 5, clock | Output; Game Boy is master | 5 V → 3.3 V input translation | GP2, physical pin 4 |
| Pin 6, ground | Common reference | Ground | GND, physical pin 3 |
| Pin 1, power; pin 4 | Not used by this adapter | Leave disconnected | — |

Use level-converter hardware designed for push-pull clock/data at 8.192 kHz and isolate outputs when the Game Boy is off. A qualified electronics builder should check the interface before power-on. This kit does not include a validated PCB schematic or a manufactured cable.

## Install and run

1. Put `pumpboy-link.gb` on the compatible flash cartridge and insert it in the Game Boy.
2. Hold BOOTSEL while connecting the Pico to USB. Copy `pumpboy_link.uf2` onto its `RPI-RP2` drive. It reboots as a USB serial adapter. Flashing replaces the Pico's existing firmware; use a dedicated Pico.
3. Assemble and verify the level-shifted wiring above, then power both devices.
4. Open the companion served from this build (`http://localhost:8765/?hardware=1` for local testing) in desktop Chrome or Edge. Click **Connect USB adapter**, and choose the Pico serial device. Keep this page open and active. Do not open the port in another serial terminal.
5. Wait for **LINK CONNECTED** (allow 10–20 seconds for the complete settings snapshot). If the operating system opens a serial monitor automatically, close it. A plain USB-UART adapter cannot replace this firmware.
6. On the Game Boy, press Start and use the launch desk to edit details and artwork, then Review/Launch. Leave mode set to **PRACTICE**. Press A to review costs, release it, then hold A until the meter fills. The shrine should finish with **PRACTICE COMPLETE** on the physical screen.
7. Only after that hardware test succeeds, configure upload/metadata and RPC settings in the companion page, connect a wallet, and select LIVE in the ROM. Holding A requests preparation; the wallet still requires approval before signing. The selected dev buy, slippage cap, priority fee, network fees and rent apply; the default dev buy is zero.

Names, pixels, menu choices and confirmation originate on the physical cartridge. The computer handles image upload, wallet access, transaction preparation and network confirmation. Private keys and Pinata credentials are never sent over the link cable. Browser connection forms and downloaded PNGs remain on the computer. Sound plays on the Game Boy. Saved drafts are copied to browser storage; this ROM-only cartridge does not persist artwork across power-off or restore drafts from the PC.

## Link behavior and recovery

The ROM uses the original internal serial clock, MSB first. The adapter writes data on falling clock edges and samples on rising edges. To avoid stalling native graphics, the prototype initiates one byte per game-loop iteration, with each 125-byte packet taking roughly 2–5 seconds in software. PBL2 sends four packets per complete settings snapshot. Status may lag by several seconds. This conservative rate is intentional; it does not attempt the port's full throughput.

PBL1 frames are `50 42 LENGTH BODY CRC_LO CRC_HI`. CRC16-CCITT-FALSE covers BODY (polynomial 0x1021, initial 0xffff). BODY begins with version 1, type, 16-bit command ID, and a four-byte host session nonce. Type 1 snapshots carry mailbox bytes 0–47 and 64 bytes of packed pixels (four pixels per byte, lowest bits first). PBL2 retains the framing and base snapshot, with version 2 and metadata chunk types 4, 5 and 6. Chunks carry mailbox bytes 512–767 in 112/112/32-byte pieces, padded to 112 bytes. All pieces share the base command sequence and nonce; the browser commits only a complete set, resetting partial assembly on each new base packet. Type 3 (version 1) starts a host session. Type 2 returns a result byte, metadata-source flag and four 20-character status lines. Unknown versions, bad checksums, old command IDs and wrong nonces are ignored. CRC detects transmission errors; it is not cryptographic authentication.

On every USB connection the host establishes a new nonce and takes the first valid snapshot as a baseline. It **does not replay the current command**. Reconnecting while the ROM is waiting reports a paused launch. Missing replies disable the cartridge's launch confirmation after ~10 seconds of ROM time. There is no automatic transaction retry. If unplugged after signing/sending, check the companion's transaction link before attempting a new launch. Do not reload or close the companion page while a transaction is in flight.

If there is no handshake: verify you flashed the link ROM, inspect GND and the three translated signals, confirm USB is a data cable and Web Serial is available, and check the Game Boy is powered on. If random bytes/CRC failures persist, check the connector orientation and translation before changing software. Use a logic analyzer at the translated 3.3 V side to validate edges and byte framing. Do not connect the analyzer or Pico directly to 5 V lines unless rated for them.

## Build firmware from source

Requires the official Pico SDK (tested here with 1.5.1), its TinyUSB submodule, CMake and an `arm-none-eabi` compiler. The build targets the original RP2040 Pico.

```sh
export PICO_SDK_PATH=/absolute/path/to/pico-sdk
cmake -S pico -B build -DPICO_BOARD=pico
cmake --build build -j4
```

The result is `build/pumpboy_link.uf2`. GPIO assignments are at the top of `pico/main.c`. SDK/compiler dependencies are not bundled. Rebuild the ROM from the website source with `python3 scripts/build-rom.py` and GBDK 4.5.0 installed (`GBDK_HOME` can override its path).

## Technical references

- [Game Boy serial protocol](https://gbdev.io/pandocs/Serial_Data_Transfer_%28Link_Cable%29.html)
- [Game Boy connector pinout and orientation](https://gbdev.io/pandocs/External_Connectors.html)
- [Pico board and electrical documentation](https://datasheets.raspberrypi.com/pico/pico-datasheet.pdf)
- [Pico SDK](https://github.com/raspberrypi/pico-sdk)
- [GBDK serial and hardware APIs](https://gbdk.org/docs/api/gb_8h.html)

## Pump Island cartridge

The link cartridge is the same 128 KB MBC1 Pump Island ROM as the browser build, compiled with the serial link enabled. Start opens the four-step launch desk; Start while walking returns to it. The village is optional scenery built from the template's Mabe Village rooms: the terminal in your house edits the name and ticker, the arcade claw draws or rolls an emblem, the fisherman links the wallet, the shopkeeper opens launch settings, Ulrira and the phone booth edit links and bio, the library laptop opens device settings, and the pump station in the Dream Shrine reviews and launches.

In the editor, A paints, B erases, Select changes ink, A + Select opens tools, and B + Select generates an emblem. Start saves and exits. Eight Link's Awakening MIDI arrangements play through the browser jukebox (Select in Device/Connection). Music + Effects on the cartridge plays a native Mabe Village lead reduction. Artwork and names remain in working RAM and are lost on power-off; the companion can save a local copy. The cartridge does not implement battery-backed saves.

## Native launch settings

Select on the desk opens dev buy, creator/holder rewards, links/bio and transaction fees. Left/right changes choices; A enters a submenu; B saves and returns. Links are edited on the cartridge with case switching and HTTPS prefixes. The separate cost confirmation displays maximum dev buy, priority fee, additional network/rent costs and the permanent holder-rewards choice. The companion receives these settings and metadata in the same complete PBL2 snapshot as the launch command. Use the matching companion and ROM from this kit.