MiSTer FPGA
MiSTer is fully supported by Zaparoo and is where the project originally started. Zaparoo has several MiSTer-exclusive features because of this, including MiSTer-specific ZapScript commands.
File paths
| Item | Path |
|---|---|
| Config file | /media/fat/zaparoo/config.toml |
| Data directory | /media/fat/zaparoo |
| Log file | /tmp/zaparoo/core.log |
| Mappings directory | /media/fat/zaparoo/mappings |
The /media/fat directory is the top level of the SD card. The /tmp directory is not accessible from the SD card and is deleted when MiSTer is powered off.
Install
Zaparoo is available in Update All as a dedicated item in Tools & Scripts. Update All can install Zaparoo Core and can also enable Zaparoo Frontend in your MiSTer.ini file. Frontend is optional; Core can run in the background with the standard MiSTer menu.
Once Core is installed, run zaparoo from the MiSTer Scripts menu. A prompt will offer to enable Zaparoo as a startup service. That service starts at the end of MiSTer's boot; see start Core earlier if you want it ready sooner after power on.
For manual Core installation, download from the Downloads page and copy zaparoo.sh to the Scripts folder on your SD card.
When Update All installed Core, it also updates it; a zaparoo.sh you copied by hand can update itself. See Core updates. Update All can also install artwork and game manual packs that Core imports with the mister-docs scraper.
If you previously had TapTo installed, make sure the old tapto.sh is removed from your Scripts folder and that linux/user-startup.sh no longer references it. Having both services running simultaneously can cause double-launches and detection conflicts. Zaparoo is a direct replacement. Your existing NFC cards will continue to work.
Game tracking
Zaparoo can detect games launched outside of Zaparoo, like games started directly from the MiSTer menu. This is needed for playtime tracking to work correctly. Enable the recents and log_file_entry settings in MiSTer's configuration for the most accurate tracking.
To enable them:
- Open
MiSTer.inion your SD card (located at/media/fat/MiSTer.ini) - Look for a
recents=line. If it exists, change it torecents=1. If there's norecentsline, addrecents=1to the file. - Look for a
log_file_entry=line and set it tolog_file_entry=1. Add the line if it isn't already present. - Save the file and reboot MiSTer
The recents setting records recently launched games. log_file_entry records the filename selected in MiSTer's file browser, which lets Zaparoo match a MiSTer launch to a specific game. MiSTer.ini warns about the extra SD card writes from recents, but it's not a real concern with modern SD cards.
If you run Zaparoo's MiSTer Main build, none of this is needed: Main reports the running game to Core itself.
Start Core earlier
Core is started by /media/fat/linux/user-startup.sh, which MiSTer runs last during boot, after networking, Bluetooth and Samba. The menu appears before that finishes, so for a short while after power on a scanned token does nothing. Two ways to start Core sooner:
- Install Zaparoo Frontend. Its MiSTer Main build starts Core before the menu even loads, and there is nothing extra to maintain.
- Add an init script. Over SSH, create
/etc/init.d/S11zaparoowith the contents below, make it executable withchmod +x /etc/init.d/S11zaparoo, and reboot. It runs early in the init sequence instead of at the end. The file lives insidelinux/linux.img, so a MiSTer Linux update removes it and you need to add it again. Leave themrext/zaparooline inuser-startup.shalone: starting the service twice is harmless, and that line is what keeps Core starting once the script is gone.
#!/bin/sh
# Start Zaparoo Core early in MiSTer's boot. Lives inside linux.img, so
# add it again after a MiSTer Linux update.
ZAPAROO=/media/fat/Scripts/zaparoo.sh
[ -x "$ZAPAROO" ] || exit 0
case "$1" in
start|stop|restart|status) "$ZAPAROO" -service "$1" ;;
esac
Uninstall
There is no uninstall command on MiSTer. To remove Zaparoo:
- Delete
/media/fat/Scripts/zaparoo.sh. - Remove the
mrext/zaparooline from/media/fat/linux/user-startup.sh. - Delete
/media/fat/zaparooif you also want to remove your configuration, mappings, and data.
Device profile data
Device profiles automatically separate save files and save states on MiSTer. Existing saves remain under the shared profile, while each personal profile gets separate directories in the active storage location. When odelot's custom RetroAchievements Main is installed, Core can also switch account configuration with each profile.
Device backups
MiSTer supports portable device backups containing Zaparoo data, MiSTer settings, input mappings, saves, save states, profile-specific save directories, shared-profile saves and settings, names.txt, the legacy mappings file, and the profile name file. Create local backups from the Core terminal UI, or link Zaparoo Online for cloud snapshots and scheduling.
Readers
| Type | Reader | Support | Setup | Notes |
|---|---|---|---|---|
| NFC/RFID | PN532 USB | Supported | Auto-detected | |
| NFC/RFID | PN532 Module | Supported | Depends on wiring | UART can auto-detect. I2C is supported. |
| NFC/RFID | ACR122U | Supported | Manual enable | Uses libnfc: LED and beeper do not work, and some clone variants are incompatible. |
| NFC/RFID | RC522 | Limited | Via Simple Serial | Requires a microcontroller; not a direct USB reader. |
| Barcode and QR | Zaparoo App camera | Supported | Via Zaparoo App | |
| Barcode and QR | RS-232 scanner | Supported | Manual config | |
| Optical and Media | Optical Drive | Supported | Manual config | |
| Optical and Media | External Drive | Supported | Manual enable | |
| Custom and Virtual | MQTT Reader | Supported | Manual config | |
| Custom and Virtual | Simple Serial | Supported | Manual config | |
| Custom and Virtual | File Reader | Supported | Manual config | |
| Displays and Integrations | TTY2OLED | Supported | Manual enable |
Each reader's page has setup steps and troubleshooting. See readers to compare them, or the setup guide to pick one for your setup.
Launchers
MiSTer supports 100+ systems including consoles, computers, and arcade games. Games launch automatically using the official core folder structure from Downloader.
See Launchers for the full list of supported systems, file extensions, special features, and alternate cores.
Main forks
Some MiSTer Main forks are available with Zaparoo integration or features that work well with Zaparoo.
Zaparoo
Zaparoo's own build of MiSTer Main ships with Zaparoo Frontend and works without it too. It reports the running game to Core, starts Core before the menu, and adds kiosk mode, auto-save, disc autorun, and commands a card can send. See Zaparoo MiSTer Main.
spark2k06
An alternative version of MiSTer Main by spark2k06 adds many Zaparoo-related features:
- Show status of connected reader as icon in top bar
- Zaparoo standby screen
- Box art on game load
- Many additional MGL features
See spark2k06's repository for more details.
Insert-Coin
An alternative version of MiSTer Main by funkycochise as part of the Insert-Coin project. This version hides the loading screen before cores start games, which works great with Zaparoo.
Troubleshooting
Zaparoo does not start at boot. Run zaparoo from the MiSTer Scripts menu and accept the prompt to enable it as a startup service, or check that /media/fat/linux/user-startup.sh contains the mrext/zaparoo line.
Tokens do nothing for a while after power on. Core is started last in MiSTer's boot sequence, so it can lag behind the menu appearing. See start Core earlier.
Games started from the MiSTer menu are not tracked. Playtime tracking needs recents=1 and log_file_entry=1 in MiSTer.ini. See game tracking.
A reader is detected by the wrong driver, or conflicts with another serial device. Other USB serial devices, such as tty2oled or an Arduino, can confuse auto-detection. Disable auto_detect in config.toml and set the reader path manually; see reader drivers.
Logs are empty after a reboot. MiSTer keeps the log in /tmp, which is cleared at shutdown. Collect logs right after the problem happens; see the help page.
FAQ
Which NFC reader should I use with MiSTer?
The PN532 USB reader is the recommended choice. It works out of the box with no configuration required. The ACR122U is also supported on MiSTer but is more prone to clone compatibility issues.
Do I need the app to use Zaparoo on MiSTer?
No. Once Zaparoo Core is installed, you can write tokens using the built-in TUI from the Scripts menu or the Web UI. The Zaparoo App makes things easier but is not required.
Do I have to use Zaparoo Frontend?
No. Core runs as a background service and can scan tokens while you continue using the standard MiSTer menu. Frontend is an optional controller-friendly library interface. The App and Web UI are also optional ways to manage Core.
Will Zaparoo work with SNAC or through a USB hub?
Do not plug NFC readers into the SNAC/USER port on MiSTer. It looks like USB but it's not. Use a standard USB port or hub instead. USB hubs are fine!
Do my existing TapTo NFC cards work after upgrading to Zaparoo?
Yes. Zaparoo is a direct replacement for TapTo and all existing cards continue to work without being rewritten.