Skip to content

Commit 1f0f384

Browse files
matmairmatmair
authored
Update fork to new structure (#16)
* add fork notice * add publishing action * Update setup.py * another action * add dependency and rename * update package name * Delete python-publish.yml * restore old readme * add new readme * switch to toml * remove unneeded depenencies
1 parent 56cf439 commit 1f0f384

File tree

5 files changed

+339
-257
lines changed

5 files changed

+339
-257
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Release to PyPi
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
env:
8+
python_version: 3.8
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v2
16+
- name: Setup Python ${{ env.python_version }}
17+
uses: actions/setup-python@v2
18+
with:
19+
python-version: ${{ env.python_version }}
20+
- name: Install Python build dependencies
21+
run: |
22+
pip install setuptools twine build
23+
- name: Build binary
24+
run: |
25+
python3 -m build
26+
- name: Publish tp PyPi
27+
run: python3 -m twine upload dist/*
28+
env:
29+
TWINE_USERNAME: __token__
30+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
31+
TWINE_REPOSITORY: pypi

‎OLD_README.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
## brother\_ql
2+
3+
A Python package to control Brother QL label printers.
4+
It implements the raster language of those printers and allows you to send instruction files to your printer.
5+
In more details, the following is possible with this package:
6+
7+
* Create raster language files for the Brother label printers.
8+
They can be created from image files or programmatically in your own Python script.
9+
* Print raster instruction files with your Brother label printer via different backends:
10+
* pyusb (works cross-platform)
11+
* network (works cross-platform for WiFi/Ethernet-enabled printers)
12+
* linux\_kernel (works on Linux only; uses the /dev/usb/lp0 device handles)
13+
14+
The following printers are claimed to be supported (✓ means verified by the author or by contributors):
15+
16+
* QL-500 (✓), QL-550 (✓), QL-560 (✓), QL-570 (✓), QL-580N, QL-650TD, QL-700 (✓), QL-710W (✓),
17+
QL-720NW (✓), QL-800 (✓), QL-810W (✓), QL-820NWB (✓), QL-1050 (✓), and QL-1060N (✓).
18+
19+
The new QL-800 series can print labels with two colors (black and red) on DK-22251 labels.
20+
21+
Note: If your printer has an 'Editor Lite' mode, you need to disable it if you want to print via USB.
22+
Make sure that the corresponding LED is not lit by holding the button down until it turns off.
23+
24+
If you're interested in printing labels using a web interface, check out [brother\_ql\_web][],
25+
which builds upon this package.
26+
27+
## Why
28+
29+
The special feature of this package is that no printer driver is required for it to work.
30+
This software bypasses the whole printing system including printer drivers and directly
31+
talks to your label printer instead.
32+
This means that even though Brother doesn't offer a driver for the Raspberry Pi (running
33+
Linux on ARM) you can print nicely using this software.
34+
And even if there are drivers for your operating system, many programs have difficulties to set
35+
the page sizes and margins for the labels correctly.
36+
If you want to print with high precision (which is important for barcodes for example),
37+
you rather want to have control about every single pixel to be printed.
38+
This is where brother\_ql comes into the game.
39+
40+
## Installation
41+
42+
brother\_ql is [available on the Python Package Index][PyPI] to be installed with pip:
43+
44+
pip install --upgrade brother_ql
45+
46+
The upgrade flag makes sure, you get the latest version of brother\_ql but also
47+
of its dependencies.
48+
49+
Alternatively, you can install the latest version from Github using:
50+
51+
pip install --upgrade https://github.com/pklaus/brother_ql/archive/master.zip
52+
53+
This package was mainly created for use with Python 3.
54+
The essential functionality, however, will also work with Python 2: the creation of label files.
55+
56+
In order to run the `brother_ql` command line utility, the directory it resides in
57+
needs to be in the PATH envirnoment variable.
58+
On some systems, the `pip install` command defaults to the `--user` flag resulting in the utility
59+
being put in the `~/.local/bin` directory.
60+
On those systems, extending the path variable via `export PATH="${PATH}:~/.local/bin"` is needed.
61+
62+
## Usage
63+
64+
The main user interface of this package is the command line tool `brother_ql`.
65+
66+
Usage: brother_ql [OPTIONS] COMMAND [ARGS]...
67+
68+
Command line interface for the brother_ql Python package.
69+
70+
Options:
71+
-b, --backend [pyusb|network|linux_kernel]
72+
-m, --model [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]
73+
-p, --printer PRINTER_IDENTIFIER
74+
The identifier for the printer. This could
75+
be a string like tcp://192.168.1.21:9100 for
76+
a networked printer or
77+
usb://0x04f9:0x2015/000M6Z401370 for a
78+
printer connected via USB.
79+
--debug
80+
--version Show the version and exit.
81+
--help Show this message and exit.
82+
83+
Commands:
84+
analyze interpret a binary file containing raster...
85+
discover find connected label printers
86+
info list available labels, models etc.
87+
print Print a label
88+
send send an instruction file to the printer
89+
90+
There are some global options available such as --model and --printer.
91+
They can also be provided by environment variables (`BROTHER_QL_MODEL` and `BROTHER_QL_PRINTER`).
92+
93+
The global options are followed by a command such as `info` or `print`.
94+
The most important command is the `print` command and here is its CLI signature:
95+
96+
Usage: brother_ql print [OPTIONS] IMAGE [IMAGE] ...
97+
98+
Print a label of the provided IMAGE.
99+
100+
Options:
101+
-l, --label [12|29|38|50|54|62|102|17x54|17x87|23x23|29x42|29x90|39x90|39x48|52x29|62x29|62x100|102x51|102x152|d12|d24|d58]
102+
The label (size, type - die-cut or endless).
103+
Run `brother_ql info labels` for a full
104+
list including ideal pixel dimensions.
105+
-r, --rotate [auto|0|90|180|270]
106+
Rotate the image (counterclock-wise) by this
107+
amount of degrees.
108+
-t, --threshold FLOAT The threshold value (in percent) to
109+
discriminate between black and white pixels.
110+
-d, --dither Enable dithering when converting the image
111+
to b/w. If set, --threshold is meaningless.
112+
-c, --compress Enable compression (if available with the
113+
model). Label creation can take slightly
114+
longer but the resulting instruction size is
115+
normally considerably smaller.
116+
--red Create a label to be printed on
117+
black/red/white tape (only with QL-8xx
118+
series on DK-22251 labels). You must use
119+
this option when printing on black/red tape,
120+
even when not printing red.
121+
--600dpi Print with 600x300 dpi available on some
122+
models. Provide your image as 600x600 dpi;
123+
perpendicular to the feeding the image will
124+
be resized to 300dpi.
125+
--lq Print with low quality (faster). Default is
126+
high quality.
127+
--no-cut Don't cut the tape after printing the label.
128+
--help Show this message and exit.
129+
130+
So, printing an image file onto 62mm endless tape on a QL-710W label printer can be as easy as:
131+
132+
export BROTHER_QL_PRINTER=tcp://192.168.1.21
133+
export BROTHER_QL_MODEL=QL-710W
134+
brother_ql print -l 62 my_image.png
135+
136+
The available label names can be listed with `brother_ql info labels`:
137+
138+
Name Printable px Description
139+
12 106 12mm endless
140+
29 306 29mm endless
141+
38 413 38mm endless
142+
50 554 50mm endless
143+
54 590 54mm endless
144+
62 696 62mm endless
145+
102 1164 102mm endless
146+
17x54 165 x 566 17mm x 54mm die-cut
147+
17x87 165 x 956 17mm x 87mm die-cut
148+
23x23 202 x 202 23mm x 23mm die-cut
149+
29x42 306 x 425 29mm x 42mm die-cut
150+
29x90 306 x 991 29mm x 90mm die-cut
151+
39x90 413 x 991 38mm x 90mm die-cut
152+
39x48 425 x 495 39mm x 48mm die-cut
153+
52x29 578 x 271 52mm x 29mm die-cut
154+
62x29 696 x 271 62mm x 29mm die-cut
155+
62x100 696 x 1109 62mm x 100mm die-cut
156+
102x51 1164 x 526 102mm x 51mm die-cut
157+
102x152 1164 x 1660 102mm x 153mm die-cut
158+
d12 94 x 94 12mm round die-cut
159+
d24 236 x 236 24mm round die-cut
160+
d58 618 x 618 58mm round die-cut
161+
162+
**Pro Tip™**:
163+
For the best results, use image files with the matching pixel dimensions.
164+
Die-cut labels have to be in the exact pixel dimensions stated above.
165+
For endless label rolls, you can provide image files with a pixel width as stated above.
166+
If you provide a file with different dimensions when creating an endless label file,
167+
it will be scaled to fit the width.
168+
169+
### Backends
170+
171+
There are multiple backends for connecting to the printer available (✔: supported, ✘: not supported):
172+
173+
Backend | Kind | Linux | Mac OS | Windows
174+
-------|-------|---------|---------|--------
175+
network (1) | TCP | ✔ | ✔ | ✔
176+
linux\_kernel | USB | ✔ (2) | ✘ | ✘
177+
pyusb (3) | USB | ✔ (3.1) | ✔ (3.2) | ✔ (3.3)
178+
179+
Notes:
180+
181+
1. The network backend doesn't support reading back the printer state, currently.
182+
Failure such as *wrong label type* or *end of label roll reached* won't be detected by this software.
183+
2. The label printer should show up automatically as `/dev/usb/lp0` when connected.
184+
Please check the ownership (user, group) of this file to be able to print as a regular user.
185+
Consider setting up a udev .rules file.
186+
3. PyUSB is a Python wrapper allowing to implement USB communication in userspace.
187+
1. On Linux: install libusb1 as offered by your distribution: `sudo apt-get install libusb-1.0-0` (Ubuntu, Debian), `sudo zyppe in libusb-1_0-0` (OpenSUSE), `sudo pacman -S libusb` (Arch).
188+
2. On Mac OS: Install [Homebrew](https://brew.sh/) and then install libusb1 using: `brew install libusb`.
189+
3. On Windows: download [libusb-win32-devel-filter-1.2.6.0.exe](https://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/1.2.6.0/)
190+
from sourceforge and install it.
191+
After installing, you have to use the "Filter Wizard" to setup a "device filter" for the label printer.
192+
193+
### Legacy command line tools
194+
195+
For a long time, this project provided multiple command line tools, such as
196+
`brother_ql_create`, `brother_ql_print`, `brother_ql_analyze`, and more.
197+
The overview of those tools can still be found in the [LEGACY][] documentation.
198+
The use of these tools is now considered deprecated and they will be
199+
removed in a future release.
200+
201+
## Author
202+
203+
This software package was written by Philipp Klaus based on Brother's documentation
204+
of its raster language and based on additinal reverse engineering efforts.
205+
206+
* Philipp Klaus
207+
<[email protected]>
208+
209+
Many more have contributed by raising issues, helping to solve them,
210+
improving the code and helping out financially.
211+
212+
## Contributing
213+
214+
There are many ways to support the development of brother\_ql:
215+
216+
* **File an issue** on Github, if you encounter problems, have a proposal, etc.
217+
* **Send an email with ideas** to the author.
218+
* **Submit a pull request** on Github if you improved the code and know how to use git.
219+
* **Finance a label printer** from the [author's wishlist][] to allow him to extend the device coverage and testing.
220+
* **Donate** an arbitrary amount of money for the development of brother\_ql [via Paypal][donation].
221+
222+
Thanks to everyone helping to improve brother\_ql.
223+
224+
## Links
225+
226+
* The source code and issue tracker of this package is to be found on **Github**: [pklaus/brother\_ql][].
227+
* The package is also to be found on the Python Package Index **PyPI**: [brother\_ql][PyPI].
228+
* A curated list of related and unrelated software can be found [in this document][related-unrelated].
229+
230+
[author's wishlist]: https://www.amazon.de/registry/wishlist/3GSVLPF08AFIR
231+
[donation]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&[email protected]&lc=US&item_name=Donation+to+brother_ql+Development&no_note=0&cn=&currency_code=USD&bn=PP-DonationsBF:btn_donateCC_LG.gif:NonHosted
232+
[brother\_ql\_web]: https://github.com/pklaus/brother_ql_web
233+
[LEGACY]: https://github.com/pklaus/brother_ql/blob/master/LEGACY.md
234+
[pklaus/brother\_ql]: https://github.com/pklaus/brother_ql
235+
[PyPI]: https://pypi.python.org/pypi/brother_ql
236+
[related-unrelated]: https://gist.github.com/pklaus/aeb55e18d36690df6a84a3eab49e9fd7

0 commit comments

Comments
 (0)