Bluetooth label printers

Cobblr prints to cheap Bluetooth thermal label printers straight from your browser: no print server, no cables, no vendor app. You need Chrome or Edge on a desktop or an Android device. iPhones and iPads cannot do this at all (see iPhones and iPads).

The loop:

1. Go to Configuration → Devices → Printers, press Connect a printer.
2. Pick Connect through this browser and choose your printer. Cobblr asks the printer what it is and fills in the dialect, width, and orientation from a saved profile, so there is usually nothing to type.
3. Press Print test on the printer's row, and a test label comes out.

Setting one up

The Connect flow asks one non-technical question: whether you want to install anything.

• Connect through this browser installs nothing: your browser asks which printer, you pick yours, Cobblr sets it up from the model it recognises. The quick path for a Bluetooth printer.
• Connect through an edge bridge is 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.
• The browser asks for the device once per machine: allowing it on your laptop does not allow it on your phone.
• No trip to Configuration needed: when the Labels page has no printer, it prompts you to connect a Bluetooth one right there.

Why there is nothing technical to answer

You are never asked which kind of Bluetooth your printer uses, and you should not have to know. These printers never join your network (no IP address, no web page, only Bluetooth), so Cobblr puts the door that works on your device 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.

On connect, Cobblr picks the channel most likely to be the print pipe, preferring ones known to be used for printing, so an untried model still works. Bench-tested models ship with their settings recorded, so their 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

1. Press Look again.
2. Still missing? Some label printers, usually ones that ship with a USB cable, use older Bluetooth Classic, which 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 and asks it what roll is loaded, so there is nothing to measure. 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, because 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.

Why some printers never appear in the chooser

The chooser shows label printers rather than everything Bluetooth in range, matched on advertised services and known model names, so you are not hunting past headphones, phones, and TVs. Some inexpensive printers announce neither and will not appear.

Setting it up by hand

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

1. Pick the Command dialect: the language your printer speaks, and the one setting worth getting right first. Most cheap label printers use TSPL. Phomemo M-series and similar receipt-style printers use ESC/POS raster.
2. Enter the media width in millimetres and pick the feed type. Cobblr works out the print width (shown in inches too). A printer 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 labels. Orientation flips the image, and Top margin is the strip at the top 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, 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 prints from the browser tab you are in, 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, the label-as-you-go workflow. Print to on the Labels page prints the whole queued batch. The browser asks which printer once per session, not 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 hands-off station: open Labels, choose Auto-print, pick your Bluetooth printer, set when to fire (each label, or every N). From then on, scanning or adding a thing prints its label on its own, no trip to the queue. The browser holds the printer, so it runs while the Labels tab is open and the printer is connected. Close the tab or walk out of range and it pauses until you reconnect.
• Labels across prints more than one label per physical label when your stock is wider than one code needs. Set it when adding or editing the printer (2 across a 50 mm roll splits each label into two faces). Print and Auto-print both tile onto one feed. A layout set up on one printer shows as a reusable option on the next.

What your printer reports, and what it remembers

• Check, on the row of a serial-port printer, asks it what roll is loaded and how much battery is left, so you see it before a run rather than after wasting labels. The roll size is read from the media itself, so it follows a roll swap. Printers driven over Bluetooth straight from the browser print normally but stay silent about their status.
• Each printer remembers its loaded label size, saved with your workspace rather than the browser, so it is right tomorrow or from another computer. Switching printers switches the size: one machine with 40 x 30 stock and one with 50 x 30 each keep their own setting.
• Two printers of the same model are told apart, so a job cannot come out on the wrong one. If the expected printer is off or out of range, Cobblr asks rather than quietly using the other.

Battery gauge behaviour, and how same-model printers are recognised

Battery shows as a small gauge that fills with the charge actually left and turns amber before a run is at risk. A charging printer is never flagged low. The reading is taken once per visit, not continuously, because asking costs a real connection to the printer.

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 (Bluetooth exposes no permanent hardware serial), so on another computer Cobblr asks you to pick once more.

When it does not work

If nothing comes out, switch the Command dialect and print the test again before changing anything else. Try TSPL first on anything sold as a label printer. If labels drift steadily in one direction, nudge Gap (mm) a tenth or two the opposite way until the drift stops.

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 above.
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, 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, then flushed them when it decided it was 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 Low Energy. Browsers only reach the latter over Bluetooth.	Press Look again, pair 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.

Rules of thumb, and measuring the gap without a ruler

A wrong-dialect printer looks exactly like one that is broken, out of paper, or not really connected. A wrong gap is a steady drift in one direction, not a random mess: each label prints slightly further along the roll until your content walks off the edge, and getting the sign of the error right matters more than the exact number. Cobblr can also measure the spacing without a ruler and without any help from the printer (many of these printers 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. That routine currently lives in the printer self-test tool, which has no public address yet, so for now hand-tuning is the practical route.

Two rules of thumb. Garbled output is better news than no output: Cobblr is talking to the right channel and only the dialect or width is off. And if the printer's own phone app is open, close it: it holds the Bluetooth connection and your browser cannot take it.

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 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.

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. A bridge also prints with nobody present (what an automation needs) and reaches Bluetooth Classic printers a browser cannot. Pointing at a bridge is a change of route, not a different kind of printer, so every setting above stays the same. Two ways to point at one:

• A bridge on the computer you browse from: choose Connect through an edge bridge in the Connect flow. A bridge already running on this machine is found automatically and its printers listed by name. Press Add, with no address, port, or token to type. This prints straight from your browser, so it needs no pairing and no relay token.
• A bridge on a separate machine (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.

Press Test on a bridged printer's row: Cobblr connects and asks the printer about itself, and a thermal one answers with its loaded roll and battery, so you can confirm it is ready before sending anything.

Bridge details: test messages, calibration, trusted origins

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.

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. A self-hosted Cobblr on its own domain has to be added to the bridge's list of trusted web origins before the browser may reach it.

The bridge path is newer than the browser one, so treat it as the least proven route for now.

Which printer, and which dialect

• PM220-family printers (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: ESC/POS raster.
• Those two families cover 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: pair in your computer's Bluetooth settings, then Find my paired printer.
• A model with a USB port gives you a fallback if the Bluetooth side turns out to be awkward.

If you 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.