Esc/Pos

Module escpos.escpos

Main class

This module contains the abstract base class Escpos.

author

Manuel F Martinez and others

organization

Bashlinux and python-escpos

copyright

Copyright (c) 2012-2017 Bashlinux and python-escpos

license

MIT

class escpos.escpos.Escpos(profile=None, magic_encode_args=None, **kwargs)

Bases: object

ESC/POS Printer object

This class is the abstract base class for an esc/pos-printer. The printer implementations are children of this class.

device = None

image(img_source, high_density_vertical=True, high_density_horizontal=True, impl='bitImageRaster', fragment_height=960, center=False)

Print an image

You can select whether the printer should print in high density or not. The default value is high density. When printing in low density, the image will be stretched.

Esc/Pos supplies several commands for printing. This function supports three of them. Please try to vary the implementations if you have any problems. For example the printer IT80-002 will have trouble aligning images that are not printed in Column-mode.

The available printing implementations are:

• bitImageRaster: prints with the GS v 0-command

• graphics: prints with the GS ( L-command

• bitImageColumn: prints with the ESC *-command

When trying to center an image make sure you have initialized the printer with a valid profile, that contains a media width pixel field. Otherwise the centering will have no effect.

Parameters

• img_source – PIL image or filename to load: jpg, gif, png or bmp

• high_density_vertical – print in high density in vertical direction default: True

• high_density_horizontal – print in high density in horizontal direction default: True

• impl – choose image printing mode between bitImageRaster, graphics or bitImageColumn

• fragment_height – Images larger than this will be split into multiple fragments default: 960

• center – Center image horizontally default: False

qr(content, ec=0, size=3, model=2, native=False, center=False, impl='bitImageRaster')

Print QR Code for the provided string

Parameters

• content – The content of the code. Numeric data will be more efficiently compacted.

• ec – Error-correction level to use. One of QR_ECLEVEL_L (default), QR_ECLEVEL_M, QR_ECLEVEL_Q or QR_ECLEVEL_H. Higher error correction results in a less compact code.

• size – Pixel size to use. Must be 1-16 (default 3)

• model – QR code model to use. Must be one of QR_MODEL_1, QR_MODEL_2 (default) or QR_MICRO (not supported by all printers).

• native – True to render the code on the printer, False to render the code as an image and send it to the printer (Default)

• center – Centers the code default: False

• impl – Image-printing-implementation, refer to image() for details

charcode(code='AUTO')

Set Character Code Table

Sets the control sequence from CHARCODE in escpos.constants as active. It will be sent with the next text sequence. If you set the variable code to AUTO it will try to automatically guess the right codepage. (This is the standard behaviour.)

Parameters

code – Name of CharCode

Raises

CharCodeError

static check_barcode(bc, code)

This method checks if the barcode is in the proper format. The validation concerns the barcode length and the set of characters, but won’t compute/validate any checksum. The full set of requirement for each barcode type is available in the ESC/POS documentation.

As an example, using EAN13, the barcode 12345678901 will be correct, because it can be rendered by the printer. But it does not suit the EAN13 standard, because the checksum digit is missing. Adding a wrong checksum in the end will also be considered correct, but adding a letter won’t (EAN13 is numeric only).

Todo

Add a method to compute the checksum for the different standards

Todo

For fixed-length standards with mandatory checksum (EAN, UPC), compute and add the checksum automatically if missing.

Parameters

• bc – barcode format, see barcode()

• code – alphanumeric data to be printed as bar code, see barcode()

Returns

bool

barcode(code, bc, height=64, width=3, pos='BELOW', font='A', align_ct=True, function_type=None, check=True)

Print Barcode

This method allows to print barcodes. The rendering of the barcode is done by the printer and therefore has to be supported by the unit. By default, this method will check whether your barcode text is correct, that is the characters and lengths are supported by ESCPOS. Call the method with check=False to disable the check, but note that uncorrect barcodes may lead to unexpected printer behaviour. There are two forms of the barcode function. Type A is default but has fewer barcodes, while type B has some more to choose from.

Use the parameters height and width for adjusting of the barcode size. Please take notice that the barcode will not be printed if it is outside of the printable area. (Which should be impossible with this method, so this information is probably more useful for debugging purposes.)

Todo

On TM-T88II width from 1 to 6 is accepted. Try to acquire command reference and correct the code.

Todo

Supplying pos does not have an effect for every barcode type. Check and document for which types this is true.

If you do not want to center the barcode you can call the method with align_ct=False, which will disable automatic centering. Please note that when you use center alignment, then the alignment of text will be changed automatically to centered. You have to manually restore the alignment if necessary.

Todo

If further barcode-types are needed they could be rendered transparently as an image. (This could also be of help if the printer does not support types that others do.)

Parameters

• code – alphanumeric data to be printed as bar code

• bc –

  barcode format, possible values are for type A are:

  • UPC-A

  • UPC-E

  • EAN13

  • EAN8

  • CODE39

  • ITF

  • NW7

  Possible values for type B:

  • All types from function type A

  • CODE93

  • CODE128

  • GS1-128

  • GS1 DataBar Omnidirectional

  • GS1 DataBar Truncated

  • GS1 DataBar Limited

  • GS1 DataBar Expanded

  If none is specified, the method raises BarcodeTypeError.

• height (int) – barcode height, has to be between 1 and 255 default: 64

• width (int) – barcode width, has to be between 2 and 6 default: 3

• pos –

  where to place the text relative to the barcode, default: BELOW

  • ABOVE

  • BELOW

  • BOTH

  • OFF

• font –

  select font (see ESC/POS-documentation, the device often has two fonts), default: A

  • A

  • B

• align_ct (bool) – If this parameter is True the barcode will be centered. Otherwise no alignment command will be issued.

• function_type – Choose between ESCPOS function type A or B, depending on printer support and desired barcode. If not given, the printer will attempt to automatically choose the correct function based on the current profile. default: A

• check – If this parameter is True, the barcode format will be checked to ensure it meets the bc requirements as definged in the ESC/POS documentation. See check_barcode() for more information. default: True.

Raises

BarcodeSizeError, BarcodeTypeError, BarcodeCodeError

soft_barcode(barcode_type, data, impl='bitImageColumn', module_height=5, module_width=0.2, text_distance=1, center=True)

text(txt)

Print alpha-numeric text

The text has to be encoded in the currently selected codepage. The input text has to be encoded in unicode.

Parameters

txt – text to be printed

Raises

TextError

textln(txt='')

Print alpha-numeric text with a newline

The text has to be encoded in the currently selected codepage. The input text has to be encoded in unicode.

Parameters

txt – text to be printed with a newline

Raises

TextError

ln(count=1)

Print a newline or more

Parameters

count – number of newlines to print

Raises

ValueError if count < 0

block_text(txt, font=None, columns=None)

Text is printed wrapped to specified columns

Text has to be encoded in unicode.

Parameters

• txt – text to be printed

• font – font to be used, can be a or b

• columns – amount of columns

Returns

None

set(align='left', font='a', bold=False, underline=0, width=1, height=1, density=9, invert=False, smooth=False, flip=False, double_width=False, double_height=False, custom_size=False)

Set text properties by sending them to the printer

Parameters

• align (str) –

  horizontal position for text, possible values are:

  • ’center’

  • ’left’

  • ’right’

  default: ‘left’

• font (str) – font given as an index, a name, or one of the special values ‘a’ or ‘b’, referring to fonts 0 and 1.

• bold (bool) – text in bold, default: False

• underline (bool) – underline mode for text, decimal range 0-2, default: 0

• double_height (bool) – doubles the height of the text

• double_width (bool) – doubles the width of the text

• custom_size (bool) – uses custom size specified by width and height parameters. Cannot be used with double_width or double_height.

• width (int) – text width multiplier when custom_size is used, decimal range 1-8, default: 1

• height (int) – text height multiplier when custom_size is used, decimal range 1-8, default: 1

• density (int) – print density, value from 0-8, if something else is supplied the density remains unchanged

• invert (bool) – True enables white on black printing, default: False

• smooth (bool) – True enables text smoothing. Effective on 4x4 size text and larger, default: False

• flip (bool) – True enables upside-down printing, default: False

line_spacing(spacing=None, divisor=180)

Set line character spacing.

If no spacing is given, we reset it to the default.

There are different commands for setting the line spacing, using a different denominator:

‘+’’ line_spacing/360 of an inch, 0 <= line_spacing <= 255 ‘3’ line_spacing/180 of an inch, 0 <= line_spacing <= 255 ‘A’ line_spacing/60 of an inch, 0 <= line_spacing <= 85

Some printers may not support all of them. The most commonly available command (using a divisor of 180) is chosen.

cut(mode='FULL', feed=True)

Cut paper.

Without any arguments the paper will be cut completely. With ‘mode=PART’ a partial cut will be attempted. Note however, that not all models can do a partial cut. See the documentation of your printer for details.

Parameters

• mode – set to ‘PART’ for a partial cut. default: ‘FULL’

• feed – print and feed before cutting. default: true

Raises

ValueError – if mode not in (‘FULL’, ‘PART’)

cashdraw(pin)

Send pulse to kick the cash drawer

Kick cash drawer on pin 2 or pin 5 according to default parameter. For non default parameter send a decimal sequence i.e. [27,112,48] or [27,112,0,25,255]

Parameters

pin – pin number, 2 or 5 or list of decimals

Raises

CashDrawerError

linedisplay_select(select_display=False)

Selects the line display or the printer

This method is used for line displays that are daisy-chained between your computer and printer. If you set select_display to true, only the display is selected and if you set it to false, only the printer is selected.

Parameters

select_display (bool) – whether the display should be selected or the printer

linedisplay_clear()

Clears the line display and resets the cursor

This method is used for line displays that are daisy-chained between your computer and printer.

linedisplay(text)

Display text on a line display connected to your printer

You should connect a line display to your printer. You can do this by daisy-chaining the display between your computer and printer.

Parameters

text – Text to display

hw(hw)

Hardware operations

Parameters

hw –

hardware action, may be:

• INIT

• SELECT

• RESET

print_and_feed(n=1)

Print data in print buffer and feed n lines

if n not in range (0, 255) then ValueError will be raised

Parameters

n – number of n to feed. 0 <= n <= 255. default: 1

Raises

ValueError – if not 0 <= n <= 255

control(ctl, count=5, tab_size=8)

Feed control sequences

Parameters

• ctl –

  string for the following control sequences:

  • LF for Line Feed

  • FF for Form Feed

  • CR for Carriage Return

  • HT for Horizontal Tab

  • VT for Vertical Tab

• count – integer between 1 and 32, controls the horizontal tab count. Defaults to 5.

• tab_size – integer between 1 and 255, controls the horizontal tab size in characters. Defaults to 8

Raises

TabPosError

panel_buttons(enable=True)

Controls the panel buttons on the printer (e.g. FEED)

When enable is set to False the panel buttons on the printer will be disabled. Calling the method with enable=True or without argument will enable the panel buttons.

If panel buttons are enabled, the function of the panel button, such as feeding, will be executed upon pressing the button. If the panel buttons are disabled, pressing them will not have any effect.

This command is effective until the printer is initialized, reset or power-cycled. The default is enabled panel buttons.

Some panel buttons will always work, especially when printer is opened. See for more information the manual of your printer and the escpos-command-reference.

Parameters

enable – controls the panel buttons

Return type

None

query_status(mode)

Queries the printer for its status, and returns an array of integers containing it.

Parameters

mode – Integer that sets the status mode queried to the printer. - RT_STATUS_ONLINE: Printer status. - RT_STATUS_PAPER: Paper sensor.

Return type

array(integer)

is_online()

Queries the online status of the printer.

Returns

When online, returns True; False otherwise.

Return type

bool

paper_status()

Queries the paper status of the printer.

Returns 2 if there is plenty of paper, 1 if the paper has arrived to the near-end sensor and 0 if there is no paper.

Returns

2: Paper is adequate. 1: Paper ending. 0: No paper.

Return type

int

class escpos.escpos.EscposIO(printer, autocut=True, autoclose=True, **kwargs)

Bases: object

ESC/POS Printer IO object

Allows the class to be used together with the with-statement. You have to define a printer instance and assign it to the EscposIO class. This example explains the usage:

with EscposIO(printer.Serial('/dev/ttyUSB0')) as p:
    p.set(font='a', height=2, align='center', text_type='bold')
    p.printer.set(align='left')
    p.printer.image('logo.gif')
    p.writelines('Big line\n', font='b')
    p.writelines('Привет')
    p.writelines('BIG TEXT', width=2)

After the with-statement the printer automatically cuts the paper if autocut is True.

set(**kwargs)

Set the printer-parameters

Controls which parameters will be passed to Escpos.set(). For more information on the parameters see the set()-methods documentation. These parameters can also be passed with this class’ constructor or the writelines()-method.

Parameters

kwargs – keyword-parameters that will be passed to Escpos.set()

writelines(text, **kwargs)

close()

called upon closing the with-statement