EscaPy is a thoroughly tested tool that reliably and almost exhaustively interprets the ESC/P and ESC/P2 command sets defined by Epson (Wikipedia - Epson ESC/P), then converts the data formerly intended for printers into a modern PDF file.
Open Contents
TL;DR: Your DOS system or emulator will be able to produce searchable PDF files. This tool is compatible with files produced by the Libre Printer interface discussed below.
Nowadays, older equipment may still be in use in sectors such as medical or industrial (machine tools). While the software of the old days were often designed to use dot-matrix printers exclusively, these printers can break down or can no longer be used due to a lack of consumables available on the market.
As a result, the entire system has to be replaced without justification.
EscaPy generates PDF files from the raw data sent to the printer. Files can therefore be stored permanently, printed on new hardware, indexed by an archiving system (text remains accessible) or simply consulted at any time.
Note that data destined for the printer must be captured in some way. The Libre Printer project accomplishes exactly this task by providing a software and hardware interface pretending to be a printer compatible with older hardware.
EscaPy is a project that took ~2 months of full-time work and 12k+ lines including documentation & tests, for its first version. If it has been useful to you in any way and you would like to contribute to its development, please follow the link below, with all thanks :
1EB6dc6YULzHR4TMqLi5fomZ6wmdP3N5cW
Advanced ESC/P ESC/P2 command set support
Nearly all commands are supported (text, graphics and barcodes).
! See details & coverage of the command set !
*: Not recommended command.
‡: Extended command (added on modern printers)
✅: Implemented.
❗: Not fully implemented.
⬜: Not implemented.
🚫: Will not be implemented.Setting the page format ESC ( C Set page length in defined unit ✅ ESC ( c Set page format ✅ ESC C Set page length in lines ✅ ESC C NUL Set page length in inches ✅ ESC N Set bottom margin ✅ ESC O Cancel bottom margin ✅ ESC Q Set right margin ✅ ESC l Set left margin ✅ ESC ( S Set paper dimensions‡ ✅ Moving the print position CR Carriage return ✅ LF Line feed ✅ FF Form feed ✅ ESC $ Set absolute horizontal print position ✅ ESC ( $ Set absolute horizontal print position‡ ✅ ESC \ Set relative horizontal print position ✅ ESC ( / Set relative horizontal print position‡ ✅ ESC ( V Set absolute vertical print position ✅ ESC ( v Set relative vertical print position ✅ ESC J Advance print position vertically ✅ HT Tab horizontally ✅ VT Tab vertically ✅ ESC f Horizontal/vertical skip* ✅ BS Backspace* ✅ Setting the units ESC ( U Set unit ✅ ESC 0 Select 1/8-inch line spacing ✅ ESC 2 Select 1/6-inch line spacing ✅ ESC 3 Set n/180-inch line spacing ✅ ESC 3 Set n/216-inch line spacing ✅ ESC + Set n/360-inch line spacing ✅ ESC A Set n/60-inch line spacing* ✅ ESC A Set n/72-inch line spacing* ✅ ESC 1 Select 7/72-inch line spacing* ✅ ESC D Set horizontal tabs ✅ ESC B Set vertical tabs ✅ ESC b Set vertical tabs in VFU channels* ⬜ ESC / Select vertical tab channel* ⬜ ESC e Set fixed tab increment* ✅ ESC a Select justification* ⬜ Selecting characters ESC ( t Assign character table ✅ ESC t Select character table ✅ ESC R Select an international character set ✅ ESC & Define user-defined characters ❗ ESC : Copy ROM to RAM ✅ ESC % Select user-defined set ✅ ESC x Select LQ or draft ✅ ESC x Select NLQ or draft ✅ ESC k Select typeface ✅ ESC X Select font by pitch and point ✅ ESC c Set horizontal motion index (HMI) ✅ ESC P Select 10.5-point, 10-cpi ✅ ESC P Select 10-cpi ✅ ESC M Select 10.5-point, 12-cpi ✅ ESC M Select 12-cpi ✅ ESC g Select 10.5-point, 15-cpi ✅ ESC g Select 15-cpi ✅ ESC p Turn proportional mode on/off ✅ ESC SP Set intercharacter space ✅ ESC E Select bold font ✅ ESC F Cancel bold font ✅ ESC 4 Select italic font ✅ ESC 5 Cancel italic font ✅ ESC ! Master select ✅ ESC G Select double-strike printing ✅ ESC H Cancel double-strike printing ✅ ESC - Turn underline on/off ✅ ESC ( - Select line/score ✅ ESC S Select superscript/subscript printing ✅ ESC T Cancel superscript/subscript printing ✅ ESC q Select character style ✅ SI Select condensed printing ✅ ESC SI Select condensed printing* ✅ DC2 Cancel condensed printing ✅ SO Select double-width printing (one line) ✅ ESC SO Select double-width printing (one line)* ✅ DC4 Cancel double-width printing (one line) ✅ ESC W Turn double-width printing on/off ✅ ESC w Turn double-height printing on/off ✅ Control-code character printing ESC ( ^ Print data as characters ✅ ESC 6 Enable printing of upper control codes ✅ ESC 7 Enable upper control codes ✅ ESC I Enable printing of control codes ✅ ESC m Select printing of upper control codes* ✅ Mechanical control ESC EM Control paper loading/ejecting ✅ ESC U Turn unidirectional mode on/off 🚫 ESC < Unidirectional mode (one line)* 🚫 BEL Beeper* 🚫 ESC 8 Disable paper-out detector* 🚫 ESC 9 Enable paper-out detector* 🚫 ESC s Select low-speed mode* 🚫 Printing color and graphics ESC ( G Select graphics mode ✅ ESC . 0 / ESC . 1 Print raster graphics ✅ ESC . 2 Enter TIFF RLE compressed mode ✅ ESC . 3 Enter TIFF Delta Row compressed mode‡ ✅ ESC * Select bit image ✅ ESC ? Reassign bit-image mode* ✅ ESC K Select 60-dpi graphics* ✅ ESC L Select 120-dpi graphics* ✅ ESC Y Select 120-dpi, double-speed graphics* ✅ ESC Z Select 240-dpi graphics* ✅ ESC ^ Select 60/120-dpi, 9-pin graphics ✅ ESC r Select printing color ✅ ESC ( r Select printing color‡ ✅ ESC ( D Set raster resolution‡ ✅ ESC i Transfer raster image‡ ✅ Printing method control ESC ( i Select MicroWeave print mode ✅ ESC ( e Select Ink Drop Size‡ ⬜ ESC ( K Set monochrome/color mode‡ ✅ ESC ACK Flush buffers after MicroWeave print mode‡ 🚫 ESC ( m Set print method‡ 🚫 Printing bar codes ESC ( B Bar code setup and print ✅ Data and memory control ESC SOH @EJL 1284.4\n@EJL \n Exit packet mode ✅ ESC SOH @EJL 1284.4\n@EJL\n@EJL\n Enter D4 mode ✅ ESC @ Initialize printer ✅ CAN Cancel line* ⬜ DEL Delete last character in buffer* ⬜ DC1 Select printer* 🚫 DC3 Deselect printer* 🚫 ESC # Cancel MSB control* ⬜ ESC = Set MSB to 0* ⬜ ESC > Set MSB to 1* ⬜ Deleted commands ESC j Reverse paper feed* 🚫 ESC i Select immediate print mode* 🚫 Binary mode commands for ESC . 2 & ESC . 3 raster graphics modes <XFER>Transfer raster graphics data ✅ <CLR>Clear seed row (Delta Row compression)‡ ✅ <MOVX>Set relative horizontal position ✅ <MOVY>Set relative vertical position ✅ <COLR>Select printing color ✅ <CR>Carriage return to left-most print position ✅ <EXIT>Exit TIFF compressed mode ✅ <MOVXBYTE>Set unit to 8 dots ✅ <MOVXDOT>Set unit to 1 dot ✅ Remote commands (all commands are supported, but only a few useful ones are implemented.) ESC ( R Set remote mode‡ ✅ ESC NUL NUL NUL Exit remote mode‡ ✅ RS Reset printer‡ ✅ FP Set relative left margin‡ ✅ JH Set job name‡ ✅ JS Start job‡ ✅ Advanced font support
Specify in advance the fonts you wish to use. 14 different fonts can be specified, each in 2 versions (fixed and proportional fonts), for a total of 28 fonts.
Use system-installed or custom fonts.
Text enhancements (strikethrough, underline, highlight, etc.) are supported.
Fonts examples & character style implementations.Several rendering modes for graphic commands
Points can be rendered as dots or rectangles. In all cases, the file is vectorized (infinitely scalable).
Graphic element magnifications. Two ways of rendering.
Delta Row compression with 720p rendering.NB: Rendering as an image is not yet available, but such a result can be obtained with GhostScript for this task (see examples).
Note regarding color rendering: When two CMYK colored objects overlap in printing, then either the object 'on top' will knock out the color of the one underneath it, or the colors of the two objects will mix in the overlapped area. This behaviour can be set using the property overPrint of your PDF viewer. This is mandatory for a good rendering of the PDF files built by Escapy.
On Okular, since June 2023, the option is under the “Configure Rendering Engines” / “Enable Overprint Preview”Searchable text
Text remains as text, not as images. This makes content search and indexing possible.
Wide range of encodings available
A major effort has been made to ensure that the essential encodings of this era and more, are also supported by EscaPy. It's easy to add to this list. Contributions are welcome.
Characters that can be printed in the place of the intervals dedicated to control characters, and international characters (National Replacement Character Set) are also injected into the encoding tables.
Support for many common encodings.NB: It is still necessary to ensure that the fonts used support the selected character sets.
See details
- PC437 (US)
- PC437 Greek
- PC932 (Japanese)
- PC850 (Multilingual)
- PC851 (Greek)
- PC853 (Turkish)
- PC855 (Cyrillic)
- PC860 (Portugal)
- PC863 (Canada-French)
- PC865 (Norway)
- PC852 (East Europe)
- PC857 (Turkish)
- PC862 (Hebrew)
- PC864 (Arabic)
- PC AR864
- PC866 (Russian)
- (Bulgarian ASCII****)
- PC866 LAT. (Latvian)
- PC869 (Greek)
- USSR GOST (Russian)
- ECMA-94-1
- KU42 (K.U. Thai)
- TIS11 (TS 988 Thai)
- TIS18 (GENERAL Thai)
- TIS17 (SIC STD. Thai)
- TIS13 (IBM STD. Thai)
- TIS16 (SIC OLD Thai)
- PC861 (Iceland)
- BRASCII
- Abicomp
- MAZOWIA (Poland)
- Code MJK (CSFR)
- ISO8859-7 (Latin/Greek)
- ISO8859-1 (Latin 1)
- TSM/WIN (Thai system manager)
- ISO Latin 1T (Turkish)
- Bulgaria
- Hebrew 7
- Hebrew 8
- Roman 8
- PC774 (Lithuania)
- Estonia (Estonia)
- ISCII
- PC-ISCII
- PC APTEC
- PC708
- PC720
- OCR-B
- ISO Latin 1
- ISO 8859-2 (ISO Latin 2)
- ISO Latin 7 (Greek)
Page formats
47 portrait formats and their landscape equivalents are predefined. Custom sizes are also available.
User-defined characters support (ESC/P2 only)
A user can send customized bitmap characters to the printer. A mapping file will be generated to map the received characters to modern unicode codes (see examples).
Enhanced reliability thanks to testing (~100%)
EscaPy is an implementation of a standard made up of over 600 pages covered by almost 300 tests.
A coverage rate close to 100% eliminates most of the erratic behavior that a non-rigorously tested application can produce.
However, a coverage rate of 100% does not guarantee that the program rigorously follows the standard, but that its behavior is most often in line with what the developer expected when he designed it.
Facilitated development
The code is fully documented to facilitate maintenance and enhancements.
All operating systems should be supported, although this project is mainly developed for a GNU-Linux system as an everyday computer.
Simple installation from PyPI (beware, the package name is not the project name!):
$ pip install pyscapeInstallation from sources :
$ pip install .Install the project in editable mode for developpers :
$ make install
# Or
$ pip install -e .[dev]Installation on Debian :
- Download the
.debfile in the releases section of this repo. - Then :
apt install ./escapy_1.0.0-2_all.deb$ escapy -h
usage: [-h] [--pins [PINS]] [--single_sheets | --no-single_sheets] [-o [OUTPUT]]
[-c [CONFIG]] [-db [USERDEF_DB_FILEPATH]] [-v]
esc_prn
positional arguments:
esc_prn ESC raw printer file. - to read from stdin.
options:
-h, --help show this help message and exit
--pins [PINS] number of needles of the print head (9, 24, 48). Leave it unsetfor ESCP2 modern printers. (default: unset)
--single_sheets, --no-single_sheets
single-sheets or continuous paper. (default: single-sheets)
-o [OUTPUT], --output [OUTPUT]
PDF output file. - to write on stdout. (default: output.pdf)
-c [CONFIG], --config [CONFIG]
configuration file to use. (default: ./escapy.conf,
~/.local/share/escapy/escapy.conf)
-db [USERDEF_DB_FILEPATH], --userdef_db_filepath [USERDEF_DB_FILEPATH]
mappings between user-defined chararacter codes and unicode.
(default: ./user_defined_mapping.json)
-v, --version show program's version number and exitNB : The configuration file supplied by the application contains all the information needed to configure the virtual printer (margins, page formats, etc.), fonts and folders.
Standard input/output streams are active, so it is possible to chain tools :
$ cat my_file.prn | escapy - -o - > my_pdf.pdfFor example, to convert the generated PDF into a TIFF image with GhostScript :
$ cat my_file.prn | escapy - -o - | \
gs -dBATCH -dNOPAUSE -dSAFER \
-dNoSeparationFiles -dSimulateOverprint=true -sDEVICE=tiffsep -r720 \
-sOutputFile=out-%d.tiff -The configuration file supplied by the application contains all the information needed to configure the virtual printer (margins, page formats, etc.), fonts and folders.
By default, the escapy.conf file is searched for in the current folder.
If it doesn't exist, it is searched for in the standard software configuration
folder on your system (see below).
This folder is created if it doesn't already exist.
On GNU/Linux systems:
~/.local/share/escapy/, /etc/escapy/escapy.conf
On Windows systems:
C:\\Users\\<YOUR_USERNAME>\\AppData\\Local\\escapy
On MacOS systems:
/Users/<YOUR_USERNAME>/Library/Application Support/escapy
The default file is in the repository folder: data.
Profile example:
[colors]
0 = black
[color:black]
display = Black
offset = 120
rgb = #000000
cmyk = 0,0,0,100
[color:black:mono]
offset = 0
Profiles are files stored by default in a profiles folder next to the
default configuration file installed on the system (see above).
They contain a section listing the colors used by the printer, as well as a section defining each of these colors as follows.
Expected keys in each color section:
- rgb: RGB color code (starting with a #);
- cmyk: CMYK channels (4 coma separated values).
Optional keys:
- display: Human readable name;
- offset: Nozzle position adjustement offset (in 1/180th of an inch).
Regarding nozzle offsets:
Most Epson print heads align all color nozzles on the same horizontal line.
However, some models use one color as a reference, with the other color
nozzles physically offset from it.
We need to compensate for the data generated by the driver in order to determine the correct position of the received colored data.
Depending on whether monochrome or color mode is selected, the range of nozzles may vary. That's why each color can be found in a dedicated monochrome version.
For reasons of licensing and personal preference, EscaPy does not embed fonts (except for a minimal version of Courier and Helvetica).
List of fonts that can be embedded in Epson printers
- Roman
- Sans serif
- Courier
- Prestige
- Script
- OCR-B
- OCR-A
- Orator
- Orator-S
- Script C
Free fonts a proprietary equivalents :
| Proprietary | Free -> | ||||
|---|---|---|---|---|---|
| Courier New | Liberation Mono | Noto Sans Mono | FreeMono | Fira Mono, Fira Code | Roboto Mono |
| Times New Roman | Liberation Serif | Noto Serif | FreeSerif | FiraGO | Roboto Serif |
| Arial | Liberation Sans | Noto Sans | FreeSans | Fira Sans | Roboto |
| OCR-A / OCR-B fonts | Square stroke ends OCR-A & OCR-B | Rounded ends & extended character coverage OCR-B |
See also Recursive free font :
Free bitmap-style fonts :
Non-free fonts or fonts with restrictive licenses, often with a very limited character set, but close to the embedded fonts on Epson printers :
- Script C
- Romant
- Prestige
- OCR-A
- OCR-B
- Dotrice (nice dotmatrix style, needs a conversion to the TTF format via fontforge or online tools like everythingfonts).
Noto, FreeFont and Fira fonts are normally installed on most systems, but can also be installed manually with the following command (on Debian systems and derivatives):
$ apt install fonts-noto fonts-freefont-ttf fonts-firacodeThe same goes for Liberation fonts:
$ apt install fonts-liberationWindows proprietary fonts can be installed with the following command:
$ apt install ttf-mscorefonts-installerMore generally, think of the fnt tool as a package manager for managing and
installing fonts.
A JSON file is created and updated when custom characters are found. The user must specify the desired character in the unicode character set. The changes will be applied to the PDF by restarting the software.
Example:
{
"83e1a70_1": {
"mode": 1,
"proportional_spacing": false,
"scripting": null,
"1": "\ufffd"
}
}
Here, a character is defined under the unique key 83e1a70_1;
the character with code 1 in the table is momentarily associated with
the undefined character \ufffd (UNDEFINED).
A modification to match this code with the character ♫ could be as follows:
{
"83e1a70_1": {
"mode": 1,
"proportional_spacing": false,
"scripting": null,
"1": "♫"
}
}
By default, the JSON file (user_defined_mapping.json) is created in the current
folder, but this can be changed in the configuration file.
A folder containing the image of the bitmap character received can also be created
by enabling the option images_path in the section [UserDefinedCharacters] of
the configuration file.
The ESC/P and ESC/P2 standards do not seem to support Chinese or Japanese languages (encodings were apparently not provided for). However, some language evolutions (ESC/POS, ESC/P-K, ESC/P J84) and printers do support this. While in theory these languages can be implemented, their documentation remains hard to find and is beyond the scope of the current project. See Wikipedia - ESC variants.
The easiest way to achieve this is to use the printer in graphics mode (raster or bitimage) instead of text mode.
The management of modern fonts and their display on our screens would not have been possible without the work of French engineer Pierre Bézier (1910-1999), who also, through his work at Renault, revolutionized computer-aided design (CAD).
The Epson-Seiko teams of the 90's deserve our thanks for producing complete documentation of the language interpreted by their printers.
Since the 2010s, Epson-Seiko (like so many other brands) tends to no longer publish language evolutions or advanced technical specifications for their machines. The brand tends to consider that this is now an industrial secret and none of your business.
In an ethical world, we wouldn't have to decipher these proprietary protocols. If you too feel that this is not appropriate, then you should consider manufacturers who respect your right to repair/modify what you own.
This project is open for any contribution! Any bug report can be posted by opening an issue.
EscaPy is distributed under two licenses: one for community use and the other for commercial use.
EscaPy is released under the AGPL (Affero General Public License).
The aim is to limit the uses integrated into proprietary devices whose vendors do not participate in the project in an equitable way, and who are guilty of any violation of the EscaPy license or of the free software used by EscaPy itself.
If you are interested in this license, please contact us.