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 barcode (alternate command: ^BO)
	^B1 orientation, checkDigit, height, line, lineAbove	Code 11 barcode
	^B2 orientation, height, line, lineAbove, checkDigit	Interleaved 2 of 5 barcode
	^B3 orientation, checkDigit, height, line, lineAbove	Code 39 barcode
	^B4 orientation, heightMultiplier, line, mode	Code 49 barcode
	^B5 orientation, height, line, lineAbove	Planet Code barcode
	^B7 orientation, rowHeight, security, columns, rows, truncate	PDF417 barcode
	^B8 orientation, height, line, lineAbove	EAN-8 barcode
	^B9 orientation, height, line, lineAbove, checkDigit	UPC-E barcode
	^BA orientation, height, line, lineAbove, checkDigit	Code 93 barcode
	^BB orientation, height, checkDigit, columns, rows, mode	Codablock barcode
	^BC orientation, height, line, lineAbove, checkDigit, mode	Code 128 barcode
	^BD mode, position, total	UPS MaxiCode barcode
	^BE orientation, height, line, lineAbove	EAN-13 barcode
	^BF orientation, rowHeight, mode	MicroPDF417 barcode
	^BI orientation, height, line, lineAbove	Industrial 2 of 5 barcode
	^BJ orientation, height, line, lineAbove	Standard 2 of 5 barcode
	^BK orientation, checkDigit, height, line, lineAbove, startChar, stopChar	ANSI Codabar barcode
	^BL orientation, height, lineAbove	LOGMARS barcode
	^BM orientation, checkDigitType, height, line, lineAbove, checkDigit	MSI barcode
	^BO orientation, magnification, eci, size, readerInit, symbols, id	Aztec barcode (alternate command: ^B0)
	^BP orientation, checkDigit, height, line, lineAbove	Plessey barcode
	^BQ orientation, model, magnification, errorCorrection, mask	QR Code barcode (model 2 only; no mixed mode or Kanji)
	^BR orientation, type, magnification, sepHeight, height, segWidth	GS1 DataBar (RSS) barcode
	^BS orientation, height, line, lineAbove	UPC/EAN extension
	^BT orientation, width, widthRatio, height, pdfWidth, pdfHeight	TLC 39 barcode
	^BU orientation, height, line, lineAbove, checkDigit	UPC-A barcode
	^BX orientation, height, quality, columns, rows, format, escape, ratio	Data Matrix barcode (quality 200 only)
	^BY width, widthRatio, height	Barcode field defaults
	^BZ orientation, height, line, lineAbove, type	Postal barcode
	^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 script, console, echo	Start ZBI (alternate command: ~JI)
	^JJ opMode, appMode, signalMode, errMode, reprintMode, ribbonMode	Set auxiliary port
	~JK	Delayed cut
	~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 wired	Set network boot print server check priority
	^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, start, num, 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, target, action	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	Suppress 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.
Example command line argument: -Dlabelary.license.path=/path/to/labelary.license
labelary.port: When deploying Labelary in API mode, used to specify the port to use (defaults to port 80).
Example command line argument: -Dlabelary.port=8080
labelary.host: When deploying Labelary in API mode, used to specify the listen host address to bind to. This can 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.
Example command line argument: -Dlabelary.host=localhost
labelary.access.log.dir: When deploying Labelary in API mode, enables the creation of NCSA-format access logs in the specified directory. The access log files are rotated daily and deleted after 90 days.
Example command line argument: -Dlabelary.access.log.dir=/path/to/logs
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.
Example command line argument: -Dlabelary.png.compression.quality=0.5
labelary.font.[fontName].file, labelary.font.[fontName].printerPath: 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. 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).
The example below registers the font file at C:\fonts\MyFont.ttf with Labelary as font Z at printer path B:MY.TTF.
Example command line arguments: -Dlabelary.font.z.file=C:\fonts\MyFont.ttf -Dlabelary.font.z.printerPath=B:MY.TTF