Repository of the NES RetroAchievements Adapter project – a maker initiative with a "cyberpunk western" style that transforms the physical NES console (released in 1985) by adding Internet connectivity and achievement functionality, supported by the amazing RetroAchievements community.
- Disclaimer
- Introduction
- Getting Started (How to Build)
- Architecture and Functionality
- Limitations
- General Information
- Next Steps
- Version History
- Contributions
- License
- FAQ
- Acknowledgments
- Similar Projects
The project is not responsible for any use or damage it may cause. Build and use it at your own risk. This is a PROTOTYPE that works but still needs to evolve into a final version—with revised hardware, extensive testing, and easy replication. We want everyone to be able to build and use this prototype, but only attempt it if you know what you're doing.
The NES RA Adapter transforms your original NES console into an interactive, Internet-connected machine, allowing real-time achievement unlocking through the RetroAchievements platform. Inspired by the Game Genie with a touch of cyberpunk western, the adapter:
- Identifies the game by reading the cartridge (via CRC calculation).
- Monitors the console's memory to detect events and achievements.
- Provides connectivity and interface through a TFT screen, buzzer, and smartphone configuration.
- nes-pico-firmware: source code for the firmware used on the Raspberry Pi Pico (Chinese purple board).
- nes-esp-firmware: source code for the firmware used on the ESP32 C3 Super Mini.
- hardware: schematics for building your version on a protoboard/perfboard and PCB files for prototype versions v0.1 and v0.2.
- 3d parts: Fusion 360 and STL files for the modeled case, inspired by the Game Genie.
- miscellaneous: auxiliary tool and files (LCD mirror Web App / CRC32<->RA Hash map creator / AWS Lambda to shrink RA response / TFT config).
| Part Name | Quantity | Total Cost (USD)* |
|---|---|---|
| 72-pin slot** | 2x | (2x ~$2.50) ~ $5.00 |
| SN74HC4066*** | 7x | (7x ~$0.85) ~ $6.00 |
| Raspberry Pi Pico (purple board) | 1x | ~ $3.00 |
| ESP32 C3 Supermini | 1x | ~ $2.50 |
| LCD 240x240 driver ST7789 | 1x | ~ $2.75 |
| Buzzer 3V + Transistor BC548 | 1x | ~ $1.25 |
| Total (without PCB, 3D case) | ~ $20.50 |
* Source: Aliexpress - 2025-03-29
** In the miniaturized version, only 1 slot is needed
*** A more stable alternative to SN74HC4066 would be 26x SN74LVC1G3157DBVR (SMD) - see details here.
Currently, the project offers two options for circuit assembly:
- Protoboard/Perfboard: Assemble the circuit using a protoboard, following the schematic available in the
hardwarefolder. - PCBs: Order the PCBs (v0.1 or v0.2) using the files in the
hardwarefolder for a more robust assembly.
-
Download the firmwares from the Releases section.
-
Raspberry Pi Pico - Connect the Pico to the computer via USB while holding the BOOTSEL button. A folder will open on your desktop. Copy the
nes-pico-firmware.uf2file to this folder. This guide can help you understand the process. -
ESP32 C3 Supermini – You'll need to install esptool. Here’s a guide. If you're using the Arduino IDE with ESP32, you already have it installed.
- First, identify the COM port assigned to the ESP32 when connected via USB (in this example, it's COM11).
- Open the command line, navigate to the nes-esp-firmware folder inside the release files, and run the following commands (change the COM port approperly):
esptool.exe --chip esp32c3 --port "COM11" --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode keep --flash_freq keep --flash_size keep 0x0 "nes-esp-firmware.ino.bootloader.bin" 0x8000 "nes-esp-firmware.ino.partitions.bin" 0xe000 "boot_app0.bin" 0x10000 "nes-esp-firmware.ino.bin"
esptool.exe --chip esp32c3 --port COM11 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 2162688 ra_rash_map.bin
The adapter uses two microcontrollers working together:
- Game Identification: Reads part of the cartridge to calculate the CRC and identify the game.
- Memory Monitoring: Uses two cores to monitor the bus and process writes using the rcheevos library:
- Core 0: Calculates the CRC, runs rcheevos routines, and manages serial communication with the ESP32.
- Core 1: Uses PIO to intercept the bus and detect stable values in write operations. Employs DMA to transfer data to a ping-pong buffer and forwards relevant addresses to Core 0 via a circular buffer.
- Note: Serial communication has a limit of approximately 32KB, restricting the size of the achievement list response.
- Connectivity and Interface: Provides Internet to the NES and manages a TFT screen to display achievements, along with a buzzer for sound effects.
- Configuration Management: Stores Wi-Fi and RetroAchievements credentials in EEPROM; configuration is done via smartphone connected to the ESP32 access point.
- File System and Communication: Uses LittleFS to store a hash table (CRC32 to MD5) for cartridge identification and game images.
- EXPERIMENTAL – Streams LCD content to a Web App - Uses WebSocket and mDNS to serve a web app that mirrors the LCD display and shows additional achievement events that don’t fit on the physical screen. (More details available in the
miscfolder.) The web app becomes available as soon as the game image appears on the LCD and can be accessed athttp://nes-ra-adapter.local— make sure your smartphone is connected to the same Wi-Fi network.
-
Testing with different games: The adapter has been tested with about 50 games, and issues were detected in 2. Check the compatibility page for more details. We are working to improve compatibility.
-
Frame and reset detection: It is not possible to detect a frame by simply inspecting cartridge signals. A heuristic is used, which has shown good results so far, but there is no guarantee it will work for all achievements. Additionally, console RESET detection is not yet implemented, requiring the console to be turned off and on for a reset.
-
Server Response Size: RAM is limited to 32KB for storing the RetroAchievements response, which includes the list of achievements and memory addresses to monitor. The source-code of a AWS Lambda function is available (misc folder) to remove unnecessary fields or reduce the achievement list, ensuring the response fits within this limit.
-
Rare Limitation: Some Games May Be Unmasterable It’s possible that the ESP32 (with a ~62KB limit) not only removes unused attributes from achievements, but also filters out very large achievements if the full list exceeds the Raspberry Pi Pico’s 32KB limit. This means some games might not be fully masterable using the adapter. In future versions, I’ll look into adding a warning for the user when this filtering occurs. (out of 50 games tested, this filtering happened in two - FF1 lost a missible achievement and Guardian Legend lost some big achievements)
-
Leaderboards is disabled To shrink data between ESP32 and Pico and because we are using a heuristic to detect frames, the leaderboard feature is disabled.
-
Power Consumption: The adapter typically consumes 0.105A (max ~0.220A). The LCD screen consumes about 0.035A. Consumption is within the limit of the 7805 voltage regulator present in the NES
-
Logic Level Conversion (5V vs 3.3V): The prototypes do not use logic level conversion to avoid signal delays. The bus between the cartridge and the NES is disabled when identifying the cartridge (not affecting the NES), and current levels are within Pico’s limits. In the final version, current limiting will be considered to reduce stress on the Pico. If someone in the community identifies the need for level shifting and develops a test scheme without compromising signals, contributions are welcome.
Develop a board approximately the size of a Game Genie that fits into the NES 001 cartridge slot. Include a ground plane, decoupling capacitors, current-limiting resistors, and smaller traces to reduce interference.
Update the case (currently inspired by the Game Genie) to fit the new circuit layout.
- Version 0.7 (2025-07-09) - Changes to the frame detection heuristic, using microseconds instead of milliseconds and doing frame skipping if necessary to stay as close as possible to the 60hz cadence (or 50hz, when handling a DEFINE during compilation).
- Version 0.6 (2025-06-25) - Bug fix in serial comm on ESP32, "show password" feature for RA credentials during setup, filtering of some achievements directly in the RA API.
- Version 0.5 (2025-06-24) - Hardcore mode enabled. LED status in a semaphore way (green, yellow, red) to make the LCD optional. Minor bug fixes.
- Version 0.4 (2025-05-15) - Make the experimental mirror screen feature more stable on pico firmaware. Releases an Android App (APK - release section) to help on the usage of the mirror screen feature.
- Version 0.3 (2025-04-24) – Improve error handling, optimize ram usage, deployed an experimental feature to stream the content of the tiny LCD to a smartphone
- Version 0.2 (2025-04-07) – Optimizations to reduce energy consumption.
- Version 0.1 (2025-03-28) – Initial prototype version.
Everyone is welcome to contribute!
- Submit improvements and pull requests via GitHub.
- Join our Discord channel: https://discord.gg/baM7y3xbsA
- Support us by buying a coffee to help with hardware prototype costs.
- This project source code is distributed under the GPLv3 license.
- The PCB circuits are distributed under CC-BY-4.0 license.
- The 3d parts are distributed under CC-BY-NC-4.0 license.
- Q: Are you planning to sell the adapter?
- A: No. This is a fully open-source, community-driven DIY project.
- Q: So how can I get one?
- A: It's a DIY project — you can build it yourself! If you're not comfortable doing that, don’t worry: as seen with other open-source projects like the GBSControl, GB Interceptor and Open Source Cartridge Reader, the community often steps in to produce and sell units for those who don’t want to build their own.
- Q: Am I allowed to manufacture and sell it?
- A: Yes! Both the hardware and software licenses allow commercial use. Please note that the 3D-printed case files were created using Fusion 360 under a non-commercial license, but they can be redesigned in other software for commercial purposes.
- Q: Do I need to open my NES to use it?
- A: Our goal is for it to work like a Game Genie — a plug-and-play adapter that fits between the console and the cartridge, with no need to open the NES. However, current prototypes still require opening the console.
- Q: Do I need to modify my NES in any way?
- A: No. The adapter is plug-and-play and doesn’t require any console modification.
- Q: Do I need to connect it to a computer?
- A: No! It’s fully self-contained with built-in Wi-Fi. If you ever need to configure it, you can do so from your smartphone. All achievement processing is handled onboard.
- Q: Will the adapter work with EverDrives?
- A: The adapter needs to read the cartridge to identify the game, but when using an EverDrive, it reads the EverDrive’s firmware instead of the game itself. That’s one of the reasons why supporting EverDrives is not currently possible.
- Q: Will it work with Japanese Famicom systems?
- A: We haven’t tested with original Japanese consoles yet, but it should work with 72-to-60 pin adapters. Many Japanese games are already mapped on RetroAchievements, and we’ve successfully tested some using a 60-to-72 adapter.
- Q: Will it work with the Disk System?
- A: We haven’t tested with the Disk System since we don’t have one. It’s a possible future enhancement if we can get the hardware for testing.
- Thanks to RetroAchievements and its community for providing achievements for nearly all games and making the system available to everyone.
- Thanks to NESDEV for detailed NES documentation and a welcoming forum.
- People that helped us during the donation campaing (April/25) - THANK-YOU:
- Aaron P.
- Stupid C. G.
- Elaine B.
- I F. S.
- Ken G.
- Kaffe S.
- Jonathan
- Sharon L.
- Daniel P.
- Ricardo S. S.
- Fabio H. A. F.
- Anuar N.
- Bryan D. S.
- Giovanni M. C.
- Paulo H. A. S.
- Fernando G. S.
- Rafael B. M.
- Thiago G. O.
- Jerome V. V.
- Ricardo V. A. M.
- Tiago T.
- Leonardo P. K.
- Fábio S.
- Anderson A. B.
- Rubens M. P.
- Silvio L.
- Carlos R. S.
- Ademar S. J.
- Marcel A. B. C.
- Peterson F. I.
- Denis D. F. F.
- Luis A. S.
- Ariovaldo P.
- Theo M. O. C. P.
- Thiago P. L.
- André R.
- RA2SNES: https://github.com/Factor-64/RA2Snes - RA2Snes is a program built using Qt 6.7.3 in C++ and C that bridges the QUsb2Snes webserver & rcheevos client to allow unlocking Achievements on real Super Nintendo Hardware through the SD2Snes USB port.
