Printing labels

Labels are how a physical case becomes a Shelf record. This page covers getting a printer connected, what fits on each tape size, the calibration print you should do before trusting the first real run, and what to do when nothing comes out.

How printing actually works

Your browser never talks to the printer. That sounds like a limitation; it's the thing that makes printing from a phone work at all.

The short version: Shelf is a print queue. A small program called the print relay runs on one always-on machine on the same network as the printer — an office Mac, a Mac mini, a Raspberry Pi, a NAS container — and it sits there asking Shelf whether there's anything to print, checking in about once a minute either way. It never accepts incoming connections, so there's nothing to open on your firewall and no certificates to manage.

Why it has to be this way: a phone's browser has no printer on it, and a secure page like Shelf isn't allowed to call an insecure warehouse IP directly — every mobile browser blocks that outright. So the phone only ever talks to Shelf, which it already trusts, and the relay does the rest. The practical payoff is that anyone on the team can print a label from their phone, from anywhere the office WiFi reaches, without standing next to the printer.

The two printers

	Brother VC-500W	Zebra ZD411D
Tape	Colour ZINK tape cassettes, 12mm / 25mm / 50mm	Monochrome direct-thermal, 2in (50mm)
Gets sent	A rendered picture of the label	Drawing instructions the printer follows itself
Best for	Everything with colour on it — the brand band, coral accents	Volume runs where colour doesn't matter

Both print the same label designs; they just get there differently. Nothing in the app changes depending on which one you pick, other than which printer you choose in the print dialog.

Connecting a printer

This is a once-per-site job, and it needs someone comfortable running a command on the machine that will host the relay. Everything after it is click-and-print for everyone else.

1. In Shelf, go to Settings → Printers → Add relay (Owners and Admins only). Name it after the machine — "Warehouse Mac mini", "Office Pi". Shelf shows you a one-time key and an install command with your workspace's details already filled in. Copy both; the key is shown once and never again. Put it in your password manager.
2. On the always-on machine, run the command you were given. It needs Node 20 or newer and nothing else — the relay has no dependencies to install.
3. Within about a minute, the relay appears in Settings → Printers with its hostname and a "last seen" time that keeps ticking over, along with any printer it can find.
4. Set it to start automatically so it survives a reboot. The install notes cover launchd on macOS, systemd on Linux, and Docker.

Two traps worth knowing before you spend an afternoon on it:

• On a Mac, don't run the relay from a folder inside Documents, Desktop or Downloads. macOS blocks background processes from reading those folders, and the relay will hang with no error message at all — it just silently does nothing. Copy it somewhere else first.
• Give the printer a fixed address in your router (a DHCP reservation), or identify it by its serial number rather than its IP. Printers get new IPs after a power cut, and a relay pointed at a bare IP will simply stop finding it. Identified by serial, it re-finds the printer on its own.

When the printer moves anyway

If a printer drops off and comes back somewhere else, click Find printer next to it in Settings → Printers. That tells the relay to go looking on its next check-in; give it a minute or two and refresh. There's no separate "searching…" screen — the printer's status simply updates once the relay reports back.

What fits on each label

Labels come from a fixed set of presets — a preset is a brand, a layout and a tape size — rather than a freeform designer. That's deliberate: nobody can accidentally design a label whose QR code doesn't scan. Your workspace picks a default preset in Settings → Labels, and a category can pin its own if it needs something different.

The trade-off is always the same: the QR has to stay big enough to scan, so the smaller the tape, the less text there's room for.

Tape	Layouts	What it carries
12mm	Horizontal, vertical, square, and the stacked Shelf-code label	QR and the found-portal address. The square is QR-only — there is genuinely no room for anything else.
25mm	Horizontal, vertical, square, plus a fixed "pool code" shape for blank labels	QR, asset ID, found address, and — on the horizontal — a phone number and your logo. The square drops the phone number and logo for space.
50mm	Horizontal, vertical, square	The lot: QR, asset ID, found address, phone, email, postal address, stored location, logo. The square drops the contact rail (phone, email, address).

Every label, at every size, carries the found-portal address. That one is never dropped — it's the whole point of putting a label on a case that leaves the building. See Lost & found.

The 12mm stacked label

The one built for the Shelf-code system, and the right default for most gear. On roughly 69mm of 12mm tape it carries, top to bottom:

1. The QR code.
2. The Shelf code stacked as ART / GRP / 123 / ABC.
3. A Code 128 barcode of the same six characters, running along the tape — sideways, because across 12mm of tape the bars would be thinner than the printer can actually print and no scanner would read them.
4. The found-portal address.

All four carry the same identifier, so however someone comes at it — phone camera, warehouse scanner gun, or reading it aloud — they get the same asset. See Barcodes & codes for what the six characters are and why they look like that.

This layout is Artefact-branded only; the other brands have no six-character wordmark to stack in place of ARTGRP.

The calibration print

Do this once per printer, before you trust a real run. It takes two minutes and it's the difference between a drawer of labels and a drawer of slightly wrong labels.

1. Load 25mm tape.
2. Settings → Labels → Calibration print → Print calibration label (or Test print on a printer's own page under Settings → Printers, which queues the same thing).
3. Take a ruler to what comes out. It prints tick marks every 5mm along the tape and a 10mm × 10mm square.
4. The ticks should measure 5mm apart and the square should measure 10mm on each side.

If either is out by more than a percent or two, the printer isn't printing at the resolution Shelf assumes and every label will be subtly the wrong size — which shows up as QR codes that scan badly rather than as anything obvious. Stop and get that sorted before printing asset labels; it's a setting in the code, so it's a job for whoever maintains your install.

Before a big run on a Zebra, print one label and actually scan it — both the QR and the barcode — with the phone and the scanner you'll be using. The Zebra path is built to Zebra's published spec rather than proved against every model in the wild, and finding out on label one is much cheaper than finding out on label three hundred.

Printing day to day

Once a printer is connected, there are two ways to get a label:

From an asset or kit. Open it, choose Print label…, pick a preset and a printer, choose how many copies (up to 20), print. You get live status in the dialog — Queued, Claimed, Printing, Done — so you know whether to go and look at the printer or go and look at the network.

Blank first, details later — the fast way to add gear. The Get a label button on the Assets page (and floating over the scanner) prints a label from the pool of unassigned codes. Stick it on the case, scan it, and Shelf asks for a title — that's the whole add-an-asset flow: label, scan, name. It beats typing forty records into a laptop and then trying to work out which case each one was. There's also a photo picker on the same panel, but it doesn't attach anything to the asset yet — add a photo afterward from the asset's edit page.

The printer picker remembers your last choice on that device, so the second label is one tap.

When nothing comes out

What you see	What it means	What to do
The job sits at Queued and never moves	No relay is online for that printer	Check Settings → Printers — is the relay's "last seen" recent? If not, the relay program has stopped. Restart it.
Printing is refused with "…is offline (since …)"	The relay is running but can't reach the printer	Check the printer is powered on and on the network, then click Find printer.
Printing is refused with "The relay … is offline"	The relay itself hasn't checked in for three minutes or more	That's the relay machine, not the printer — check it's awake and the program is running.
The job goes straight to Failed with a connection error	Working as intended: the printer really is unreachable	Fix what the error names, then print again.
Find printer seems to do nothing	The relay only picks up the request on its next check-in, and needs a second one to report back	Wait a minute or two and refresh.
The relay never appears at all after install	Usually the key — a stray space from copy-paste, or it's been rotated since	Rotate the key in Settings → Printers and paste it in again carefully.
No printer to choose in the print dialog	Nothing is enabled for the workspace yet	Settings → Printers, enable a printer, or add a relay if there isn't one.

Shelf also emails your Owners and Admins if a printer or its relay stays offline for more than 15 minutes, so a printer that dies on a Friday night isn't discovered at 7am on Monday during a load-out. One honest limit: if your site has only a single relay and that relay's machine dies completely, there's nothing left running to notice — the alert covers a printer dropping off, and covers a relay dropping off when you have more than one. A site running on one relay should treat the "last seen" column in Settings → Printers as the thing to glance at.

Related

• Getting started — the short version of connecting a printer
• Assets, kits & labels — what a label is for and what scanning one does
• Barcodes & codes — the codes being printed
• Lost & found — the address on every label
• Workspace settings — generating and managing batches of codes ahead of a big intake day
• Troubleshooting — quiet zones, calibration, and print jobs that queue silently