dodoooh/brother_ql_app repository overview

⁠Brother QL Printer App

A web interface and REST API for Brother QL label printers. Compose a label in the browser or send it from a script. The app renders it, queues it and prints it over the network, over USB, or through a Linux device node.

Open the demo⁠. It is the real interface with a simulated printer behind it, runs entirely in your browser, and prints nothing.

⁠Features

• Text, images, QR codes and PDFs, plus combined layouts (text with a QR code or an image beside it)
• A live preview rendered by the same code that drives the printer
• A print queue with per-job status, reprint and cancel
• Media detection: the app can read which roll is loaded and follow it
• Print alignment calibration per label type, with an optional bleed
• Round die-cut labels, and text that runs lengthwise along continuous tape
• Optional mains power control through a relay
• Keep-alive for network printers that fall asleep
• A documented REST API with a Swagger UI, for Home Assistant, Apple Shortcuts or a shell script

⁠Quick start

# docker-compose.yml
services:
  brother_ql_app:
    image: dodoooh/brother_ql_app:dev
    container_name: brother_ql_app
    ports:
      - "5000:5000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    environment:
      - PYTHONPATH=/app
      - FLASK_ENV=production

docker compose up -d

The interface is then at http://<host>:5000 and the API documentation at http://<host>:5000/api/v1/ui/. Set your printer address under Settings or with PUT /api/v1/settings.

The image is published for linux/amd64 and linux/arm64, which covers a 64-bit Raspberry Pi, a NAS and an ordinary server. There is no 32-bit build: Pillow ships no armv7 wheel, so it would have to be compiled, and this image deliberately carries no compiler. On a 32-bit system, build it yourself with docker build.

The API is open to whoever can reach the port. That matches what it drives: a label printer accepts a raster on port 9100 from anyone on the same network, with or without this app in front of it. Give it a network you trust, or a reverse proxy, and see API_KEY below if you run it without the interface.

⁠Printing from a script

curl -X POST http://<host>:5000/api/v1/text/print \
  -H 'Content-Type: application/json' \
  -d '{
        "text": "Shelf A-12",
        "settings": { "label_size": "62", "font_size": 50 }
      }'

The call returns a job id straight away. Poll GET /api/v1/jobs/{id} if you need the result. Add -H 'X-API-Key: ...' if you set that variable. Image and PDF upload, QR codes, combined layouts, printer status and queue control work the same way and are documented in the Swagger UI, which is generated from the specification the server routes on. The demo carries the same reference as a static page⁠, for reading it without installing anything.

⁠Print queue

Jobs are printed one at a time, because the printer accepts one connection at a time. The queue shows what each job is doing, including the phases a job passes through while it waits for a printer to become available.

⁠Mains power control

A Brother QL starts up on its own as soon as mains power returns, at least the QL-820NWB this was built against. That makes a relay in front of it a remote power switch: cutting the supply switches the printer off, restoring it switches the printer on, and nobody has to walk over and press the button.

The relay is anything that can be driven by a webhook: a Shelly, a Tasmota plug, an ESPHome switch, or a Node-RED flow in front of one. The app closes it when a job arrives at a printer that is not answering, and opens it again once the configured window has passed.

A printer that has just been switched on needs time. The app waits for it, holding the job in the queue instead of failing it, and retries the print a few times while the device settles. The waiting times come from watching a QL-820NWB boot, so they are one printer's numbers for now.

The feature is off by default, and switching the printer off again is a separate setting. printer_auto_power_off_minutes should match what the printer's own menu shows, since the app subtracts it from the keep-alive window and has no way to read it from the device.

⁠Configuration

Settings live in data/settings.json. Edit them in the interface or with PUT /api/v1/settings. Any of them can also be sent with a single print request under settings, where they override the stored value for that job only.

Printer

Layout and rendering

Media detection

Keep-alive and mains power

Environment variables:

The relay credential is an environment variable and not a setting, because GET /settings returns the configuration to any client that can read it.

⁠Tested printers and media

What has actually been printed, rather than what the label catalogue says is possible. The app knows about far more media than this table lists; these are the combinations somebody has held in their hand.

If you print on something that is not in the table, a line here is welcome: printer, media, and whether anything needed calibration.

⁠On a phone

The interface works on one, and POST /api/v1/share accepts a file from the iOS share sheet or an Android HTTP Shortcut and hands it to the print form.

⁠Development

python3 -m venv venv && source venv/bin/activate
pip install -r requirements-dev.txt
python src/app.py

Python 3.11 is required. The test suite needs a TrueType font installed (fonts-dejavu); without one, about a third of it skips.

pytest

src/api/openapi.yaml is the source of truth for routing. An endpoint changes there and in its controller, or it does not change.

⁠AI assistance

Yes, this project is built with AI assistance. It belongs to the toolchain like anything else here, and what comes out of it is reviewed and tested by a human before it lands. Keeping a project this size moving, mostly alone and in spare time, would not otherwise be realistic.

⁠Contributing

Contributions are welcome. Open an issue or send a pull request. Reports from printers and media that are not in the table above are useful too.

⁠Acknowledgments

• DL6ER for support for additional printer models and label types, and for USB printing
• MSanteler⁠ for finding and diagnosing the hardcoded label width, which meant every roll narrower than 62 mm printed at the wrong scale

⁠Changelog

changelog.md⁠.

⁠Licence

CC BY-NC-SA 4.0. See LICENSE⁠.