Wed, 05 Aug 2009 17:10:56 +0100
add README
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 Using 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 Using 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 higher (libptouch is tested with libgd 2.0.36)
83 Briefly, this means any common Linux distribution (Debian or RedHat based)
84 released in 2006 or later should successfully build libptouch. As for other
85 Unices, or older versions of Linux.... you're on your own.
87 On Ubuntu or Debian, the following command will install all the packages
88 necessary to build libptouch:
89 $ sudo apt-get install build-essential libgd2-xpm-dev
91 Once you have installed the necessary tools and libraries, you can compile
92 libptouch by using the following command:
93 $ tar -zxf libptouch-$VERSION.tgz
94 $ cd libptouch-$VERSION
95 $ make
97 This will build the libptouch library and documentation from the source code.
100 T. TODO, aka Things That Don't Work Yet.
101 ========================================
102 * Printers with printheads that don't have 128 dots will not work. This
103 basically means you can't use any printer whose maximum label tape width
104 is less than 24mm.
106 * I'd like to implement graphics inversion. Basically, where there is white,
107 the printer will print black. This could be useful for printing
108 white-on-black labels when you're out of white-on-black tape, or vice versa
109 :)
111 * There is no support for serial port printers. At all.
113 * The PT-PC is not, and will likely never be supported, as it uses a
114 different printing protocol and can only print bit image graphics on the
115 central 3.5mm (!) of the label tape.
117 * The QL-series label printers aren't supported either. I'd love to add
118 support for them, but I don't have a QL-series printer to play with. The
119 same applies to the rest of the P-touch (PT-series) printers that aren't
120 listed as "Supported" in the list above.
122 * Data compression. The later PT-series printers support "Packbits"
123 compression of each print line. At the moment, this isn't implemented.
124 Instead, a "COPY N BYTES" compression control byte is sent, followed by
125 a line of print data. Rinse, repeat.
127 * No option to set the feed amount. I'm not even 100% sure if this works
128 on most PT-series printers, but it might be worth implementing. See
129 <http://www.undocprint.org/formats/page_description_languages/brother_p-touch>.
132 R. References
133 =============
134 1. Brother Industries, Ltd. "PT-9500PC Command Reference, CBP-RASTER Mode
135 (PTCBP Mode) Volume" August 29, 2003, version 1.0.
136 Available online: http://etc.nkadesign.com/Printers/QL550LabelPrinter