Common routines to deal with QL label printers. More...

Macros
#define	BIT(x) (1 << (x))

#define	QL_NO_COMPRESSION 0x00

#define	QL_TIFF_COMPRESSION 0x02

#define	QL_BI_COLOR 0x01

#define	QL_CUT_AT_END 0x08

#define	QL_HIGH_RESOLUTION 0x40

#define	QL_AUTO_CUT 0x40

#define	QL_CUT_EACH_LABEL 0

#define	QL_WHAT_IS_BIT_0 0x01

#define	QL_MEDIA_ENTRY_VALID 0x02

#define	QL_WIDTH_ENTRY_VALID 0x04

#define	QL_LENGTH_ENTRY_VALID 0x08

#define	QL_RASTER_ENTRY_VALID 0x10

#define	QL_HIGH_PRINT_QUALITY 0x40

#define	QL_RECOVER_ENTRY_VALID 0x80

#define	QL_MEDIA_TYPE_CONTINUOUS 0xa

#define	QL_MEDIA_TYPE_DIE_CUT 0xb

#define	QL_QUALITY_PRINT 0x40

#define	QL_FAST_PRINT 0x00

Functions
void	transform_to_monochrome (size_t input_cnt, const signed short input[input_cnt], unsigned char *data)

static int	ql_page_print (struct qldriver *ql)

static int	ql_last_page_print (struct qldriver *ql)

static int	ql_compression_setup (struct qldriver *ql, unsigned mode)

int	ql_auto_powerdown (struct qldriver *ql, unsigned short time_out)

int	ql_auto_powerup (struct qldriver *ql, unsigned short mode)

int	ql_reset (struct qldriver *ql)

static int	ql_invalidate_and_initialize (struct qldriver *ql)

static int	ql_extended_mode_set (struct qldriver *ql, unsigned value)

static int	ql_cut_mode_set (struct qldriver *ql, unsigned mode)

static int	ql_cut_on_label_n (struct qldriver *ql, unsigned cut_on_page)

static int	ql_notification_disable (struct qldriver *ql)

static int	ql_dynamic_mode (struct qldriver *ql)

static int	ql_define_tape_margins (struct qldriver *ql, uint16_t margins)

static int	ql_print_information (struct qldriver *ql, int media_type, int media_width, int media_length, int raster, int start_page, int quality)

int	ql_job_header_generate (struct qldriver *ql)

int	ql_job_footer_generate (struct qldriver *ql)

int	ql_page_header_generate (struct qldriver *ql, int first_time)

Detailed Description

Common routines to deal with QL label printers.

Copyright: GNU General Public License 2.0 or later

Author: Jürgen Borleis

Macro Definition Documentation

◆ BIT

#define BIT ( x ) (1 << (x))

Just a helper to write more readable code

◆ QL_AUTO_CUT

#define QL_AUTO_CUT 0x40

Bit to setup the printer into "auto cut" mode. Used in the ql_cut_mode_set() function as its mode parameter

◆ QL_BI_COLOR

#define QL_BI_COLOR 0x01

Bit to setup the printer into bi-colour print mode. Used in the ql_extended_mode_set() function as its value parameter

Note: Can be or'ed with the QL_CUT_AT_END and QL_HIGH_RESOLUTION bits.

◆ QL_CUT_AT_END

#define QL_CUT_AT_END 0x08

Bit to setup the printer into "cut when job is finished" mode. Used in the ql_extended_mode_set() function as its value parameter

Note: It is still unclear what exactly this bit means in conjunction to the other cutting related bits. If someone has an idea, drop me a note.; Can be or'ed with the QL_BI_COLOR and QL_HIGH_RESOLUTION bits.

◆ QL_CUT_EACH_LABEL

#define QL_CUT_EACH_LABEL 0

Default value for the ql_cut_on_label_n() function to define "cut each single label" To be used as its cut_on_page parameter.

◆ QL_FAST_PRINT

#define QL_FAST_PRINT 0x00

Always use with bi-colour printing (according to the datasheet)

◆ QL_HIGH_PRINT_QUALITY

#define QL_HIGH_PRINT_QUALITY 0x40

◆ QL_HIGH_RESOLUTION

#define QL_HIGH_RESOLUTION 0x40

Bit to setup the printer into "high resolution" mode. E.g. 600 DPI in vertical direction. Used in the ql_extended_mode_set() function as its value parameter

Note: Can be or'ed with the QL_BI_COLOR and QL_CUT_AT_END bits.

◆ QL_LENGTH_ENTRY_VALID

#define QL_LENGTH_ENTRY_VALID 0x08

◆ QL_MEDIA_ENTRY_VALID

#define QL_MEDIA_ENTRY_VALID 0x02

◆ QL_MEDIA_TYPE_CONTINUOUS

#define QL_MEDIA_TYPE_CONTINUOUS 0xa

◆ QL_MEDIA_TYPE_DIE_CUT

#define QL_MEDIA_TYPE_DIE_CUT 0xb

◆ QL_NO_COMPRESSION

#define QL_NO_COMPRESSION 0x00

Value to signal the printer, the print data will be sent without any compression. Used in the ql_compression_setup() function as its mode parameter

◆ QL_QUALITY_PRINT

#define QL_QUALITY_PRINT 0x40

never use while bi-colour printing (according to the datasheet)

◆ QL_RASTER_ENTRY_VALID

#define QL_RASTER_ENTRY_VALID 0x10

◆ QL_RECOVER_ENTRY_VALID

#define QL_RECOVER_ENTRY_VALID 0x80

I found a hint. When set, it means: only print on labels of matching size

◆ QL_TIFF_COMPRESSION

#define QL_TIFF_COMPRESSION 0x02

Value to signal the printer, the print data will be sent in TIFF compression. Used in the ql_compression_setup() function as its mode parameter

Attention: Only for reference. Compression isn't supported, yet

◆ QL_WHAT_IS_BIT_0

#define QL_WHAT_IS_BIT_0 0x01

Unknown meaning in the #print_inform::valid member

◆ QL_WIDTH_ENTRY_VALID

#define QL_WIDTH_ENTRY_VALID 0x04

Function Documentation

◆ ql_auto_powerdown()

int ql_auto_powerdown	(	struct qldriver *	ql,
		unsigned short	time_out
	)

Set the printer's auto power down behaviour if it is idle

Parameters

[in]	ql	Full job description
[in]	time_out	Time out when idle to enter power down mode

time_out can be:

0x0000: disable auto power off
0x0001: auto power off after 10 minutes
0x0002: auto power off after 20 minutes
0x0003: auto power off after 30 minutes
0x0004: auto power off after 40 minutes
0x0005: auto power off after 50 minutes
0x0006: auto power off after 60 minutes

If the printer enters the power down mode, it disconnects itself from the USB and can be re-enabled manually only with its local power button. This is a really bad idea for remote printers.

Note: This command is reverse-engineered, it isn't listed in the programming manual; The big endian format for the subcommand's data (here time_val) is guessed only. All other printer commands use little endian for multibyte parameter. So, the command's data might have a different format/content than listed here

◆ ql_auto_powerup()

int ql_auto_powerup	(	struct qldriver *	ql,
		unsigned short	mode
	)

Set the printer's power up behaviour when connecting to external power

Parameters

[in]	ql	Full job description
[in]	mode	Power On mode

mode can be:

0x0000 Keep offline when connecting to external power
0x0001 Go online when connecting to external power

Note: This command is reverse-engineered, it isn't listed in the programming manual; The big endian format for the subcommand's data (here mode) is guessed only. All other commands use little endian for multibyte parameter. So, the command's data might have a different format/content than listed here

◆ ql_compression_setup()

static int ql_compression_setup	(	struct qldriver *	ql,
		unsigned	mode
	)

static

Setup the line data compression mode

Parameters

[in]	ql	Full job description
[in]	mode	Compression more, one of QL_NO_COMPRESSION or QL_TIFF_COMPRESSION

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

Note: Only a few printers can deal with compression, so QL_TIFF_COMPRESSION isn't supported, yet.; To be sent at the beginning of a page's raster and required at each page (according to the manual)

◆ ql_cut_mode_set()

static int ql_cut_mode_set	(	struct qldriver *	ql,
		unsigned	mode
	)

static

Setup "various mode"

Parameters

[in]	ql	Full job description
[in]	mode	Cutter mode, '0' or QL_AUTO_CUT

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

Note: Selection between auto and manual?; Same command for the QL500 but different content (TODO); To be sent at the beginning of a page and required at each page (according to the manual)

◆ ql_cut_on_label_n()

static int ql_cut_on_label_n	(	struct qldriver *	ql,
		unsigned	cut_on_page
	)

static

Setup the label count when to cut

Parameters

[in]	ql	Full job description
[in]	cut_on_page	Auto cut after this amount of pages (can be QL_CUT_EACH_LABEL for cut every label)

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

Attention: Makes sense only if auto-cut is enabled

Note: Nothing happens (at least with the cutter), if this command wasn't sent.; To be sent at the beginning of a page and required at each page (according to the manual)

◆ ql_define_tape_margins()

static int ql_define_tape_margins	(	struct qldriver *	ql,
		uint16_t	margins
	)

static

Setup the margins (top and bottom) to be used for this print

Parameters

[in]	ql	Full job description
[in]	margins	Top and bottom margins [dots] TODO maybe better in mm?

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

Precondition: According to the QL800 manual, the margins must be at least 3 mm (or 35 dots) and max. 127 mm (or 1500 dots).

Attention: Since the margin is defined in dots, it is resolution dependend (vertical!)

Note: From the manual: "since a margin amount cannot be specified with die-cut labels, this command is sent with a margin amount of 0."
(from section 2.2.3 Explanation of print data for the test page)

 Continuous tape:

            cut                                          cut
  -----------|--------------------------------------------|--------------
         |   |   |                                    |   |   |
   ----->|   |   |<------- printable area ----------->|   |   |<---------
         |   |   |                                    |   |   |
  -----------|--------------------------------------------|--------------
         |<->|<->| < margins                margins > |<->|<->|

 Die-cut labels (assumption, but was wrong!):

            cut                                           cut
  -----------|--------------------------------------------|-------------------
  -------+   |   +------------------------------------+   |   +---------------
         |   |   |                                    |   |   |
  ------>|   |   |<---------- printable area -------->|   |   |<--------------
         |   |   |                                    |   |   |
  -------+   |   +------------------------------------+   |   +---+-----------
  -----------|--------------------------------------------|-------------------

 Die-cut labels, margin handling (reality):

            cut                                           cut
  -----------|--------------------------------------------|-------------------
  -------+   |   +------------------------------------+   |   +---------------
         |   |   |  |                              |  |   |   |
  ------>|   |   |  |<------- printable area ----->|  |   |   |<--------------
         |   |   |  |                              |  |   |   |
  -------+   |   +------------------------------------+   |   +---+-----------
  -----------|--------------------------------------------|-------------------
             |<->|<>| < margins          margins > |<>|<->|
                                                        ^---- implicit margin added by the printer
                                                     ^------- implicit margin added by the printer
*

Attention: The top and bottom margins of 35 dots are implicit for die-cut labels. The printer doesn't print in these areas, even if data was sent for them.
It is even more worse: data sent for these areas (e.g. lines of data) will not be ignored. The printer increases the size of the label instead.
And the next cut is made inside the following label - instead of inbetween them.

Note: To be sent at the beginning of a page and required at each page (according to the manual)

◆ ql_dynamic_mode()

static int ql_dynamic_mode ( struct qldriver * ql )

static

Configure the printer to a sepcifc "dynamic mode"

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

For some QL models this has to be done at most once per run-time. The printer operates in this mode until it is turned off again. But read the note below!

Note: No rule without exception: according to its datasheet, the QL600 requires this command right after the reset command and requires it again after the ql_last_page_print() but with mode 'default' (eg. mode = 0xff); To be sent at the beginning of a page and required at each page (according to the manual). The real requirement is unclear, since the datasheet lists different requirements at different pages.

◆ ql_extended_mode_set()

static int ql_extended_mode_set	(	struct qldriver *	ql,
		unsigned	value
	)

static

Send expanded mode

Parameters

[in]	ql	Full job description
[in]	value	Ored list of of QL_BI_COLOR, QL_CUT_AT_END or QL_HIGH_RESOLUTION

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

QL_BI_COLOR Set printer into bi-colour mode (QL8xx with special DK roll only)
QL_CUT_AT_END Cut only at the end of the job (refer ql_last_page_print() for details)
QL_HIGH_RESOLUTION Switch to 600 DPI in vertical direction (never use in combination with QL_BI_COLOR) (known for QL8xx printers for now)

Note: With the cutter related bit 3 cutting at the end (whatever 'end' here is meant) can be controlled; To be sent at the beginning of a page and required at each page (according to the manual)

◆ ql_invalidate_and_initialize()

static int ql_invalidate_and_initialize ( struct qldriver * ql )

static

Start a new print job from the printer's point of view

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

To be sent at the beginning of a new print job or if the current processing has to be stopped at the printer's side.

From the datasheet: "If data transmission is to be stopped midway, send the “initialize” command after sending the “invalidate” command for the appropriate number of bytes to return to the receiving state, where the print buffer is cleared."

Note: invalidate means the specified amount of zero bytes; initialize means the *ESC,@* command in ql_reset(); To be sent once at the beginning of a print job (according to the manual)

◆ ql_job_footer_generate()

int ql_job_footer_generate ( struct qldriver * ql )

Send the footer commands after a print job

Parameters

[in] ql Full job description

Attention: Do not call in case of a procesing failure. These commands make sense only if the print job was successful.

Called once per print job at the end. But only:

if the whole job was successful
no termination request was received

◆ ql_job_header_generate()

int ql_job_header_generate ( struct qldriver * ql )

Send the heading commands to setup the printer prior a print job

Parameters

[in] ql Full job description

Called once per print job at the beginning

◆ ql_last_page_print()

static int ql_last_page_print ( struct qldriver * ql )

static

Finish the current print job

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

This code is to be sent after the last page to finish the whole print job.

Note: To be sent at the end of a page's raster, if it is the last page of the job (according to the manual)

◆ ql_notification_disable()

static int ql_notification_disable ( struct qldriver * ql )

static

Disable the printer's notification capability

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

We do not have a real back channel, so we can't recieve its data

Todo:: But it would be useful to have a back channel!

◆ ql_page_header_generate()

int ql_page_header_generate	(	struct qldriver *	ql,
		int	first_time
	)

Parameters

[in]	ql	Full job description
[in]	first_time	Flag if called the first time in a print job

Return values

0	On success
-ENODEV	Device seems gone (e.g. channel to the next stage is gone)

Called once per page at the beginning

Note: In case of -ENODEV it makes no sense trying to send any further data or commands

Precondition: The qldriver::trim member must be up to data, e.g. its content matches the current raster page header

Todo:

Deal with QL_FAST_PRINT/QL_QUALITY_PRINT for monochrome use case

Do the QL_QUALITY_PRINT and QL_HIGH_RESOLUTION bits depend on each other?

Deal with auto cut setting and when to cut (and if the printer has a cutter). To make it simple: only "cut at end" and "cut each" should be supported

◆ ql_page_print()

static int ql_page_print ( struct qldriver * ql )

static

Finish the current page

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

This code is to be sent after a page.

It seems, this command is only to be sent, if more than one page in one job should be printed. If the job contains only one page, the ql_last_page_print() is enough to do the right thing.

Note: To be sent at the end of a page's raster, if it isn't the last page to be print (according to the manual)

◆ ql_print_information()

static int ql_print_information	(	struct qldriver *	ql,
		int	media_type,
		int	media_width,
		int	media_length,
		int	raster,
		int	start_page,
		int	quality
	)

static

Send information about the job or the next page

Parameters

[in]	ql	Full job description
[in]	media_type	QL_MEDIA_TYPE_CONTINUOUS or QL_MEDIA_TYPE_DIE_CUT, negative value for not defined
[in]	media_width	Width of the to be printed medium in [mm], negative value for not defined
[in]	media_length	Length of the to be printed media in [mm] ('0' for continuous roll), negative value for not defined
[in]	raster	Count of rasterlines of one "page", negative value for not defined
[in]	start_page	'0' for the first page, '1' for continuous page
[in]	quality	QL_QUALITY_PRINT or QL_FAST_PRINT

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

The manual encodes this info (as an example):

This is the command for “1.1" × 3.5" (29 mm × 90 mm)” die-cut labels.

into:

 1b 69 7A 8F 0B 1D 5A DF 03 00 00 00 00
                                  ^^___ Starting page
                      ^^_^^_^^_^^______ 991 raster lines ~83 mm
                   ^^__________________ 90 mm length
                ^^_____________________ 29 mm width
             ^^________________________ Media type: die cut
          ^^___________________________ 8F: 10x0 1111
                                                    ^_ ????
                                                   ^__ Media type valid
                                                  ^___ Width valid
                                                 ^____ Length valid
                                               ^______ Raster invalid (vague interpretation!)
                                             ^________ fast print
                                            ^_________ Recovery

For the DK1201 roll (die-cut 29 mm x 90 mm label), the QL800 datasheet defines:

width: 342 dots
heigt: 1061 dots (= top margin + printable height + top/bottom margin)
printable width: 306 dots
printable height: 991 dots
left/right margin: 18 dots
top/bottom margin: 35 dots Note: all at 300 DPI

Note: To be sent at the beginning of a page and required at each page (according to the manual)

◆ ql_reset()

int ql_reset ( struct qldriver * ql )

Initialize/reset the printer

Parameters

[in] ql Full job description

Return values

0	On success
Negative	Error code from the ql_printer_data_send() call

This command can also be used every time to terminate a current print

Note: To be sent once at the beginning of a print job (according to the manual)

◆ transform_to_monochrome()

void transform_to_monochrome	(	size_t	input_cnt,
		const signed short	input[input_cnt],
		unsigned char *	data
	)

Convert an array of signed shorts into a monochrome pattern (one signed short into one bit)

Parameters

[in]	input_cnt	Count of pixel in input
[in]	input	Where to get the quantized input data
[out]	data	Where to store the converted output data

Note: Since the printer prints from right to left, each pattern gets mirrored(!) here. First pixel printed (at the right border) is the MSB of the first byte

Precondition: PRINT_DOT_VAL means: print a dot, everything else means: do not print a dot, e.g. the input data must already be quantized

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BIT

◆ QL_AUTO_CUT

◆ QL_BI_COLOR

◆ QL_CUT_AT_END

◆ QL_CUT_EACH_LABEL

◆ QL_FAST_PRINT

◆ QL_HIGH_PRINT_QUALITY

◆ QL_HIGH_RESOLUTION

◆ QL_LENGTH_ENTRY_VALID

◆ QL_MEDIA_ENTRY_VALID

◆ QL_MEDIA_TYPE_CONTINUOUS

◆ QL_MEDIA_TYPE_DIE_CUT

◆ QL_NO_COMPRESSION

◆ QL_QUALITY_PRINT

◆ QL_RASTER_ENTRY_VALID

◆ QL_RECOVER_ENTRY_VALID

◆ QL_TIFF_COMPRESSION

◆ QL_WHAT_IS_BIT_0

◆ QL_WIDTH_ENTRY_VALID

Function Documentation

◆ ql_auto_powerdown()

◆ ql_auto_powerup()

◆ ql_compression_setup()

◆ ql_cut_mode_set()

◆ ql_cut_on_label_n()

◆ ql_define_tape_margins()

◆ ql_dynamic_mode()

◆ ql_extended_mode_set()

◆ ql_invalidate_and_initialize()

◆ ql_job_footer_generate()

◆ ql_job_header_generate()

◆ ql_last_page_print()

◆ ql_notification_disable()

◆ ql_page_header_generate()

◆ ql_page_print()

◆ ql_print_information()

◆ ql_reset()

◆ transform_to_monochrome()