4010ffc01b
- TCP server exposing USB Brother QL printers on port 9100 - Supports all Brother QL series label printers - Async architecture for handling concurrent print jobs - Raspberry Pi deployment script and systemd service - Documentation for setup and InvenTree integration
184 lines
4.2 KiB
Markdown
184 lines
4.2 KiB
Markdown
# 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/Copy the Project
|
|
|
|
```bash
|
|
# Create project directory
|
|
mkdir -p ~/brother-ql-bridge
|
|
cd ~/brother-ql-bridge
|
|
|
|
# Copy files: bridge.py, config.py, pyproject.toml, requirements.txt
|
|
```
|
|
|
|
### 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
|
|
```
|