Reader Drivers
Reader drivers let Zaparoo Core communicate with different types of reader hardware. Each driver handles the protocol and connection method for one reader type.
How drivers work
When Zaparoo Core starts, it:
- Loads all enabled reader drivers
- Attempts to auto-detect connected readers when auto-detect is enabled
- Establishes connections to detected or manually configured readers
- Begins listening for token scans
PN532 USB readers support auto-detection on their listed platforms, and the ACR122U does on Windows. On Linux-based platforms the ACR122U driver is enabled but only searches for the reader once you turn on auto-detect for it. The Epilogue Operator bridge is also detected automatically on MiSTer when its script is installed. RS-232 barcode and Simple Serial readers, along with MQTT, display, external-drive, and fallback NFC drivers, require manual configuration or explicit enabling.
Available drivers
NFC readers
NFC readers support NFC tags, cards, and compatible toys such as Amiibo and LEGO Dimensions.
| Driver ID | Hardware | Platforms | Documentation |
|---|---|---|---|
pn532, pn532uart | PN532 USB modules | Current Core platforms | PN532 USB |
pn532i2c, pn532spi | PN532 bare modules | Current Core platforms | PN532 Module |
libnfcacr122 | ACR122U reader | Linux-based platforms | ACR122U |
acr122pcsc | ACR122U reader | Windows | ACR122U |
legacypn532uart (legacy) | PN532 USB fallback | Linux-based platforms | See legacy NFC drivers |
legacypn532i2c (legacy) | PN532 I2C fallback | Linux-based platforms | See legacy NFC drivers |
Driver IDs with underscores, such as pn532_uart and simple_serial, are still supported. Core strips underscores internally, but new configurations should use the non-underscore driver IDs shown here.
Optical readers
| Driver ID | Hardware | Platforms | Documentation |
|---|---|---|---|
opticaldrive | CD/DVD/Blu-ray drives | Linux-based platforms | Optical Drive |
Cartridge readers
| Driver ID | Hardware | Platforms | Documentation |
|---|---|---|---|
operator | Epilogue GB, SN, and 64 Operator cartridge bridges | MiSTer | Epilogue Operator |
The operator driver is enabled by default. Core auto-detects it when /media/fat/Scripts/Operator.sh is present; no manual reader configuration is required.
Display devices
| Driver ID | Hardware | Platforms | Documentation |
|---|---|---|---|
tty2oled | TTY2OLED serial displays | Current Core platforms | TTY2OLED |
tty2oled is disabled by default. Enable it before use.
Barcode readers
| Driver ID | Hardware | Platforms | Documentation |
|---|---|---|---|
rs232barcode | RS-232 barcode/QR scanners | Current Core platforms | RS-232 Scanner |
The Zaparoo App can also scan barcodes and QR codes using your device's camera. Scanned codes are sent to Core via the API and don't require a dedicated reader driver.
Protocol and virtual readers
These drivers support custom hardware, automation, and non-reader token sources:
| Driver ID | Purpose | Platforms | Documentation |
|---|---|---|---|
mqtt | MQTT broker integration | Current Core platforms | MQTT Reader |
externaldrive | USB/SD cards as tokens | Current Core platforms | External Drive |
simpleserial | Custom microcontroller readers | Current Core platforms | Simple Serial |
file | File-based virtual reader | Current Core platforms | File Reader |
externaldrive is disabled by default. Enable it directly or add a manual connection for the drive you want Core to watch.
Configuration
Auto-detection
By default, Zaparoo Core automatically detects readers whose drivers support auto-detection:
[readers]
auto_detect = true
Some drivers are enabled but not auto-detected by default. For those readers, add a manual connection or enable auto-detect for the specific driver. For example, to have Core search for an ACR122U on a Linux-based platform:
[readers.drivers.libnfcacr122]
auto_detect = true
Manual reader configuration
To manually specify a reader, add a readers.connect section to your config.toml:
[[readers.connect]]
driver = "pn532uart"
path = "/dev/ttyUSB0"
A [[readers.connect]] entry also enables that driver unless the driver is explicitly disabled with [readers.drivers.DRIVER_ID]. See the individual reader page for driver-specific paths and options.
Driver-specific settings
You can control individual drivers with readers.drivers sections:
[readers.drivers.tty2oled]
enabled = true
[readers.drivers.simpleserial]
enabled = false
auto_detect = false
Use [readers.drivers.DRIVER_ID] for driver settings. [[readers.drivers]] is not valid config syntax.
Troubleshooting
Reader not detected
- Check auto-detect is enabled with
auto_detect = trueinconfig.toml. - Enable debug logging with
debug_logging = trueinconfig.toml. - Check the hardware connection. Make sure the USB cable is a data cable, not power-only.
- Review the hardware-specific reader page for setup and troubleshooting notes.
- Try manual configuration with
[[readers.connect]].
Unable to enumerate USB device
A Linux message such as usb 1-1-port2: unable to enumerate USB device means the operating system could not identify the USB hardware. This happens before Zaparoo Core can open the reader, so changing reader-driver settings will not fix it until the device appears to the operating system.
Check the connection in this order:
- Disconnect the reader, wait a few seconds, and reconnect it.
- Try another standard USB port without an extension cable or unpowered hub. On MiSTer, do not use the SNAC/USER port.
- If the cable is detachable, replace it with a known data cable.
- Power the host off completely, then start it again with the reader disconnected and reconnect it after startup.
- Test the reader and cable on another computer. If it works there but not through a hub, try a powered hub.
On Linux-based platforms, run lsusb to check whether the device is present. Review dmesg or the system log for repeated USB protocol, disconnect, or power errors. Linux kernel USB errors such as -EPROTO, -EILSEQ, and -EOVERFLOW can point to hardware, firmware, or cable problems.
After the device appears in lsusb, restart Core, then continue with the reader-specific troubleshooting steps.
Multiple readers
You can connect multiple readers simultaneously:
[[readers.connect]]
driver = "pn532uart"
path = "/dev/ttyUSB0"
[[readers.connect]]
driver = "pn532uart"
path = "/dev/ttyUSB1"
[[readers.connect]]
driver = "opticaldrive"
path = "/dev/sr0"
Each reader operates independently and can scan tokens.
Legacy NFC drivers
Core v2.6.0 switched PN532 readers to the newer pn532 driver. The old libnfc-based PN532 drivers are still available as fallback options if a reader worked before v2.6.0 but has trouble with the newer driver.
When to use legacy drivers
Use the legacy drivers if you experience:
- Connection issues with PN532 readers that worked before v2.6.0
- Problems reading or writing specific tag types
- I2C communication issues on embedded platforms
Configuration
Manually configure your reader to use the legacy driver:
For PN532 UART/USB readers:
[[readers.connect]]
driver = "legacypn532uart"
path = "/dev/ttyUSB0"
For PN532 I2C readers:
[[readers.connect]]
driver = "legacypn532i2c"
path = "/dev/i2c-1"
Limitations
The legacy drivers have the following limitations compared to the new driver:
- Higher CPU usage
- MIFARE tags require pre-formatting before use
- No FeLiCa tag support
- Less responsive feel when scanning
- Windows is not supported
Reporting issues
If you need to use the legacy drivers, please report the issue you're experiencing with the new driver on GitHub or Discord. Reports help improve the current PN532 driver.