Initial commit: Brother QL USB-to-Network Bridge
- 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
This commit is contained in:
timmyhadwen
183
README.md
Normal file
183
README.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user