python-escpos - Python library to manipulate ESC/POS Printers¶

Installation¶

Methods¶

Printers¶

There 3 different type of printers:

Raspberry Pi¶

This instructions were tested on Raspbian.

Unless you have done any distro with libusb-1.0 on the Raspberry Pi, the following instructions should works fine on your raspberry distro.

# apt-get install python-imaging python-serial python-setuptools

# git clone https://github.com/manpaz/python-escpos.git
# cd python-escpos
# python setup.py build
# sudo python setup.py install

TODO¶

Usage¶

xxxx:xxxx

# lsusb
Bus 002 Device 001: ID 04b8:0202 Epson ...

# lsusb -vvv -d xxxx:xxxx | grep iInterface
    iInterface              0
# lsusb -vvv -d xxxx:xxxx | grep bEndpointAddress | grep OUT
      bEndpointAddress     0x01  EP 1 OUT

Epson = printer.Usb(0x04b8,0x0202)

Generic = printer.Usb(0x1a2b,0x1a2b,0,0x81,0x02)

Epson = printer.Network("192.168.1.99")

Epson = printer.Serial("/dev/tty0")

Epson = printer.File("/dev/usb/lp1")

from escpos import *
""" Seiko Epson Corp. Receipt Printer M129 Definitions (EPSON TM-T88IV) """
Epson = printer.Usb(0x04b8,0x0202)
# Print text
Epson.text("Hello World\n")
# Print image
Epson.image("logo.gif")
# Print QR Code
Epson.qr("You can readme from your smartphone")
# Print barcode
Epson.barcode('1324354657687','EAN13',64,2,'','')
# Cut paper
Epson.cut()

%appdata%/python-escpos/config.yaml

$HOME/.config/python-escpos/config.yaml

from escpos import config
c = config.Config()
c.load()

from escpos import config
c = config.Config()
printer = c.printer()

printer:
        type: File
        devfile: /dev/someprinter

printer:
        type: network
        host: 127.0.0.1
        port: 9000

from escpos import printer
p = printer.Serial()  # adapt this to your printer model

file = open("binary-blob.bin", "rb")  # read in the file containing your commands in binary-mode
data = file.read()
file.close()

p._raw(data)

Epson = escpos.Escpos(0x04b8,0x0202,0)

Epson = printer.Usb(0x04b8,0x0202)

Printing Barcodes¶

Most ESC/POS-printers implement barcode-printing. The barcode-commandset is implemented in the barcode-method. For a list of compatible barcodes you should check the manual of your printer. As a rule of thumb: even older Epson-models support most 1D-barcodes. To be sure just try some implementations and have a look at the notices below.

from escpos.printer import Dummy, Serial
p = Serial()
# print CODE128 012ABCDabcd
p.barcode("{B012ABCDabcd", "CODE128", function_type="B")

Contributing¶

This project is open to any kind of contribution. You can help with improving the documentation, adding fixes to the code, providing test cases in code or as a description or just spreading the word. Please feel free to create an issue or pull request. In order to reduce the amount of work for everyone please try to adhere to good practice.

The pull requests and issues will be prefilled with templates. Please fill in your information where applicable.

This project uses semantic versioning and tries to adhere to the proposed rules as well as possible.

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from __future__ import unicode_literals

Changelog¶

Esc/Pos¶

Module escpos.escpos

Main class

This module contains the abstract base class Escpos.

class escpos.escpos.Escpos(columns=32)¶

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.

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

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. Currently you have to check manually whether your barcode text is correct. 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.

Todo

Add a method to check barcode codes. Alternatively or as an addition write explanations about each barcode-type. Research whether the check digits can be computed autmatically.

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. default: A

Raises:

BarcodeSizeError, BarcodeTypeError, BarcodeCodeError

block_text(txt, columns=None)¶

Text is printed wrapped to specified columns

Text has to be encoded in unicode.

Parameters:	txt – text to be printed columns – amount of columns
Returns:	None

cashdraw(pin)¶

Send pulse to kick the cash drawer

Kick cash drawer on pin 2 or pin 5 according to parameter.

Parameters:	pin – pin number, 2 or 5
Raises:	CashDrawerError

charcode(code)¶

Set Character Code Table

Sends the control sequence from escpos.constants to the printer with escpos.printer.'implementation'._raw().

Parameters:	code – Name of CharCode
Raises:	CharCodeError

codepage = None¶

control(ctl, pos=4)¶

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 pos – integer between 1 and 16, controls the horizontal tab position
Raises:	TabPosError

cut(mode=u'')¶

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.

Todo

Check this function on TM-T88II.

Parameters:	mode – set to ‘PART’ for a partial cut

device = None¶

hw(hw)¶

Hardware operations

Parameters:	hw – hardware action, may be: INIT SELECT RESET

image(img_source, high_density_vertical=True, high_density_horizontal=True, impl=u'bitImageRaster')¶

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

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

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

qr(content, ec=0, size=3, model=2, native=False)¶

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)

set(align=u'left', font=u'a', text_type=u'normal', width=1, height=1, density=9, invert=False, smooth=False, flip=False)¶

Set text properties by sending them to the printer

Parameters:

align – horizontal position for text, possible values are: CENTER LEFT RIGHT default: LEFT font – font type, possible values are A or B, default: A text_type – text type, possible values are: B for bold U for underlined U2 for underlined, version 2 BU for bold and underlined BU2 for bold and underlined, version 2 NORMAL for normal text default: NORMAL width – text width multiplier, decimal range 1-8, default: 1 height – text height multiplier, decimal range 1-8, default: 1 density – 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 – True enables text smoothing. Effective on 4x4 size text and larger, default: False flip – True enables upside-down printing, default: False

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

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 EsposIO-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.

close()¶

called upon closing the with-statement

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)¶

Printer implementations¶

Module escpos.printer

This module contains the implementations of abstract base class Escpos.

class escpos.printer.Dummy(*args, **kwargs)¶

Bases: escpos.escpos.Escpos

Dummy printer

This class is used for saving commands to a variable, for use in situations where there is no need to send commands to an actual printer. This includes generating print jobs for later use, or testing output.

inheritance:

close()¶

output¶

Get the data that was sent to this printer

class escpos.printer.File(devfile=u'/dev/usb/lp0', auto_flush=True, *args, **kwargs)¶

Bases: escpos.escpos.Escpos

Generic file printer

This class is used for parallel port printer or other printers that are directly attached to the filesystem. Note that you should stay away from using USB-to-Parallel-Adapter since they are unreliable and produce arbitrary errors.

inheritance:

close()¶

Close system file

flush()¶

Flush printing content

open()¶

Open system file

class escpos.printer.Network(host, port=9100, timeout=60, *args, **kwargs)¶

Bases: escpos.escpos.Escpos

Network printer

This class is used to attach to a networked printer. You can also use this in order to attach to a printer that is forwarded with socat.

If you have a local printer on parallel port /dev/usb/lp0 then you could start socat with:

socat -u TCP4-LISTEN:4242,reuseaddr,fork OPEN:/dev/usb/lp0

Then you should be able to attach to port 4242 with this class. Otherwise the normal usecase would be to have a printer with ethernet interface. This type of printer should work the same with this class. For the address of the printer check its manuals.

inheritance:

close()¶

Close TCP connection

open()¶

Open TCP socket with socket-library and set it as escpos device

class escpos.printer.Serial(devfile=u'/dev/ttyS0', baudrate=9600, bytesize=8, timeout=1, parity='N', stopbits=1, xonxoff=False, dsrdtr=True, *args, **kwargs)¶

Bases: escpos.escpos.Escpos

Serial printer

This class describes a printer that is connected by serial interface.

inheritance:

close()¶

Close Serial interface

open()¶

Setup serial port and set is as escpos device

class escpos.printer.Usb(idVendor, idProduct, timeout=0, in_ep=130, out_ep=1, *args, **kwargs)¶

Bases: escpos.escpos.Escpos

USB printer

This class describes a printer that natively speaks USB.

inheritance:

close()¶

Release USB interface

open()¶

Search device on USB tree and set it as escpos device

Constants¶

Module escpos.constants

Set of ESC/POS Commands (Constants)

This module contains constants that are described in the esc/pos-documentation. Since there is no definitive and unified specification for all esc/pos-like printers the constants could later be moved to capabilities as in escpos-php by @mike42.

Exceptions¶

Module escpos.exceptions

ESC/POS Exceptions classes

Result/Exit codes:

• 0 = success
• 10 = No Barcode type defined BarcodeTypeError
• 20 = Barcode size values are out of range BarcodeSizeError
• 30 = Barcode text not supplied BarcodeCodeError
• 40 = Image height is too large ImageSizeError
• 50 = No string supplied to be printed TextError
• 60 = Invalid pin to send Cash Drawer pulse CashDrawerError
• 70 = Invalid number of tab positions TabPosError
• 80 = Invalid char code CharCodeError
• 90 = USB device not found USBNotFoundError
• 100 = Set variable out of range SetVariableError
• 200 = Configuration not found ConfigNotFoundError
• 210 = Configuration syntax error ConfigSyntaxError
• 220 = Configuration section not found ConfigSectionMissingError

exception escpos.exceptions.BarcodeCodeError(msg=u'')¶

Bases: escpos.exceptions.Error

No Barcode code was supplied.

No data for the barcode has been supplied in escpos.escpos.Escpos.barcode(). The returncode for this exception is 30.

exception escpos.exceptions.BarcodeSizeError(msg=u'')¶

Bases: escpos.exceptions.Error

Barcode size is out of range.

This exception indicates that the values for the barcode size are out of range. The size of the barcode has to be in the range that is specified in escpos.escpos.Escpos.barcode(). The resulting returncode is 20.

exception escpos.exceptions.BarcodeTypeError(msg=u'')¶

Bases: escpos.exceptions.Error

No Barcode type defined.

This exception indicates that no known barcode-type has been entered. The barcode-type has to be one of those specified in escpos.escpos.Escpos.barcode(). The returned error code is 10.

exception escpos.exceptions.CashDrawerError(msg=u'')¶

Bases: escpos.exceptions.Error

Valid pin must be set in order to send pulse.

A valid pin number has to be passed onto the method escpos.escpos.Escpos.cashdraw(). The returncode for this exception is 60.

exception escpos.exceptions.CharCodeError(msg=u'')¶

Bases: escpos.exceptions.Error

Valid char code must be set.

The supplied charcode-name in escpos.escpos.Escpos.charcode() is unknown. Ths returncode for this exception is 80.

exception escpos.exceptions.ConfigNotFoundError(msg=u'')¶

Bases: escpos.exceptions.Error

The configuration file was not found

The default or passed configuration file could not be read Ths returncode for this exception is 200.

exception escpos.exceptions.ConfigSectionMissingError(msg=u'')¶

Bases: escpos.exceptions.Error

The configuration file is missing a section

The part of the config asked for doesn’t exist in the loaded configuration Ths returncode for this exception is 220.

exception escpos.exceptions.ConfigSyntaxError(msg=u'')¶

Bases: escpos.exceptions.Error

The configuration file is invalid

The syntax is incorrect Ths returncode for this exception is 210.

exception escpos.exceptions.Error(msg, status=None)¶

Bases: exceptions.Exception

Base class for ESC/POS errors

exception escpos.exceptions.ImageSizeError(msg=u'')¶

Bases: escpos.exceptions.Error

Image height is longer than 255px and can’t be printed.

The returncode for this exception is 40.

exception escpos.exceptions.SetVariableError(msg=u'')¶

Bases: escpos.exceptions.Error

A set method variable was out of range

Check set variables against minimum and maximum values Ths returncode for this exception is 100.

exception escpos.exceptions.TabPosError(msg=u'')¶

Bases: escpos.exceptions.Error

Valid tab positions must be in the range 0 to 16.

This exception is raised by escpos.escpos.Escpos.control(). The returncode for this exception is 70.

exception escpos.exceptions.TextError(msg=u'')¶

Bases: escpos.exceptions.Error

Text string must be supplied to the text() method.

This exception is raised when an empty string is passed to escpos.escpos.Escpos.text(). The returncode for this exception is 50.

exception escpos.exceptions.USBNotFoundError(msg=u'')¶

Bases: escpos.exceptions.Error

Device wasn’t found (probably not plugged in)

The USB device seems to be not plugged in. Ths returncode for this exception is 90.

Config¶

Module escpos.config

ESC/POS configuration manager.

This module contains the implentations of abstract base class Config.

class escpos.config.Config¶

Bases: object

Configuration handler class.

This class loads configuration from a default or specificed directory. It can create your defined printer and return it to you.

load(config_path=None)¶

Load and parse the configuration file using pyyaml

Parameters:	config_path – An optional file path, file handle, or byte string for the configuration file.

printer()¶

Returns a printer that was defined in the config, or throws an exception.

This method loads the default config if one hasn’t beeen already loaded.

Image helper¶

Module escpos.image

Image format handling class

This module contains the image format handler EscposImage.

class escpos.image.EscposImage(img_source)¶

Bases: object

Load images in, and output ESC/POS formats.

The class is designed to efficiently delegate image processing to PIL, rather than spend CPU cycles looping over pixels.

height¶

Height of image in pixels

to_column_format(high_density_vertical=True)¶

Extract slices of an image as equal-sized blobs of column-format data.

Parameters:	high_density_vertical – Printed line height in dots

to_raster_format()¶

Convert image to raster-format binary

width¶

Width of image in pixels

width_bytes¶

Width of image if you use 8 pixels per byte and 0-pad at the end.