visitor-signin/docs/PRINTING.md

Badge printing

The app renders the badge and sends it to the Brother QL-820NWB over TCP port 9100, speaking Brother's raster command language directly. No CUPS, no driver, no print dialog, and no Python.

Why not AirPrint

AirPrint from the kiosk browser means iPadOS renders the badge from print CSS and picks the page geometry from what the printer advertises. That costs exact control of the 60.96 mm print width, makes two-colour DK-22251 output impossible, and cannot suppress the print dialog — so a staff member has to tap "Print" for every visitor. Fine for a staffed desk, useless for unattended sign-in.

Doing it server-side also means the kiosk device stops mattering. An iPad, an old Android tablet, a browser on a NUC: they all just POST.

Layout

src/printing/
  ql-raster.js     command language: media, cut, expanded mode, bit packing
  ql-status.js     decoder for the 32-byte status frames
  ql-transport.js  TCP client for port 9100
  ql-print.js      printPng / printerHealth, plus the serial queue
src/printer.js     badge layout and rendering (unchanged by this work)

Protocol details follow Brother's Raster Command Reference, QL-800/810W/820NWB v1.01. Where that manual and pklaus/brother_ql disagree, the manual wins; brother_ql targets older models and several of its defaults are wrong for this hardware (200-byte invalidate instead of 400, the print-quality bit set during two-colour jobs, the media-length valid bit asserted for continuous tape).

The roll setting is not cosmetic

sites.printer_label must match the roll physically in the machine:

Roll	Setting
DK-22205, 62 mm white	62
DK-22251, 62 mm black/red	62red

This is enforced by the printer, not by us. A monochrome job sent to a black/red roll is refused outright, and vice versa. It applies even when the badge has no red on it — with 62red set, every job is built as two-colour and the red plane is simply empty.

The printer's own error message is misleading here. It says "change it to Monochrome media", which points at a driver setting that doesn't exist in this setup. The fix is the roll dropdown in the admin console, or swapping the roll.

Status, and why there isn't much

Manual section 5.9: over a network connection the print data is sent as-is and nothing comes back. Status frames only arrive over USB. brother_ql documents the same limitation for its network backend.

So printerHealth returns a tri-state ready:

• true — the printer answered and everything is fine
• false — it answered and something is wrong
• null — reachable, but it won't say

null is the normal answer here. Show it as amber/unknown in the admin console; colouring it green claims something we don't know. Likewise printPng returns confirmed: false when no status came back: the bytes were delivered, but whether paper moved is unknown.

Consequence worth accepting: a jammed or empty printer cannot be detected. The practical signal is a visitor saying no badge appeared. That is tolerable because the evacuation record is written before printing is attempted. If real roll monitoring is ever needed, the lead to follow is SNMP — the Brother Status Monitor on Windows gets roll state over the network somehow, and it is not using port 9100.

Concurrency

The QL accepts one TCP connection at a time and has no job spooler worth the name. Two visitors signing in together would otherwise produce a refused connection, half a label, or both. Every job goes through a serial queue keyed on printer host, in ql-print.js.

That queue is in-process. Running more than one app instance against one printer would need a lock in SQLite instead.

Geometry

Print head	720 pins, 60.96 mm at 300 dpi
62 mm roll printable	696 pins, 58.9 mm
Margins	12 pins each side
Feed margin	35 dots (3 mm), the documented minimum
Length	150 to 11811 raster lines (12.7 mm to 1 m)

Every raster line sent is the full 90 bytes regardless of the roll. Narrower media just means more pins miss the paper.

Diagnostics

Reachability and roll state:

docker compose exec visitor-signin node -e "
  import('./src/printing/ql-print.js').then(async m =>
    console.log(await m.printerHealth({ host: '10.142.177.169', label: '62red' })));
"

If a label never appears, work down this list:

Nothing at all, Cannot reach printer. Routing or firewall between the container and the printer. Try nc -vz IP 9100 from the Ubuntu host; if that works but the container doesn't, it is Docker networking.

Connects but silent. Normal. See above.

Media mismatch error. The roll setting and the physical roll disagree.

Labels come out blank. Roll in backwards, or a non-Brother roll with no end sensor. The printer reports no error for this.

Everything mirrored. The bit packing is wrong. The head clocks each raster line out right-to-left; see packRow.

First label after a power cycle is misaligned. Feed one label from the front panel before the first sign-in of the day.

Known rough edge

Photos are not dithered. drawBadge draws them straight and the plane conversion thresholds at luminance 180. A thermal head has no grey, so faces come out blotchy. The fix is Floyd–Steinberg on the photo region before it goes on the canvas, inside drawBadge.

---

Created by: Jess Rogerson (yelling commands at Claude.AI)