# Memperbaiki Struk Printer Termal Bluetooth Flutter yang Kacau

> Debugging berbasis gejala untuk pencetakan termal Flutter: code page tidak cocok, buffer meluap, penulisan berpotongan, ukuran kertas salah, dan triase lima menit.

URL: https://www.matthewswong.com/id/blog/flutter-thermal-printer-garbled-receipt-fixes/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-08-18
- Updated: 2026-08-18
- Category: Software Development

> **Key takeaway:** 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 |

*Taksonomi kegagalan yang sama berlaku untuk printer label maupun printer struk, karena keduanya menerima aliran byte tanpa kanal umpan balik. Yang bisa Anda periksa adalah keluarannya, jadi keluaran itulah titik awal debugging. Foto:*

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

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.

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.

*Kriteria sukses yang sesungguhnya: struk utuh, setiap baris lengkap, diakhiri pemotongan. Sampai kertasnya terlihat seperti ini, transport yang melaporkan sukses hanya berarti byte-nya sudah meninggalkan ponsel. Foto:*

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

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

## Sumber dan bacaan lanjutan

- Epson ESC/POS Command Reference
- Dokumentasi python-escpos tentang code page dan magic encode
- esc_pos_utils_plus di pub.dev (capability profile, ukuran kertas)
- esc_pos_bluetooth di GitHub (pola penulisan berpotongan)

## Source links

- https://reference.epson-biz.com/modules/ref_escpos/index.php
- https://python-escpos.readthedocs.io/en/latest/api/magicencode.html
- https://pub.dev/packages/esc_pos_utils_plus
- https://github.com/andrey-ushakov/esc_pos_bluetooth

## FAQ

### Kenapa printer termal saya mencetak simbol acak alih-alih teks?

Kalau hanya karakter beraksen yang salah, byte UTF-8 sedang dibaca lewat code page satu byte sehingga tiap byte menjadi glifnya sendiri. Kalau karakter pertama saja sudah berupa sampah, dialek perintahnya yang salah — biasanya capability profile yang tidak cocok dengan perangkat keras, atau urutan byte yang disalin dari model printer lain.

### Kenapa struk panjang berhenti tercetak di tengah?

Payload-nya melampaui buffer printer. Printer Bluetooth 58 mm punya buffer kecil dan sering tanpa flow control yang berguna, jadi penulisan panjang bisa kehilangan ekornya begitu saja. Kirim dalam potongan sekitar 128 sampai 256 byte dengan jeda pendek di antaranya, dan setel kedua nilainya memakai struk terpanjang yang benar-benar dicetak toko.

### Tata letaknya terbaca tapi tidak ada yang rata. Apa yang salah?

Hampir pasti ukuran kertas yang diberikan ke generator. Membangun untuk 80 mm lalu mencetak di 58 mm tidak terpotong dengan jelas; ia menghasilkan teks yang secara konsisten tidak sejajar di margin kanan karena jumlah kolomnya salah. Periksa argumen PaperSize sebelum yang lain.

### Aplikasi bilang cetak berhasil tapi tidak ada yang keluar. Kenapa?

Penulisan yang sukses hanya berarti byte meninggalkan perangkat. Penyebab umumnya adalah koneksi basi setelah printer tidur atau sempat dimatikan, atau printer yang sedang tidur dan kehilangan penulisan pertama yang membangunkannya. Sambung ulang dan coba sekali lagi secara otomatis sebelum menampilkan error ke kasir.

### Bagaimana men-debug masalah pencetakan yang dilaporkan sebuah toko?

Bekerjalah naik dari perangkat keras. Cetak self test milik printer, lalu inisialisasi polos ditambah beberapa karakter dan perintah potong, lalu teks bergaya, lalu byte fixture yang di-commit, baru struk sungguhan. Setiap langkah menambah tepat satu lapisan, jadi langkah pertama yang gagal langsung menyebut pelakunya tanpa menebak.

---

- HTML version: https://www.matthewswong.com/id/blog/flutter-thermal-printer-garbled-receipt-fixes/
- English: https://www.matthewswong.com/en/blog/flutter-thermal-printer-garbled-receipt-fixes/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
