.. _zpl-index: ######### ZPL Guide ######### The ZPL (Zebra Programming Language) support in |trademark| 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 :file:`nc.exe` was extracted (using the password ``nc``) to :file:`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 :ref:`virtualprinter`. The ZPL code below was sent to both printers with the font name being the only difference: .. code-block:: zpl ^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 .. figure:: /media/triumvirate.png Rendered on a Zebra printer .. figure:: /media/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. .. csv-table:: :header: 203 dpi, 300 dpi, Comment :widths: 10, 10, 60 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 :menuselection:`SETTINGS --> Print Jobs --> Protocol Emulation --> Unsupported Command Behavior` ==================== Enable ZPL Emulation ==================== Enable and configure the ZPL emulation under :ref:`item-protocol_emulation`. Check Connection ================ After a restart, check that the protocol is enabled by connecting to the printer's IP address at port 9100. .. code-block:: doscon C:\Users\Evo\Desktop>nc 9100 When the ZPL protocol is enabled, and a client is connected to port 9100 the text :menuselection:`ZPL client from x.x.x.x` will be displayed under :menuselection:`OPERATION --> CLIENTS`. Press :kbd:`CTRL+C` to close the connection. Note that :menuselection:`CLIENTS` displays *No Connections*. ============== First ZPL Test ============== 1. Copy the example ZPL layout below into a file that is named :file:`first.zpl`. .. code-block:: 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. .. code-block:: doscon C:\Users\Evo\Desktop>nc -w1 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 :menuselection:`SETTINGS --> Files --> Fonts` and expand *Resources To Add*. Locate the font that you want to install and press :guilabel:`+`. 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: .. code-block:: zpl ^XA ^PW400 ^LL80 ^FO10,20^A@N,24,24,E:ARIBLK.TTF ^FDTest with Arial Black^FS ^XZ .. image:: /media/custom_font.zpl.png .. _zpl-metadata: ====================== 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 :ref:`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. .. code-block:: zpl ^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 :term:`unprintable job` .. code-block:: zpl ^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 :ref:`ui:item-scan` sequence configuration. .. code-block:: zpl ^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 .. seealso:: Code Matching :ref:`API Documentation `. Example: Controlling Motorized Stand Position ============================================= Including the special variable ``__stand1-position_mm`` sets the stand position before the job is activated. .. code-block:: zpl ^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 ================== .. csv-table:: :header: Command, Description, Support, Comment :widths: 10, 40, 10, 40 ^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 mode not supported, Manual mode treated as automatic, manual binary mode broken and may be hard to fully support" ^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, "" ^CF, "Change Alphanumeric Default Font", Good, "" ^CI, "Change International Font/Encoding", Good, "Encoding in stored label formats since 20191218" ^CV, "Code Validation", Partial, "Ongoing" ^CW, "Font Identifier", Good, "" ^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. Unsupported: BMP, PCX" ~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 :ref:`zpl-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, "" ^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 20191106" ^PO, "Print Orientation", Full, "" ^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 is not supported" ^XF, "Recall Format", Partial, "Only one ^XF is supported" ^XG, "Recall Graphic", Full, "" ^XZ, "End Format", Good, "ETX is not supported" ================ Ignored Commands ================ These commands are recognized but ignored. .. csv-table:: :header: Command, Description, Support, Comment :widths: 10, 40, 10, 40 ^CC/~CC, "Change Caret", Ignored, "" ^CD/~CD, "Change Delimiter", Ignored, "" ^CO, "Cache On", Ignored, "" ^CT/~CT, "Change Tilde", 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, ""