Ringkasan Utama
Struk Bluetooth yang kacau hampir selalu punya salah satu dari lima penyebab: UTF-8 dikirim ke code page satu byte, payload yang melampaui buffer printer, ukuran kertas salah di generator, capability profile yang tidak cocok dengan perangkat keras, atau koneksi basi. Masing-masing punya gejala berbeda di kertas.
Pencetakan termal gagal dengan cara yang unik tidak membantu: printer menerima segalanya, tidak melaporkan apa pun, dan satu-satunya keluaran diagnostiknya adalah selembar kertas. Namun kertas itu justru pesan error yang sangat presisi begitu Anda belajar membacanya — bentuk kerusakannya memberi tahu lapisan mana yang bermasalah.
Ini debugging berbasis gejala. Temukan baris yang cocok dengan apa yang keluar dari printer, lalu baca bagian yang menjelaskannya.
Baca kertasnya: lima gejala, lima penyebab
Sebelum mengubah kode apa pun, amati struk yang gagal dengan teliti dan cocokkan dengan tabel ini. Kecocokannya biasanya tidak ambigu.
| Apa yang terlihat di kertas | Hampir pasti | Periksa di mana |
|---|---|---|
| Tata letak benar, tetapi karakter beraksen jadi dua glif aneh | Byte UTF-8 dibaca lewat code page satu byte | Encoding teks dan code page yang aktif |
| Awalnya sempurna, lalu berhenti di tengah struk | Payload melampaui buffer printer | Penulisan berpotongan dan jeda antar potongan |
| Semua terbaca tapi tidak ada yang rata di margin | Ukuran kertas salah, sehingga jumlah kolomnya salah | Argumen PaperSize pada generator |
| Simbol acak sejak karakter pertama | Dialek perintah salah atau tidak didukung | Capability profile dan urutan byte yang di-hardcode |
| Tidak ada apa-apa, tetapi aplikasi melaporkan sukses | Koneksi basi, atau printer sedang tidur | Logika connect, reconnect, dan percobaan ulang |

Gejala satu: karakter beraksen berantakan
Ini laporan paling umum sekaligus paling mudah diperbaiki. Printer menyimpan tabel karakter satu byte dan mencetak dari tabel mana pun yang aktif; urutan UTF-8 tiba sebagai byte-byte terpisah, sehingga masing-masing menjadi glifnya sendiri.
// 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', ' ');Dua pertahanan. Biarkan generator meng-encode teks lewat capability profile alih-alih Anda mendorong byte mentah sendiri, dan normalkan data toko yang masuk — katalog pemasok penuh apostrof melengkung dan spasi non-breaking yang selamat melewati basis data lalu mati di kepala cetak.
Hati-hati kalau hanya menguji dengan nama produk buatan sendiri. Data pengembangan adalah ASCII yang bersih; data toko sungguhan berisi tanda derajat, tanda pisah en yang ditempel dari spreadsheet, dan sesekali emoji di nama produk. Uji dengan salinan katalog asli pelanggan sebelum rilis.
Gejala dua: struk berhenti di tengah jalan
Printer 58 mm punya buffer kecil dan, lewat Bluetooth serial, sering tanpa flow control yang berguna. Tulis struk panjang dalam satu panggilan dan ekornya bisa hilang begitu saja. Petunjuknya: kegagalan berkorelasi dengan panjang struk — uji tiga baris selalu berhasil, tiket dapur empat puluh baris gagal.
/// 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.Memotongnya dengan jeda pendek memperbaiki hal ini, dan angkanya spesifik per perangkat keras. Mulai dari nilai konservatif, lalu ukur dengan struk terpanjang yang benar-benar dicetak toko. Jeda yang terlalu pendek memunculkan lagi pemotongan; yang terlalu panjang membuat meja kasir sibuk terasa lelet, jadi setel kedua nilainya bersamaan alih-alih menggandakan salah satunya secara buta.

Tiga gejala sisanya
Sisa tabelnya cepat terselesaikan begitu Anda tahu apa yang harus diperiksa.
- Ketidaksejajaran di mana-mana menunjuk ke ukuran kertas. Memberi 80 mm ke generator sementara mencetak di 58 mm menghasilkan teks yang terbaca dan salah secara konsisten di margin kanan.
- Sampah sejak karakter pertama menunjuk ke dialek perintah. Muat capability profile yang cocok dengan perangkat kerasnya dan hapus urutan byte buatan tangan yang disalin dari forum untuk model lain.
- Kesunyian dengan penulisan yang sukses menunjuk ke koneksi. Printer portabel tidur, dan penulisan pertama setelah itu sering hilang — sambung ulang dan coba sekali lagi sebelum memunculkan error.
- Cetakan pudar atau belang sama sekali bukan bug perangkat lunak. Itu soal mutu kertas, kepala cetak kotor, atau baterai habis, dan tidak ada kode yang bisa memperbaikinya.
Poin terakhir layak ditegaskan karena paling banyak membuang waktu rekayasa. Kalau self test printer sendiri sudah pudar, hentikan debugging aplikasi Anda.
Triase lima menit yang mengisolasi lapisannya
Ketika laporan masuk, bekerjalah naik dari perangkat keras, bukan turun dari kode. Setiap langkah menambah tepat satu lapisan, jadi kegagalan pertama langsung menyebut pelakunya.
/// 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 defectMenyimpan byte fixture yang di-commit untuk langkah keempat itulah yang membuat proses ini cepat. Ia menyingkirkan data langsung, kondisi jaringan, dan ERP dari gambaran, sehingga kalau fixture-nya tercetak dan struk langsungnya tidak, cacatnya terbukti ada pada cara struk dibangun, bukan pada cara ia dikirim.
Tambahkan layar developer tersembunyi yang membuang payload terakhir sebagai heksa dan bisa mengirimnya ulang. Bisa meminta toko menekan dua tombol lalu membacakan enam belas byte pertama menggantikan spekulasi sepanjang satu hari penuh.
Mencegah kejadian berikutnya
Tiga kebiasaan mencegah bug-bug ini berulang di aplikasi yang saya rawat.
- Golden byte fixture di CI, sehingga perubahan tata letak atau encoding menggagalkan tes, bukan menggagalkan toko.
- Satu tempat yang memformat mata uang dan satu tempat yang menormalkan nama produk, keduanya diterapkan sebelum struk dibangun.
- Layar pengaturan printer yang menampilkan status adapter, status izin, status pairing, dan hasil terakhir, sehingga toko bisa membedakan keempat penyebabnya tanpa Anda.
Pencetakan termal Bluetooth terlihat tidak andal terutama karena kegagalannya senyap. Beri diri Anda lingkar umpan balik — baca kertasnya, isolasi satu lapisan sekaligus, simpan byte fixture — dan lima penyebab yang sama akan menjelaskan hampir setiap struk kacau yang fotonya pernah dikirimkan kepada Anda.

