# 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

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

### Step 2: Clone the Repository

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

### Step 3: Setup Python Environment

Using `uv` (recommended):
```bash
# 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:
```bash
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:

```bash
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

```bash
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:

```bash
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:

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

Check status:

```bash
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:
```bash
sudo lsof -i :9100
```