Skip to main content
Version: Next

RS-232 Scanner

Connect a physical barcode or QR code scanner through an RS-232 serial port or USB-to-serial adapter. The scanner must be configured for RS-232 or USB-COM output and send each scan as a line of serial text.

Platforms​

Base OS
WindowsSupported
macOSSupported
LinuxSupported
FPGA
MiSTerSupported
MiSTeXSupported
Retro Gaming OS
BatoceraSupported
RePlayOSSupported
Handheld and Gaming Linux
SteamOSSupported
BazziteSupported
ChimeraOSSupported
Media Center
LibreELECSupported

Setup​

The RS-232 barcode reader is not auto-detected. Add it manually to your config.toml with the serial port path for your scanner.

Configuration​

On Linux or macOS:

[[readers.connect]]
driver = "rs232barcode"
path = "/dev/ttyUSB0"  # Linux/macOS

On Windows:

[[readers.connect]]
driver = "rs232barcode"
path = "COM3"  # Windows

Finding your serial port​

Linux:

ls /dev/ttyUSB* /dev/ttyACM*

macOS:

ls /dev/tty.usb* /dev/cu.usb*

Windows:

  • Check Device Manager, then Ports (COM & LPT)
  • Look for "USB Serial Port (COMX)"

Connection settings​

Zaparoo Core uses these fixed serial settings for the rs232barcode driver:

  • Baud rate: 9600
  • Data bits: 8
  • Parity: none
  • Stop bits: 1

These settings are not configurable in Core. If your scanner uses different settings, reconfigure the scanner with its manual or programming barcodes.

Keyboard Emulation Mode

Many barcode scanners ship in keyboard emulation mode by default, which is not supported by this reader driver. Switch your scanner to RS-232 mode or USB-COM mode using either:

  • A physical switch on the scanner
  • Programming barcodes from the scanner's manual

Look for settings labeled "Serial Mode", "RS-232", or "USB-COM" in your scanner documentation.

Usage​

QR codes with embedded ZapScript​

QR codes can hold enough text to embed ZapScript directly. Use the QR code generator or another QR code tool to create a code with your ZapScript:

**launch.random:snes

Scan the QR code and Zaparoo runs the ZapScript.

Linear barcodes with mappings​

Linear barcode capacity depends on the format, scanner, and label size. For UPCs, EAN codes, and short custom IDs, mappings are usually the practical choice: the barcode stores an ID, and Zaparoo maps that ID to ZapScript.

Example workflow:

  1. Print a barcode with a short identifier, such as SONIC001.

  2. Create a mapping in mappings/barcodes.toml:

[[mappings.entry]]
token_key = "id"
match_pattern = "SONIC001"
zapscript = "@Genesis/Sonic the Hedgehog"
  1. Scan the barcode. Zaparoo matches SONIC001 and executes the mapped ZapScript.

See the mappings documentation for more details on creating and managing mappings.

Troubleshooting​

Scanner not working​

  1. Verify your scanner is in RS-232 or USB-COM mode, not keyboard emulation mode
  2. Check the correct serial port path using the commands above
  3. Check permissions (Linux/macOS): 
    sudo usermod -a -G dialout $USER
    # Log out and back in for changes to take effect
  4. Enable debug logging (debug_logging = true) and check for "opened RS232 barcode reader" messages

Nothing happens when scanning​

  1. For QR codes that contain ZapScript directly, verify the QR code text is valid ZapScript.
  2. For mapped barcodes, verify the mapping uses token_key = "id" and that match_pattern matches the scanned value.
  3. Check your scanner isn't adding unwanted prefixes or suffixes. Core strips common STX/ETX framing, but other extra characters can break exact mappings.
  4. If your scanner uses different serial settings, reconfigure it to 9600 8N1 using programming barcodes from the manual.