PRG32

PRG32 is an open-source educational runtime for teaching RISC-V assembly and C programming in undergraduate computer architecture and systems courses. PRG32 exposes a minimal interface built around the init/update/draw game loop.

PRG32 provides an entire retro-gaming environment to run native RV32IMAC machine code on the Espressif ESP32-C6, a commercially available microcontroller. The platform includes embedded firmware, a .prg32 cartridge format and toolchain, a QEMU-based desktop emulator and can be used in combination with the Cartridge Store, a server providing app-store-style distribution, multiplayer relay, score tracking, and frame-level metrics collection.

Cartridges reach a running console without Wi-Fi or a bootloader reset: the resident firmware recognizes the framed prg32-io-1.0 protocol on the board's native USB port, shows upload progress, verifies the cartridge, and can start it. The same protocol serves the SDK command line, QEMU, PRG32-QT, and web applications such as the PRG32-Construction-Kit through the browser's Web Serial API.

PRG32 is not a CPU instruction emulator. Code runs natively on ESP32-C6 hardware, or on Espressif QEMU firmware target ESP32-C3 for desktop graphics/testing.

Hardware

The platform is designed around the Espressif ESP32-C6 microcontroller and uses accessible, low-cost components for easy classroom assembly. The standard hardware setup includes:

• Display: A 2.8" SPI ILI9341 TFT display. PRG32 uses the classic retro-game resolution of 320x200 with a 256-entry RGB565 palette.
• Audio: One or two MAX98357A I2S amplifiers for mono or stereo sound.
• Input: A simple digital joystick and action buttons wired directly to GPIO pins. GPIO12 and GPIO13 stay free for the native USB connector used for offline cartridge uploads.

Please refer to the Hardware & Pinouts guide for further information about breadboard wiring diagrams, PCB references and the full bill of materials.

Academic Profile

• Project domain: Embedded Systems and Computer Architecture Education
• Platform focus: ESP32-C6 (hardware) and ESP32-C3 QEMU path (desktop emulation)
• Course style: first-year/early undergraduate assembly and systems labs
• Academic supervisor / project lead: Raffaele Montella - UniParthenope
• Contributor (student): Simone Boscaglia - UniParthenope - Computer Science student
• Contributor (student): Ivan Cafiero - UniParthenope - Computer Science student

Install & Setup

Windows

1. Install Git for Windows and Python 3.
2. Download and run the Espressif ESP-IDF Tools Installer for Windows.
3. Select an ESP-IDF 5.4 or newer release.
4. Include support for esp32c3 and esp32c6.
5. (Optional) Check the QEMU RISC-V emulator box during installation if you want to use the QEMU desktop emulator.
6. Open the "ESP-IDF PowerShell" shortcut created by the installer. This will activate the ESP-IDF environment, so pip will install into it.
7. Clone the project and verify your setup from that shell

cd $HOME\Documents
git clone https://github.com/riscv-prg32/PRG32
cd PRG32
pip install pyaudio zeroconf
python -m prg32 doctor

Notes

• Use the ESP-IDF PowerShell or ESP-IDF Command Prompt, not a plain terminal where idf.py has not been exported.
• Plug the ESP32-C6 into its connector labelled USB (not UART). Windows 10 and 11 install the driver for it automatically; it appears in Device Manager under Ports (COM & LPT) as USB Serial Device (COMx). Run python -m prg32 esp32c6 ports to check that PRG32 sees it.
• Cartridge uploads, run, key, and Wi-Fi commands find the board without --port when only one is connected. With several boards, pass the one you want, for example --port COM5.
• If the board does not appear, try another USB-C cable: charge-only cables power the board but carry no data.
• If flashing fails, check Device Manager for the ESP32-C6 serial port and pass it explicitly with -p COMx.
• If PlatformIO Monitor cannot open the port, close Arduino Serial Monitor, ESP-IDF Monitor, and every other terminal using the same COM port.

Linux

Install dependencies (Debian/Ubuntu):

sudo apt update
sudo apt install -y git wget flex bison gperf python3 python3-venv python3-pip python3-zeroconf cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 curl zip portaudio19-dev

Install QEMU native libraries (optional, required for QEMU desktop emulator only):

sudo apt install -y libgcrypt20 libglib2.0-0 libpixman-1-0 libsdl2-2.0-0 libslirp0

Install ESP-IDF:

cd $HOME
git clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32c3,esp32c6
. ./export.sh
# Install Python packages inside the ESP-IDF environment
pip install pyaudio zeroconf
# Optional: install QEMU desktop emulator
python $IDF_PATH/tools/idf_tools.py install qemu-riscv32

Clone the project and verify your setup:

git clone https://github.com/riscv-prg32/PRG32
cd PRG32
python3 -m prg32 doctor

Linux serial permissions:

sudo usermod -aG dialout "$USER"

Log out and back in after changing group membership.

Notes

• Serial permissions are required. Without dialout membership (uucp on Arch-based systems) PRG32 cannot open the board, and uploads report that no ESP32-C6 was found. Check with groups; after usermod, log out and back in, then reconnect the USB cable.
• Plug the ESP32-C6 into its connector labelled USB (not UART). It appears as /dev/ttyACM0; the UART connector appears as /dev/ttyUSB0 or /dev/ttyACM1 and cannot receive cartridges. Run python3 -m prg32 esp32c6 ports to check that PRG32 sees the board.
• Cartridge uploads, run, key, and Wi-Fi commands find the board without --port when only one is connected. With several boards, pass the one you want, for example --port /dev/ttyACM0.
• Close serial monitors (idf.py monitor, screen, minicom) before an upload; only one program can use the port at a time.

macOS

Install dependencies:

brew install git cmake ninja dfu-util ccache libusb python curl zip portaudio

Install QEMU native libraries (optional, required for QEMU desktop emulator only):

brew install libgcrypt glib pixman sdl2 libslirp

Install ESP-IDF:

cd $HOME
git clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32c3,esp32c6
. ./export.sh
# Install Python packages inside the ESP-IDF environment
pip install pyaudio zeroconf
# Optional: install QEMU desktop emulator
python $IDF_PATH/tools/idf_tools.py install qemu-riscv32

Clone the project and verify your setup:

git clone https://github.com/riscv-prg32/PRG32
cd PRG32
python3 -m prg32 doctor

PlatformIO (Alternative)

While ESP-IDF standalone is the primary and recommended way to install and build PRG32, you can also use PlatformIO. Open the repository root in PlatformIO. The checked-in platformio.ini default environment targets the ESP32-C6.

CLI Setup (Linux/macOS):

python3 -m venv .venv-platformio
. .venv-platformio/bin/activate
python3 -m pip install platformio
pio run
pio run -t upload
pio device monitor -b 115200

VS Code Setup (Windows):

1. Install Git for Windows.
2. Install Visual Studio Code.
3. Install the Espressif ESP-IDF extension for VS Code.
4. Install the PlatformIO extension for VS Code.
5. Install the Microsoft C/C++ and Python extensions.

• Use the checked-in PRG32.code-workspace for student labs; paths are workspace-relative.

CLI Setup (Windows):

cd $HOME\Documents\PRG32
pio run
pio run -t upload
pio device monitor -b 115200

The ESP32-C6 build keeps UART0 as the primary ESP-IDF console and enables native USB Serial/JTAG as a secondary output for PlatformIO Monitor. A healthy boot logs the configured prg32_lcd ILI9341 pins before drawing the splash.

The PlatformIO environment is for the physical ESP32-C6 classroom board. Keep using the commands in the QEMU documentation for QEMU screen builds.

Tip

After installing PRG32, read Getting Started With PRG32 to learn how to run your first cartridge.

Important

For assistance with setup or execution issues, please refer to the troubleshooting guide.

Documentation Index

Guides & Workflows:

• Getting Started With PRG32: End-to-end setup and manual.
• QEMU Virtual Screen: Desktop testing and troubleshooting.
• Cartridges: The .prg32 build/upload workflow.
• Offline USB Device Protocol: Upload, run, and performance retrieval over native USB or QEMU without Wi-Fi.
• Web-to-USB Deployment: Browser deployment contract for the PRG32-Construction-Kit and CartridgeStore.
• Cartridge CI/CD: Automated Bach, Blackjack, DeviceDemo, and Poing packages with downloadable previews.
• Hardware & Pinouts: Board, display, and input architecture.

Learning Materials:

• Teaching with PRG32: Instructor notes and classroom setup.
• Assembly Tutorial | C Tutorial
• Labs Overview
• Example Games

APIs & Advanced Features:

• Framework C/Assembly ABI
• HTTP APIs (Score, Metrics, Multiplayer)
• PRG32-QT Debugger and SDK Commands
• Performance Test Guide
• Audio Guide
• Assets Tools

Additional References:

• Repository Structure
• Publishing Firmware

Contributors

• Raffaele Montella - UniParthenope - academic supervisor / project lead
• Simone Boscaglia - UniParthenope - Computer Science student
• Ivan Cafiero - UniParthenope - Computer Science student

See CONTRIBUTORS.md for contributor metadata suitable for academic submissions.

Citation

For reports, theses, or coursework submissions, use the citation metadata in CITATION.cff.