Labelary Engine Documentation

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.

Note that 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, ecic, err, menuSymbol, symbols, idAztec bar code (alternate command: ^BO)
^B1 orientation, checkDigit, height, intLine, intLineAboveCode 11 bar code
^B2 orientation, height, intLine, intLineAbove, checkDigitInterleaved 2 of 5 bar code
^B3 orientation, checkDigit, height, intLine, intLineAboveCode 39 bar code
^B4 orientation, heightMultiplier, intLine, modeCode 49 bar code
^B5 orientation, height, intLine, intLineAbovePlanet Code bar code
^B7 orientation, rowHeight, security, columns, rows, truncatePDF417 bar code
^B8 orientation, height, intLine, intLineAboveEAN-8 bar code
^B9 orientation, height, intLine, intLineAbove, checkDigitUPC-E bar code
^BA orientation, height, intLine, intLineAbove, checkDigitCode 93 bar code
^BB orientation, height, security, columns, rows, modeCodablock bar code
^BC orientation, height, intLine, intLineAbove, checkDigit, modeCode 128 bar code (modes N, U and A only; UCC check digit not supported)
^BD mode, position, totalUPS MaxiCode bar code
^BE orientation, height, intLine, intLineAboveEAN-13 bar code
^BF orientation, rowHeight, modeMicroPDF417 bar code
^BI orientation, height, intLine, intLineAboveIndustrial 2 of 5 bar code
^BJ orientation, height, intLine, intLineAboveStandard 2 of 5 bar code
^BK orientation, checkDigit, height, intLine, intLineAbove, startChar, stopCharANSI Codabar bar code
^BL orientation, height, intLineAboveLOGMARS bar code
^BM orientation, checkDigitType, height, intLine, intLineAbove, checkDigitMSI bar code
^BO orientation, magnification, ecic, err, menuSymbol, symbols, idAztec bar code (alternate command: ^B0)
^BP orientation, checkDigit, height, intLine, intLineAbovePlessey bar code
^BQ orientation, model, magnification, errorCorrection, maskQR code bar code (model 2 only; mixed mode and Kanji not supported)
^BR orientation, symbology, magnification, separatorHeight, height, segmentWidthRSS bar code
^BS orientation, height, intLine, intLineAboveUPC/EAN extension
^BT orientation, width, widthRatio, height, narrowWidth, rowHeightTLC39 bar code
^BU orientation, height, intLine, intLineAbove, printCheckDigitUPC-A bar code
^BX orientation, height, quality, columns, rows, format, escapeData matrix bar code (quality 200 only)
^BY width, widthRatio, heightBar code field defaults
^BZ orientation, height, intLine, intLineAbove, typePostal bar code
^CC charChange caret (alternate command: ~CC)
^CD charChange delimiter (alternate command: ~CD)
^CF fontName, height, widthChange default font
^CI charset, src1, dest1, src2, dest2, ...Change international font (charsets 0-13, 15, 27, 28, 31, 33-36 only)
^CM memoryDevice, memoryDevice, memoryDevice, memoryDeviceChange memory letter designation
^CN overrideCut now
^CO on, kilobytes, typeCache on
^CP modeRemove label
^CT charChange tilde (alternate command: ~CT)
^CV validationCode validation
^CW fontName, pathSet font identifier
~DB path, orientation, maxHeight, maxWidth, base, space, chars, copyright, dataDownload bitmap font
~DE path, tableSize, 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 hexadecimaml indicator
^FL extensionPath, basePath, linkFont link
^FM x1, y2, 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
~HMHost RAM status
~HQ queryHost query
~HSHost status return
^HTHost linked font list
~HUHost alert configuration
^HVHost verification
^HW pathHost directory list
^HY pathUpload graphics
^HZ paramDisplay 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 settingsEarly warning settings
^JI path, console, echo, memoryStart ZBI (alternate command: ~JI)
^JJ opMode, appMode, printSignalMode, errorMode, 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 labels, manualSelection, first, lastHead test interval
^JU configurationConfiguration update
^JW tensionSet ribbon tension
~JXCancel current format
^JZ reprintReprint after error
~KBKill battery
^KD formatSelect date and time format
^KL languageSelect language
^KN name, descriptionSet printer name
^KP passwordSet password
^KV cutAmount, cutMargin, presentType, presentTimeout, loopLengthKiosk values
^LFList font links
^LH x, yLabel home
^LL lengthLabel length
^LR reverseLabel reverse print
^LS shiftLabel shift
^LT topLabel 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 maxLength, maxLogicalPaper, maxPhysicalPaper, maxRibbonMax label length
^MM mode, prepeelPrint mode
^MN mediaMedia tracking
^MP modeMode protection
^MT mediaTypeMedia type
^MU units, baseDpi, desiredDpiSet units of measurement
^MW enableModify head cold warning
^NC deviceSet primary network device
~NC networkIdNetwork connect
^ND device, resolution, ip, mask, gateway, wins, timeout, seconds, arp, portModify network settings
^NI networkIdNetwork ID number
~NRSet all network printers transparent
^NS setting, ip, subnetMask, gatewayChange network settings
~NTSet current printer transparent
^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
^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
~RO counterReset counter
^SC baud, wordLength, parity, stopBits, protocolMode, 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, haltHalt alert
^SR resistanceSet printhead resistance
^SS web, media, ribbon, length, intensity1, intensity2, sensing, mediaSensing, ledSensingSet 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
~TA adjustmentTear-off adjust position
^TB orientation, maxWidth, maxHeightText block
^TO from, toTransfer object
~WCPrint configuration label
^WD pathPrint directory label
~WQ queryWrite query
^XAStart format (alternate command: 0x02)
^XBSupress backfeed
^XF pathRecall format
^XG path, magnificationX, magnificationYRecall graphics
^XS length, thresholdSet dynamic calibration
^XZEnd format (alternate command: 0x03)
^ZZ seconds, immediatePrinter sleep

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.

See here for an example of a label that uses this command to simulate 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.

See here for an example of a label that uses this command to simulate label stock with a color logo pre-printed in the upper right corner.

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 using Labelary in HTTP server mode, used to specify the port to use (defaults to port 80).
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 the vast majority of 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.