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.
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.
- 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
Windows
- Install Git for Windows and Python 3.
- Download and run the Espressif ESP-IDF Tools Installer for Windows.
- Select an ESP-IDF 5.4 or newer release.
- Include support for
esp32c3andesp32c6. - (Optional) Check the QEMU RISC-V emulator box during installation if you want to use the QEMU desktop emulator.
- Open the "ESP-IDF PowerShell" shortcut created by the installer.
- Clone the project and verify your setup from that shell:
cd $HOME\Documents
git clone https://github.com/riscv-prg32/PRG32
cd PRG32
python -m prg32 doctor- Use the ESP-IDF PowerShell or ESP-IDF Command Prompt, not a plain terminal
where
idf.pyhas not been exported. - 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 cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 curl zipInstall 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 libslirp0Install 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
# Optional: install QEMU desktop emulator
python $IDF_PATH/tools/idf_tools.py install qemu-riscv32Clone the project and verify your setup:
git clone https://github.com/riscv-prg32/PRG32
cd PRG32
python3 -m prg32 doctorLinux serial permissions:
sudo usermod -aG dialout "$USER"Log out and back in after changing group membership.
ESP32-C6 boards usually appear as /dev/ttyACM0; USB serial adapters may appear as /dev/ttyUSB0. If the board is visible but flashing fails, check dialout membership and
reconnect the USB cable after logging in again.
macOS
Install dependencies:
brew install git cmake ninja dfu-util ccache libusb python curl zipInstall QEMU native libraries (optional, required for QEMU desktop emulator only):
brew install libgcrypt glib pixman sdl2 libslirpInstall 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
# Optional: install QEMU desktop emulator
python $IDF_PATH/tools/idf_tools.py install qemu-riscv32Clone the project and verify your setup:
git clone https://github.com/riscv-prg32/PRG32
cd PRG32
python3 -m prg32 doctorPlatformIO (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 115200VS Code Setup (Windows):
- Install Git for Windows.
- Install Visual Studio Code.
- Install the Espressif ESP-IDF extension for VS Code.
- Install the PlatformIO extension for VS Code.
- Install the Microsoft C/C++ and Python extensions.
- Use the checked-in
PRG32.code-workspacefor student labs; paths are workspace-relative.
CLI Setup (Windows):
cd $HOME\Documents\PRG32
pio run
pio run -t upload
pio device monitor -b 115200The 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 idf.py commands in docs/qemu.md 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.
Guides & Workflows:
- Getting Started With PRG32: End-to-end setup and manual.
- QEMU Virtual Screen: Desktop testing and troubleshooting.
- Cartridges: The
.prg32build/upload workflow. - 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:
Additional References:
- 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.
For reports, theses, or coursework submissions, use the citation metadata in CITATION.cff.