Pico Game Console (v1)

The original Pico Game Console firmware: an SSD1306 OLED (128×64), six buttons, a PWM buzzer, and a simple line-based text interpreter (PGCScript) driven from a PC over USB serial.

⚠️ This is v1. The interpreter was rewritten from scratch for the pico-gc-v2 firmware (PgcScript v2 — CAScript-flavoured, compiled bytecode, functions/loops/wait(), and all of the v1 bugs below fixed). v1 is kept as the original reference.

Related: Pico-GC-Game-Repo (which holds the v1 games in V1/) · pico-gc-v2 (the rewrite)

Hardware

Part	Wiring
OLED	SSD1306 128×64, I2C1, GP6 (SDA) / GP7 (SCL), addr 0x3C
Buttons	UP / DOWN / LEFT / RIGHT / A / B on GP10–GP14, GP16 (active-low, internal pull-ups)
Buzzer	GP15 (PWM)
Onboard LED	GP25

How it works

The firmware boots, initializes display/buttons/audio, then loops forever:

1. polls the buttons, printing BTN_DOWN <name> / BTN_UP <name> over USB,
2. drains the USB serial buffer into process_command(),
3. re-runs the loaded script's loop section once per frame (~60 FPS).

Games are written in PGCScript, a tiny line-based language: each line is one instruction and the interpreter re-parses and re-executes every line every frame. A script is uploaded over serial as:

BEGIN_LOAD
<every line of the game file>
END_LOAD

Lines before the # --- LOOP --- marker run once as setup; lines after it re-run every frame. The full language reference (commands, limits, gotchas) lives in the game repo: Pico-GC-Game-Repo/PGCScript_Documentation.md.

Uploading a game

Use pico_launcher.py from the game repo: it scans for *.txt files whose first line is # PICO_CONSOLE_GAME <title>, shows a menu, and streams the chosen one to the Pico over 115200 serial.

Building

cmake -B build
cd build && make

Flash build/pico_game_console.uf2 (hold BOOTSEL, drag-and-drop).

Known limitations (all fixed in v2)

• Conditional nesting deeper than 3 levels can overflow the stack into the audio thread and kill the buzzer until power-cycle.
• text messages over 63 chars overflow a 64-byte buffer.
• rand is unseeded — the same sequence replays every boot.
• Audio notes are silently dropped when the 32-deep queue is full.
• No button debouncing.
• The OLED re-sends all 8 pages every frame (~20 ms) — the FPS ceiling.
• No functions, loops, or math beyond + - / rand; restarting a game means hand-resetting every variable.