Brother Label Printers

ProxyBox Zero supports Brother label printers over USB using the open-source printer-driver-ptouch CUPS driver. Plug the printer in, and it is auto-discovered and ready to print — but these printers have one hard requirement that is different from every other printer type: your PDF’s page size must match the tape or label loaded in the printer.

Supported models

Model	Type	Media
PT-P900W (incl. PT-P900Wc)	P-touch tape	TZe tape, 3.5–36mm
PT-P950NW	P-touch tape	TZe tape, 3.5–36mm
QL-700	QL label	DK rolls — continuous and die-cut
QL-810W	QL label	DK rolls — continuous and die-cut
QL-820NWB	QL label	DK rolls — continuous and die-cut

USB connection only.

Note

The QL-700’s P-touch Editor Lite mode presents the printer to the host as a USB storage drive rather than a printer. Turn Editor Lite off (Editor Lite LED unlit) before plugging into the ProxyBox.

Caution

The QL-1100 / QL-1110 / QL-1115 are not supported — they are not covered by the open-source driver, and Brother’s own driver doesn’t run on ProxyBox hardware. A QL-1100 will appear in the printer list but prints will not work.

The page size is the label size

ProxyBox reads the loaded tape from USB P-touch printers and matches your PDF page against that tape before queueing the job. QL printers use the PDF page size to select a supported label size; make sure that roll is loaded. There is no separate media setting or job parameter:

• Format your PDF page to the physical label, in the sizes listed below. Either orientation works (a 24mm × 100mm label can be a 100mm × 24mm page).
• ProxyBox accepts only PDFs for these printers. A P-touch mismatch returns HTTP 400 with the detected loadedTape; a QL mismatch returns HTTP 400 listing the valid sizes. Nothing is queued.
• PDF page sizes are measured in points: 1mm = 2.835pt (72pt = 1 inch).

For example, a label for 24mm tape is a page 68pt wide (24mm), by however long you want the label to be.

To print from the admin UI, select Print File on the printer’s card or drag the PDF onto it, then select Print in the confirmation dialog. USB P-touch test prints use the detected tape; the QL Label roll selector only applies to test labels.

Matching accepts either orientation with a 2pt tolerance. If a page’s length matches the loaded tape’s width, it can print rotated even when its original width names another tape: a 68 × 51pt page with 18mm tape loaded resolves to a 51 × 68pt label.

Sizing your labels

Read loadedTape.widthPt from GET /api/v1/printers/{path} and render your PDF page at that width with the length your label needs. Use a successful reading containing widthPt; a failure contains reason, and a busy printer with no previous reading returns null. For P-touch, capabilities.mediaSupported is the driver default, not the loaded media source.

A station that always runs one width can skip the lookup and render at that width. ProxyBox still checks each job against the loaded tape. Swapping to a cassette that does not match either page dimension produces a 400 naming both tape sizes when the requested width is recognized.

For example, a 24mm-wide, 50mm-long label is a 68 × 142pt PDF page. Every P-touch tape width accepts label lengths from 12.7mm (36pt) to 1000mm (2834pt).

P-touch tape sizes (PT-P900W, PT-P950NW)

Tape	Page width	Custom length?
TZe 36mm	102pt	Yes — 36–2834pt
TZe 24mm	68pt	Yes
TZe 18mm	51pt	Yes
TZe 12mm	34pt	Yes
TZe 9mm	26pt	Yes
TZe 6mm	17pt	Yes
TZe 3.5mm	10pt	Yes

Tape is continuous, so you control the label length with your page length — a 68 × 400pt page prints a 24mm × 141mm label, cut automatically. The 36–2834pt length range applies to every width, including 3.5mm tape. Heat-shrink tubes, FLe labels, and incompatible or unknown tape types/widths are rejected as unsupported tape.

QL label sizes (QL-700, QL-810W, QL-820NWB)

Continuous rolls (you control the length via page length, except 12mm):

Roll	Page width
DK 62mm	176pt
DK 54mm	153pt
DK 50mm	142pt
DK 38mm	108pt
DK 29mm	82pt
DK 12mm	34pt (fixed 100mm length only)

Die-cut labels (page must match the label exactly):

Label	Page size
62 × 100mm	176 × 283pt
62 × 29mm	176 × 82pt
38 × 90mm	108 × 255pt
29 × 90mm	82 × 255pt
23 × 23mm	65 × 65pt
17 × 87mm	48 × 246pt
17 × 54mm	48 × 153pt
58mm circular (CD/DVD)	165 × 165pt
24mm circular	68 × 68pt
12mm circular	34 × 34pt

Test prints

For USB P-touch printers, Test Print uses the detected tape and fits the label length to the content on every tape width, with a minimum of 36pt. The API’s media parameter is optional; if supplied, it must match the detected media name.

For QL printers, pick the loaded roll in the Label roll selector beside Test Print, then click Test Print. Continuous rolls at least 36pt wide use a fitted length; narrower rolls and die-cut labels use the named size.

Troubleshooting

P-touch refuses a job before printing

• 400 — Media mismatch: resize the PDF to loadedTape.widthPt and a length of 36–2834pt, or load the matching tape. An invalid PDF also returns 400.
• 409 — Tape problem: no cassette is loaded, the tape is unsupported, or the printer reports an error such as cover open. The response names the condition.
• 503 — Tape unreadable: the USB status read fails or times out. This also occurs when the queue is busy and no reading exists. Check power and USB connectivity, let queued printing finish, then check again.

See the print response examples. A busy queue reuses its last tape reading, including during the 20 seconds after its last state change; wait until printing and cutting finish before swapping tape.

Red error light, nothing prints (but the job reported success)

For QL printers, the job’s size can match supported media without matching the roll actually loaded. The size picker declares the roll for test prints; it does not read it. Brother printers reject mismatched jobs after accepting the data, so the job reports success while the printer sits with a red light.

For a P-touch printer with a width error, press its power button once to clear the error, then check the tape and resend a correctly sized PDF. ProxyBox checks against the detected tape, but a reading reused while the queue is busy describes the cassette at the time it was read.

Tips

• TZe vs HSe: the tape reader checks the media type as well as the width. Heat-shrink tubes return 409 even if their width code matches a supported tape.
• Long P-touch labels: for cable flags, name tags, or anything longer than 100mm, make the page longer, up to 2834pt (1000mm).
• Colors: these are monochrome thermal printers. Content prints in black; use bold, high-contrast designs.