Bluetooth label printers

Cheap thermal label printers are the ones most people end up buying for bin and part labels. Almost none of them join your network: no IP address, no web page, nothing on the network can reach them. They speak Bluetooth to a phone app and that is it. Cobblr prints to them from your browser instead. No print server, no cables, no vendor app.

To set one up:

1. Use Chrome or Edge on a desktop or an Android device. iPhones and iPads cannot do this at all, see iPhones and iPads.
2. Go to Configuration → Devices → Printers and press Connect a printer.
3. Pick Connect through this browser, then choose your printer.
4. Press Print test on the printer's row. Nothing came out? Change the Command dialect and print the test again before anything else.

Setting one up

Connect a printer asks one question, and it is not a technical one: whether you want to install anything.

• Connect through this browser installs nothing. Your browser asks which printer to use, you pick yours, and Cobblr asks the printer what it is, then fills in the dialect, width, and orientation from a saved profile. There is usually nothing to type.
• Connect through an edge bridge uses a small helper app that reaches printers a browser cannot, keeps printing when you close the tab, and prints from a phone. See iPhones and iPads below.
• The door that works on your device comes first. On Safari, Firefox, and anything on an iPhone or iPad no browser can reach a label printer directly, so the browser door is greyed out with the reason and the bridge leads. Nothing is offered that cannot work.
• Your browser asks for the device once per machine, so allowing it on your laptop does not allow it on your phone.
• The Labels page prompts you to connect a Bluetooth printer when it has none, so you do not have to start from Configuration.

How Cobblr recognises a printer it has never seen

You are never asked which kind of Bluetooth your printer uses, and you do not need to know anything about its internals. When Cobblr connects it looks at the channels the printer offers and picks the one most likely to be the print pipe, preferring ones known to be used for printing, so a model nobody has tried before still works. Models tested against real hardware ship with their settings recorded, so for those the numbers are confirmed rather than guesswork. Supporting a new model is a settings change, not a code change.

If your printer is not in the list

The device chooser shows label printers only, matched on the services a printer advertises and on known model names. Some inexpensive printers announce neither and will not appear.

1. Press Look again.
2. Still missing? Some label printers, usually the ones that ship with a USB cable, use an older kind of Bluetooth (Classic) that no browser can reach over Bluetooth at all, whatever the pairing screen suggests. Pair the printer in your computer's own Bluetooth settings first.
3. Press Find my paired printer and pick it. Cobblr reaches it as a serial port instead, and asks it what roll is loaded so there is nothing to measure.
4. If it cannot report its roll (normal for a plain roll with no size code), set the label size by hand to finish.

• This route needs Chrome or Edge on a desktop computer. Phones and tablets cannot open a serial port from a web page.
• Either way you connect, Cobblr sends an identical label, so everything else on this page works the same.

Setting it up by hand

For a model Cobblr does not recognise yet, or to change a setting afterwards, open Add printer or Edit for the full form. (Pair & auto-detect there fills the dialect, width, and orientation from a known profile.)

1. Pick the Command dialect. This is the language your printer speaks, and it is the one setting worth getting right before anything else. Most cheap label printers use TSPL. Phomemo M-series and similar receipt-style printers use ESC/POS raster.
2. Describe the roll you loaded. Enter the media width in millimetres and pick the feed type. Cobblr works out the print width from that (and shows it in inches too). A printer you set up earlier keeps working and shows its width converted to millimetres when you edit it.
3. On TSPL, describe the label. Label height (mm) and Gap (mm) are the label and the unprinted space between one label and the next. Orientation flips the image around. Top margin is the strip at the top of each label the print head cannot reach.
4. If a blank label feeds out between prints, turn on Don't feed to the tear bar. Printers push the finished label out to be torn off, then pull it back before the next one, but a roll with no size code leaves the printer guessing, so it feeds forward and never comes back.

Three ways to print to it

Everything below prints from the browser tab you are in, because that is the only thing that can reach a Bluetooth printer. Print test on the printer's row checks the setup. Print label on any record prints that one label straight away when a Bluetooth printer is your default, which is the label-as-you-go workflow. And Print to on the Labels page prints the whole queued batch. Your browser asks which printer to use once per session, not once per label.

The one thing that still needs a networked printer or an edge bridge is printing with no browser open: from an iPhone, or from an automation.

Auto-print, and more than one label per feed

• Auto-print makes a Bluetooth printer a hands-off station: open Labels, choose Auto-print, pick the printer, and set when to fire (each label, or every N). Scanning or adding a thing then prints its label with no trip to the queue.
• It runs while the Labels tab is open and the printer is connected, because the browser holds the printer. Close the tab or walk out of range and it pauses until you reconnect.
• Labels across, set when you add or edit the printer, prints more than one label on each physical label when your labels are wider than one code needs (2 across a 50 mm roll splits each label into two faces). Both Print and Auto-print tile them onto one feed.
• A layout set up on one printer is a reusable option on the next, so you configure it once.

What your printer reports, and what it remembers

• Check, on the row of a printer connected as a serial port, asks it what roll is loaded and how much battery is left, before a run rather than after wasting labels.
• Printers driven over Bluetooth straight from the browser print normally but stay silent about their status, so no reading appears for them.
• Each printer remembers the label size loaded in it, saved with your workspace rather than the browser, so it is right when you come back tomorrow or print from another computer. Switching printers switches the size with it.
• Two printers of the same model are told apart, so a job cannot come out on the wrong one. If the printer it expects is switched off or out of range, it asks rather than quietly using the other one.

How the readings and the memory work

The roll size is read from the media itself, so it follows a roll swap. Battery shows as a small gauge that fills with the charge actually left and turns amber before a run is at risk, and a printer that is charging is never flagged as low. The reading is taken once per visit, not continuously, because asking costs a real connection to the printer.

One machine loaded with 40 x 30 stock and one with 50 x 30 each keep their own size setting. Cobblr learns which physical machine is which the first time you pair or print, from the printer you pick in the browser's device list. That memory belongs to the browser you set it up in, because Bluetooth does not expose a permanent hardware serial, so on another computer Cobblr asks you to pick once more.

When it does not work

Try TSPL first on anything sold as a label printer.

What you see	What it is	What to do
It connects and accepts the job, but nothing prints	The dialect is wrong. Silent, because the printer did not recognise anything you sent.	Switch Command dialect and print the test again.
Each label prints a little further off than the last	The gap is wrong, so the printer's idea of where a label starts drifts from where it really starts.	Adjust Gap (mm) as described below.
Everything is upside down	Orientation. Some models treat the roll as feeding the other way.	Switch Orientation.
The top of every label is cut off	Content is being drawn into the strip the print head cannot reach.	Raise Top margin (dots). 24 dots is about 3 mm, which is typical.
A blank label feeds out between every print	The roll has no size code in it, so the printer feeds to the tear bar and guesses where the next label starts.	Turn on Don't feed to the tear bar in the printer's settings.
Nothing happens, then everything prints at once after you open and close the lid	The printer was not ready and quietly buffered the jobs instead of saying so. It flushes them when it decides it is ready.	Open and close the lid. If a printer seems dead, press its feed button first. If paper feeds, the printer is fine and you have a dialect or readiness problem.
Your printer is not in the browser's device chooser at all	Probably Bluetooth Classic rather than Bluetooth Low Energy. Browsers can only reach the latter over Bluetooth.	Press Look again, pair the printer in your computer's Bluetooth settings, then Find my paired printer so Cobblr reaches it as a serial port. If it still will not drive from a browser, use USB if it has a port, or an edge bridge.

• Garbled output is better news than no output. It means Cobblr is talking to the right channel and only the dialect or width is off.
• Close the printer's own phone app if it is open. It holds the Bluetooth connection and your browser cannot take it.

Why the wrong dialect looks like a dead printer, and what Cobblr refuses up front

A printer set to the wrong dialect connects, accepts everything you send it, and prints nothing, with no error, because it never received a single command it recognised. It looks exactly like a printer that is broken, out of paper, or not really connected.

When a printer connects but cannot be driven from a browser, Cobblr names the reason and offers the way that does work, usually an edge bridge, rather than showing a raw browser error. A model whose Bluetooth accepts everything and prints nothing is recognised and refused up front, so you are pointed at the bridge instead of a printer that looks connected and never prints.

Getting the spacing right

The gap causes the most confusion after dialect. If it is wrong, every label prints slightly further along the roll than the one before, so after a dozen labels your content has walked off the edge. The giveaway is a steady drift in one direction rather than a random mess.

1. Print a few labels and see which way they are creeping.
2. Nudge Gap (mm) a tenth or two in the opposite direction.
3. Repeat until the drift stops. Getting the sign of the error right matters more than the exact number.

Measuring the gap without a ruler (not shipped yet)

Cobblr can also measure this without a ruler and without help from the printer (plenty of them ignore their own calibration command). It prints a card with a numbered scale, you read back the topmost number you can actually see, and doing that twice works out the true spacing of your roll. That routine lives in an internal calibration tool that has not shipped in the app yet, so hand-tuning is the practical route for now. When the guided calibration lands it will replace this paragraph.

iPhones and iPads

They cannot drive these printers, and this will not be fixed. Neither Safari nor Chrome on iOS supports Web Bluetooth, and there is no server-side way around it, because the printer travels with the person instead of sitting on the network.

The way around it is an edge bridge: a small always-on machine near the printer (a Raspberry Pi is the usual choice) that holds the connection and takes jobs from Cobblr over the network. There are two ways to point at one:

• A bridge on the same computer you browse from. Choose Connect through an edge bridge in the Connect flow. If a bridge is already running on this machine, Cobblr finds it and lists its printers by name. You press Add, with no address, port, or token to type. This prints straight from your browser, so it needs no pairing to anything and no relay token.
• A bridge on a separate machine, like a Pi in the workshop. Add the printer from Configuration → Devices → Printers, choose Via edge bridge, pick the bridge from the ones your workspace already knows, and press Ask the bridge what it serves to fill in the printer instead of typing its instance name from memory. It then shows as via edge bridge in the printer menu.
• Test on a bridged printer's row asks the printer about itself. A thermal one answers with its loaded roll and battery, so you can confirm it is ready before sending anything.
• The bridge holds the printer's calibration. Dialect, margins, and feed are configured once in the bridge, and Cobblr sends it the label as an image.
• The bridge path is newer than the browser one, so treat it as the least proven route for now.

What else a bridge gives you, and two setup notes

A bridge also lets printing happen with nobody present, which is what an automation needs, and it reaches Bluetooth Classic printers a browser cannot. Pointing Cobblr at a bridge is a change of route, not a different kind of printer, so every setting above stays the same.

If the address answers but the printer is asleep or out of range, the test says so. If nothing answers at the address at all, it says that instead, because the two have different fixes.

A self-hosted Cobblr on its own domain has to be added to the bridge's list of trusted web origins before the browser is allowed to reach it.

Which printer, and which dialect

• PM220 and similar, sold under brand names like POLONO and NELKO, are largely the same hardware and speak TSPL. A POLONO PM220S is the model we bench-tested, and its settings ship with Cobblr.
• Phomemo M-series printers are the common exception: they speak ESC/POS raster.
• Between those two families you have covered most of what is on sale for under about forty dollars.
• Bluetooth Low Energy is the smoother kind. A listing that tells you to pair through its own app rather than your phone's Bluetooth settings is a hint it is the right kind. Bluetooth Classic models work too, but only from a desktop, through the steps above.
• A model with a USB port gives you a fallback if the Bluetooth side turns out to be awkward.
• Already own a 4 × 6 shipping-label printer? You do not need any of this. See Label printers for that route, including printing several small labels on one 4 × 6 and cutting them apart.

For what size labels to use and how to lay them out, see QR labels.