Labelary Engine Documentation

  1. ZPL Command Support
  2. ZPL Extensions for Simulating Colored Label Stock
  3. 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, widthSet font for current field
^A@ orientation, height, width, pathUse font name to call font
^B0 orientation, magnification, eci, size, readerInit, symbols, idAztec bar code (alternate command: ^BO)
^B1 orientation, checkDigit, height, line, lineAboveCode 11 bar code
^B2 orientation, height, line, lineAbove, checkDigitInterleaved 2 of 5 bar code
^B3 orientation, checkDigit, height, line, lineAboveCode 39 bar code
^B4 orientation, heightMultiplier, line, modeCode 49 bar code
^B5 orientation, height, line, lineAbovePlanet Code bar code
^B7 orientation, rowHeight, security, columns, rows, truncatePDF417 bar code
^B8 orientation, height, line, lineAboveEAN-8 bar code
^B9 orientation, height, line, lineAbove, checkDigitUPC-E bar code
^BA orientation, height, line, lineAbove, checkDigitCode 93 bar code
^BB orientation, height, checkDigit, columns, rows, modeCodablock bar code
^BC orientation, height, line, lineAbove, checkDigit, modeCode 128 bar code
^BD mode, position, totalUPS MaxiCode bar code
^BE orientation, height, line, lineAboveEAN-13 bar code
^BF orientation, rowHeight, modeMicroPDF417 bar code
^BI orientation, height, line, lineAboveIndustrial 2 of 5 bar code
^BJ orientation, height, line, lineAboveStandard 2 of 5 bar code
^BK orientation, checkDigit, height, line, lineAbove, startChar, stopCharANSI Codabar bar code
^BL orientation, height, lineAboveLOGMARS bar code
^BM orientation, checkDigitType, height, line, lineAbove, checkDigitMSI bar code
^BO orientation, magnification, eci, size, readerInit, symbols, idAztec bar code (alternate command: ^B0)
^BP orientation, checkDigit, height, line, lineAbovePlessey bar code
^BQ orientation, model, magnification, errorCorrection, maskQR Code bar code (model 2 only; no mixed mode or Kanji)
^BR orientation, type, magnification, sepHeight, height, segWidthGS1 DataBar (RSS) bar code
^BS orientation, height, line, lineAboveUPC/EAN extension
^BT orientation, width, widthRatio, height, pdfWidth, pdfHeightTLC 39 bar code
^BU orientation, height, line, lineAbove, checkDigitUPC-A bar code
^BX orientation, height, quality, columns, rows, format, escape, ratioData Matrix bar code (quality 200 only)
^BY width, widthRatio, heightBar code field defaults
^BZ orientation, height, line, lineAbove, typePostal bar code
^CC caretChange caret (alternate command: ~CC)
^CD delimChange delimiter (alternate command: ~CD)
^CF fontName, height, widthChange 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, multipleChange memory letter designation
^CN overrideCut now
^CO on, kilobytes, typeCache on
^CP modeRemove label
^CT tildeChange tilde (alternate command: ~CT)
^CV validateCode validation (use the Labelary linter instead)
^CW fontName, pathSet font identifier
~DB path, orient, height, width, ascent, space, glyphs, copyright, dataDownload bitmap font
~DE path, size, dataDownload encoding
^DF pathDownload format
~DG path, totalBytes, rowBytes, dataDownload graphics
~DNAbort download graphics
~DS path, size, dataDownload scalable font
~DT path, size, dataDownload TrueType font
~DU path, size, dataDownload unbounded TrueType font
~DY path, format, extension, totalBytes, rowBytes, dataDownload objects (extensions G, B, P and T only)
~EGErase all graphics (alternate command: ^EG)
^FB maxWidth, maxLines, lineSpacing, alignment, hangingIndentField block
^FC indicator1, indicator2, indicator3Field clock
^FD dataField data
^FH hexIndicatorField hexadecimal indicator
^FL extensionPath, basePath, linkFont link
^FM x1, y1, x2, y2, ...Field multiple origin locations
^FN fieldNumberField number
^FO x, y, alignmentField origin
^FP direction, characterSpacingField parameter
^FRField reverse print
^FSField separator (alternate command: 0x0F)
^FT x, y, alignmentField typeset
^FV dataField variable
^FW orientation, alignmentField orientation
^FX commentComment
^GB width, height, thickness, color, roundingGraphic box
^GC diameter, thickness, colorGraphic circle
^GD width, height, thickness, color, orientationGraphic diagonal line
^GE width, height, thickness, colorGraphic ellipse
^GF format, dataBytes, totalBytes, rowBytes, dataGraphic field
^GS orientation, height, widthGraphic symbol
~HBBattery status
~HDHead diagnostic
^HF pathHost format
^HG pathHost graphic
^HHConfiguration label return
~HIHost identification
^HLSend RFID data log to host (alternate command: ~HL)
~HMHost RAM status
~HQ queryHost query
^HR prefix, suffix, start, end, antennaSelectionCalibrate RFID tag position
~HSHost status return
^HTHost linked font list
~HUHost alert configuration
^HV fieldNumber, bytes, prefix, suffix, modeHost verification
^HW path, formatHost directory list
^HY pathUpload graphics
^HZ selector, path, longFilenamesDisplay description information
^ID pathDelete object
^IL pathImage load
^IM pathImage move
^IS path, printImage save
~JACancel all
^JB deviceInitialize flash memory
~JBReset optional memory
~JCSet media sensor calibration
~JDEnable communications diagnostics
~JEDisable communications diagnostics
~JF pauseSet battery condition
~JGGraphing sensor calibration
^JH settingsSet early warning settings
^JI path, console, echo, memoryStart ZBI (alternate command: ~JI)
^JJ opMode, appMode, signalMode, errMode, reprintMode, ribbonModeSet auxiliary port
~JLSet label length
^JM adjustmentSet print density
~JNHead test fatal
~JOHead test not fatal
~JPPause and cancel format
~JQStop ZBI
~JRPower on reset
^JS sensorSensor select
~JS sequenceChange backfeed sequence
^JT interval, manual, first, lastSet head test interval
^JU configurationConfiguration update
^JW tensionSet ribbon tension
~JXCancel current format
^JZ reprintReprint after error
~KBKill battery
^KC enable, device, prefix, identifierSet DHCP client ID
^KD formatSelect date and time format
^KL languageSelect language
^KN name, descriptionSet printer name
^KP password, levelSet control panel password
^KV cutAmount, cutMargin, presentType, presentTimeout, loopLenKiosk values
^LFList font links
^LH x, yLabel home
^LL lengthLabel length
^LR reverseLabel reverse print
^LS distanceLabel shift
^LT distanceLabel top
^MA type, print, threshold, frequency, unitsMaintenance alerts
^MC clearMap clear
^MD darknessModifierModify darkness
^MF powerupAction, closingActionMedia feed
^MI type, messageAdjust maintenance information message
^ML maxLengthSet max label length
^MM mode, prepeelPrint mode
^MN media, offsetMedia tracking
^MP functionMode protection
^MT mediaTypeMedia type
^MU units, baseDpi, desiredDpiSet units of measurement
^MW enableModify head cold warning
^NB checkSet network boot print server check
^NC deviceSet primary network device
~NC networkIdNetwork connect
^ND device, res, ip, mask, gateway, wins, timeout, secs, arp, portModify network settings
^NI networkIdNetwork ID number
^NN name, contact, location, getCommunity, setCommunity, trapCommunityConfigure SNMP
^NP deviceSet primary device
~NRSet all network printers transparent
^NS res, ip, mask, gateway, wins, timeout, secs, arp, portModify wired network settings
~NTSet current printer transparent
^NT server, domainConfigure SMTP
^NW timeoutSet password timeout
^PA defaultGlyph, bidi, charShaping, openTypeSupportAdvanced text properties
^PF rowsSlew rows
^PHSlew to home position (alternate command: ~PH)
~PL lengthAdditional present length
^PM mirrorPrint mirror image
~PM serialNumber, wipeCountDecommission printer
^PN lengthPresent now
^PO orientationPrint orientation
^PPProgrammable pause (alternate command: ~PP)
^PQ labels, labelsBetweenPauses, replicates, noPause, cutOnErrorPrint quantity
^PR printSpeed, slewSpeed, backfeedSpeedPrint rate
~PRApplicator reprint
~PSPrint start
^PW widthPrint width
^RA fieldNumber, format, retries, motion, byteTypeRead RFID AFI or DSFID byte
^RB totalBits, partition1, partition2, ... , partition16Configure RFID EPC data structure
^RE enable, retriesEnable RFID EAS bit
^RF operation, format, passwordOrBlock, bytes, memoryBankRead or write RFID data (write operations only)
^RI fieldNumber, order, retries, motionRead RFID tag ID
^RL lockAction, p1, p2, epcOp, userOpLock and unlock RFID tag memory
^RM enableConfigure RFID motion
^RN enableConfigure RFID multiple tag detection
~RO counterReset counter
^RQ format, chipType, optionWrite RFID EPC data and passwords
^RR retries, adaptiveConfigure RFID retries and adaptive antenna
^RS type, pos, voidLen, labels, onError, signal, deprecated, voidSpeedConfigure RFID
^RT fieldNumber, startBlock, blocks, format, retries, motion, modeRead RFID tag
^RU prefix, escapeCharRead RFID tag ID
~RV enableConfigure RFID reporting
^RW readPower, writePower, antennaElementConfigure RFID power levels
^RZ password, passwordType, lockTypeSet RFID tag password
^SC baud, wordBits, parity, stopBits, mode, protocolSet serial communications
~SD darknessSet darkness
^SE pathSelect encoding
^SF mask, incrementSerialized field
^SI setting, valueSet sensor intensity
^SL mode, languageSet RTC mode and language
^SN start, increment, padSerialized data
^SO clock, months, days, years, hours, minutes, secondsSet RTC offset
^SP rowStart print
^SQ condition, destination, stopStop and start alerts
^SR resistanceSet printhead resistance
^SS web, media, ribbon, length, int1, int2, sense, mediaSense, ledSenseSet media sensors
^ST month, day, year, hour, minute, second, formatSet RTC date and time
^SX condition, destination, set, clear, setting, portSet alert
^SZ versionSet ZPL version (version 2 only)
~TA adjustmentTear-off adjust position
^TB orientation, maxWidth, maxHeightText block
^TO from, toTransfer object
^WA receive, transmitConfigure wireless antenna
~WCPrint configuration label
^WD pathPrint directory label
^WE mode, index, authType, keyType, key1, key2, key3, key4Configure WEP
^WF retries, motion, protect, format, typeWrite RFID AFI or DSFID byte
^WI res, ip, mask, gateway, wins, timeout, secs, arp, portModify wireless network settings
^WL mode, username, passwordConfigure LEAP
~WLPrint network configuration label
^WP oldPassword, newPasswordSet wireless password
~WQ queryWrite query
^WR rate1, rate2, rate55, rate11, powerSet wireless transmit rate
~WRReset wireless radio card
^WS essid, mode, preamble, pulse, interval, mask, internationalConfigure wireless radio card
^WT block, retries, motion, protect, format, verifyWrite RFID tag
^WV enableConfigure RFID write verify
^WX securityType, parametersConfigure wireless security
^XAStart format (alternate command: 0x02)
^XBSupress backfeed
^XF pathRecall format
^XG path, magnificationX, magnificationYRecall graphics
^XS length, threshold, gainSet dynamic calibration
^XZEnd format (alternate command: 0x03)
^ZZ seconds, immediatePrinter 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).