{"id":47711137,"url":"https://github.com/rh1tech/frank-nes","last_synced_at":"2026-04-25T18:06:56.388Z","repository":{"id":343231087,"uuid":"1176820380","full_name":"rh1tech/frank-nes","owner":"rh1tech","description":"NES emulator for RP2350","archived":false,"fork":false,"pushed_at":"2026-04-22T13:17:32.000Z","size":26369,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T15:17:55.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rh1tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T12:12:06.000Z","updated_at":"2026-04-22T13:17:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rh1tech/frank-nes","commit_stats":null,"previous_names":["rh1tech/murmnes","rh1tech/frank-nes"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/rh1tech/frank-nes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rh1tech%2Ffrank-nes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rh1tech%2Ffrank-nes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rh1tech%2Ffrank-nes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rh1tech%2Ffrank-nes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rh1tech","download_url":"https://codeload.github.com/rh1tech/frank-nes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rh1tech%2Ffrank-nes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32271291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T18:32:15.908Z","updated_at":"2026-04-25T18:06:56.382Z","avatar_url":"https://github.com/rh1tech.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FRANK NES\n\nNES (Nintendo Entertainment System) emulator for Raspberry Pi Pico 2 (RP2350) with HDMI/VGA/TV output, SD card ROM browser, NES/SNES gamepad, USB gamepad, PS/2 keyboard, and audio over HDMI, I2S, or PWM.\n\nBased on [QuickNES](https://github.com/libretro/QuickNES_Core) by Shay Green (blargg).\n\n## Screenshots\n\n| ROM Selector | Gameplay | Settings |\n|:---:|:---:|:---:|\n| ![ROM Selector](screenshots/screen1.png) | ![Gameplay](screenshots/screen2.png) | ![Settings](screenshots/screen3.png) |\n\n## Supported Platforms\n\nfrank-nes supports five RP2350-based hardware platforms with different video output options:\n\n| Platform | Board | Video Outputs | Audio |\n|----------|-------|---------------|-------|\n| **m2** | [Murmulator 2.0](https://murmulator.ru) / [FRANK](https://rh1.tech/projects/frank?area=about) | HDMI (HSTX), HDMI/VGA (PIO), Composite TV | HDMI, I2S, PWM |\n| **m1** | Murmulator 1.x | HDMI/VGA (PIO), Composite TV | I2S, PWM |\n| **pc** | [Olimex RP2040-PICO-PC](https://www.olimex.com/Products/MicroPython/PICO/RP2040-PICO-PC/) | HDMI (HSTX) | HDMI, PWM |\n| **dv** | [Pimoroni Pico DV](https://shop.pimoroni.com/products/pimoroni-pico-dv-demo-base) | HDMI/VGA (PIO) | I2S, PWM |\n| **z0** | [Waveshare RP2350-PiZero](https://www.waveshare.com/rp2350-pizero.htm) | HDMI/VGA (PIO) | I2S, PWM |\n\nSelect the platform at build time: `PLATFORM=dv ./build.sh`\n\nThe default platform is **m2**. Each platform has its own board configuration header with pin assignments for SD card, PS/2 keyboard, NES gamepad, audio, and PSRAM. The build system auto-selects the correct video driver and rejects incompatible combinations.\n\n## Features\n\n- Multiple video outputs: HDMI via HSTX, PIO-based HDMI/VGA with autodetect, composite TV\n- Full NES APU sound emulation (pulse, triangle, noise, DMC) over HDMI, I2S, or PWM\n- VRC6, VRC7, FME-7, and Namco 163 expansion audio support\n- NES and Dendy (PAL) emulation modes\n- 8MB QSPI PSRAM support for ROM loading and tile cache\n- SD card ROM browser with cover art, game info, and animated cartridge selector\n- File browser mode for navigating large ROM collections and subdirectories\n- ROM search (F3 / Select+A)\n- On-demand ROM loading (ROMs loaded from SD when selected, not at boot)\n- 6-slot save states with color thumbnails\n- NES and SNES gamepad support (directly connected)\n- USB gamepad support (via native USB Host)\n- PS/2 keyboard support\n- Configurable input routing (map any input device to Player 1 or Player 2)\n- Master volume control\n- Runtime settings menu with persistence\n\n## Hardware Requirements\n\n- **Raspberry Pi Pico 2** (RP2350) or compatible board\n- **8MB QSPI PSRAM** (mandatory)\n- **HDMI or VGA connector** (directly connected via resistors, no encoder needed)\n- **SD card module** (SPI mode)\n- **NES or SNES gamepad** (directly connected) – OR –\n- **USB gamepad** (via native USB port)\n- **I2S DAC module** (e.g., TDA1387, PCM5102) for external audio output (optional, PWM audio works without any DAC)\n\n\u003e **Note:** When USB HID is enabled, the native USB port is used for gamepad input. USB serial console (CDC) is disabled in this mode; use UART for debug output.\n\n### PSRAM\n\nFRANK NES requires 8MB PSRAM to run the ROM selector. Without PSRAM, only a single ROM embedded in flash or the first ROM on SD card can be loaded. You can obtain PSRAM-equipped hardware in several ways:\n\n1. **Solder a PSRAM chip** on top of the Flash chip on a Pico 2 clone (SOP-8 flash chips are only available on clones, not the original Pico 2)\n2. **Build a [Nyx 2](https://rh1.tech/projects/nyx?area=nyx2)** – a DIY RP2350 board with integrated PSRAM\n3. **Purchase a [Pimoroni Pico Plus 2](https://shop.pimoroni.com/products/pimoroni-pico-plus-2?variant=42092668289107)** – a ready-made Pico 2 with 8MB PSRAM\n\n## Pin Assignment (M2 Layout)\n\n\u003e Pin assignments for other platforms are defined in `src/platform/pico/board_*.h`.\n\n### HDMI (via 270 Ohm resistors)\n\n| Signal | GPIO |\n|--------|------|\n| CLK-   | 12   |\n| CLK+   | 13   |\n| D0-    | 14   |\n| D0+    | 15   |\n| D1-    | 16   |\n| D1+    | 17   |\n| D2-    | 18   |\n| D2+    | 19   |\n\n### SD Card (SPI mode)\n\n| Signal  | GPIO |\n|---------|------|\n| CLK     | 6    |\n| MOSI    | 7    |\n| MISO    | 4    |\n| CS      | 5    |\n\n### NES/SNES Gamepad\n\n| Signal | GPIO |\n|--------|------|\n| CLK    | 20   |\n| LATCH  | 21   |\n| DATA 1 | 26   |\n| DATA 2 | 27   |\n\n\u003e **Note:** Gamepad 2 uses the same CLK and LATCH as Gamepad 1, only the DATA pin differs.\n\n### I2S Audio (optional)\n\n| Signal | GPIO |\n|--------|------|\n| DATA   | 9    |\n| BCLK   | 10   |\n| LRCLK  | 11   |\n\n### PS/2 Keyboard\n\n| Signal | GPIO |\n|--------|------|\n| CLK    | 2    |\n| DATA   | 3    |\n\n### PSRAM (auto-detected)\n\n| Chip Package | GPIO |\n|--------------|------|\n| RP2350B      | 47   |\n| RP2350A      | 8    |\n\n## How to Use\n\n### SD Card Setup\n\n1. Format an SD card as **FAT32**\n2. Create a `nes` directory in the root\n3. Copy `.nes` ROM files into the `nes/` directory\n4. (Optional) Copy game metadata for cover art and game info – extract `sdcard/metadata.zip` to your SD card's `nes/` directory\n5. Insert the SD card and power on the device\n\n### First Boot and Caching\n\nOn the **first boot**, FRANK NES scans all ROM files in `nes` and computes a CRC32 checksum for each one. This is used to look up cover art and game metadata. **This process can be slow if you have many ROMs** - a few seconds per file depending on size.\n\nThe checksums are cached in `nes/.crc_cache` so subsequent boots are fast. The cache is automatically updated when new ROMs are added.\n\n\u003e **Recommendation:** Keep the number of ROMs on your SD card reasonable (under 50-100). Loading metadata for hundreds of ROMs will slow down boot time significantly, even with caching. The ROM selector loads cover art on-the-fly as you browse.\n\n### Welcome Screen\n\nOn boot, a welcome screen is displayed with the FRANK NES logo, version, and author information. Press **A** or **Start** to continue (or wait 10 seconds for auto-continue).\n\nIf no SD card is detected, an error message is shown for 5 seconds before falling back to any ROM embedded in flash.\n\n### ROM Selector\n\nAfter the welcome screen, the ROM selector displays your game library as animated NES cartridges with cover art:\n\n- **Left / Right** – Browse ROMs\n- **Up** – Show game info panel (year, genre, players, description)\n- **Down** – Hide game info panel\n- **A / Start** – Load selected ROM and start playing\n\nThe last selected ROM is remembered across reboots.\n\n### During Gameplay\n\n- **Select + Start** (gamepad), **F12** or **ESC** (keyboard) – Open settings menu\n\n### Game Metadata\n\nFor cover art and game info in the ROM selector, place metadata files on the SD card:\n\n```\nnes/metadata/Images/160/{X}/{CRC32}.555   – Cover art (RGB555 format)\nnes/metadata/descr/{X}/{CRC32}.txt        – Game info (XML format)\n```\n\nWhere `{X}` is the first hex digit of the CRC32, and `{CRC32}` is the 8-digit uppercase hex checksum (computed from the ROM data after the 16-byte iNES header).\n\n## Controller Support\n\n### NES Gamepad\n\n| NES Button | Action         |\n|------------|----------------|\n| D-pad      | Movement       |\n| A          | A              |\n| B          | B              |\n| Start      | Start          |\n| Select     | Select         |\n| Select + Start | Settings menu |\n\n### SNES Gamepad\n\nThe emulator automatically detects SNES controllers.\n\n| SNES Button     | NES Button |\n|-----------------|------------|\n| D-pad           | D-pad      |\n| B (bottom)      | A          |\n| Y (left)        | B          |\n| Start           | Start      |\n| Select          | Select     |\n| Select + Start  | Settings menu |\n\n### USB Gamepad\n\nStandard USB gamepads are supported with automatic button mapping when built with USB HID support.\n\n### PS/2 / USB Keyboard\n\n| Key        | NES Button |\n|------------|------------|\n| Arrow keys | D-pad      |\n| Z          | A          |\n| X          | B          |\n| Enter      | Start      |\n| Space      | Select     |\n| F12 / ESC  | Settings menu |\n\n## Settings Menu\n\nPress **Select + Start** during gameplay (or **F12** / **ESC** on keyboard) to open the settings menu:\n\n| Setting       | Options                                          |\n|---------------|--------------------------------------------------|\n| Player 1      | Any, NES Pad 1, NES Pad 2, USB 1, USB 2, Keyboard |\n| Player 2      | NES Pad 1, NES Pad 2, USB 1, USB 2, Keyboard, Disabled |\n| Audio         | HDMI, I2S, PWM, Disabled (availability depends on platform) |\n| Volume        | 0% – 100% (10% steps)                            |\n| Mode          | NES (NTSC 60 Hz), Dendy (PAL 50 Hz)              |\n| Save Game     | Save state to SD card (6 slots with thumbnails)   |\n| Load Game     | Load state from SD card                           |\n| Back to ROM Selector | Return to ROM browser (resets emulator)    |\n| Back to Game  | Resume gameplay                                   |\n\nSettings are saved to `nes/.settings` and persist across reboots. Save states are stored in `nes/.save/{rom_name}_{slot}.sav`.\n\n## Building\n\n### Prerequisites\n\n1. Install the [Raspberry Pi Pico SDK](https://github.com/raspberrypi/pico-sdk) (version 2.0+)\n2. Set environment variable: `export PICO_SDK_PATH=/path/to/pico-sdk`\n3. Install ARM GCC toolchain\n\n### Build\n\n```bash\ngit clone https://github.com/rh1tech/frank-nes.git\ncd frank-nes\n./build.sh                    # Default: M2, HSTX HDMI\nPLATFORM=dv ./build.sh        # Pimoroni Pico DV\nPLATFORM=m1 ./build.sh        # Murmulator 1.x (PIO HDMI/VGA)\nPLATFORM=pc ./build.sh        # Olimex PICO-PC (HSTX HDMI)\nPLATFORM=z0 ./build.sh        # RP2350-PiZero (PIO HDMI/VGA)\n```\n\nOutput: `build/frank-nes.uf2`\n\n### Build Options\n\nYou can pass options via environment variables:\n\n```bash\n# Platform selection (default: m2)\nPLATFORM=dv ./build.sh\n\n# Composite TV output (M1 and M2 only)\nVIDEO_COMPOSITE=1 ./build.sh\n\n# PIO HDMI/VGA output (auto-selected for m1, dv, z0)\nHDMI_PIO=1 ./build.sh\n\n# Embed a ROM directly in flash (no SD card needed)\nNES_ROM=path/to/game.nes ./build.sh\n\n# Enable USB HID gamepad support\nUSB_HID=1 ./build.sh\n```\n\n### Release Build\n\nBuild all 8 platform/video variants at once:\n\n```bash\n./release.sh          # Interactive version prompt\n./release.sh 1.05     # Specify version\n```\n\nThis produces UF2 files for every supported platform and video combination.\n\n### Flashing\n\n```bash\n# With device in BOOTSEL mode:\n./flash.sh\n\n# Or manually:\npicotool load build/frank-nes.uf2\n```\n\n## Troubleshooting\n\n### Device won't boot after changing settings\n\nRemove the `nes/.settings` file from the SD card to restore defaults.\n\n### ROM selector shows no cover art\n\nMake sure the metadata files are in the correct directory structure on the SD card. See [Game Metadata](#game-metadata) above.\n\n### First boot is very slow\n\nThis is normal – CRC32 checksums are being computed for all ROMs. Subsequent boots will be fast thanks to the cache file. Reduce the number of ROMs if boot time is unacceptable.\n\n## License\n\nCopyright (c) 2026 Mikhail Matveev \u003c\u003cxtreme@rh1.tech\u003e\u003e\n\nThis project is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE) for details.\n\nNote: The QuickNES core is licensed under LGPL-2.1-or-later. The PS/2 keyboard driver is licensed under GPL-2.0-or-later. The HDMI driver (pico_hdmi) is released under the Unlicense. Other components have their own licenses as noted below.\n\n## Acknowledgments\n\nThis project incorporates code and ideas from the following projects:\n\n| Project | Author(s) | License | Used For |\n|---------|-----------|---------|----------|\n| [QuickNES](https://github.com/libretro/QuickNES_Core) | Shay Green (blargg) | LGPL-2.1 | NES emulation core |\n| [EMU2413](https://github.com/libretro/QuickNES_Core) | Mitsutaka Okazaki, xodnizel | Custom | VRC7 (YM2413/OPLL) sound emulation |\n| [pico_hdmi](https://github.com/fliperama86/pico_hdmi) | fliperama86 | Unlicense | HSTX-native HDMI output with audio |\n| [pico-spec](https://github.com/DnCraptor/pico-spec) | DnCraptor | GPL-3.0 | PIO HDMI/VGA driver, composite TV driver, multi-platform pin configs |\n| [FatFS](http://elm-chan.org/fsw/ff/) | ChaN | Custom permissive | FAT32 filesystem for SD card |\n| [pico_fatfs_test](https://github.com/elehobica/pico_fatfs_test) | Elehobica | BSD-2-Clause | SD card PIO-SPI driver |\n| [pico-infonesPlus](https://github.com/fhoedemakers/pico-infonesPlus) | shuichitakano, fhoedemakers | MIT | NES/SNES gamepad PIO driver, game metadata |\n| [PS/2 keyboard driver](https://github.com/mrmltr) | mrmltr | GPL-2.0 | PS/2 keyboard PIO driver |\n| [TinyUSB](https://github.com/hathach/tinyusb) | Ha Thach | MIT | USB HID host driver |\n| [Raspberry Pi Pico SDK](https://github.com/raspberrypi/pico-sdk) | Raspberry Pi Foundation | BSD-3-Clause | Hardware abstraction layer |\n\nSpecial thanks to:\n\n- Shay Green (blargg) for the QuickNES emulator core and Blip_Buffer audio library\n- Mitsutaka Okazaki for the EMU2413 OPLL emulator\n- fliperama86 for the pico_hdmi HSTX HDMI output library\n- DnCraptor for the pico-spec project (PIO HDMI/VGA, composite TV drivers, and multi-platform board configurations)\n- shuichitakano for the original pico-infones Pico port and NES gamepad PIO driver\n- fhoedemakers for pico-infonesPlus and game metadata\n- The libretro team for maintaining the QuickNES fork\n- Nintendo for the original NES hardware\n- The Raspberry Pi Foundation for the RP2350 and Pico SDK\n- The Murmulator community for hardware designs and testing\n\n## Author\n\nMikhail Matveev \u003c\u003cxtreme@rh1.tech\u003e\u003e\n\n[https://rh1.tech](https://rh1.tech) | [GitHub](https://github.com/rh1tech/frank-nes)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frh1tech%2Ffrank-nes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frh1tech%2Ffrank-nes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frh1tech%2Ffrank-nes/lists"}