Raster to QL-570
================


What is this?
-------------

A CUPS driver for printing labels on the QL-570. This can also be used to
directly drive the printer (see example below).


Motivation
----------

I had some issues with the driver from the vendor. I figured that I need to
have some clue about what is going on in order to do something about that. I
ended up writing a driver, oops.


What is the relation to `ptouch-driver`?
----------------------------------------

As far as I understand, `ptouch-driver` is based on the reverse engineered
protocol. The `rastertoql570` is based on the protocol specification (much)
later released by the vendor. The `ptouch-driver` is far more complete
with regards to the surroundings, methinks.


Documentation
-------------

The files generated by Doxygen can be viewed here:

http://static.xenoworld.de/docs/rastertoql570


What works?
-----------

### Media types

I use the printer mainly with 62mm continuous tape.

| media type | works |
|------------|-------|
| 62mm       | ✔     |
| 29x90.3mm  | ✗  ❶  |

❶ Tried this only briefly, the output was not as expected. I will investigate
further, but I suppose that the problems are on the user side of things.


### Features

These work in principle, some of these are not yet configurable.

* Automatic cutting after each label
* Automatic cutting after every n labels
* 300dpi and 600dpi printing


How do I use this?
------------------

Everything is a bit crude right now. First, you need GCC and the CUPS
development libraries (the package might be called `cups-devel` or something
similar). The driver needs the libraries `cups` and `cupsimage`. Run `make`
in the `src/` directory.

After building the driver, you end up with a file `rastertoql570` (in the
project's root directory), you have to put this file in the CUPS filters
directory, (e.g. `/usr/lib/cups/filter/`).  After that you can just click
through the CUPS printer installation with your favourite tool or through the
interface at http://localhost:631/. When you reach the step to provide a
PPD-file, use the `ppd-file.ppd` in the project's root directory.

It should now be possible to print labels. Be aware that, regardless of the
tool, you should create a custom document with the dimensions you want. If you
use, for example, gLabels, create a 12.7mm by 62mm label and include some 1mm
margins. If you want to print smaller labels, try with a 6.35mm x 62mm label,
but *remember to set the resolution to 600DPI in that case*.


How do I use the provided files to directly drive the printer?
--------------------------------------------------------------

This assumes that, if you connect the printer to your computer via USB, some
magic configures it as a printer and provides you with a device such as
`/dev/usb/lp0`. On two of my machines that ‘just worked’™. Given the right
permissions you can simply open this file and write to it.


Printing a couple of black lines is as simple as this:

~~~~~~~~~~~~~{.c}
#include "ql570.h"

int main()
{
	FILE *device = fopen("/dev/usb/lp0", "wb");
	ql_status status = {0};
	ql_print_info print_info = { .raster_number[0] = 150 };
	uint8_t buffer[90];

	ql_init(false, device);
	ql_status_request(device);
	ql_status_read(&status, device);
	ql_page_start(&print_info, device);
	ql_set_extended_options(true, false, device);
	
	for (int i = 0; i < 150; i++) {
		memset(buffer, i % 5 == 0 ? 0xFF : 0x00, 90);
		buffer[0] = 0x00;
		buffer[1] = 0x00;
		ql_raster(90, buffer, device);
	}
	
	ql_raster_end(90, device);
	ql_page_end(true, device);
	fclose(device);
}
~~~~~~~~~~~~~

The fully commented example kann be found in `src/examples/minimal.c`.

If you need some quick and dirty way to print something meaningful on a label,
use GIMP to create a 720x150 pixel image and export it later as XBM. These are
simple C files, the structure is pretty self-explanatory.

TODO: Provide example for this, include how to mirror the images...


Stuff to be done
----------------

* Tell the vendor about unclear or wrong information in the specification.
* Test with other media types.
* Try to support other printers in the QL series.
* Maybe use CMake.
* Improve overview document.
* There are a couple of nanosleep-calls and the 100ms or so waiting time are
  completely arbitrary.
* Currently arguments to the program are ignored. Ideally a help should be
  printed, and some parameters should be used.
* Handle SIGTERM.
* Walk through TODOs in the code.
* Improve documentation with regards to optional features.
* Show some care for endianess.
* Improve the PPD-file, this hasn't received much love.