Brother QL Bridge

A TCP-to-USB bridge that exposes a USB-connected Brother QL label printer on the network, making it compatible with network-based printing tools like InvenTree's Brother plugin.

What It Does

• Listens on TCP port 9100 (standard raw printing port)
• Receives print jobs from network clients
• Forwards the raw Brother raster data to a USB-connected QL printer

Supported Printers

• QL-500, QL-550, QL-560, QL-570, QL-580N
• QL-650TD, QL-700, QL-710W, QL-720NW
• QL-800, QL-810W, QL-820NWB
• QL-1050, QL-1060N

Raspberry Pi Deployment

Prerequisites

1. Raspberry Pi with Raspberry Pi OS (Bookworm or later recommended)
2. Brother QL printer connected via USB
3. Python 3.10+

Step 1: Install System Dependencies

sudo apt update
sudo apt install -y python3 python3-pip python3-venv libusb-1.0-0-dev

Step 2: Clone the Repository

git clone https://github.com/timmyhadwen/brother-ql-bridge.git
cd brother-ql-bridge

Step 3: Setup Python Environment

Using uv (recommended):

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install dependencies
cd ~/brother-ql-bridge
uv venv
uv pip install -r requirements.txt

Or using standard pip:

cd ~/brother-ql-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 4: Configure USB Permissions

Create a udev rule to allow non-root access to Brother printers:

sudo tee /etc/udev/rules.d/99-brother-ql.rules << 'EOF'
# Brother QL label printers
SUBSYSTEM=="usb", ATTR{idVendor}=="04f9", MODE="0666"
EOF

sudo udevadm control --reload-rules
sudo udevadm trigger

Step 5: Test the Bridge

cd ~/brother-ql-bridge
source .venv/bin/activate
python bridge.py -v

You should see output like:

2024-12-21 16:30:00 [INFO] Found printer: QL-570
2024-12-21 16:30:00 [INFO] USB connection established
2024-12-21 16:30:00 [INFO] Bridge server listening on ('0.0.0.0', 9100)

Step 6: Install as Systemd Service

Create the service file:

sudo tee /etc/systemd/system/brother-ql-bridge.service << EOF
[Unit]
Description=Brother QL USB-to-Network Bridge
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME/brother-ql-bridge
ExecStart=$HOME/brother-ql-bridge/.venv/bin/python bridge.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable brother-ql-bridge
sudo systemctl start brother-ql-bridge

Check status:

sudo systemctl status brother-ql-bridge
sudo journalctl -u brother-ql-bridge -f  # Follow logs

Configuration

Edit config.py to customize:

Setting	Default	Description
TCP_HOST	0.0.0.0	Listen address (0.0.0.0 = all interfaces)
TCP_PORT	9100	TCP port for incoming print jobs
USB_DEVICE	None	USB device path (None = auto-detect)
PRINTER_MODEL	QL-570	Printer model for compatibility
LOG_LEVEL	INFO	Logging verbosity

Command Line Options

python bridge.py [-h] [-p PORT] [-H HOST] [-d DEVICE] [-v]

Options:
  -p, --port PORT      TCP port (default: 9100)
  -H, --host HOST      Bind address (default: 0.0.0.0)
  -d, --device DEVICE  USB device (e.g., usb://0x04f9:0x2028)
  -v, --verbose        Enable debug logging

Using with InvenTree

Configure InvenTree's Brother label plugin with:

• IP Address: Your Raspberry Pi's IP address
• Port: 9100 (or your configured port)
• Model: Your printer model (e.g., QL-570)

Troubleshooting

"No Brother QL printer found on USB"

1. Check USB connection: lsusb | grep Brother
2. Verify udev rules are loaded: sudo udevadm control --reload-rules
3. Unplug and replug the printer

Permission denied errors

Ensure udev rules are in place and you've re-plugged the printer after adding them.

Service won't start

Check logs: sudo journalctl -u brother-ql-bridge -n 50

Port 9100 in use

Either change the port in config.py or stop the conflicting service:

sudo lsof -i :9100