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 password nc) to C:\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
../_images/triumvirate.png

Rendered on a Zebra printer

../_images/trivium.png

Rendered on an Evolabel printer

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 SETTINGS ‣ Print Jobs ‣ Protocol Emulation ‣ Unsupported Command Behavior

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 ZPL client from x.x.x.x will be displayed under OPERATION ‣ CLIENTS.

Press CTRL+C to close the connection.

Note that CLIENTS displays No Connections.

First ZPL Test

  1. 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
    
  2. 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

  1. Insert a USB drive with a TrueType font.
  2. Navigate to SETTINGS ‣ Files ‣ Fonts 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
../_images/custom_font.zpl.png

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