Merge branch 'feature-sphinx'
This commit is contained in:
Patrick Kanzler
commit
c3fbdf28d4
|
|
@ -6,13 +6,46 @@
|
||||||
Welcome to python-escpos's documentation!
|
Welcome to python-escpos's documentation!
|
||||||
=========================================
|
=========================================
|
||||||
|
|
||||||
Contents:
|
Python ESC/POS is a library which lets the user have access to all those printers handled by ESC/POS commands, as defined by Epson, from a Python application.
|
||||||
|
|
||||||
|
The standard usage is send raw text to the printer, but in also helps the user to enhance the experience with those printers by facilitating the bar code printing in many different standards,as well as manipulating images so they can be printed as brand logo or any other usage images migh have.
|
||||||
|
|
||||||
|
Text can be justified and fonts can be changed by size, type and weight.
|
||||||
|
|
||||||
|
Also, this module handles some hardware functionalists like, cut paper, cash drawer kicking, printer reset, carriage return and others concerned to the carriage alignment.
|
||||||
|
|
||||||
|
------------
|
||||||
|
|
||||||
|
There are some different printers I'd like to acquire, unfortunately
|
||||||
|
not all, even used, are cheaper and easy to get.
|
||||||
|
|
||||||
|
If you want to help funding money to get more printers or just want to
|
||||||
|
donate because you like the project, please be in touch and I'll be
|
||||||
|
sending my PayPal info so you can donate.
|
||||||
|
|
||||||
|
Thank you!
|
||||||
|
|
||||||
|
User Documentation:
|
||||||
|
-------------------
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
api-documentation
|
user/dependencies
|
||||||
|
user/installation
|
||||||
|
user/methods
|
||||||
|
user/printers
|
||||||
|
user/raspi
|
||||||
|
user/todo
|
||||||
|
user/usage
|
||||||
|
|
||||||
|
API:
|
||||||
|
----
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
api
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
[Dolphin]
|
||||||
|
HeaderColumnWidths=270,74,108
|
||||||
|
Timestamp=2015,12,27,17,3,8
|
||||||
|
Version=3
|
||||||
|
ViewMode=1
|
||||||
|
|
@ -0,0 +1,57 @@
|
||||||
|
************
|
||||||
|
Dependencies
|
||||||
|
************
|
||||||
|
|
||||||
|
Fedora
|
||||||
|
------
|
||||||
|
|
||||||
|
Fortunately everything is on Fedora repositories.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# yum install python-imaging pyserial pyusb python-qrcode
|
||||||
|
|
||||||
|
Ubuntu
|
||||||
|
------
|
||||||
|
|
||||||
|
Ultimately, this instructions also apply to Raspbian, in case you are
|
||||||
|
interested to install python-escpos on your Raspberry with Raspbian.
|
||||||
|
|
||||||
|
Install the packages available on distro repositories.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# apt-get install python-imaging pyserial
|
||||||
|
|
||||||
|
The packages which are not available at Ubuntu repositories need to be
|
||||||
|
installed manually.
|
||||||
|
|
||||||
|
pyusb
|
||||||
|
^^^^^
|
||||||
|
This is the python binding to libusb-1.0
|
||||||
|
|
||||||
|
* Get the latest tarball from `sourceforge <http://sourceforge.net/projects/pyusb/files/PyUSB%201.0/>`__
|
||||||
|
* Build and install it
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# tar zxvf pyusb-1.*.tar.gz
|
||||||
|
# cd pyusb-1.*
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
python-qrcode
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This is the python module to generate QR Codes
|
||||||
|
|
||||||
|
* Checkout the latest code from `github <https://github.com/lincolnloop/python-qrcode>`__
|
||||||
|
* Build and install it
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# git clone https://github.com/lincolnloop/python-qrcode
|
||||||
|
# cd python-qrcode
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
|
@ -0,0 +1,40 @@
|
||||||
|
************
|
||||||
|
Installation
|
||||||
|
************
|
||||||
|
|
||||||
|
System preparation
|
||||||
|
------------------
|
||||||
|
|
||||||
|
1. Install the required
|
||||||
|
`dependencies <https://github.com/manpaz/python-escpos/wiki/Dependencies>`__
|
||||||
|
|
||||||
|
2. Get the *Product ID* and *Vendor ID* from the lsusb command
|
||||||
|
``# lsusb Bus 002 Device 001: ID 1a2b:1a2b Device name``
|
||||||
|
|
||||||
|
3. Create a udev rule to let users belonging to *dialout* group use the
|
||||||
|
printer. You can create the file
|
||||||
|
``/etc/udev/rules.d/99-escpos.rules`` and add the following:
|
||||||
|
``SUBSYSTEM=="usb", ATTRS{idVendor}=="1a2b", ATTRS{idProduct}=="1a2b", MODE="0664", GROUP="dialout"``
|
||||||
|
Replace *idVendor* and *idProduct* hex numbers with the ones that you
|
||||||
|
got from the previous step. Note that you can either, add yourself to
|
||||||
|
"dialout" group, or use another group you already belongs instead
|
||||||
|
"dialout" and set it in the ``GROUP`` parameter in the above rule.
|
||||||
|
|
||||||
|
4. Restart udev ``# sudo service udev restart`` In some new systems it
|
||||||
|
is done with ``# sudo udevadm control --reload``
|
||||||
|
|
||||||
|
Install
|
||||||
|
-------
|
||||||
|
|
||||||
|
* Clone python-escpos from github
|
||||||
|
* Change directory to python-escpos and install the package
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# cd python-escpos
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
* Enjoy !!!
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,118 @@
|
||||||
|
*******
|
||||||
|
Methods
|
||||||
|
*******
|
||||||
|
|
||||||
|
.. note:: **TODO** Merge this page into the API-description.
|
||||||
|
|
||||||
|
Escpos class
|
||||||
|
------------
|
||||||
|
|
||||||
|
Escpos inherits its methods to the printers. the following methods are
|
||||||
|
defined:
|
||||||
|
|
||||||
|
image("image\_name.ext")
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Prints an image. Its adjust the size in order to print it.
|
||||||
|
|
||||||
|
* ``image_name.ext`` is the complete file name and location of any image type (jpg, gif, png, bmp)
|
||||||
|
|
||||||
|
Raises ``ImageSizeError`` exception.
|
||||||
|
|
||||||
|
qr("text")
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
Prints a QR code. The size has been adjusted to Version 4, so it can be
|
||||||
|
enough small to be printed but also enough big to be read by a smart
|
||||||
|
phone.
|
||||||
|
|
||||||
|
* ``text`` Any text that needs to be QR encoded. It could be a slogan,
|
||||||
|
salutation, url, etc.
|
||||||
|
|
||||||
|
barcode("code", "barcode\_type", width, height, "position", "font")
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Prints a barcode.
|
||||||
|
|
||||||
|
* ``code`` is an alphanumeric code to be printed as bar code
|
||||||
|
* ``barcode_type`` must be one of the following type of codes:
|
||||||
|
|
||||||
|
* UPC-A
|
||||||
|
* UPC-E
|
||||||
|
* EAN13
|
||||||
|
* EAN8
|
||||||
|
* CODE39
|
||||||
|
* ITF
|
||||||
|
* NW7
|
||||||
|
|
||||||
|
* ``width`` is a numeric value in the range between (1,255) *Default:* 64
|
||||||
|
* ``height`` is a numeric value in the range between (2,6) *Default:* 3
|
||||||
|
* ``position`` is where to place the code around the bars, could be one of the following values:
|
||||||
|
|
||||||
|
* ABOVE
|
||||||
|
* BELOW
|
||||||
|
* BOTH
|
||||||
|
* OFF > *Default:* BELOW
|
||||||
|
|
||||||
|
* ``font`` is one of the 2 type of fonts, values could be:
|
||||||
|
|
||||||
|
* A
|
||||||
|
* B > *Default:* A Raises ``BarcodeTypeError``, ``BarcodeSizeError``, ``BarcodeCodeError`` exceptions.
|
||||||
|
|
||||||
|
text("text")
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Prints raw text. Raises ``TextError`` exception.
|
||||||
|
|
||||||
|
set("align", "font", "type", width, height)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Set text properties.
|
||||||
|
* ``align`` set horizontal position for text, the possible values are:
|
||||||
|
|
||||||
|
* CENTER
|
||||||
|
* LEFT
|
||||||
|
* RIGHT > > *Default:* left
|
||||||
|
|
||||||
|
* ``font`` type could be ``A`` or ``B``. *Default:* A
|
||||||
|
* ``type`` type could be ``B`` (Bold), ``U`` (Underline) or ``normal``. *Default:* normal
|
||||||
|
* ``width`` is a numeric value, 1 is for regular size, and 2 is twice the standard size. *Default*: 1
|
||||||
|
* ``height`` is a numeric value, 1 is for regular size and 2 is twice the standard size. *Default*: 1
|
||||||
|
|
||||||
|
cut("mode")
|
||||||
|
^^^^^^^^^^^
|
||||||
|
|
||||||
|
Cut paper.
|
||||||
|
* ``mode`` set a full or partial cut. *Default:* full
|
||||||
|
|
||||||
|
**Partial cut is not implemented in all printers.**
|
||||||
|
|
||||||
|
cashdraw(pin)
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Sends a pulse to the cash drawer in the specified pin.
|
||||||
|
|
||||||
|
* ``pin`` is a numeric value which defines the pin to be used to send the pulse, it could be 2 or 5. Raises ``CashDrawerError()``
|
||||||
|
|
||||||
|
hw("operation")
|
||||||
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Hardware operations.
|
||||||
|
|
||||||
|
* ``operation`` is any of the following options:
|
||||||
|
|
||||||
|
* INIT
|
||||||
|
* SELECT
|
||||||
|
* RESET
|
||||||
|
|
||||||
|
control("align")
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Carrier feed and tabs.
|
||||||
|
* ``align`` is a string which takes any of the following values:
|
||||||
|
|
||||||
|
* LF *for Line Feed*
|
||||||
|
* FF *for Form Feed*
|
||||||
|
* CR *for Carriage Return*
|
||||||
|
* HT *for Horizontal Tab*
|
||||||
|
* VT *for Vertical Tab*
|
||||||
|
|
@ -0,0 +1,42 @@
|
||||||
|
********
|
||||||
|
Printers
|
||||||
|
********
|
||||||
|
|
||||||
|
.. note:: **TODO** Merge this page into the API-description.
|
||||||
|
|
||||||
|
There 3 different type of printers:
|
||||||
|
|
||||||
|
USB(idVendor, idProduct, interface, in\_ep, out\_ep)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Based on pyusb and libusb-1.0
|
||||||
|
|
||||||
|
* ``idVendor`` is the Vendor ID
|
||||||
|
* ``idProduct`` is the Product ID
|
||||||
|
* ``interface`` is the USB device interface (default = 0)
|
||||||
|
* ``in_ep`` is the input end point (default = 0x82)
|
||||||
|
* ``out_ep`` is the output end point (default = 0x01)
|
||||||
|
|
||||||
|
Serial("devfile", baudrate, bytesize, timeout)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Based on pyserial, default values are based on the defaults set by
|
||||||
|
DIP\_SWITCH\_1 on the documentation(hardware side).
|
||||||
|
|
||||||
|
* ``devfile`` is an alphanumeric device file name under /dev filesystem (default = /ev/ttyS0)
|
||||||
|
* ``baudrate`` is the Baud rate for serial transmission (default = 9600)
|
||||||
|
* ``bytesize`` sets the serial buffer size (default = 8)
|
||||||
|
* ``timeout`` defines Read/Write timeout (default = 1)
|
||||||
|
|
||||||
|
Network("host", port)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Based on socket
|
||||||
|
* ``host`` is an alphanumeric host name, could be either DNS host name or IP address.
|
||||||
|
* ``port`` to write to (default = 9100)
|
||||||
|
|
||||||
|
File("file\_name")
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Printcap printers
|
||||||
|
* ``file_name`` is the full path to the device file name
|
||||||
|
|
@ -0,0 +1,68 @@
|
||||||
|
************
|
||||||
|
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.
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
------------
|
||||||
|
|
||||||
|
First, install the packages available on Raspbian.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# apt-get install python-imaging python-serial python-setuptools
|
||||||
|
|
||||||
|
PyUSB
|
||||||
|
^^^^^
|
||||||
|
|
||||||
|
PyUSB 1.0 is not available on Ubuntu, so you have to download and
|
||||||
|
install it manually
|
||||||
|
|
||||||
|
1. Download the latest tarball from
|
||||||
|
`Sourceforge <http://sourceforge.net/projects/pyusb/files/>`__
|
||||||
|
2. Decompress the zip file
|
||||||
|
3. Install the library
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# wget ...
|
||||||
|
# unzip pyusb*.zip
|
||||||
|
# cd pyusb*
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
python-qrcode
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
1. Checkout the code from github
|
||||||
|
2. Install the library
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# git clone https://github.com/lincolnloop/python-qrcode
|
||||||
|
# cd python-qrcode
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
If you have installed pyusb for libusb-1.0 then you need to:
|
||||||
|
|
||||||
|
1. Download the latest file
|
||||||
|
1. Decompress the file
|
||||||
|
1. Install the library
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# git clone https://github.com/manpaz/python-escpos.git
|
||||||
|
# cd python-escpos
|
||||||
|
# python setup.py build
|
||||||
|
# sudo python setup.py install
|
||||||
|
|
||||||
|
Now you can attach your printer and and test it with the example code in
|
||||||
|
the project's `home <https://github.com/manpaz/python-escpos>`__
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
****
|
||||||
|
TODO
|
||||||
|
****
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
------------
|
||||||
|
|
||||||
|
python-escpos is the initial idea, from here we can start to build a
|
||||||
|
robust library to get most of the ESC/POS printers working with this
|
||||||
|
library.
|
||||||
|
|
||||||
|
Eventually, this library must be able to cover almost all the defined
|
||||||
|
models detailed in the ESC/POS Command Specification Manual.
|
||||||
|
|
||||||
|
Details
|
||||||
|
-------
|
||||||
|
|
||||||
|
What things are planned to work on?
|
||||||
|
|
||||||
|
Testing
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
* Test on many printers as possible (USB, Serial, Network)
|
||||||
|
|
||||||
|
Design
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
* Add all those sequences which are not common, but part of the ESC/POS
|
||||||
|
Command Specifications.
|
||||||
|
|
||||||
|
* Port to Python 3
|
||||||
|
* Windows compatibility (hidapi instead libusb?)
|
||||||
|
* PDF417 support
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,138 @@
|
||||||
|
*****
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
Define your printer
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
USB printer
|
||||||
|
^^^^^^^^^^^
|
||||||
|
|
||||||
|
Before start creating your Python ESC/POS printer instance, you must see
|
||||||
|
at your system for the printer parameters. This is done with the 'lsusb'
|
||||||
|
command.
|
||||||
|
|
||||||
|
First run the command to look for the "Vendor ID" and "Product ID", then
|
||||||
|
write down the values, these values are displayed just before the name
|
||||||
|
of the device with the following format:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
xxxx:xxxx
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# lsusb
|
||||||
|
Bus 002 Device 001: ID 04b8:0202 Epson ...
|
||||||
|
|
||||||
|
Write down the the values in question, then issue the following command
|
||||||
|
so you can get the "Interface" number and "End Point"
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
# lsusb -vvv -d xxxx:xxxx | grep iInterface
|
||||||
|
iInterface 0
|
||||||
|
# lsusb -vvv -d xxxx:xxxx | grep bEndpointAddress | grep OUT
|
||||||
|
bEndpointAddress 0x01 EP 1 OUT
|
||||||
|
|
||||||
|
The first command will yields the "Interface" number that must be handy
|
||||||
|
to have and the second yields the "Output Endpoint" address.
|
||||||
|
|
||||||
|
**USB Printer initialization**
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = printer.Usb(0x04b8,0x0202)
|
||||||
|
|
||||||
|
By default the "Interface" number is "0" and the "Output Endpoint"
|
||||||
|
address is "0x01", if you have other values then you can define with
|
||||||
|
your instance. So, assuming that we have another printer where in\_ep is
|
||||||
|
on 0x81 and out\_ep=0x02, then the printer definition should looks like:
|
||||||
|
|
||||||
|
**Generic USB Printer initialization**
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Generic = printer.Usb(0x1a2b,0x1a2b,0,0x81,0x02)
|
||||||
|
|
||||||
|
Network printer
|
||||||
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
You only need the IP of your printer, either because it is getting its
|
||||||
|
IP by DHCP or you set it manually.
|
||||||
|
|
||||||
|
**Network Printer initialization**
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = printer.Network("192.168.1.99")
|
||||||
|
|
||||||
|
Serial printer
|
||||||
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Must of the default values set by the DIP switches for the serial
|
||||||
|
printers, have been set as default on the serial printer class, so the
|
||||||
|
only thing you need to know is which serial port the printer is hooked
|
||||||
|
up.
|
||||||
|
|
||||||
|
**Serial printer initialization**
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = printer.Serial("/dev/tty0")
|
||||||
|
|
||||||
|
Other printers
|
||||||
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Some printers under /dev can't be used or initialized with any of the
|
||||||
|
methods described above. Usually, those are printers used by printcap,
|
||||||
|
however, if you know the device name, you could try the initialize
|
||||||
|
passing the device node name.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = printer.File("/dev/usb/lp1")
|
||||||
|
|
||||||
|
The default is "/dev/usb/lp0", so if the printer is located on that
|
||||||
|
node, then you don't necessary need to pass the node name.
|
||||||
|
|
||||||
|
Define your instance
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
The following example demonstrate how to initialize the Epson TM-TI88IV
|
||||||
|
on USB interface
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
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()
|
||||||
|
|
||||||
|
How to update your code for USB printers
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
Old code
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = escpos.Escpos(0x04b8,0x0202,0)
|
||||||
|
|
||||||
|
New code
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Epson = printer.Usb(0x04b8,0x0202)
|
||||||
|
|
||||||
|
Nothe that "0" which is the interface number is no longer needed.
|
||||||
Loading…
Reference in New Issue