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: there is 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. You need Chrome or Edge on a desktop or an Android device. iPhones and iPads cannot do this at all, which is covered at the end.
Setting one up
Go to Configuration → Devices → Printers and press Connect a printer. Cobblr 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 sets it up from the model it recognises. This is the quick path for a Bluetooth printer.
- 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. It is covered under iPhones and iPads below.
You are never asked which kind of Bluetooth your printer uses, because that is not something you should have to know. 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 instead. Nothing is offered that cannot work.
Pick Connect through this browser, choose your printer, 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. Press Print test on the printer's row and a test label comes out.
Your browser asks for the device once per machine, so allowing it on your laptop does not allow it on your phone.
You do not need to know anything about your printer's 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 that have been 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 rather than everything Bluetooth in range, matched on the services a printer advertises and on known model names, so you are not hunting past headphones, phones, and TVs. Some inexpensive printers announce neither and will not appear.
If yours is missing, press Look again. 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, then 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. If it cannot report its roll, which is normal for a plain roll with no size code, you 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. (You can also press Pair & auto-detect there to fill the dialect, width, and orientation from a known profile.)
- 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.
- 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.
- 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.
- 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 in it leaves the printer guessing, so it feeds forward and never comes back.
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.
You do not have to start from Configuration. When the Labels page has no printer, it prompts you to connect a Bluetooth one right there, so you can pair without leaving the page.
Auto-print, and more than one label per feed
Auto-print turns a Bluetooth printer into a hands-off station: open Labels, choose Auto-print, pick your Bluetooth printer, and set when to fire (each label, or every N). From then on, scanning or adding a thing prints its label on its own, with no trip to the queue. Because the browser holds the printer, this 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.
If your labels are wider than one code needs, a Bluetooth printer can print more than one label on each physical label. Set Labels across when you add or edit the printer (2 across a 50 mm roll splits each label into two faces), and both Print and Auto-print tile them onto one feed. A layout you set up on one printer shows up as a reusable option on the next, so you configure it once.
What your printer reports, and what it remembers
Some label printers can sense the roll you have loaded and report it back, along with their battery level. A printer connected as a serial port has a Check button on its row: press it and Cobblr asks the printer what roll is loaded and how much battery is left, so you can 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. Battery shows as a small gauge that fills with the charge actually left and turns amber before a run is at risk; 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. 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 you happened to use, so it is right when you come back tomorrow or print from another computer. Switching printers switches the size with it, so one machine loaded with 40 x 30 stock and one with 50 x 30 each keep their own setting.
If you own two printers of the same model, Cobblr tells them apart so a job cannot come out on the wrong one. It 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. If the printer it expects is switched off or out of range, it asks rather than quietly using the other one.
Why dialect matters so much
A printer set to the wrong dialect connects, accepts everything you send it, and prints nothing. There is no error, because as far as the printer is concerned it never received a single command it recognised. It looks exactly like a printer that is broken, out of paper, or not really connected.
If nothing comes out, change the dialect and print the test again before you change anything else. Try TSPL first on anything sold as a label printer.
Getting the spacing right
The setting that causes the most confusion after dialect is the gap. 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.
Print a few labels, see which way they are creeping, and nudge Gap (mm) a tenth or two in the opposite direction until the drift stops. Getting the sign of the error right matters more than the exact number.
Cobblr can also measure this for you without a ruler and without any help from the printer, which is useful because plenty 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 is enough to work out the true spacing of your roll. That routine currently lives in the printer self-test tool rather than in the app, and that tool does not have a public address yet, so for now the hand-tuning above is the practical route.
When it does not work
| 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 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. |
Two rules of thumb. Garbled output is better news than no output, because it means 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 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 ending up with a printer that looks connected and never prints.
iPhones and iPads
They cannot drive these printers, and this is not something that will 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 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.
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 list of 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. A printer added this way shows as via edge bridge in the printer menu.
Press Test on a bridged printer's row and Cobblr connects and asks the printer about itself; a thermal one answers with the roll it has loaded and its battery, so you can confirm it is ready before sending anything. 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, so the 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 is allowed to reach it.
The bridge path is newer than the browser one, so treat it as the least proven of the routes for now.
Which printer, and which dialect
The cheap Bluetooth label printers sold as PM220 and similar, under brand names like POLONO and NELKO, are largely the same hardware and they 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.
Two things worth checking before you buy anything else:
- 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 one in your computer's Bluetooth settings first, then use 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.