Thermal Printer driver for CUPS, Linux, and Raspberry Pi: zj-58

Update:slightly cleaned up for Raspbian Stretch, 2017-11.

This might be my last post on mini-printers, as I’ve found a driver that just works with CUPS on Raspberry Pi. It also works on Ubuntu on my laptop, and should work (though untried) on Mac OS. You’ll have to build it from source, but it’s not too hard.

The hard part is working out if your thermal printer will work or not. There are many out there, and they’re all slightly different. If they support the ESC/POS bitmap command GS v 0 on 58 mm wide paper, they should work. The ones I’ve tested are:

Sparkfun thermal printer — which now appears to be identical to the Adafruit unit, and is referred to as the “A1 (or A2) micro panel printer” in the documentation.

Known not to work:

BTHT-V6 printer — which uses a completely different command set. (Roughly that of an Epson FX-80 for image commands, if you care.)

If you have a manual for your printer, check it to see if it prints bitmaps by sending a three byte header of 29 118 48 (or 1D 76 30 in hexadecimal). If you’re not sure, try it with a small test image, and be ready by the power switch …

You’ll still have to set up the printer to accept jobs, but now you have the driver installed.

Setting up the printer

This bit is much more graphical. Open up the printer settings window (Preferences → Print Settings):

Select the Add icon, and the New Printer window opens:

The POS5890U shows up as “Unknown” on my USB port, as Linux doesn’t know the name of this device from its USB ID.

Update (for the slightly desperate): In the land of “Things have changed!”, my Catex printer isn’t showing up at all. I had to resort to this in the Enter URI option:

(hey, this image doesn’t quite match the flow. Look only at the the “Device URI” bit please)

parallel:/dev/usb/lp0 seems to work. Another option might be looking at the output of

sudo /usr/lib/cups/backend/usb

which suggests that usb://Unknown/Printer might work too. (All of this might need to have been preceded by

sudo usermod -a -G lp pi

and a logout or reboot; I did say this was for the slightly desperate …)

If the above doesn’t apply, your printer might have an known ID, or show up as a serial port. Select the right one, and click Forward:

Here, I’m really pleased that the driver is for a Zijiang unit, as it’s conveniently at the end of the list. Click Forward …

No options here, so again, Forward …

I changed the name from the default ZJ-58 to the more unixly zj58. You don’t have to, but either way, Apply the changes.

And there it is, registered as a printer!

Printer Options

Most printers expect paper wider than 58 mm, but mini-printers can’t do that. To tell the system about paper sizes, right click on the printer’s icon, and change the printer settings:

A test page might print properly now, but you should probably go into Printer Options first:

You do want to set the media size to at least 58 × 210 mm. This is just the longest strip it will print in one ‘page’; if your print is shorter, it won’t waste extra paper. You can choose longer prints, but not wider. The default assume your local standard paper size which —be it A4, Letter, or whatever — will not be what you want here. Hit OK.

Printing something

You could print the self test page, but it’s long and boring. If you’re fairly sure your printer will be supported, try this scaled PDF version of the Raspberry Pi Logo: raspberry-pi-logo. Printed and scanned, it came out like this:

Not the best rendition, but not bad for a $30 receipt printer. My test image came out like this (iffy scan, sorry):

I haven’t covered the intricacies of setting up serial port connections here; maybe another time. Also, there’s a short delay (maybe 10–20 s) between selecting Print and the printer coming to life. CUPS is pretty complex, and is doing things in the background while you wait.

(Seeing as I use their logo prominently up there, I should totes acknowledge that “Raspberry Pi is a trademark of the Raspberry Pi Foundation”. Also, I couldn’t have done all this without the support of Reed Zhao. Though Reed has moved on to bigger things and doesn’t sell printers any more, his help — not to mention the generous loan of a couple of printers — was very welcome.)

I am having trouble printing images with my Nano Thermal Printer from Adadfruit and wanted to ask if you could help.

I have followed a tutorial on making an instant camera using a Raspberry Pi, can’t seem to get it to work and I’m thinking it may have something to do with the CUPS libraries or ZJ-58 Github folders you discussed above.

I am running a Raspberry Pi Zero W with Raspbian Lite.
When I initiate a print, using a lp command, the output I get is “request id is ZJ-58-## (1 files(s))” (where ## is the number of times I’ve attempted to print) and then nothing happens.

I have been working on this project for several months now and can’t seem to figure it out.
Please let me know if you could be of any help.

I wonder why the CUPS folks have not released a generic “EPSON ESC/POS” printer driver where the above parameters can be tweaked and entered manually.

The driver you linked was installed but didn’t work. A sample print gave gibberish. A second text-only printing (by clicking the CUPS “print self-test page” read “IF YOU CAN READ THIS YOU’RE USING THE WRONG DRIVER FOR YOUR PRINTER”.

A crude bug-finding code it seems…

Any ideas before I head over to the CUPS maling list and pull my hair?
FC

The zj58 driver is the nearest thing to a generic CUPS ESC-POS driver, Fernando. Steve Hawley’s driver might work, but it’s designed for an 80 mm printer so the PPD will need extensive rework for a narrower printer: https://github.com/plinth666/epsonsimplecups

Hi Jan — the 10–20 second delay is an unavoidable side-effect of using CUPS. In order to support almost every bitmap printer ever, CUPS does a lot in the background:

reads the input file

guesses what format it is in

converts that internally to PDF (I think)

loads the driver for the particular printer

runs the internally-generated PDF through the driver

spools the result to the printer

cleans up

All of this is almost instantaneous on a modern laptop or desktop, but takes a few seconds on a Raspberry Pi.

If you want quicker output and can accept a limited subset of input files, then feeding small bitmaps or plain text to the printer’s raw spool input is very fast. But this isn’t reliable in all cases, so I put up with CUPS’s delay.

I’m using the TTL JP-701 printer (serial:/dev/serial0?baud=9600), and while following your guide, I only get as far as the last screen of the New Printer dialog. When I hit “Apply”, the Pi only thinks for a few seconds (hour glass cursor), then nothing. The dialog doesn’t close, the printer doesn’t get added, nothing happens. Any ideas?

In case it’s relevant, I started from a headless Raspbian Lite, then added raspberrypi-ui-mods etc. in order to get a GUI to configure the printer. The rest works just fine.

I could work my POS 80 printer with this driver. The weird thing is I can print but it is cutting from right side and there is really enough place on the paper. I can not see the right side of the my PDF. I selected already 80mm x 210 mm paper size but it is acting like 58 mm printer?
Is there any way to fix this?

Hi Scruss
I succesfully added the printer (Zijiang ZJ-58 -> serial:/dev/ttyAMA0?baud=19200).
It prints fine,but instead “dot” or “spot” , I obtain small “+”. It’s frustrating because the picture(jpg or png) is visible but it will build with this characters and not with dots.

I tested with the official Adaifruit installation and with yours.
Voltage 8,4V- 2,3A