Philipp Klaus
159 lines
7.3 KiB
Markdown
159 lines
7.3 KiB
Markdown
## brother\_ql
|
|
|
|
A Python package to control Brother QL label printers.
|
|
It implements the raster language of those printers and allows you to send instruction files to your printer.
|
|
In more details, the following is possible with this package:
|
|
|
|
* Create raster language files for the Brother label printers.
|
|
They can be created from image files or programmatically in your own Python script.
|
|
* Print raster instruction files with your Brother label printer via different backends:
|
|
* pyusb (works cross-platform)
|
|
* network (works cross-platform for WiFi/Ethernet-enabled printers)
|
|
* linux\_kernel (works on Linux only; uses the /dev/usb/lp0 device handles)
|
|
|
|
The following printers are claimed to be supported (✓ means verified by the author or by contributors):
|
|
|
|
* QL-500 (✓), QL-550, QL-560, QL-570 (✓), QL-580N, QL-650TD, QL-700 (✓), QL-710W (✓), QL-720NW (✓), QL-1050, and QL-1060N.
|
|
|
|
## Why
|
|
|
|
The special feature of this package is that no printer driver is required for it to work.
|
|
This software bypasses the whole printing system including printer drivers and directly
|
|
talks to your label printer instead. This means that even though Brother doesn't offer
|
|
a driver for the Raspberry Pi (running Linux on ARM) you can print nicely using this software.
|
|
And even if there are drivers for your operating system, many programs have difficulties to set
|
|
the page sizes and margins for the labels correctly. If you want to print with high precision
|
|
(which is important for barcodes for example), you rather want to have control about every
|
|
single pixel to be printed. This is where brother\_ql comes into the game.
|
|
|
|
## Installation
|
|
|
|
brother\_ql is available from PyPI with pip:
|
|
|
|
pip install brother_ql
|
|
# or to upgrade to a newer release:
|
|
pip install --upgrade brother_ql
|
|
|
|
Alternatively, you can install the latest development version from Github using:
|
|
|
|
pip install --upgrade https://github.com/pklaus/brother_ql/archive/master.zip
|
|
|
|
This package was mainly created for use with Python 3. The essential functionality, however, will also work with Python 2: the creation of label files.
|
|
|
|
## Usage
|
|
|
|
The main user interface of this package are its command line tools.
|
|
You can also use its functionality from your own Python code (yet, there is no dedicated API documentation).
|
|
The following sections show how to use the most important CLI tools.
|
|
|
|
### Create
|
|
|
|
The command line tool `brother_ql_create` is possibly the most important piece of software in this package.
|
|
It allows you to create a new instruction file in the label printers' raster language:
|
|
|
|
brother_ql_create --model QL-500 ./720x300_monochrome.png > 720x300_monochrome.bin
|
|
|
|
If you want to find out about its options, just call the tool with `--help`:
|
|
|
|
brother_ql_create --help
|
|
|
|
giving:
|
|
|
|
usage: brother_ql_create [-h] [--model MODEL] [--label-size LABEL_SIZE]
|
|
[--rotate {0,90,180,270}] [--threshold THRESHOLD]
|
|
[--no-cut] [--loglevel LOGLEVEL]
|
|
image [outfile]
|
|
|
|
positional arguments:
|
|
image The image file to create a label from.
|
|
outfile The file to write the instructions to. Defaults to
|
|
stdout.
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--model MODEL, -m MODEL
|
|
The printer model to use. Check available ones with
|
|
`brother_ql_info list-models`.
|
|
--label-size LABEL_SIZE, -s LABEL_SIZE
|
|
The label size (and kind) to use. Check available ones
|
|
with `brother_ql_info list-label-sizes`.
|
|
--rotate {0,90,180,270}, -r {0,90,180,270}
|
|
Rotate the image (counterclock-wise) by this amount of
|
|
degrees.
|
|
--threshold THRESHOLD, -t THRESHOLD
|
|
The threshold value (in percent) to discriminate
|
|
between black and white pixels.
|
|
--no-cut Don't cut the tape after printing the label.
|
|
--loglevel LOGLEVEL Set to DEBUG for verbose debugging output to stderr.
|
|
|
|
The image argument should be a PNG/GIF/JPEG image file.
|
|
Here is the output of `brother_ql_info list-label-sizes` listing the available options for `--label-size`:
|
|
|
|
Supported label sizes:
|
|
Name Printable px Description
|
|
12 106 (12 mm endless)
|
|
29 306 (29 mm endless)
|
|
38 413 (38 mm endless)
|
|
50 554 (50 mm endless)
|
|
54 590 (54 mm endless)
|
|
62 696 (62 mm endless)
|
|
102 1164 (102 mm endless)
|
|
17x54 165 x 566 (17 x 54 mm^2)
|
|
17x87 165 x 956 (17 x 87 mm^2)
|
|
23x23 202 x 202 (23 x 23 mm^2)
|
|
29x42 306 x 425 (29 x 42 mm^2)
|
|
29x90 306 x 991 (29 x 90 mm^2)
|
|
39x90 413 x 991 (38 x 90 mm^2)
|
|
39x48 425 x 495 (39 x 48 mm^2)
|
|
52x29 578 x 271 (52 x 29 mm^2)
|
|
62x29 696 x 271 (62 x 29 mm^2)
|
|
62x100 696 x 1109 (62 x 100 mm^2)
|
|
102x51 1164 x 526 (102 x 51 mm^2)
|
|
102x152 1164 x 1660 (102 x 152 mm^2)
|
|
d12 94 x 94 (12 mm diameter, round)
|
|
d24 236 x 236 (24 mm diameter, round)
|
|
d58 618 x 618 (58 mm diameter, round)
|
|
|
|
**Pro Tip™**:
|
|
For the best results, use image files with the matching pixel dimensions. Die-cut labels have to be in the exact pixel dimensions stated above. For endless label rolls, you can provide image files with a pixel width as stated above. If you provide a file with different dimensions when creating an endless label file, it will be scaled to fit the width.
|
|
|
|
Some notes:
|
|
|
|
Currently, the `brother_ql_create` tool doesn't support the 600x300 dpi mode supported by some printers.
|
|
The output will always use the 300dpix300dpi mode with the *high quality preference* set.
|
|
|
|
### Print
|
|
|
|
Once you have a Brother QL instruction file, you can send it to the printer like this:
|
|
|
|
cat my_label.bin > /dev/usb/lp1
|
|
|
|
Be sure to have permission to write to the device (usually adding yourself to the *lp* group is sufficient.
|
|
|
|
Or via network (if you have a LAN/WLAN enabled Brother QL):
|
|
|
|
nc 192.168.0.23 9100 < my_label.bin
|
|
|
|
You can also use the tool `brother_ql_print` (Py3 only) to send the instructions to your printer:
|
|
|
|
brother_ql_print 720x151_monochrome.bin /dev/usb/lp0
|
|
# or
|
|
brother_ql_print --backend network 720x151_monochrome.bin tcp://192.168.0.23:9100
|
|
# or (requires PyUSB: `pip install pyusb`)
|
|
brother_ql_print 720x151_monochrome.bin usb://0x04f9:0x2015
|
|
|
|
If your printer has problems printing the instructions file, it may blink its LED (green or red) depending on the model. This can have many reasons, eg.:
|
|
|
|
* The selected label doesn't match.
|
|
* End of paper.
|
|
* Unsupported opcode (wrong `--model` when using `brother_ql_create`?)
|
|
|
|
## Debugging
|
|
|
|
More info on how to debug difficult situations is to be found in the [DEBUG doc](https://github.com/pklaus/brother_ql/DEBUG.md).
|
|
|
|
## Links
|
|
|
|
* The source code and issue tracker of this package is to be found on **Github**: [pklaus/brother_ql](https://github.com/pklaus/brother_ql).
|
|
* The package is also to be found on **PyPI**: [brother_ql](https://pypi.python.org/pypi/brother_ql).
|