Printers

A job names its printer by id (registered on this daemon), name (an OS queue or a manually added printer) or host (a network address); see Print job messages › Schema v1. Printers are registered in <home>/printers.json by discovery, the admin UI or the CLI.

Auto-discovery#

Discovery runs at startup, every intervalMinutes, and on demand from the admin UI's Add printer tab. New printers are registered as discovered when autoAdd is on. Printers you add manually are never overwritten. Results list only printers that weren't registered yet, plus a count of the ones that were.

Source	Finds
OS queues	Every printer installed in CUPS or Windows. Zebra drivers (`zebra` / `zdesigner` / `zpl`) are marked `zpl`, everything else `document`.
Port 9100 scan	Zebra label printers, identified by SNMP (sysDescr / hrDeviceDescr, community `scan.snmpCommunity`).
IPP (port 631 scan + mDNS `_ipp` / `_ipps`)	Network printers that report (Get-Printer-Attributes) that they accept PDF are registered as driverless IPP document printers, with their real make and model.
mDNS `_pdl-datastream`	Raw-socket printers identified as Zebra by TXT record or SNMP.

The scan covers each private interface's subnet (capped at the /22 around the address), or the scan ranges you set on the Add printer tab or in discovery.scan.subnets (each at most a /16). Printers on other subnets are found only through mDNS until you add their ranges.

Devices that need your decision are listed instead of being registered. Each comes with buttons to add it the suggested way:

Unidentified devices have port 9100 open but no SNMP or IPP answer (often Zebras with SNMP off).
IPP printers that don't accept PDF need an OS install with a driver.
Queues shared by another computer (<printer> @ <host>, CUPS /printers/… paths) print only while that computer is on.

The scan never sends print data to anything. It only opens and closes TCP connections, sends SNMP GETs and IPP Get-Printer-Attributes. A probe like ~HI would print a garbage page on a non-Zebra laser printer.

Label resolution (203 / 300 / 600 dpi)#

ZPL is measured in printer dots, so a label designed for 203 dpi prints at about 68% size on a 300 dpi printer (and 300 dpi ZPL is cut off on a 203 dpi printer). Each label printer therefore has a resolution setting (203, 300 or 600 dpi) that you set. Discovery only suggests a value when the model name contains it ("ZT410-203dpi"); you confirm it.

The daemon converts only when it has to:

Label (detected from the ZPL)	Printer (set)	Result
same as the printer	203 / 300 / 600	sent unchanged, byte for byte
clearly another resolution	203 / 300 / 600	rescaled to the printer's resolution
can't tell	any	sent unchanged
any	not set	sent unchanged

Detection: each label's resolution comes from its own ZPL. An explicit ^MU base decides; otherwise the daemon uses ^PW/^LL against common label sizes and the coordinates the label uses. A resolution at which the label would be wider than the printer's head (print width, default 4.1", i.e. a 4" printer) is ruled out. The label is treated as matching whenever it fits the printer's own resolution, and every decision is logged with its reason.
Rescaling: every parameter measured in dots is converted: positions, all fonts and ^CF, boxes and shapes, ^BY and barcode heights, QR/DataMatrix/Aztec module sizes, label shift and top. ^GF/~DG graphics are resampled. Field data is never touched.
Not rescaled: labels that change the command prefix or delimiter (^CC/^CT/^CD) or use ^MU with inches/mm. Graphics stored on the printer (^XG/^IM) and binary-format graphics stay as they are.

Set the resolution in the admin UI or with printers add --dpi <203|300|600>; --print-width <in> changes the head width (only for wide-format printers).

Manual setup#

In the admin UI's Add printer tab, or from the CLI:

bash

node dist/cli.js printers os                                             # OS queues
node dist/cli.js printers add --id dock-1-zebra --name "Dock 1" --kind zpl --host 10.4.1.107 --port 9100
node dist/cli.js printers add --id office-laser --name "Office" --kind document --queue Brother_HL_L2360D_series
node dist/cli.js printers add --id xerox-4 --name "Xerox 4th Floor" --kind document --ipp ipp://10.4.1.105:631/ipp/print
node dist/cli.js printers scan-ranges --set 10.4.0.0/20 --community public   # what discovery scans
node dist/cli.js printers discover
node dist/cli.js printers list | remove <id>

Kind	Connection
`zpl` (label printer)	`--host` + `--port` (raw TCP), or `--queue` (an OS print queue)
`document`	`--queue` (an OS print queue, printed through CUPS or the Windows spooler), `--ipp` (driverless IPP), or `--host` (raw TCP; the printer must accept PDF directly)

The running daemon picks up changes made through the CLI automatically, because both read printers.json. Run the CLI with the service's home (Install › Home directory).

Windows: the service runs as LocalSystem, so install printers machine-wide.

Test prints#

printers test <id> prints a ZPL test label on a label printer, or a PDF test page on a document printer. On label printers, --zpl my-label.zpl prints your own ZPL instead. In the admin UI, label printers also have Custom test…, which opens the default test label as editable ZPL and prints your version as a one-off.

bash

node dist/cli.js printers test dock-1-zebra                              # ZPL test label / PDF test page
node dist/cli.js printers test dock-1-zebra --zpl my-label.zpl           # label printers: print your own ZPL instead

Test prints need a valid license (License).