Barcode Scanner

HelixScreen can read Spoolman QR codes from a USB or Bluetooth barcode scanner, so you can identify a spool by scanning it instead of picking from a list.

This guide covers both USB and Bluetooth scanners, and how to fix the most common Bluetooth pairing problem on Raspberry Pi.

USB Scanners

Most USB barcode scanners present themselves to the Pi as a plain HID keyboard — no driver install needed.

Plug the scanner into any USB port.
Open Settings → Barcode Scanner.
If the scanner appears under “USB devices”, tap it to select. Otherwise “Auto-detect” will pick the first HID keyboard that isn’t your physical keyboard.
Open the QR scanner overlay (wherever the app offers it — e.g. from the filament panel) and test by scanning a Spoolman QR code.

Keymap

If scanned text comes out garbled, the scanner is emitting keycodes for a different keyboard layout than the one HelixScreen is decoding. Under Settings → Barcode Scanner → Keymap pick the layout your scanner is programmed to use (QWERTY is the default).

Bluetooth Scanners

HelixScreen supports Bluetooth HID barcode scanners (the kind that pair as a keyboard-like device).

Pairing

Power on the scanner. Make sure it’s in Classic Bluetooth pairing mode (not BLE). The scanner’s manual will have a config barcode to select Classic mode if needed — most default to Classic.
Open Settings → Barcode Scanner → Scan Bluetooth.
When your scanner appears in the dropdown, tap Pair.
If pairing succeeds, the scanner becomes selected automatically.

⚠️ “Paired, but scanner is not usable”

If you see a warning toast that says pairing worked but the scanner is not usable, your adapter is refusing the HID connection because the scanner didn’t perform a bonded pair.

This is a security default in BlueZ: HID devices must be bonded (cryptographic key exchanged and stored) before the kernel will route their keystrokes. Many inexpensive barcode scanners only support “Just Works” pairing, which produces a paired-but-not-bonded link — and gets rejected.

Fix

Relax the HID-bonded-only policy on your Pi. You’ll need SSH access.

SSH to the Pi:
Terminal window
```
ssh pi@helixpi.local
```
Edit the BlueZ input config:
Terminal window
```
sudo nano /etc/bluetooth/input.conf
```

Find the line:

#ClassicBondedOnly=true

Uncomment it and change to:

ClassicBondedOnly=false

Save and restart BlueZ:
Terminal window
```
sudo systemctl restart bluetooth
```
In HelixScreen, forget any previous pairing for this scanner, then pair again. You should not see the warning this time and scanning into the QR overlay will work.

Security note: ClassicBondedOnly=false lets any unbonded HID peripheral connect, which slightly widens the attack surface for keystroke injection. This is only a concern in hostile RF environments. For typical home and workshop use, the change is safe.

BLE Mode

Some scanners support both Classic and BLE modes. BLE uses different pairing mechanics that always bond, so the issue above doesn’t apply — but not all scanners advertise reliably in BLE. If Classic works, stick with it.

Troubleshooting

Symptom	Fix
No scanner appears in the dropdown	Is Bluetooth enabled on your Pi? See Bluetooth Setup.
”Pairing failed” (Connection timed out)	Scanner isn’t in pairable mode. Power-cycle it and scan its Classic-mode config barcode.
”Pairing failed” (Host is down)	Scanner is flashing but refusing Classic connections. Power-cycle and retry; some scanners get stuck between BLE and Classic advertising.
”Paired, but scanner is not usable”	Set `ClassicBondedOnly=false` — see above.
Scanner pairs, but scanned text types into the app’s UI instead of being captured as a QR code	Open the QR scanner overlay before scanning. Outside the overlay, the scanner is just a keyboard.
Scanned text has wrong characters	Set the correct keymap under Settings → Barcode Scanner.

Notes

Only one scanner (USB or Bluetooth) is used at a time. If both are configured, the paired Bluetooth scanner wins.
When a Bluetooth scanner is selected, HelixScreen captures its keystrokes exclusively so they don’t leak into other UI widgets. USB scanners run in passive mode (some scanners rely on this) — if USB scanner keystrokes leak into focused text inputs, that is a known limitation.