Skip to main content

Reader Drivers

Reader drivers are software components that enable Zaparoo Core to communicate with different types of reader hardware. Each driver implements the specific protocol and communication method required for a particular reader type.

How Drivers Work​

When Zaparoo Core starts, it:

  1. Loads all enabled reader drivers
  2. Attempts to auto-detect connected readers (if enabled)
  3. Establishes connections to detected or manually configured readers
  4. Begins listening for token scans

Most users don't need to worry about drivers - they work automatically! Auto-detection is enabled by default and works for most hardware.

Available Drivers​

NFC Readers​

NFC readers are the most common type, supporting NFC tags, cards, and compatible toys (Amiibo, Lego Dimensions, etc.).

Driver IDHardwarePlatformsDocumentation
pn532, pn532_uartPN532 USB modulesAll platformsPN532 USB
pn532_i2c, pn532_spiPN532 bare modulesAll platformsPN532 Module
acr122_usbACR122U readerLinux, MiSTerACR122U
acr122_pcscACR122U readerWindowsACR122U

Optical Readers​

Driver IDHardwarePlatformsDocumentation
optical_driveCD/DVD/Blu-ray drivesLinux-based platformsOptical Drive

Display Devices​

Driver IDHardwarePlatformsDocumentation
tty2oledTTY2OLED serial displaysAll platformsTTY2OLED

Protocol & Virtual Readers​

These drivers enable custom hardware integration and automation:

Driver IDPurposePlatformsDocumentation
simple_serialCustom microcontroller readersAll platformsSimple Serial
fileFile-based virtual readerAll platformsFile Reader

Configuration​

Auto-Detection​

By default, Zaparoo Core automatically detects most readers:

[readers]
auto_detect = true  # Default setting

Manual Reader Configuration​

To manually specify a reader, add a readers.connect section to your config.toml:

[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB0'

See individual hardware documentation for driver-specific configuration options.

Driver-Specific Settings​

You can control individual drivers with readers.drivers sections:

[readers.drivers.tty2oled]
enabled = true  # Enable disabled-by-default drivers

[readers.drivers.simple_serial]
enabled = false  # Disable problematic drivers
auto_detect = false  # Disable auto-detect for specific drivers

Troubleshooting​

Reader Not Detected​

  1. Check auto-detect is enabled - Set auto_detect = true in config.toml
  2. Enable debug logging - Set debug_logging = true in config.toml
  3. Check hardware connection - Verify USB cable, power, etc. and make sure the cable is a data cable, not power-only
  4. Review driver documentation - See hardware-specific troubleshooting
  5. Try manual configuration - Explicitly configure the reader

Multiple Readers​

You can connect multiple readers simultaneously:

[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB0'

[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB1'

[[readers.connect]]
driver = 'optical_drive'
path = '/dev/sr0'

Each reader operates independently and can scan tokens.

See Also​