Skip to main content
BlogSoftware Development

Fixing Garbled Flutter Bluetooth Thermal Printer Receipts

Symptom-first debugging for Flutter thermal printing: code page mismatches, buffer overruns, chunked writes, wrong paper size and a five-minute triage.

Matthews Wong

Software Engineer

August 202611 min read
Fixing Garbled Flutter Bluetooth Thermal Printer Receipts

Key Takeaway

Garbled Bluetooth receipts almost always have one of five causes: UTF-8 sent to a single-byte code page, a payload that overran the printer buffer, the wrong paper size in the generator, a capability profile that does not match the hardware, or a stale connection. Each has a distinct symptom on paper.

Thermal printing fails in a uniquely unhelpful way: the printer accepts everything, reports nothing, and the only diagnostic output is a strip of paper. That paper, though, is a surprisingly precise error message once you learn to read it — the shape of the corruption tells you which layer broke.

This is symptom-first debugging. Find the row that matches what came out of the printer, then read the section that explains it.

Read the paper: five symptoms, five causes

Before changing any code, look carefully at the failed receipt and match it against this table. The match is usually unambiguous.

What the paper showsAlmost certainlyWhere to look
Correct layout, but accented characters are two odd glyphsUTF-8 bytes interpreted through a single-byte code pageText encoding and the active code page
Perfect start, then it stops mid-receiptThe payload outran the printer's bufferChunked writes and inter-chunk delay
Everything readable but nothing lines up at the marginWrong paper size, so the column count is wrongThe generator's PaperSize argument
Random symbols from the very first characterA wrong or unsupported command dialectThe capability profile and any hardcoded byte sequences
Nothing at all, but the app reports successA stale connection, or the printer asleepConnect, reconnect and retry logic
A small thermal label printer photographed against a plain background
The same failure taxonomy applies to label printers and receipt printers alike, because both take a byte stream with no feedback channel. What you can inspect is the output, so the output is where debugging starts. Photo: Wagtail11 / Wikimedia Commons, CC0

Symptom one: mangled accented characters

This is the most common report and the easiest to fix. The printer holds single-byte character tables and prints from whichever one is active; UTF-8 sequences arrive as separate bytes, so each becomes its own glyph.

// Symptom: "Rp 25.000" prints as "Rp 25.000" on one printer and as
// two stray glyphs on another. Cause: the bytes were UTF-8 and the
// printer was reading them through a single-byte code page.

// Wrong — hands raw UTF-8 to a printer that has never heard of it.
bytes.addAll(utf8.encode('Café Anggrek'));

// Right — let the generator encode to the active code page, and pick
// a capability profile that matches the hardware.
final profile = await CapabilityProfile.load(name: 'default');
final generator = Generator(PaperSize.mm58, profile);
bytes.addAll(generator.text('Cafe Anggrek'));   // ASCII survives anywhere

// Safest of all for shop data you do not control: normalise first.
String asciiFold(String input) => input
    .replaceAll(RegExp(r'[\u2018\u2019]'), "'")
    .replaceAll(RegExp(r'[\u201C\u201D]'), '"')
    .replaceAll('\u00A0', ' ');

Two defences. Let the generator encode text through a capability profile rather than pushing raw bytes yourself, and normalise incoming shop data — supplier catalogues are full of curly apostrophes and non-breaking spaces that survive a database round trip and die at the print head.

Beware of testing only with your own product names. Development data is clean ASCII; real shop data includes degree signs, en dashes pasted from a spreadsheet, and the occasional emoji in a product name. Test with a copy of the customer's actual catalogue before release.

Symptom two: the receipt stops halfway

A 58 mm printer has a small buffer and, over Bluetooth serial, often no usable flow control. Write a long receipt in one call and the tail can simply be dropped. The give-away is that failures correlate with receipt length: three-line tests always work, forty-line kitchen tickets fail.

/// Symptom: the top of the receipt is perfect and the bottom is
/// missing, or a long receipt prints as fragments. Cause: the payload
/// outran a small serial buffer with no flow control in between.
const chunkSize = 256;            // conservative; some firmware wants 128
const pauseBetweenChunks = Duration(milliseconds: 40);

Future<void> sendChunked(List<int> bytes) async {
  for (var offset = 0; offset < bytes.length; offset += chunkSize) {
    final end = (offset + chunkSize).clamp(0, bytes.length);
    await PrintBluetoothThermal.writeBytes(bytes.sublist(offset, end));
    await Future.delayed(pauseBetweenChunks);
  }
}

// Tune chunkSize and the pause together, and measure with the longest
// receipt the shop actually prints — a 40-line kitchen ticket, not the
// three-line demo that always worked.

Chunking with a short pause fixes it, and the numbers are hardware-specific. Start conservative, then measure with the longest receipt the shop actually prints. A pause that is too short reintroduces truncation; one that is too long makes a busy counter feel sluggish, so tune both values together rather than doubling one blindly.

A complete printed shop receipt with header, item lines, total and footer all legible
The actual success criterion: a complete receipt, every line intact, ending in a cut. Until the paper looks like this, a transport reporting success only means bytes left the phone. Photo: Виктор Пинчук / Wikimedia Commons, CC BY 4.0

The three remaining symptoms

The rest of the table resolves quickly once you know what to check.

  • Misalignment everywhere points at paper size. Passing 80 mm to the generator while printing on 58 mm produces text that is readable and consistently wrong at the right margin.
  • Garbage from the very first character points at the command dialect. Load a capability profile that matches the hardware and remove any hand-rolled byte sequences copied from a forum post for a different model.
  • Silence with a successful write points at the connection. Portable printers sleep, and the first write after that is often lost — reconnect and retry once before surfacing an error.
  • Faint or patchy print is not a software bug at all. It is paper quality, a dirty head or a flat battery, and no amount of code will fix it.

That last one deserves emphasis because it wastes the most engineering time. If the printer's own self test is faint, stop debugging your app.

A five-minute triage that isolates the layer

When a report comes in, work up from the hardware rather than down from the code. Each step adds exactly one layer, so the first failure names the culprit.

/// The five-minute triage script. Run it before reading any app code.
/// Each step isolates one layer, and the first one that fails is the bug.
///
/// 1. Print the printer's own self test  (hold FEED while powering on)
///       -> proves paper, head, battery, firmware
/// 2. Send ESC @ then "HELLO" then a cut, nothing else
///       -> proves pairing, SPP link and write path
/// 3. Send the same with double height and bold
///       -> proves the style commands the profile is emitting
/// 4. Send one full receipt from a committed byte fixture
///       -> proves the builder, in isolation from live data
/// 5. Send the live receipt that failed
///       -> whatever changed between 4 and 5 is your defect

Keeping a committed byte fixture for step four is what makes this fast. It removes live data, network state and the ERP from the picture, so if the fixture prints and the live receipt does not, the defect is provably in how the receipt was built rather than in how it was sent.

Add a hidden developer screen that dumps the last generated payload as hex and can re-send it. Being able to ask a shop to tap two buttons and read you the first sixteen bytes replaces an entire day of speculation.

Preventing the next one

Three habits have kept these bugs from recurring in the apps I maintain.

  • Golden byte fixtures in CI, so a layout or encoding change fails a test rather than a shop.
  • One place that formats currency and one place that normalises product names, both applied before the receipt is built.
  • A printer settings screen that shows adapter state, permission state, pairing state and last result, so the shop can distinguish the four causes without you.

Bluetooth thermal printing looks unreliable mostly because its failures are silent. Give yourself a feedback loop — read the paper, isolate a layer at a time, keep a byte fixture — and the same five causes explain nearly every garbled receipt you will ever be sent a photograph of.

FAQ

Frequently Asked Questions

Short answers to what readers ask most about this topic.

Why does my thermal printer print random symbols instead of text?

If only accented characters are wrong, UTF-8 bytes are being read through a single-byte code page and each byte becomes its own glyph. If the very first character is already garbage, the command dialect is wrong — usually a capability profile that does not match the hardware, or byte sequences copied from a different printer model.

Why does a long receipt stop printing halfway through?

The payload outran the printer's buffer. A 58 mm Bluetooth printer has a small buffer and often no usable flow control, so a long write can simply have its tail dropped. Send in chunks of around 128 to 256 bytes with a short pause between them, and tune both values with the longest receipt the shop actually prints.

The layout is readable but nothing aligns. What is wrong?

Almost certainly the paper size passed to the generator. Building for 80 mm and printing on 58 mm does not clip obviously; it produces text that is consistently misaligned at the right margin because the column count is wrong. Check the PaperSize argument before anything else.

The app says printing succeeded but nothing came out. Why?

A successful write only means bytes left the device. The usual causes are a stale connection after the printer slept or was power-cycled, or the printer being asleep and losing the first write that wakes it. Reconnect and retry once automatically before showing an error to the cashier.

How do you debug a printing problem reported from a shop?

Work up from the hardware. Print the printer's own self test, then a bare initialise plus a few characters plus a cut, then styled text, then a committed byte fixture, then the live receipt. Each step adds exactly one layer, so the first step that fails names the culprit without guessing.