Setup Printer Termal Bluetooth Panda 58mm di Flutter

Printer Panda ada di mana-mana di ritel Indonesia. Ia duduk di meja warung, di dalam tas kurir, dan di balik loket PPOB, harganya sebagian kecil dari Epson meja, dan ia adalah printer yang paling sering diminta didukung oleh aplikasi POS Indonesia. Ia juga alasan banyak developer Flutter menemukan bahwa mencetak lewat Bluetooth bukan satu masalah melainkan tiga: izin, pairing, dan protokol.

Ini setup yang bertahan bagi saya di beberapa perangkat dan versi Android, ditulis dalam urutan yang seharusnya Anda kerjakan, bukan urutan yang dipakai dokumentasi paketnya.

Printer Panda itu apa, secara teknis

Panda adalah merek, bukan protokol, dan hal yang berguna dari lini ini justru betapa konvensionalnya ia. Membaca spesifikasi resmi model-model umum sudah memberi hampir semua yang Anda butuhkan sebelum menulis kode.

• Model meja PRJ-58D mencetak hingga 100 mm per detik pada kertas 57,5 mm lewat USB dan Bluetooth, dan menyediakan konektor RJ-11 untuk laci uang.
• Model portabel PRJ-R58B-II adalah unit mobile 58 mm beresolusi 230 dpi yang mencetak sekitar 50 sampai 90 mm per detik, dengan baterai isi ulang di kisaran 1500 sampai 2500 mAh tergantung varian.
• Keduanya menerima perintah ESC/POS, dan itulah satu-satunya alasan aplikasi Flutter yang ditulis untuk himpunan perintah turunan Epson bisa bekerja di sana.

Poin terakhir itu layak direnungkan. Anda tidak sedang menulis kode Panda; Anda menulis kode ESC/POS lalu memilih transport. Kalau abstraksi Anda mencerminkan hal itu, berpindah merek di kemudian hari hanya memakan satu nilai konfigurasi, bukan penulisan ulang.

Empat transport, dan mana yang benar-benar Anda dapat

Bluetooth bukan satu hal, dan perbedaannya menentukan paket Flutter mana yang sama sekali bisa berbicara dengan printer Anda.

Konsekuensi terpentingnya ada di iOS. Apple tidak pernah membuka Bluetooth Classic serial port profile untuk aplikasi pihak ketiga — aksesorinya perlu sertifikasi MFi atau External Accessory framework — sehingga printer yang langsung jalan di Android bisa jadi tidak terjangkau dari iPhone kecuali ia juga menyediakan antarmuka low energy. Putuskan hal ini sebelum menjanjikan rilis iOS.

Kumpulan dependensi yang tidak menghalangi

Tiga paket sudah menutup seluruh pekerjaan. Dua di antaranya adalah pemisahan transport dan konten di atas; yang ketiga adalah model izin runtime Android, yang tidak bisa Anda hindari di Android 12 ke atas.

# pubspec.yaml — the two-package split most Flutter POS apps end up with
dependencies:
  print_bluetooth_thermal: ^1.2.2   # transport: discovery, connect, writeBytes
  esc_pos_utils_plus: ^2.0.4        # content: builds the ESC/POS byte list
  permission_handler: ^11.3.1       # Android 12+ runtime permissions

Tahan diri menambahkan paket keempat. Setiap plugin tambahan di ranah ini membawa pendapatnya sendiri soal pemindaian, platform channel-nya sendiri, dan definisi koneksinya sendiri — dan dua di antaranya dalam satu aplikasi akan berebut adapter.

Struk pertama, dari ujung ke ujung

Alurnya sengaja lurus: aktifkan, hubungkan, susun, tulis, putuskan. Hampir semua bug pencetakan Bluetooth yang muncul sesekali yang pernah saya kejar berasal dari mengerjakan langkah-langkah ini dalam urutan berbeda, atau dari melewatkan pemutusan koneksi.

import 'package:esc_pos_utils_plus/esc_pos_utils_plus.dart';
import 'package:print_bluetooth_thermal/print_bluetooth_thermal.dart';

/// Discover, connect, print, disconnect. Deliberately linear: the failure
/// modes of a 58 mm Bluetooth printer are all about ordering.
Future<void> printTestReceipt(String macAddress) async {
  if (!await PrintBluetoothThermal.bluetoothEnabled) {
    throw StateError('Bluetooth is off');
  }

  final connected = await PrintBluetoothThermal.connect(
    macPrinterAddress: macAddress,
  );
  if (!connected) throw StateError('Could not connect to $macAddress');

  try {
    final profile = await CapabilityProfile.load();
    final generator = Generator(PaperSize.mm58, profile);

    final bytes = <int>[
      ...generator.text(
        'TOKO SUMBER REJEKI',
        styles: const PosStyles(
          align: PosAlign.center,
          bold: true,
          height: PosTextSize.size2,
          width: PosTextSize.size2,
        ),
      ),
      ...generator.text('Jl. Diponegoro 12',
          styles: const PosStyles(align: PosAlign.center)),
      ...generator.hr(),
      ...generator.row([
        PosColumn(text: 'Kopi Susu', width: 8),
        PosColumn(
          text: '25.000',
          width: 4,
          styles: const PosStyles(align: PosAlign.right),
        ),
      ]),
      ...generator.feed(2),
      ...generator.cut(),
    ];

    await PrintBluetoothThermal.writeBytes(bytes);
  } finally {
    await PrintBluetoothThermal.disconnect;
  }
}

Dua detail menanggung beban. Capability profile adalah yang memetakan maksud generator ke dialek perintah printer tertentu, jadi memuatnya sekali lalu memakainya ulang menjaga struk tetap konsisten secara internal. Dan pemutusan koneksi harus ada di blok finally: koneksi yang tertinggal terbuka setelah exception memblokir transaksi berikutnya, dan solusi versi kasir adalah merestart aplikasi.

Pairing, dalam urutan yang berhasil

Pemasangan di lapangan jauh lebih sering gagal di tahap pairing daripada di kode. Urutan inilah yang kini saya tuliskan ke lembar setup toko.

1. Isi penuh baterai printer sebelum pairing pertama. Printer dengan baterai lemah akan berhasil dipasangkan lalu memutus koneksi saat arus pencetakan sesungguhnya ditarik.
2. Lakukan pairing di pengaturan Android, bukan di aplikasi, dan pastikan printer muncul sebagai perangkat terpasang dengan nama yang stabil.
3. Di aplikasi, tampilkan daftar perangkat terpasang dan biarkan pengguna memilih sekali; simpan alamat MAC-nya pada perangkat itu, bukan pada akun pengguna.
4. Cetak struk uji segera, dari layar pengaturan. Kalau pencetakan pertama baru terjadi saat transaksi sungguhan, kegagalan pertama juga terjadi saat transaksi sungguhan.

Menyimpan MAC per perangkat penting di toko dengan banyak kasir. Dua tablet yang menyinkronkan akun yang sama jika tidak akan berebut satu alamat printer, dan masing-masing diam-diam mencetak ke printer milik yang lain.

Yang rusak setelah demo

Printer Bluetooth yang lancar di meja Anda gagal dengan tiga cara yang bisa ditebak di dalam toko.

• Ia tidur. Sebagian besar model portabel mati sendiri setelah beberapa menit menganggur, dan pencetakan pertama setelah itu membangunkannya tetapi bisa hilang. Sambung ulang dan coba sekali lagi sebelum menampilkan error.
• Baterainya melemah. Mencetak menarik arus jauh lebih besar daripada menganggur, jadi printer di angka dua puluh persen mencetak satu struk lalu terputus di struk kedua. Tampilkan status baterai kalau modelnya melaporkannya, dan beri tahu staf untuk membiarkannya tercolok.
• Tablet memindahkan adapternya. Aplikasi lain, car kit, atau headset bisa mendapat prioritas; saat menyambung ulang, alamat MAC Anda masih benar tetapi soketnya tidak. Selalu perlakukan connect sebagai sesuatu yang bisa gagal dan diulang.

Tak satu pun dari ini eksotis, dan ketiganya tidak terlihat saat pengembangan karena meja kerja punya charger, tanpa perangkat pesaing, dan seorang developer yang menekan tombol cetak setiap tiga puluh detik.

Membuat aplikasi Flutter mencetak ke printer Panda 58 mm sebagian besar soal menghormati batas: pengaturan sistem memiliki pairing, satu paket memiliki koneksi, paket lain memiliki byte, dan kode Anda memiliki percobaan ulang. Bangun dalam urutan itu dan printer berhenti menjadi bagian paling rapuh dari produk Anda.