Labelary Engine Documentation
- ZPL Command Support
- ZPL Extensions for Simulating Colored Label Stock
- Configuration via System Properties
1. ZPL Command Support
The Labelary ZPL rendering engine supports most of the ZPL formatting commands; check below to see which commands are supported and which are still being worked on. If there is a specific unsupported command which you would like us to prioritize, feel free to get in touch with us.
Most of the unsupported commands do not affect label formatting (e.g. printer serial communication commands and printer hardware configuration commands). Unsupported commands do not prevent rendering, they are merely skipped.
= Supported
= Unsupported
| ^A font, height, width | Set field font (using font name) | |
| ^A@ orientation, height, width, path | Set field font (using font path) | |
| ^B0 orientation, magnification, eci, size, readerInit, symbols, id | Aztec bar code (alternate command: ^BO) | |
| ^B1 orientation, checkDigit, height, line, lineAbove | Code 11 bar code | |
| ^B2 orientation, height, line, lineAbove, checkDigit | Interleaved 2 of 5 bar code | |
| ^B3 orientation, checkDigit, height, line, lineAbove | Code 39 bar code | |
| ^B4 orientation, heightMultiplier, line, mode | Code 49 bar code | |
| ^B5 orientation, height, line, lineAbove | Planet Code bar code | |
| ^B7 orientation, rowHeight, security, columns, rows, truncate | PDF417 bar code | |
| ^B8 orientation, height, line, lineAbove | EAN-8 bar code | |
| ^B9 orientation, height, line, lineAbove, checkDigit | UPC-E bar code | |
| ^BA orientation, height, line, lineAbove, checkDigit | Code 93 bar code | |
| ^BB orientation, height, checkDigit, columns, rows, mode | Codablock bar code | |
| ^BC orientation, height, line, lineAbove, checkDigit, mode | Code 128 bar code | |
| ^BD mode, position, total | UPS MaxiCode bar code | |
| ^BE orientation, height, line, lineAbove | EAN-13 bar code | |
| ^BF orientation, rowHeight, mode | MicroPDF417 bar code | |
| ^BI orientation, height, line, lineAbove | Industrial 2 of 5 bar code | |
| ^BJ orientation, height, line, lineAbove | Standard 2 of 5 bar code | |
| ^BK orientation, checkDigit, height, line, lineAbove, startChar, stopChar | ANSI Codabar bar code | |
| ^BL orientation, height, lineAbove | LOGMARS bar code | |
| ^BM orientation, checkDigitType, height, line, lineAbove, checkDigit | MSI bar code | |
| ^BO orientation, magnification, eci, size, readerInit, symbols, id | Aztec bar code (alternate command: ^B0) | |
| ^BP orientation, checkDigit, height, line, lineAbove | Plessey bar code | |
| ^BQ orientation, model, magnification, errorCorrection, mask | QR Code bar code (model 2 only; no mixed mode or Kanji) | |
| ^BR orientation, type, magnification, sepHeight, height, segWidth | GS1 DataBar (RSS) bar code | |
| ^BS orientation, height, line, lineAbove | UPC/EAN extension | |
| ^BT orientation, width, widthRatio, height, pdfWidth, pdfHeight | TLC 39 bar code | |
| ^BU orientation, height, line, lineAbove, checkDigit | UPC-A bar code | |
| ^BX orientation, height, quality, columns, rows, format, escape, ratio | Data Matrix bar code (quality 200 only) | |
| ^BY width, widthRatio, height | Bar code field defaults | |
| ^BZ orientation, height, line, lineAbove, type | Postal bar code | |
| ^CC caret | Change caret (alternate command: ~CC) | |
| ^CD delim | Change delimiter (alternate command: ~CD) | |
| ^CF fontName, height, width | Change default font | |
| ^CI charset, src1, dest1, src2, dest2, ... | Change encoding (charsets 0-13, 15, 27, 28, 31, 33-36 only) | |
| ^CM bAlias, eAlias, rAlias, aAlias, multiple | Change memory letter designation | |
| ^CN override | Cut now | |
| ^CO on, kilobytes, type | Cache on | |
| ^CP mode | Remove label | |
| ^CT tilde | Change tilde (alternate command: ~CT) | |
| ^CV validate | Code validation (use the Labelary linter instead) | |
| ^CW fontName, path | Set font identifier | |
| ~DB path, orient, height, width, ascent, space, glyphs, copyright, data | Download bitmap font | |
| ~DE path, size, data | Download encoding | |
| ^DF path | Download format | |
| ~DG path, totalBytes, rowBytes, data | Download graphics | |
| ~DN | Abort download graphics | |
| ~DS path, size, data | Download scalable font | |
| ~DT path, size, data | Download TrueType font | |
| ~DU path, size, data | Download unbounded TrueType font | |
| ~DY path, format, extension, totalBytes, rowBytes, data | Download objects (extensions G, B, P and T only) | |
| ~EG | Erase all graphics (alternate command: ^EG) | |
| ^FB maxWidth, maxLines, lineSpacing, alignment, hangingIndent | Field block | |
| ^FC indicator1, indicator2, indicator3 | Field clock | |
| ^FD data | Field data | |
| ^FE embedChar | Field data embed character | |
| ^FH hexIndicator | Field hexadecimal indicator | |
| ^FL extensionPath, basePath, link | Font link | |
| ^FM x1, y1, x2, y2, ... | Field multiple origin locations | |
| ^FN fieldNumber | Field number | |
| ^FO x, y, alignment | Field origin | |
| ^FP direction, characterSpacing | Field parameter | |
| ^FR | Field reverse print | |
| ^FS | Field separator (alternate command: 0x0F) | |
| ^FT x, y, alignment | Field typeset | |
| ^FV data | Field variable | |
| ^FW orientation, alignment | Field orientation | |
| ^FX comment | Comment | |
| ^GB width, height, thickness, color, rounding | Graphic box | |
| ^GC diameter, thickness, color | Graphic circle | |
| ^GD width, height, thickness, color, orientation | Graphic diagonal line | |
| ^GE width, height, thickness, color | Graphic ellipse | |
| ^GF format, dataBytes, totalBytes, rowBytes, data | Graphic field | |
| ^GS orientation, height, width | Graphic symbol | |
| ~HB | Battery status | |
| ~HD | Head diagnostic | |
| ^HF path | Host format | |
| ^HG path | Host graphic | |
| ^HH | Configuration label return | |
| ~HI | Host identification | |
| ^HL | Send RFID data log to host (alternate command: ~HL) | |
| ~HM | Host RAM status | |
| ~HQ query | Host query | |
| ^HR prefix, suffix, start, end, antennaSelection | Calibrate RFID tag position | |
| ~HS | Host status return | |
| ^HT | Host linked font list | |
| ~HU | Host alert configuration | |
| ^HV fieldNumber, bytes, prefix, suffix, mode | Host verification | |
| ^HW path, format | Host directory list | |
| ^HY path | Upload graphics | |
| ^HZ selector, path, longFilenames | Display description information | |
| ^ID path | Delete object | |
| ^IL path | Image load | |
| ^IM path | Image move | |
| ^IS path, print | Image save | |
| ~JA | Cancel all | |
| ^JB device | Initialize flash memory | |
| ~JB | Reset optional memory | |
| ~JC | Set media sensor calibration | |
| ~JD | Enable communications diagnostics | |
| ~JE | Disable communications diagnostics | |
| ~JF pause | Set battery condition | |
| ~JG | Graphing sensor calibration | |
| ^JH settings | Set early warning settings | |
| ^JI path, console, echo, memory | Start ZBI (alternate command: ~JI) | |
| ^JJ opMode, appMode, signalMode, errMode, reprintMode, ribbonMode | Set auxiliary port | |
| ~JL | Set label length | |
| ^JM adjustment | Set print density | |
| ~JN | Head test fatal | |
| ~JO | Head test not fatal | |
| ~JP | Pause and cancel format | |
| ~JQ | Stop ZBI | |
| ~JR | Power on reset | |
| ^JS sensor | Sensor select | |
| ~JS sequence | Change backfeed sequence | |
| ^JT interval, manual, first, last | Set head test interval | |
| ^JU configuration | Configuration update | |
| ^JW tension | Set ribbon tension | |
| ~JX | Cancel current format | |
| ^JZ reprint | Reprint after error | |
| ~KB | Kill battery | |
| ^KC enable, device, prefix, identifier | Set DHCP client ID | |
| ^KD format | Select date and time format | |
| ^KL language | Select language | |
| ^KN name, description | Set printer name | |
| ^KP password, level | Set control panel password | |
| ^KV cutAmount, cutMargin, presentType, presentTimeout, loopLen | Kiosk values | |
| ^LF | List font links | |
| ^LH x, y | Label home | |
| ^LL length, allMedia | Label length | |
| ^LR reverse | Label reverse print | |
| ^LS distance | Label shift | |
| ^LT distance | Label top | |
| ^MA type, print, threshold, frequency, units | Maintenance alerts | |
| ^MC clear | Map clear | |
| ^MD darknessModifier | Modify darkness | |
| ^MF powerupAction, closingAction | Media feed | |
| ^MI type, message | Adjust maintenance information message | |
| ^ML maxLength | Set max label length | |
| ^MM mode, prepeel | Print mode | |
| ^MN media, offset | Media tracking | |
| ^MP function | Mode protection | |
| ^MT mediaType | Media type | |
| ^MU units, baseDpi, desiredDpi | Set units of measurement | |
| ^MW enable | Modify head cold warning | |
| ^NB check | Set network boot print server check | |
| ^NC device | Set primary network device | |
| ~NC networkId | Network connect | |
| ^ND device, res, ip, mask, gateway, wins, timeout, secs, arp, port | Modify network settings | |
| ^NI networkId | Network ID number | |
| ^NN name, contact, location, getCommunity, setCommunity, trapCommunity | Configure SNMP | |
| ^NP device | Set primary device | |
| ~NR | Set all network printers transparent | |
| ^NS res, ip, mask, gateway, wins, timeout, secs, arp, port | Modify wired network settings | |
| ~NT | Set current printer transparent | |
| ^NT server, domain | Configure SMTP | |
| ^NW timeout | Set password timeout | |
| ^PA defaultGlyph, bidi, charShaping, openTypeSupport | Advanced text properties | |
| ^PF rows | Slew rows | |
| ^PH | Slew to home position (alternate command: ~PH) | |
| ~PL length | Additional present length | |
| ^PM mirror | Print mirror image | |
| ~PM serialNumber, wipeCount | Decommission printer | |
| ^PN length | Present now | |
| ^PO orientation | Print orientation | |
| ^PP | Programmable pause (alternate command: ~PP) | |
| ^PQ labels, labelsBetweenPauses, replicates, noPause, cutOnError | Print quantity | |
| ^PR printSpeed, slewSpeed, backfeedSpeed | Print rate | |
| ~PR | Applicator reprint | |
| ~PS | Print start | |
| ^PW width | Print width | |
| ^RA fieldNumber, format, retries, motion, byteType | Read RFID AFI or DSFID byte | |
| ^RB totalBits, partition1, partition2, ... , partition16 | Configure RFID EPC data structure | |
| ^RE enable, retries | Enable RFID EAS bit | |
| ^RF operation, format, passwordOrBlock, bytes, memoryBank | Read or write RFID data (write operations only) | |
| ^RI fieldNumber, order, retries, motion | Read RFID tag ID | |
| ^RL lockAction, p1, p2, epcOp, userOp | Lock and unlock RFID tag memory | |
| ^RM enable | Configure RFID motion | |
| ^RN enable | Configure RFID multiple tag detection | |
| ~RO counter | Reset counter | |
| ^RQ format, chipType, option | Write RFID EPC data and passwords | |
| ^RR retries, adaptive | Configure RFID retries and adaptive antenna | |
| ^RS type, pos, voidLen, labels, onError, signal, deprecated, voidSpeed | Configure RFID | |
| ^RT fieldNumber, startBlock, blocks, format, retries, motion, mode | Read RFID tag | |
| ^RU prefix, escapeChar | Read RFID tag ID | |
| ~RV enable | Configure RFID reporting | |
| ^RW readPower, writePower, antennaElement | Configure RFID power levels | |
| ^RZ password, passwordType, lockType | Set RFID tag password | |
| ^SC baud, wordBits, parity, stopBits, mode, protocol | Set serial communications | |
| ~SD darkness | Set darkness | |
| ^SE path | Select encoding | |
| ^SF mask, increment | Serialized field | |
| ^SI setting, value | Set sensor intensity | |
| ^SL mode, language | Set RTC mode and language | |
| ^SN start, increment, pad | Serialized data | |
| ^SO clock, months, days, years, hours, minutes, seconds | Set RTC offset | |
| ^SP row | Start print | |
| ^SQ condition, destination, stop | Stop and start alerts | |
| ^SR resistance | Set printhead resistance | |
| ^SS web, media, ribbon, length, int1, int2, sense, mediaSense, ledSense | Set media sensors | |
| ^ST month, day, year, hour, minute, second, format | Set RTC date and time | |
| ^SX condition, destination, set, clear, setting, port | Set alert | |
| ^SZ version | Set ZPL version (version 2 only) | |
| ~TA adjustment | Tear-off adjust position | |
| ^TB orientation, maxWidth, maxHeight | Text block | |
| ^TO from, to | Transfer object | |
| ^WA receive, transmit | Configure wireless antenna | |
| ~WC | Print configuration label | |
| ^WD path | Print directory label | |
| ^WE mode, index, authType, keyType, key1, key2, key3, key4 | Configure WEP | |
| ^WF retries, motion, protect, format, type | Write RFID AFI or DSFID byte | |
| ^WI res, ip, mask, gateway, wins, timeout, secs, arp, port | Modify wireless network settings | |
| ^WL mode, username, password | Configure LEAP | |
| ~WL | Print network configuration label | |
| ^WP oldPassword, newPassword | Set wireless password | |
| ~WQ query | Write query | |
| ^WR rate1, rate2, rate55, rate11, power | Set wireless transmit rate | |
| ~WR | Reset wireless radio card | |
| ^WS essid, mode, preamble, pulse, interval, mask, international | Configure wireless radio card | |
| ^WT block, retries, motion, protect, format, verify | Write RFID tag | |
| ^WV enable | Configure RFID write verify | |
| ^WX securityType, parameters | Configure wireless security | |
| ^XA | Start format (alternate command: 0x02) | |
| ^XB | Supress backfeed | |
| ^XF path | Recall format | |
| ^XG path, magnificationX, magnificationY | Recall graphics | |
| ^XS length, threshold, gain | Set dynamic calibration | |
| ^XZ | End format (alternate command: 0x03) | |
| ^ZZ seconds, immediate | Printer sleep |
2. ZPL Extensions for Simulating Colored Label Stock
You can simulate colored (or partially colored) label stock by using the non-standard ~BR ("background rectangle") and ~BI ("background image") commands.
These commands are ignored by physical printers, but Labelary will interpret them as requests to draw colored rectangles and images, respectively.
~BR: Background Rectangle
The ~BR command draws a colored rectangle on the label background. This command has 7 parameters:
- x: The x-coordinate position of the rectangle's top left corner, in pixels.
- y: The y-coordinate position of the rectangle's top left corner, in pixels.
- width: The width of the rectangle, in pixels.
- height: The height of the rectangle, in pixels.
- r: The R (red) component of the rectangle color (0 to 255).
- g: The G (green) component of the rectangle color (0 to 255).
- b: The B (blue) component of the rectangle color (0 to 255).
A ~BR command without any parameters clears any previously registered background rectangles.
This ~BR command example simulates label stock where the left side is white and the right side is yellow.
~BI: Background Image
The ~BI command draws a color image on the label background. This command has 4 parameters:
- x: The x-coordinate position of the image's top left corner, in pixels.
- y: The y-coordinate position of the image's top left corner, in pixels.
- magnification: The magnification to apply to the image.
- image: The image file to draw (usually a PNG file), encoded using the Base64 encoding scheme.
A ~BI command without any parameters clears any previously registered background images.
This ~BI command example simulates label stock with a color logo pre-printed in the upper right corner.
3. Configuration via System Properties
If you've licensed Labelary for on-premise, offline use, there are a number of system properties that you can use to customize the behavior of the Labelary rendering engine:
- labelary.license.path
- Used to specify the path to your license file.
- labelary.port
- When deploying Labelary in API mode, used to specify the port to use (defaults to port 80).
- labelary.host
- When deploying Labelary in API mode, used to specify the listen host address to bind to. This can be used to improve the security of the system by restricting clients to the specified IP address or hostname. If set to localhost, only local clients will be able to access the system, and only via the localhost hostname. By default, any host address may be used.
- labelary.access.log.dir
- When specified, enables the creation of NCSA-format access logs in the specified directory. The access log files are rotated daily and deleted after 90 days.
- labelary.png.compression.quality
- Specify a value between 0.0 and 1.0 to customize the tradeoff between output PNG file size and system performance. A value of 0.0 tells Labelary to spend as much time as necessary to achieve the smallest PNG file size possible, sacrificing performance for the sake of smaller output PNG files. A value of 1.0 tells Labelary to not spend any time optimizing the PNG file size, sacrificing file size for the sake of system performance. The default value is 0.2, which is the optimal setting for most labels.
- labelary.font.[fontName].printerPath, labelary.font.[fontName].file
- Used to automatically load a custom font into the Labelary virtual printer memory, rather than having to include a ~DU (upload font) command in every label template. For example, in order to register the font file at C:\fonts\MyFont.ttf with Labelary as font Z at printer path B:MY.TTF, you would set labelary.font.z.file=C:\fonts\MyFont.ttf and labelary.font.z.printerPath=B:MY.TTF. When choosing a font name for your custom font, do not use a ZPL standard font name (A, B, C, D, E, F, G, H, P, Q, R, S, T, U, V, 0) or a Labelary standard font name (J, L, N).