ZPL Guide¶
The ZPL (Zebra Programming Language) support in Evolabel™ printers provides a way to leverage legacy layouts created for Zebra™ printers.
Intended Audience¶
This document is intended for readers familiar with ZPL, who wants to discover the possibilities to use existing ZPL files with Evolabel systems.
In order to run the examples it is also good to be familiar with:
TCP/IP addresses and ports.
Transferring text files using raw TCP/IP.
In the examples we are using the Windows 10 command prompt to send files using Netcat for Windows. The file
nc.exe
was extracted (using the passwordnc
) toC:\Users\Evo\Desktop>
.
FAQ¶
How much visual difference can I expect?¶
In general you can expect small differences arising from font differences. We have made an effort to make the Trivium font optically similar and metrically compatible with the CG Triumvirate font.
You can check the result on the free online viewer. Note that the online viewer only supports single documents and no store/recall functionality. In order to test more advanced cases, test against a real printer, or use the Virtual Printer.
The ZPL code below was sent to both printers with the font name being the only difference:
^XA
^LH0,0
^PW660
^LL150
^FO10,8^GB650,140, 2,B^FS
^FO20,30^A0N,60,
^FDLorem ipsum 1234567890^FS
^FO20,100^A0N,40,
^FDPrinted with Triumvirate/Trivium font^FS
^XZ
Why do I get parentheses in my human readable?¶
Our GS1-128 barcode generator complies with the GS1 specification that states that human readable text shall have parentheses around the AIs. This only applies for barcodes with automatically generated human readable text.
Can I use my layouts created for 203 dpi?¶
Evolabel printers only use 300 dpi print heads but can scale 203 dpi layouts to 300 dpi. Note that graphical elements, text and so on are scaled from 203 to 300 dpi, but barcodes must be scaled from 200 to 300 dpi, as scaling must be uniformly performed.
The worst case errors for different barcode expansions are listed below. Note that for variable ratio barcodes the errors are often less.
203 dpi | 300 dpi | Comment |
---|---|---|
1 | 1 | 32% smaller. Poor but not used in practice. |
2 | 3 | 1.5% larger. Good |
3 | 4 | 9.8% smaller. Noticeable |
4 | 6 | 1.5% larger. Good |
5 | 7 | 5,3% smaller. Noticeable |
6 | 9 | 1.5% larger. Good |
7 | 10 | 3.3% smaller. Hardly noticeable |
8 | 12 | 1.5% larger. Good |
Can I prevent parse errors for unsupported ZPL commands?¶
It is possible to turn off the Parse error warning under
Enable ZPL Emulation¶
Enable and configure the ZPL emulation under Protocol Emulation.
Check Connection¶
After a restart, check that the protocol is enabled by connecting to the printer’s IP address at port 9100.
C:\Users\Evo\Desktop>nc <printer ip> 9100
When the ZPL protocol is enabled, and a client is connected to port 9100 the text
will be displayed under .Press CTRL+C to close the connection.
Note that
displays No Connections.First ZPL Test¶
Copy the example ZPL layout below into a file that is named
first.zpl
.^XA ^LH0,0 ^LL200 ^PW400 ^FO50,20 ^FDFirst ZPL Test^FS ^XZ
Send it to the printer and check that the preview displays a label with
First ZPL Test
in monospaced font.C:\Users\Evo\Desktop>nc -w1 <printer ip> 9100 < first.zpl
Fonts¶
Evolabel printers are using the TriviumCondensed Bold font to emulate the Zebra CG Triumvirate font, and the Liberation Mono font for monospaced fonts. It is also possible to install your own TrueType fonts. A large number of high quality free and open source fonts can be found at Google Fonts.
Note
Please ensure that you have the necessary legal rights to use the font in a printer before proceeding to installing it.
Install Font¶
- Insert a USB drive with a TrueType font.
- Navigate to +. and expand Resources To Add. Locate the font that you want to install and press
Use Installed Font in a ZPL Layout¶
Fonts can be referenced with the ^A@
command using the font filename. The
file name is case insensitive.
Example:
^XA
^PW400
^LL80
^FO10,20^A@N,24,24,E:ARIBLK.TTF
^FDTest with Arial Black^FS
^XZ
Including Job Metadata¶
By using a specially formatted ZPL comment it is possible to send job metadata like a custom job id and external settings. This can be used for identifying the job via JSON-RPC, selecting a profile or controlling a motorized stand.
The metadata is embedded as a JSON dict in the ZPL comment (^FX
command). If the comment starts with {
it is parsed as JSON and the result is used as job variables.
Note
- JSON data must not contain
^
or~
- JSON
\uxxxx
notation should be used for non ASCII data - The
^FX
command must be part of a label format (between^XA
and^XZ
) - Variables from multiple
^FX
commands are merged.
Example: Activate Profile¶
Including the special variable __profile__
activates the specified profile.
^XA
^LH0,0
^LL200
^PW400
^FX{"_custom_job_id": "job_abc1", "__profile__": "profile1"}
^FO50,20
^FDTest with job variables^FS
^XZ
This example sets the job id to job_abc1
and activates the profile profile1
.
Example: Unprintable Job¶
Including the special variable _printable
and setting it to false
creates an
unprintable job
^XA
^FX{"_custom_job_id": "job_abc2", "_printable": false}
^XZ
Example: Expected Data For Code Matching¶
Including the special variable _code_matching
allows explicitly setting expected
data used for Code Matching Validation in the Scan sequence configuration.
^XA
^BY10
^FO020,55^BIN,100,Y,N^FD12345^FS
^FO40,230^BQN,2,10^FDLA,1234567890123456789012345678901234567890^FS
^FX Exact Match Data for label verification ^FS
^FX{"_code_matching":{"expected":[["1234567890123456789012345678901234567890","12345"]]}}^FS
^XZ
See also
Code Matching API Documentation.
Example: Controlling Motorized Stand Position¶
Including the special variable __stand1-position_mm
sets the stand position before the
job is activated.
^XA
^LH0,0
^LL200
^PW400
^FX{"_custom_job_id": "job_abc1", "__stand1-position_mm": 800}
^FO50,20
^FDTest at stand position 800^FS
^XZ
Supported Commands¶
Command | Description | Support | Comment |
---|---|---|---|
^A | Scalable/Bitmapped Font | Good | |
^A@ | Use Font Name to Call Font | Good | |
^B0 | Aztec Bar Code | Good | |
^B1 | Code 11 Bar Code | Full | |
^B2 | Interleaved 2 of 5 Bar Code | Full | |
^B3 | Code 39 Bar Code | Full | |
^B7 | PDF417 Bar Code | Good | |
^B8 | EAN-8 Bar Code | Full | |
^B9 | UPC-E Bar Code | Good | Does not support eliminating check digit from human readable. We fail on UPC codes with too few 0s even if CV is N |
^BA | Code 93 Bar Code | Good | e ignored, will not print check characters |
^BC | Code 128 Bar Code (Subsets A, B, and C) | Good | |
^BD | UPS MaxiCode Bar Code | Good | Implemented Zebra-like truncation in 20181023-160714 |
^BE | EAN-13 Bar Code | Full | |
^BI | Industrial 2 of 5 Bar Codes | Full | |
^BJ | Standard 2 of 5 Bar Code | Full | |
^BK | ANSI Codabar Bar Code | Full | Libraries, blood banks |
^BM | MSI Bar Code | Good | e2 ignored, always prints check digits in interpretation |
^BO | Aztec Bar Code | Good | |
^BQ | QR Code Bar Code | Good | Mixed/manual mode and structured append since 20240115 |
^BR | GS1 Databar (formerly RSS) | Good | Since 0.28.0 |
^BS | UPC/EAN Extensions | Full | ISBN barcodes |
^BU | UPC-A Bar Code | Good | Does not support eliminating check digit from human readable |
^BX | Data Matrix Bar Code | Good | |
^BY | Bar Code Field Default | Good | |
^CC/~CC | Change Caret | Full | Since 20240820. RS also supported. |
^CD/~CD | Change Delimiter | Full | Since 20240820. US also supported. |
^CF | Change Alphanumeric Default Font | Good | |
^CI | Change International Font/Encoding | Good | Encoding in stored label formats since 0.27.1 |
^CT/~CT | Change Tilde | Full | Since 20240820. DLE also supported. |
^CV | Code Validation | Partial | Ongoing |
^CW | Font Identifier | Good | |
~DB | Download Bitmap Font | Good | Converted to TrueType, supported since 20240226 |
^DF | Download Format | Good | |
~DG | Download Graphics | Good | ASCII HEX, ZB64 supported |
~DU | Download Unbounded TrueType Font | Good | ASCII HEX, ZB64 supported |
~DY | Download Objects | Partial | PNG and GRF supported. BMP, PCX and TrueType since 20240226 |
~EG | Erase Graphics | Partial | Only supports deleting graphics from RAM |
^EG | Erase Graphics | Partial | Only supports deleting graphics from RAM |
^FB | Field Block | Good | Unsupported: e (hanging indent) |
^FC | Field Clock | Full | |
^FD | Field Data | Good | |
^FH | Field Hexadecimal Indicator | Good | |
^FN | Field Number | Good | |
^FO | Field Origin | Good | Auto justification is not supported |
^FP | Field Parameter | Partial | Since 0.29.4. Reverse and vertical printing supported for static text only. |
^FR | Field Reverse Print | Full | |
^FS | Field Separator | Full | |
^FT | Field Typeset | Good | Auto justification is not supported |
^FV | Field Variable | Partial | Variable data using ^MCN supported |
^FW | Field Orientation | Good | Auto justification is not supported |
^FX | Comment | Good | See Including Job Metadata |
^GB | Graphic Box | Good | Rounded corners are not supported |
^GC | Graphic Circle | Full | |
^GD | Graphic Diagonal Line | Full | |
^GE | Graphic Ellipse | Full | |
^GF | Graphic Field | Good | ASCII HEX, ZB64, binary |
^GS | Graphic Symbol | Good | Limited to a single symbol |
~HI | Host Identification | Partial | Reports static information |
~HS | Host Status Return | Partial | Paper out and ribbon out supported |
^HW | Host Directory List | Good | Since 0.29.4 |
^ID | Object Delete | Partial | Only supports deleting images from RAM |
^IL | Image Load | Full | |
^IM | Image Move | Full | |
^IS | Image Save | Good | |
~JA | Cancel All | Good | |
^JM | Set Dots per Millimeter | Partial | Only ^JMA is supported |
^LH | Label Home | Full | |
^LL | Label Length | Full | |
^LR | Label Reverse Print | Full | |
^MC | Map Clear | Partial | Variable data with ^MCN and ^FV is supported |
^MT | Media Type | Full | |
^MU | Set Units of Measurement | Partial | mm and inches supported since 0.27.0 |
^PO | Print Orientation | Full | |
^PM | Printing Mirror Image of Label | Partial | Only ^PMN is supported |
^PQ | Print Quantity | Good | Pause, cut, replicates, override pause count, cut on error are not applicable |
^PR | Print Rate | Good | Slew speed will be ignored |
^PW | Print Width | Full | |
~SD | Set Darkness | Good | Does not take ^MD into account |
^SF | Serialization Field (with a Standard ^FD String) | Partial | Numeric only |
^SN | Serialization Data | Partial | Numeric only |
^SO | Set Offset (for Real-Time Clock) | Full | |
^ST | Set Date and Time (for Real-Time Clock) | Full | Since 0.28.4 |
^SZ | Set ZPL Mode | Partial | Only ZPL II is supported |
^TB | Text Blocks | Good | |
^XA | Start Format | Good | STX supported since 20240820 |
^XF | Recall Format | Partial | Only one ^XF is supported |
^XG | Recall Graphic | Full | |
^XZ | End Format | Good | ETX supported since 20240820 |
Ignored Commands¶
These commands are recognized but ignored.
Command | Description | Support | Comment |
---|---|---|---|
^CO | Cache On | Ignored | |
^FA | Field Allocate | Ignored | |
~HQ | Host Query | Ignored | |
^JJ | Set Auxiliary Port | Ignored | |
~JN | Head Test Fatal | Ignored | |
~JO | Head Test Non-Fatal | Ignored | |
~JS | Change Backfeed Sequence | Ignored | |
^JU | Configuration Update | Ignored | |
^JV | Undocumented | Ignored | |
^JZ | Reprint After Error | Ignored | |
^LS | Label Shift | Ignored | |
^LT | Label Top | Ignored | |
^MD | Media Darkness | Ignored | |
^MF | Media Feed | Ignored | |
^ML | Maximum Label Length | Ignored | Since 2023-12-04 |
^MM | Print Mode | Ignored | |
^MN | Media Tracking | Ignored | |
^MS | Undocumented | Ignored | |
^PA | Advanced Text Properties | Ignored | |
^PP/~PP | Programmable Pause | Ignored | Since 0.29.4 |
~PS | Print Start | Ignored | Since 0.29.4 |
^RR | Specify RFID Retries for a Block or Enable Adaptive Antenna Selection | Ignored | |
^RS | Set Up RFID Parameters | Ignored | |
^SL | Set Mode and Language (for Real-Time Clock) | Ignored | |
~TA | Tear-off Adjust Position | Ignored |