Skip to main content
Version: Next

RS232 Scanner

Connect a physical barcode or QR code scanner via serial (RS232) interface. Works with any scanner that can output to a serial port or USB-to-serial adapter.

Setup​

The RS232 barcode reader requires manual configuration in your config.toml.

Configuration​

Add this to your config.toml:

[[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 → Ports (COM & LPT)
  • Look for "USB Serial Port (COMX)"

Connection Settings​

The reader uses these fixed serial settings:

  • Baud Rate: 9600
  • Data Bits: 8
  • Parity: None
  • Stop Bits: 1
Keyboard Emulation Mode

Many barcode scanners ship in keyboard emulation mode by default, which is not supported. You must switch your scanner to RS232 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", "RS232", or "USB-COM" in your scanner documentation.

Usage​

QR Codes with Embedded ZapScript​

QR codes have enough capacity (~4KB) to embed ZapScript directly. Simply create a QR code with your ZapScript:

**launch.random:snes

Scan the QR code and Zaparoo will execute the ZapScript immediately.

Linear Barcodes with Mappings​

Linear barcodes (Code 128, Code 39, EAN-13, etc.) can only hold ~100 characters, which usually isn't enough for full ZapScript. Instead, use mappings to map the barcode value to ZapScript.

Example workflow:

  1. Print a barcode with a simple identifier (e.g., 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.

Platform Support​

PlatformSupportedTypical Device Path
MiSTer✅/dev/ttyUSB0
Windows✅COM3
Linux✅/dev/ttyUSB0
macOS✅/dev/tty.usbserial
Batocera✅/dev/ttyUSB0
SteamOS✅/dev/ttyUSB0

Troubleshooting​

Scanner Not Working​

  1. Verify your scanner is in RS232/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. Verify the barcode contains valid ZapScript
  2. Check your scanner isn't adding unwanted prefixes/suffixes - scan a barcode into a text editor to verify the output
  3. If your scanner uses different serial settings (not 9600 baud), reconfigure it using programming barcodes from the manual