ROMs

Legal ROM use

NESpresso32 does not include any ROM files. The project provides an emulation engine what you run on it is your responsibility.

For testing and development, the right starting point is homebrew software and purpose-built emulator test ROMs. These are created specifically to run on emulators and have clear distribution terms.

• nesdev.org emulator test ROMs specifically designed to test emulator accuracy
• NES homebrew games original software made for the NES hardware and emulators

Do not download commercial ROM files from the internet. The fact that a game is old does not make it legally free to copy. Check the terms for any ROM you use.

Workflow

The full pipeline from .nes file to running game:

1. Copy .nes files into ESP32/NESpresso32/roms/
2. Run pio run -t upload
3. gen_roms.py runs automatically as a pre-build step
4. The script generates one .cpp file per ROM and a shared header gbrom.h
5. PlatformIO compiles everything and produces firmware.bin
6. The firmware is flashed to the ESP32
7. At startup, the OSD browser appears if more than one ROM is present
8. Selecting a ROM loads PRG and CHR data from flash into DRAM

The script caches build results based on file modification time and size. Only new or modified ROMs are regenerated unchanged ROMs reuse the cached output and are not recompiled.

gen_roms.py

The script at scripts/gen_roms.py runs via extra_scripts = pre:scripts/gen_roms.py in platformio.ini. For each .nes file in roms/:

1. Validates the iNES magic bytes (NES\x1A)
2. Reads the mapper number, PRG-ROM size, and CHR-ROM size from the header
3. Reads the full file as raw bytes
4. Emits a .cpp file with a const uint8_t array tagged with PROGMEM

Example of generated output:

The script also generates dataFlash/gbrom.h, which contains a struct array with one entry per ROM: title string, pointer to the array, size, mapper number, and a boolean flag indicating whether the mapper is supported.

A 40 KB ROM file becomes approximately 240 KB of C++ source text (each byte becomes 0xNN, = 6 characters). The compiler parses that and emits 40 KB in the final binary. The text blowup only exists during compilation, not in the firmware.

iNES format

Most NES ROM files use the iNES format. The first 16 bytes are a header:

Mapper number = (flags6 >> 4) | (flags7 & 0xF0). PRG-ROM is the 6502 program code. CHR-ROM is the pattern table data for the PPU (sprites and background tiles). After the 16-byte header, PRG-ROM data comes first, followed by CHR-ROM data.

The iNES 2.0 format adds more fields to bytes 8–15 for extended mapper information. NESpresso32 uses the basic iNES 1.0 fields, which is sufficient for the mappers it supports.

Custom partition table

The standard ESP32 Arduino partition table reserves space for two OTA partitions and SPIFFS. NESpresso32 uses a custom partition table (custom_partitions.csv) that removes all of that in favour of a single large app partition:

The app partition is 0x3C0000 bytes = 3,932,160 bytes = 3.75 MB. No OTA second partition, no SPIFFS. This gives the firmware plus compiled ROM data the maximum possible space on a 4 MB flash chip.

How many ROMs fit

The firmware itself is approximately 1.3 MB, leaving roughly 2.4 MB for ROM data.

The build script prints the total ROM payload size and warns if it exceeds the 2,000 KB soft limit. If the firmware does not fit in the partition, the linker will fail with a size error.

Where the data lives at runtime

PROGMEM on ESP32 maps to __attribute__((section(".irom.text"))). The linker places these arrays in the DROM (data ROM) region, which the MMU makes accessible at virtual address 0x3F400000. The SPI flash is physically separate from the CPU, but this mapping makes flash-resident data readable as normal memory.

When a ROM is selected in the OSD, rom_load_from_memory() copies the PRG and CHR data from flash into DRAM:

After loading, the emulator runs entirely from DRAM. Flash is not accessed again during emulation. DRAM access is one CPU cycle; flash access on a cache miss is 80–100 ns. Running from DRAM is essential for the timing budget.