Thu, 24 Sep 2009 22:29:12 +0100
remove accidentally-included debug code (oops!)
1 libptouch: Linux printer driver library for P-Touch label printers
2 (C) 2009 Philip Pemberton <philpem@philpem.me.uk>.
6 Table of Contents
7 =================
8 1. What is libptouch?
9 2. Supported printers
10 3. Building and Installing libptouch
11 T. TODO, aka Things That Don't Work Yet.
12 R. References
15 1. What is libptouch?
16 =====================
17 libptouch is a library that allows a user-mode application to print labels
18 using a Brother P-touch series label printer. The goal of the libptouch
19 project is to create a driver that will allow any Linux application to
20 print to a P-touch printer, using a common raster image as a source.
22 Brother only release official Linux drivers for a small number of P-touch
23 printers, and these all rely on the CUPS printing system to function (not to
24 mention the fact that the print filter is completely closed-source). On top
25 of the added complexity of having to feed data through CUPS or LPR, the print
26 quality was actually pretty poor -- the fonts were covered in jagged edges,
27 and printed barcodes looked like they'd been fed through a blender (needless
28 to say my PSC 5281 scanner wouldn't read them).
30 As a result of this, I started working on a library that could take a number
31 of Libgd images, and feed them to the P-touch in sequence. On top of that, I
32 wanted to be able to set printing parameters (that is, turn the auto-cutter
33 and mirroring options on and off) without having to butcher command lines
34 and drop to a shell. Finally, I wanted to be able to run my applications as a
35 (relatively) unprivileged user -- the printing apps should not need to be
36 'setuid root'.
38 So I set to work finding out all I could about the P-touch protocol. It turns
39 out that the standard mode for my PT-2450DX printer was the so-called "PT-CBP"
40 mode, and that documentation for this printing protocol had been released for
41 another printer in the P-touch series, the PT-9500PC[1]. Using the protocol
42 details in the PT-9500PC documentation, and after many long nights of coding,
43 lots of cups of tea and much wasted label tape, I created a library that would
44 eventually be released as libptouch.
47 2. Supported printers
48 =====================
50 NOTE: If you don't see your printer on this list, ask me about adding it.
52 +--------------+--------------------------------------------------------------+
53 | Printer | Features |
54 | Model +----+----+----------------------------------------------------+
55 | Number | S | AC | HC | PHW | DPI | MTH | MPH | |
56 +--------------+----+----+----+-----+-----+------+------+---------------------+
57 | PT-2450DX | Y | Y | | 128 | 180 | 24mm | 18mm | |
58 +--------------+----+----+----+-----+-----+-----------------------------------+
60 S = Supported/Tested
61 Y = Fully working
62 P = Partially working
63 ? = Not tested
64 AC = Auto Cutter
65 HC = Half Cut
66 MI = Mirror
67 PHW = Printhead width (pixels)
68 DPI = Dots per inch
69 MTH = Max label tape height (mm)
70 MPH = Max printing height (mm)
72 "Y" = Yes
73 " " = No
76 3. Building and Installing libptouch
77 ====================================
78 To build libptouch, you will need:
79 GNU gcc version 3.1 or later (libptouch is tested with gcc 4.3.3)
80 GNU make version 3.80 or later (libptouch is tested with make 3.81)
81 libgd version 2.0 or later (libptouch is tested with libgd 2.0.36)
83 To build the documentation, you will also need:
84 doxygen version 1.5 or later (libptouch is tested with doxygen 1.5.8)
86 Briefly, this means any common Linux distribution (Debian or RedHat based)
87 released in 2006 or later should successfully build libptouch. As for other
88 Unices, or older versions of Linux.... you're on your own.
90 On Ubuntu or Debian, the following command will install all the packages
91 necessary to build libptouch:
92 $ sudo apt-get install build-essential libgd2-xpm-dev
94 Once you have installed the necessary tools and libraries, you can compile
95 libptouch by using the following command:
96 $ tar -zxf libptouch-$VERSION.tgz
97 $ cd libptouch-$VERSION
98 $ make
100 This will build the libptouch library and documentation from the source code.
102 To install libptouch into /usr/local, type:
103 $ make install
105 To install libptouch into another directory, say /opt/libptouch, type:
106 $ make install PREFIX=/opt/libptouch
109 4. Using libptouch
110 ==================
111 [... TODO ...]
114 5. Using libptouch-based Applications Without Superuser Privileges
115 ==================================================================
116 To use a libptouch-based application without superuser (root) privileges, you
117 must do one of two things:
119 1. Set the application's group ID to the user that normally owns printers
120 (or serial ports) on your system, then chmod the application to "g+S"
121 (turn the Set Group ID bit on). This will only work if all your printers
122 use the same interface type, e.g. all serial or all USB.
124 2. Add the user who will be running the application to the 'lp' or 'dialout'
125 group (for USB or serial printers respectively). Note that a user can be
126 a member of more than one group -- see your system documentation for more
127 information.
130 T. TODO, aka Things That Don't Work Yet.
131 ========================================
132 * Printers with printheads that don't have 128 dots will not work. This
133 basically means you can't use any printer whose maximum label tape width
134 is less than 24mm.
136 * I'd like to implement graphics inversion. Basically, where there is white,
137 the printer will print black. This could be useful for printing
138 white-on-black labels when you're out of white-on-black tape, or vice versa
139 :)
141 * There is no support for serial port printers. At all.
143 * The PT-PC is not, and will likely never be supported, as it uses a
144 different printing protocol and can only print bit image graphics on the
145 central 3.5mm (!) of the label tape.
147 * The QL-series label printers aren't supported either. I'd love to add
148 support for them, but I don't have a QL-series printer to play with. The
149 same applies to the rest of the P-touch (PT-series) printers that aren't
150 listed as "Supported" in the list above.
152 * Data compression. The later PT-series printers support "Packbits"
153 compression of each print line. At the moment, this isn't implemented.
154 Instead, a "COPY N BYTES" compression control byte is sent, followed by
155 a line of print data. Rinse, repeat.
157 * No option to set the feed amount. I'm not even 100% sure if this works
158 on most PT-series printers, but it might be worth implementing. See
159 <http://www.undocprint.org/formats/page_description_languages/brother_p-touch>.
162 R. References
163 =============
164 1. Brother Industries, Ltd. "PT-9500PC Command Reference, CBP-RASTER Mode
165 (PTCBP Mode) Volume" August 29, 2003, version 1.0.
166 Available online: http://etc.nkadesign.com/Printers/QL550LabelPrinter