The RetroCYD manual

01 Hardware

RetroCYD targets the 4.0″ ESP32-32E display board documented on LCDwiki, sold as E32R40T (with resistive touch) and E32N40T (no touch). It's an ESP32 with a 320×480 ST7796S screen, microSD slot, audio amplifier and USB-C on one board — a bigger sibling of the original “Cheap Yellow Display”.

Shopping list

Supported boards

Other CYD variants (for example the original 2.8″ ESP32-2432S028) use different displays and pins and have no RetroCYD build. Flashing a build for the wrong board is harmless — you'll just get a white or garbled screen until you flash the right one.

Inside: ESP32-D0WD-V3 (dual-core Xtensa LX6, up to 240 MHz), 520 KB SRAM, 4 MB flash, no PSRAM, on-board USB-serial chip (CH340-type), BOOT and RESET buttons. Full pin map in section 11.

02 Flashing

The easiest way is the web installer. It runs entirely in your browser using ESP Web Tools and the Web Serial API.

1. Plug the board into your computer with a USB-C data cable.
2. Open this site in desktop Chrome, Edge or Opera (Windows, macOS, Linux, ChromeOS). Firefox, Safari and mobile browsers don't support Web Serial.
3. On the flasher, pick your board.
4. Click Connect & install and choose the serial port — usually named USB-SERIAL CH340, USB Serial or wchusbserial.
5. Click Install. On a first install, tick Erase device. It clears the board, not your SD card (see Erasing).
6. Wait for the progress bar to finish. The board reboots into RetroCYD.

USB-serial drivers

The board's USB port goes through a CH340-type USB-to-serial chip. If no port shows up in the list:

• Windows: Windows Update often installs the driver automatically. If not, install WCH's CH341SER driver, then check Device Manager → Ports (COM & LPT) for USB-SERIAL CH340 (COMx).
• macOS: recent versions usually recognise it out of the box. If not, install WCH's CH34x macOS driver and allow it in System Settings → Privacy & Security.
• Linux: the driver is built into the kernel. If the port appears but can't be opened, add yourself to the serial group (sudo usermod -aG dialout $USER, or uucp on Arch) and log in again. Some distros' brltty package grabs CH340 devices — removing it helps.

Only one program can use a serial port at a time: close Arduino IDE / PlatformIO serial monitors and other flashing tools first.

03 Erasing & recovery

What does “Erase device” do?

When the web installer asks whether to erase, it means erase the flash chip before writing. That clears old firmware, RetroCYD's settings (volume, brightness, calibration…) and the ROM cache. Your SD card — games and saves — is not touched. It's fully reversible: the next install puts everything back, and settings return to defaults. Erasing is recommended on a first install or when switching from other firmware.

Why the board can always be recovered

The ESP32 has a built-in bootloader in its ROM, which flashing can't overwrite. Holding BOOT (IO0) at reset always starts its download mode, so whatever happens to the firmware, you can flash again.

Recovery steps

1. Hold BOOT.
2. Tap RST (EN) once while still holding BOOT.
3. Release BOOT. The board is now in download mode and waits for the flasher (RetroCYD won't start — that's expected).
4. Flash again with the web installer (tick Erase device) or with esptool below.

Manual flashing with esptool

Prefer the command line? Download the merged .bin from the flasher panel, install esptool (pip install esptool) and run:

$ esptool.py --chip esp32 write_flash 0x0 retrocyd-cyd40-merged.bin

• Add --port COM5 (Windows) or --port /dev/ttyUSB0 (Linux) after --chip esp32 if esptool picks the wrong port.
• For a clean slate first, esptool.py --chip esp32 erase_flash is the same as the web installer's “Erase device”.
• Newer esptool releases also accept the spelling esptool --chip esp32 write-flash 0x0 …; it's the same command.
• The image is a single merged file that goes at offset 0x0. Don't split it or use other offsets.

04 SD card

Format: FAT32

Use a microSD (SDHC) card formatted FAT32. Cards up to 32 GB usually come that way and work out of the box. Bigger cards (SDXC) ship as exFAT and must be reformatted to FAT32:

• macOS: Disk Utility → select the card → Erase → Format MS-DOS (FAT), Scheme Master Boot Record.
• Linux: sudo mkfs.vfat -F 32 /dev/sdX1 — double-check the device name first.
• Windows: the built-in formatter only offers FAT32 up to 32 GB. For larger cards use a third-party FAT32 formatter, or simply buy a 32 GB card — games for these systems are tiny.

Folder layout

Insert the card and boot RetroCYD once — it creates this structure for you:

microSD (FAT32)
├── roms/
│   ├── nes/      .nes .zip
│   ├── gb/       .gb .gbc .zip
│   ├── gbc/      .gbc .gb .zip
│   ├── sms/      .sms .zip  Master System
│   ├── gg/       .gg .zip   Game Gear
│   └── chip8/    .ch8 .c8 .sc8 .zip
├── saves/
│   └── <system>/ battery saves (.sav) + save states (.st0 – .st3)
└── retrocyd/   library index cache — safe to delete, it's rebuilt

• Game Boy vs. Game Boy Color: both folders accept .gb and .gbc. Sort them however you like — e.g. monochrome games in gb/, colour games in gbc/.
• Subfolders are fine (/roms/nes/puzzle/…) — handy for big collections.
• Backups: copy /saves/ to your computer now and then. That's all your progress.

Adding games

1. Get games from a legitimate source — see Free & legal games.
2. Unzipping is optional: a .zip containing a single ROM works.
3. Copy each ROM into the matching /roms/<system>/ folder.
4. The file name is the title shown in the launcher — rename files to something readable.
5. Keep every ROM at 2 MB or less (uncompressed).
6. Eject the card safely, insert it, and if new games don't appear use Settings → Rescan library.

05 Launcher & library

The home screen shows a tile per system and a recently played list so you can jump straight back into a game. Inside a system, games are listed alphabetically; drag to scroll, or use the A–Z bar on the edge to jump to a letter.

Built for thousands of games

Reading a huge directory from FAT32 on every visit would be slow, so the first time you open a big folder RetroCYD builds a sorted index and stores it in /retrocyd/ on the card. That takes a few seconds for around 10,000 files. After that, the folder opens instantly. Delete /retrocyd/ or use Rescan library at any time to rebuild it.

The ROM cache

The ESP32 has only 520 KB of RAM — less than many ROMs — and no PSRAM. So when you launch a game, RetroCYD copies it from the SD card into a dedicated 2 MB “ROM cache” partition in flash and runs it from there.

• Launching a different game takes a couple of seconds, with a progress bar.
• Relaunching the same game is instant — it's already in the cache.
• The cache size is also the maximum ROM size: 2 MB. Every Game Boy ROM up to 2 MB fits; the few 4 MB and 8 MB titles don't.
• ZIP files with a single ROM inside (deflate or stored) are unpacked straight into the cache.

06 Controls

On-screen touch gamepad (E32R40T)

In game, the screen shows a D-pad on the left, A and B on the right, SELECT and START at the bottom and a MENU button. The E32R40T's touch panel is resistive and single-point: it can only sense one touch at a time. To make that playable, RetroCYD adds:

• Diagonal D-pad zones — press between two arrows for up-left, down-right and so on.
• A combined A+B zone for games that need both buttons at once.

Touch is great for menus, puzzle games and anything turn-based. For platformers and shooters, a wired controller is much better. If taps land in the wrong place, run Settings → Touch calibration.

The E32N40T has no touch panel at all, so a wired controller is required on that board.

Board buttons

BOOT (IO0)

Opens the in-game menu while playing. Held at reset, it enters flashing mode.

RST (EN)

Hardware reset — restarts the board.

Wired controller (recommended)

RetroCYD supports controllers that use the Wii extension protocol over I2C:

• Wii Classic Controller and Classic Controller Pro
• NES Classic Mini and SNES Classic Mini controllers

They plug into a cheap Wii extension breakout adapter, which you wire to the board's 4-pin 1.25 mm I2C header. Controllers are hot-pluggable and auto-detected — just plug one in. Third-party clones exist; most follow the same protocol, but if one isn't detected, try an original.

In game the D-pad, A, B, SELECT (−) and START (+) do what you'd expect. On the Master System and Game Gear, B is button 1, A is button 2 and START is PAUSE (Master System) or START (Game Gear). HOME opens the in-game menu; on controllers without HOME (NES / SNES Classic Mini) press SELECT + START.

Bluetooth controller (with a bridge board)

While a game runs, the CYD has no RAM to spare for Bluetooth. Bluetooth controllers therefore connect through a second ESP32 board, the bridge. It runs BlueRetro, free open-source firmware by Jacques Gagnon. The bridge receives the controller over Bluetooth and answers on the I2C header like a Wii Classic Controller Pro, so to the CYD it is just another wired controller.

• Bridge board: any ESP32-WROOM-32 dev board (“ESP32 DevKit”, “NodeMCU-32S”, CH340 or CP2102, USB-C or micro-USB). ESP32-S2, S3, C3 and C6 boards won't work: they lack the Classic Bluetooth that PlayStation and Switch controllers use.
• Wires: four jumper wires, plus 4-pin 1.25 mm cables for the CYD's serial and I2C headers, or soldered wires.
• Controller: PS5 DualSense, PS4 DualShock 4, Xbox Wireless (One S and later), Switch Pro, 8BitDo and many more.

1. Flash the bridge

Use the bridge installer on the flash page and tick Erase device. Connect the bridge board, not the CYD: the installer can't tell two ESP32 boards apart. If you install the bridge firmware onto the CYD by mistake, just flash RetroCYD again. To flash manually instead, download the merged image and run esptool.py --chip esp32 write_flash 0x0 blueretro-wii-extension-merged.bin. The bridge firmware is BlueRetro's unmodified v25.04 “Wii extension” release.

2. Wire it to the CYD

Unplug both boards first.

Power. The serial header's 5V pin carries the power of the CYD's USB-C port. The bridge adds roughly 100–150 mA, so use a USB power supply that delivers at least 1 A. Not sure which pin is 5V? With the CYD on USB, a multimeter shows about 5 V between 5V and GND. Don't take power from the I2C header's 3V3 pin. The CYD's 3.3 V regulator is a small ME6217 that already powers the CYD and its 142 mA backlight, and the extra load could overheat it and reset the CYD.

On battery, the serial header has no 5 V. Power the bridge from its own USB-C port with a power bank instead, and leave the 5V wire off. Always use one power source for the bridge, not both.

The bridge uses the same I2C address as a Wii controller, so you can't connect both at once.

3. Pair the controller

Switch the CYD on. Whenever no controller is connected, the bridge searches for one by itself; on most boards its blue LED blinks while it searches and stays on once a controller is connected. Then put the controller in pairing mode:

The bridge remembers the controller. Next time, just press PS, the Xbox button or Home. For other controllers, see BlueRetro's pairing guide.

4. Buttons

The face buttons work by position, as on a SNES pad: the right button is A and the bottom button is B.

To change the mapping, use BlueRetro's web configuration at blueretro.io. It runs in desktop or Android Chrome, connects to the bridge over Bluetooth, and only works while no controller is connected to the bridge.

Good to know

• The CYD shows PAD as soon as the bridge has power, even before a controller is paired. That's normal.
• Leave Touch switched on in Settings. With the bridge connected the CYD always finds a controller, so touch doesn't come back on by itself at startup. If the controller's battery runs out, unplug the bridge and touch returns at the next start.
• Bluetooth adds a few milliseconds of input delay, which you're unlikely to notice in 8-bit games.
• BlueRetro is © Jacques Gagnon and licensed under the Apache License 2.0. RetroCYD publishes the release unmodified and isn't affiliated with the BlueRetro project.

07 In-game menu

Open it with the BOOT button on the board, the on-screen MENU button, or HOME (or SELECT + START) on a wired controller. The game pauses while it's open.

Resume

Back to the game.

Save state

Snapshot the game right now into one of 4 slots.

Load state

Jump back to a saved snapshot.

Reset

Restart the game, like the console's reset button.

Screen scale

Change how big the picture is. Bigger pictures mean more pixels over SPI, so fewer frames are shown per second.

Volume

Adjust sound without leaving the game.

Quit

Write the battery save and return to the launcher.

08 Saves & states

Battery saves (.sav)

Games that saved progress on the cartridge's battery-backed RAM do the same here. RetroCYD writes the save to /saves/<system>/ on the SD card when you open the menu, when you quit, and periodically while you play.

Save states (.st0–.st3)

Every game gets 4 save-state slots — instant snapshots you can make anywhere, even in games without a save feature. They live next to the battery saves in /saves/<system>/.

States are emulator snapshots; a future firmware update could make old ones unloadable. For long-term progress, rely on the game's own saves.

09 Settings

Wi-Fi

Choose, test or forget the Wi-Fi network used for game downloads. See Wi-Fi & free games.

Firmware update

Checks the website for a newer version and installs it over Wi-Fi. See Updating.

Game downloads

Download new free games now, turn the automatic download at startup on or off, and pick the systems (NES, Game Boy, Game Boy Color, CHIP-8, Master System, Game Gear).

Volume

Master sound volume.

Brightness

Backlight level.

Fast display

Runs the display SPI bus at 80 MHz instead of the default 40 MHz — roughly double the pixel bandwidth, so more frames are shown. Many panels handle it; if you see glitches or noise, turn it off. If the picture is too garbled to find the setting: press RESET, then straight away press and hold BOOT for about 3 seconds. RetroCYD switches Fast display off and restarts.

Smooth motion

On by default. When most of the picture changes at once (scrolling), only every other line of the screen is updated per frame, the other half on the next frame, so twice as many frames reach the display. Still pictures are always drawn in full. Turn it off if you prefer every frame complete, at a lower frame rate while scrolling.

Show FPS

Performance overlay in the top-right corner: Game = frames emulated per second (60 is full speed), LCD = frames per second that reach the screen, CPU = how busy the emulator core is.

Touch calibration

Tap the targets to line up touch with the display. Run it if taps land off-target.

DMG palette

Choose the colours used for original (monochrome) Game Boy games.

Rescan library

Rebuild the game index — use it after adding, removing or renaming games.

About

Firmware version and a QR code that links back to this website.

Settings are stored in the NVS area of the flash chip. “Erase device” resets them to defaults; your SD card is unaffected.

10 Wi-Fi & free games

RetroCYD can fill your SD card by itself: about 1,300 free homebrew games for NES, Game Boy, Game Boy Color, Master System, Game Gear and CHIP-8, from Homebrew Hub, SMS Power! and the CHIP-8 Archive. See the full list.

1. Open Settings → Wi-Fi → Choose network, tap your network and type the password on the on-screen keyboard (?123 switches to symbols, show reveals what you typed). With a controller: D-pad to move, A to type, B to delete, START for OK.
2. RetroCYD connects once to check the password, then saves the network.
3. Open Settings → Game downloads → Download new games now. It shows how many games are new and how many MB they take, then downloads them into /roms/<system>/.
4. With Download at startup on (the default), every start checks for new games and downloads them automatically. Tap the screen or press B to skip; finished games are kept and the rest continue next time.

How it works

• The list of games is a catalog file on this website, rebuilt every week from the Homebrew Hub NES and Game Boy databases, the SMS Power! homebrew list and the CHIP-8 Archive. It includes only entries marked as games, only ones the RetroCYD cores can run, and no fan games built on other companies' characters.
• Every game is downloaded straight from its source over HTTPS (certificates are checked). RetroCYD doesn't host any ROMs. Each file must match the size and SHA-1 listed in the catalog or it is thrown away.
• Games are named by their title, e.g. /roms/gb/Tobu Tobu Girl.gb. Your own files are never overwritten. Master System and Game Gear games stay zipped as SMS Power publishes them; RetroCYD unzips them when you start them.
• RetroCYD remembers what it downloaded (/retrocyd/downloaded.txt), so a game you delete stays deleted. Forget download history brings deleted games back on the next download.
• The full set is about 250 MB. The first download takes a while (expect several minutes); later checks only fetch what's new.
• Wi-Fi is only switched on for downloads and is always off while you play, so games get all of the RAM and CPU. If a game can't get enough memory (for example after Wi-Fi was used), RetroCYD restarts and starts that game straight away (you'll see “Freeing memory”).

Updating RetroCYD over Wi-Fi

Open Settings → Firmware update → Check for update. If the website has a newer build, RetroCYD shows its version, downloads it (about 1.5 MB) and restarts twice; it takes about a minute. Your games, saves and settings stay. If Download at startup is on, the startup check also tells you when an update is available.

• Every version has a number like 1.0.0 and a build number. Updates are offered only for a higher build, never a downgrade.
• The update is checked three ways before it is used: the download size and SHA-256 must match, and ESP-IDF checks the firmware image itself.
• Keep the board powered until the launcher is back. Even if it isn't, the board still starts: it keeps the last complete copy and finishes the update on the next start.
• If a new version fails to start, the bootloader goes back to the previous one and RetroCYD tells you on the next start.
• The rare update that changes the flash layout can't be installed over Wi-Fi; RetroCYD then asks you to use the web flasher instead. The web flasher can always reinstall RetroCYD.

About the stored password: the Wi-Fi password is saved in the board's settings area without encryption. Anyone holding the board could read it, so a guest network is a good idea.

2.4 GHz networks only (the ESP32 has no 5 GHz radio). WPA2 and WPA3 personal networks and open networks work; enterprise (802.1X) networks and hotel-style sign-in pages don't.

11 Audio

Sound comes from the ESP32's built-in DAC (IO26) into the board's amplifier (enabled on IO4) and out through the 1.25 mm 2-pin speaker connector. Use an 8 Ω 1.5 W or 4 Ω 2 W speaker. It's an 8-bit DAC — perfect for 8-bit chiptunes, not hi-fi.

Change the level under Settings → Volume, or from the in-game menu.

12 Pinout & flash layout

Pin assignments of the 4.0″ ESP32-32E board (per LCDwiki), as used by RetroCYD:

Flash layout (4 MB)

The web installer writes the bootloader (0x1000), partition table (0x8000) and app (0x10000) separately, so your settings survive updates. The merged download image starts at offset 0x0. The ROM cache is filled at runtime when you launch a game.

13 Troubleshooting

14 FAQ