mirror of
https://github.com/python-escpos/python-escpos
synced 2025-10-23 09:30:00 +00:00
modernize and cleanup documentation (#542)
* disable system packages on rtd * install pycups on rtd * enable cups binding in documentation * document CupsPrinter * fix formatting * revise methods and installation * revise user/printers * revise raspi section * further revise
This commit is contained in:
Patrick Kanzler
@@ -1,19 +1,29 @@
|
||||
Printing Barcodes
|
||||
-----------------
|
||||
|
||||
:Last Reviewed: 2023-05-16
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
Many printers implement barcode printing natively.
|
||||
This hardware renderered barcodes are fast but the supported formats are limited by the printer itself and different between models.
|
||||
However, almost all printers support printing images, so barcode renderization can be performed externally by software and then sent to the printer as an image.
|
||||
As a drawback, this operation is much slower and the user needs to know and choose the image implementation method supported by the printer's commandset.
|
||||
This hardware renderered barcodes are fast but the supported
|
||||
formats are limited by the printer itself and different between models.
|
||||
However, almost all printers support printing images, so barcode
|
||||
rendering can be performed externally by software and then sent
|
||||
to the printer as an image.
|
||||
As a drawback, this operation is much slower and the user needs
|
||||
to know and choose the image implementation method supported by
|
||||
the printer's commandset.
|
||||
|
||||
barcode-method
|
||||
~~~~~~~~~~~~~~
|
||||
Since version 3.0, the ``barcode`` method unifies the previous ``barcode`` (hardware) and ``soft_barcode`` (software) methods.
|
||||
It is able to choose automatically the best printer implementation for barcode printing based on the capabilities of the printer and the type of barcode desired.
|
||||
To achieve this, it relies on the information contained in the escpos-printer-db profiles.
|
||||
The chosen profile needs to match the capabilities of the printer as closely as possible.
|
||||
Since version 3.0, the ``barcode`` method unifies the previous
|
||||
``barcode`` (hardware) and ``soft_barcode`` (software) methods.
|
||||
It is able to choose automatically the best printer implementation
|
||||
for barcode printing based on the capabilities of the printer
|
||||
and the type of barcode desired.
|
||||
To achieve this, it relies on the information contained in the
|
||||
escpos-printer-db profiles.
|
||||
The chosen profile needs to match the capabilities of the printer
|
||||
as closely as possible.
|
||||
|
||||
.. py:currentmodule:: escpos.escpos
|
||||
|
||||
@@ -33,4 +43,5 @@ For alphanumeric CODE128 you have to preface your payload with `{B`.
|
||||
# print CODE128 012ABCDabcd
|
||||
p.barcode("{B012ABCDabcd", "CODE128", function_type="B")
|
||||
|
||||
A very good description on CODE128 is also on `Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.
|
||||
A very good description on CODE128 is also on
|
||||
`Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.
|
||||
|
||||
@@ -1,24 +1,31 @@
|
||||
.. _user_installation:
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
:Last Reviewed: 2016-07-23
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
Installation with PIP
|
||||
---------------------
|
||||
Installation should be rather straight-forward. python-escpos is on PyPi, so you can simply enter:
|
||||
Installation should be rather straight-forward. python-escpos is on PyPi,
|
||||
so you can simply enter:
|
||||
|
||||
::
|
||||
|
||||
pip install python-escpos
|
||||
|
||||
This should install all necessary dependencies. Apart from that python-escpos should also be
|
||||
available as a Debian package. If you want to always benefit from the newest stable releases you should probably
|
||||
install from PyPi.
|
||||
This should install all necessary dependencies. Apart from that
|
||||
python-escpos is for some versions also available as a Debian package.
|
||||
If you want to always benefit from the newest stable releases you should
|
||||
always install from PyPi.
|
||||
If you use the ``--pre`` parameter for ``pip``, you will get the latest
|
||||
pre-release.
|
||||
|
||||
Setup udev for USB-Printers
|
||||
---------------------------
|
||||
1. Get the *Product ID* and *Vendor ID* from the lsusb command
|
||||
``# lsusb Bus 002 Device 001: ID 1a2b:1a2b Device name``
|
||||
``# lsusb Bus 002 Device 001: ID 1a2b:1a2b Device name``.
|
||||
(Or whichever way your system supplies to get the PID and VID.)
|
||||
|
||||
2. Create a udev rule to let users belonging to *dialout* group use the
|
||||
printer. You can create the file
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
Methods
|
||||
=======
|
||||
|
||||
:Last Reviewed: 2017-01-25
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
Escpos class
|
||||
------------
|
||||
|
||||
The core part of this libraries API is the Escpos class.
|
||||
You use it by instantiating a :doc:`printer <printers>` which is a child of Escpos.
|
||||
The core part of the API of this library is the Escpos class.
|
||||
You use it by instantiating a :doc:`printer <printers>` which is a child of Escpos.
|
||||
The following methods are available:
|
||||
|
||||
.. autoclass:: escpos.escpos.Escpos
|
||||
|
||||
@@ -1,15 +1,18 @@
|
||||
Printers
|
||||
========
|
||||
|
||||
:Last Reviewed: 2022-11-25
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
As of now there are 7 different type of printer implementations.
|
||||
As of now there are 8 different types of printer implementations.
|
||||
|
||||
USB
|
||||
---
|
||||
The USB-class uses pyusb and libusb to communicate with USB-based
|
||||
printers. Note that this driver is not suited for USB-to-Serial-adapters
|
||||
and similiar devices, but only for those implementing native USB.
|
||||
printers.
|
||||
|
||||
.. note::
|
||||
This driver is not suited for USB-to-Serial-adapters
|
||||
and similiar devices, but only for those implementing native USB.
|
||||
|
||||
.. autoclass:: escpos.printer.Usb
|
||||
:members:
|
||||
@@ -44,20 +47,24 @@ This driver is based on the socket class.
|
||||
|
||||
Troubleshooting
|
||||
^^^^^^^^^^^^^^^
|
||||
Problems with a network-attached printer can have numerous causes. Make sure that your device has a proper IP address.
|
||||
Often you can check the IP address by triggering the self-test of the device. As a next step try to send text
|
||||
manually to the device. You could use for example:
|
||||
Problems with a network-attached printer can have numerous causes.
|
||||
Make sure that your device has a proper IP address.
|
||||
Often you can check the IP address by triggering the self-test of the device.
|
||||
As a next step try to send text manually to the device.
|
||||
You could use for example:
|
||||
|
||||
::
|
||||
|
||||
echo "OK\n" | nc IPADDRESS 9100
|
||||
# the port number is often 9100
|
||||
|
||||
As a last resort try to reset the interface of the printer. This should be described in its manual.
|
||||
As a last resort try to reset the interface of the printer.
|
||||
This should be described in its manual.
|
||||
|
||||
File
|
||||
----
|
||||
This printer "prints" just into a file-handle. Especially on \*nix-systems this comes very handy.
|
||||
This printer "prints" just into a file-handle.
|
||||
Especially on \*nix-systems this comes very handy.
|
||||
|
||||
.. autoclass:: escpos.printer.File
|
||||
:members:
|
||||
@@ -67,8 +74,8 @@ This printer "prints" just into a file-handle. Especially on \*nix-systems this
|
||||
|
||||
Dummy
|
||||
-----
|
||||
The Dummy-printer is mainly for testing- and debugging-purposes. It stores
|
||||
all of the "output" as raw ESC/POS in a string and returns that.
|
||||
The Dummy-printer is mainly for testing- and debugging-purposes.
|
||||
It stores all of the "output" as raw ESC/POS in a string and returns that.
|
||||
|
||||
.. autoclass:: escpos.printer.Dummy
|
||||
:members:
|
||||
@@ -82,7 +89,10 @@ Supports both local and remote CUPS printers and servers.
|
||||
The printer must be properly configured in CUPS administration.
|
||||
The connector generates a print job that is added to the CUPS queue.
|
||||
|
||||
.. todo:: fix import in documentation
|
||||
.. autoclass:: escpos.printer.CupsPrinter
|
||||
:members:
|
||||
:member-order: bysource
|
||||
:noindex:
|
||||
|
||||
LP
|
||||
----
|
||||
@@ -91,10 +101,19 @@ Supports local and remote CUPS printers.
|
||||
The printer must be properly configured in CUPS administration.
|
||||
The connector spawns a new sub-process where the command lp is executed.
|
||||
|
||||
No dependencies required, but somehow the print queue will affect some print job such as barcode.
|
||||
No dependencies required, but somehow the print queue will affect some
|
||||
print job such as barcode.
|
||||
|
||||
.. autoclass:: escpos.printer.LP
|
||||
:members:
|
||||
:special-members:
|
||||
:member-order: bysource
|
||||
:noindex:
|
||||
|
||||
Win32Raw
|
||||
--------
|
||||
This driver uses a native WIN32 interface of Windows in order to print.
|
||||
Please refer to the code for documentation as this driver is currently
|
||||
not included in the documentation build.
|
||||
|
||||
.. todo:: Include Win32Raw in documentation build
|
||||
|
||||
@@ -1,41 +1,26 @@
|
||||
Raspberry Pi
|
||||
============
|
||||
|
||||
:Last Reviewed: 2017-01-05
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
This instructions were tested on Raspbian Jessie.
|
||||
|
||||
.. warning:: You should **never** directly connect an printer with RS232-interface (serial port) directly to
|
||||
a Raspberry PI or similar interface (e.g. those simple USB-sticks without encasing). Those interfaces are
|
||||
based on 5V- or 3,3V-logic (the latter in the case of Raspberry PI). Classical RS232 uses 12V-logic and would
|
||||
**thus destroy your interface**. Connect both systems with an appropriate *level shifter*.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
First, install the packages available on Raspbian.
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install python3 python3-setuptools python3-pip libjpeg8-dev
|
||||
.. warning:: You should **never** directly connect an printer with RS232-interface
|
||||
(serial port) directly to a Raspberry PI or similar interface
|
||||
(e.g. those simple USB-sticks without encasing).
|
||||
Those interfaces are based on 5V- or 3,3V-logic
|
||||
(the latter in the case of Raspberry PI).
|
||||
Classical RS232 uses 12V-logic and would **thus destroy your interface**.
|
||||
Connect both systems with an appropriate *level shifter*.
|
||||
|
||||
Installation
|
||||
------------
|
||||
You can install by using pip3.
|
||||
|
||||
::
|
||||
|
||||
sudo pip3 install --upgrade pip
|
||||
sudo pip3 install python-escpos
|
||||
The installation should be performed as described in :ref:`user_installation`.
|
||||
|
||||
Run
|
||||
---
|
||||
You need sudo and python3 to run your program.
|
||||
You can run this software as on any other Linux system.
|
||||
|
||||
::
|
||||
|
||||
sudo python3 your-program.py
|
||||
|
||||
Now you can attach your printer and and test it with the example code in the project's set of examples.
|
||||
You can find that in the `project-repository <https://github.com/python-escpos/python-escpos>`__.
|
||||
Attach your printer and test it with the example code in the project's set of examples.
|
||||
You can find that in the
|
||||
`project-repository <https://github.com/python-escpos/python-escpos>`__.
|
||||
|
||||
For more details on this check the :doc:`installation-manual <installation>`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
:Last Reviewed: 2017-06-10
|
||||
:Last Reviewed: 2023-08-10
|
||||
|
||||
Define your printer
|
||||
-------------------
|
||||
|
||||
Reference in New Issue
Block a user