Mosaico Gamer: Replaying My Childhood Games on Mosaico

Mosaico Gamer turns ESP-Mosaico into a handheld console. One firmware carries four engines: GBA (gpSP), Game Boy / Game Boy Color (gnuboy), Doom and Quake 1. Games live on the onboard NAND. Pick one from the game list and play, with sound. GBA saves are written back to NAND automatically, so they survive power-off.

You need at least one joystick sub-board, and two feel better: the left one moves, the right one handles the buttons and the camera, much like a two-handed handheld. The firmware ships with no games. Bring your own legally obtained ROM, WAD or PAK files.

Changelog

Changes since the version published on 2026-09-30:

• Wi-Fi: opening Upload over Wi-Fi joins a network already saved on the Recovery page or in this app, and shows the address without another scan or password. Press A on that page to pick a different network.
• Saves: GBA and GB/GBC write the save to NAND about 0.3 seconds after the game finishes a save, and again on quit if anything is still pending. The old scan-and-write about every 30 seconds is gone, and it no longer hitches the game.
• Time: the device asks NTP for the time as soon as it has a network address. The upload page sends the browser's time zone as soon as it opens, so quick settings show local time. The zone is remembered for the next connection.
• List labels: the right side of each game row shows the file format. .wad is WAD and .pak is PAK. They are no longer labeled GB.

How to play

Setup: attach the joystick sub-boards

1. One joystick sub-board
   Use either the left or the right slot. The picture turns to follow the side you are holding. The stick is the direction pad. The four-button ring around it is A, Start, Select and B, matching the picture you see.

2. Two joystick sub-boards (recommended)
   Attach one on each side and the picture sits upright. The left stick is direction or movement. The right module's four buttons are A / Start / Select / B, and the right stick turns the view in Quake. The left module's four buttons have their own use, described under Quake. The same pair also plays Jupiter on Fire, another Mosaico app: the left stick flies, the right stick looks around.

3. First calibration
   After attaching, let go and leave the stick alone. The firmware measures the stick's centre for about half a second. Then sweep the stick once around its edge. The stick's travel range is saved and reused on the next boot.

Add game files

Pick one of the two.

1. Upload over Wi-Fi

   • Join the network: in the game list, select Upload over Wi-Fi and press A. If the Recovery page or this app already has a saved network, the device joins it and shows an http:// address. With nothing saved, the screen asks you to press A and scan: pick a network and type the password on the on-screen keyboard, tapping letters or moving with the stick and pressing A. B deletes a character, Select switches fields, and Start connects. Press A again while already joined to switch networks. The Wi-Fi password is saved.
   • Time: the device asks NTP for the time as soon as it has an IP address. Opening the upload page sends the browser's time zone immediately, and quick settings then show local time.
   • Upload on the web page: open the address on the screen in a browser on a computer on the same network and upload files. They appear in the game list when you go back.

2. USB disk on PC
   Select USB disk on PC, press A, and connect a USB cable. This uses ESP-MSC: the device presents itself as a removable disk, and the computer reads and writes it like any USB drive. Each transfer lands on a sector of the onboard SPI NAND, which is one FAT volume. The whole NAND is that disk, about 120 MB. Drag files onto it.

Both ways accept .gb, .gbc, .gba and .wad, plus Quake .pak files. Keep the Quake data packs under their original names, pak0.pak, pak1.pak and so on, in the root of the disk. The engine loads them in order starting from pak0.pak, so pak0.pak is required and the numbering must not skip. Selecting any .pak in the game list starts Quake. The right side of each row shows the format: GB, GBC, GBA, WAD or PAK.

Game list

1. Select: push the stick up or down to move the cursor. It wraps at the top and bottom.
2. Start: press A or Start to launch the selected game. On an upload entry, the same keys open that page.
3. Delete: press Select on a game. A "THIS CANNOT BE UNDONE" box appears. A deletes, B or Select cancels. A deleted file cannot be recovered.
4. Leave a page: on the upload page, B goes back. On the on-screen keyboard, B deletes a character and a tap of the AI key cancels input. Do not hold the AI key; holding it enters Recovery.

GBA / GB / GBC

1. D-pad: the stick. It has to be pushed past a threshold, so small jitters do not register.
2. A / B / Start / Select: the four ring buttons.
3. L / R shoulders: hold the bottom-left part of the screen for L and the bottom-right part for R. You can hold both at once.
4. Saving: save in the game as usual. About 0.3 seconds after the game finishes writing, the firmware stores that save on NAND, and writes again on quit if anything is still pending. It no longer stops about every 30 seconds to scan the whole save.
5. Quit: tap the AI key to return to the game list. Do not hold it; holding it enters Recovery.

Doom

1. Move and turn: push the stick forward to walk, back to retreat, left or right to turn.
2. A: fire; confirm in menus.
3. B: open doors and use switches; also confirms in menus.
4. Start: hold to run.
5. Select: toggle the automap.
6. L / R: hold the bottom-left or bottom-right screen area to strafe.
7. Stick click: press the stick in. At the quit prompt this answers Y.
8. AI key: tap to open the Doom menu. Do not hold it; holding it enters Recovery.

Quake

1. Move: the left stick walks forward, back and strafes. The further you push, the faster you move.
2. Look: the right stick turns left and right and looks up and down. The further you push, the faster the view turns. With only one sub-board there is no look stick.
3. A: attack.
4. B: jump.
5. Start: hold to run.
6. Select: show the scoreboard.
7. Change weapon: on the left module's four buttons, up and right select the next weapon; down and left select the previous one.
8. Left stick click: answers Y at the quit prompt.
9. AI key: tap to open the Quake menu. Do not hold it; holding it enters Recovery.

Quick settings (available at any time)

1. Open: swipe down from the top edge of the screen.
2. Adjust: drag left or right on the brightness or volume slider. Settings are saved and persist across reboots.
3. Status: the panel also shows the time and battery level.
4. Close: swipe up, or tap outside the panel. While the panel is open, the game list ignores launch and delete.

Later updates

• Magnetic interaction between devices, in the style of GBA / GBC link play and trading.
• More emulators.

Specs

• Hardware: ESP-Mosaico (ESP32-S31) plus joystick sub-boards (at least one, two recommended)
• Engines: gpSP (GBA), gnuboy (GB/GBC), Doom, Quake 1 (WinQuake)
• Categories: Display & HMI / Audio / Communication
• Firmware: Iris
• License: GPL-3.0-or-later. The engines are GPL-2.0-or-later and the application code is Apache-2.0; see NOTICE in the project.
• No game ROM, WAD or PAK files are included.