Integrasi Thermal Printer & ESC/POS

Gambaran Umum

Bagi pelanggan yang berbelanja, selembar struk kertas yang tercetak adalah bukti nyata bahwa sebuah transaksi telah sah. Oleh karena itu, kemampuan Point of Sale (POS) untuk mencetak struk dengan cepat, andal, dan format yang rapi adalah sebuah kewajiban yang tidak dapat ditawar. Pada masa lalu, menghubungkan aplikasi berbasis browser (web-based) ke perangkat keras lokal seperti printer thermal adalah proses yang menyakitkan, seringkali membutuhkan instalasi program perantara yang lambat atau driver khusus yang rumit.

Namun, Temuya POS mendobrak batasan tersebut dengan pendekatan modern yang memukau. Kami menghadirkan integrasi printer thermal yang sepenuhnya berjalan di dalam browser, tanpa memerlukan perangkat lunak tambahan. Fitur ini diotaki oleh berkas sakti thermalPrinter.ts, yang memanfaatkan kecanggihan teknologi standar web masa depan seperti Web Serial API untuk koneksi kabel USB langsung, dan Web Bluetooth API untuk komunikasi nirkabel BLE (Bluetooth Low Energy) yang elegan.

Di balik kelancaran koneksi tersebut, Temuya POS memiliki sebuah “penerjemah bawaan” yang mengubah teks struk yang mudah dibaca manusia menjadi perintah biner misterius (seperti Hexadecimal Codes) yang dikenal sebagai standar bahasa ESC/POS. Standar ESC/POS ini dipahami secara universal oleh hampir 95% printer kasir yang beredar di pasaran saat ini (dari merek Epson yang legendaris hingga perangkat generik asal Tiongkok). Mulai dari menyesuaikan posisi teks menjadi rata tengah, mencetak huruf tebal untuk menonjolkan total harga, memotong kertas secara otomatis (auto-cutter), hingga memerintahkan laci kas (cash drawer) untuk terlempar terbuka dengan bunyi “Kachaang!” khas kasir—semuanya dikendalikan secara orkestra oleh integrasi arsitektural yang tertanam dalam baris-baris kode Temuya POS ini.

Skenario Bisnis Nyata

Coba bayangkan suasana akhir pekan di “Festival Makanan Nusantara”, sebuah acara kuliner pop-up luar ruangan yang ramai dikunjungi ribuan orang. Salah satu tenant, “Sate Taichan Senayan”, menggunakan aplikasi Temuya POS pada sebuah tablet portabel modern. Karena ini adalah kedai sementara (bazar), ruangannya sangat sempit dan tidak memungkinkan penarikan kabel USB panjang yang mengganggu ruang gerak para kru pemanggang sate yang sibuk bergerak.

Untuk mengatasi hal ini, manajer Sate Taichan Senayan membeli sebuah printer thermal Bluetooth (mini portable) yang dapat digantung di pinggang kasir. Saat acara dimulai, kasir membuka pengaturan Temuya POS di browser tablet mereka, memilih menu “Hubungkan Printer Bluetooth”, dan layar browser segera memunculkan jendela pop-up aman yang meminta izin untuk menyambungkan tablet dengan perangkat bernama “MTP-2”. Kasir menyetujuinya dengan sekali ketuk.

Kemudian antrean pelanggan yang panjang pun tiba. Setiap kali kasir menekan tombol “Bayar Tunai” di layar tablet, secara instan dalam sepersekian detik, modul thermalPrinter.ts di latar belakang langsung menerjemahkan daftar menu sate menjadi puluhan baris perintah ESC/POS. Perintah biner ini kemudian ditembakkan secara nirkabel melalui udara menggunakan gelombang Web Bluetooth API langsung menuju printer mini di pinggang kasir. Printer tersebut seketika mendesis mengeluarkan kertas struk yang sangat rapi: logo kedai di tengah, item terperinci, total harga dicetak tebal, dan diakhiri dengan pesan terima kasih. Struk disobek, diserahkan ke pelanggan, dan laci uang portabel pun otomatis terbuka berkat perintah pulse (tendangan listrik 12V/24V) yang dikirimkan via printer tersebut. Proses kasir yang biasanya lambat kini mengalir sangat mulus tanpa sedikitpun tersangkut urusan kabel, membuat Sate Taichan Senayan mampu melayani ratusan porsi tanpa membuat pelanggan menggerutu.

Alur Kerja Pencetakan

Grafik sekuensial di bawah ini membedah secara kronologis bagaimana sebuah pesanan yang diklik di layar React berubah menjadi bentuk wujud fisiknya, dari teks hingga menjadi gelombang biner yang dikirim via Serial atau Bluetooth.

sequenceDiagram
    autonumber
    actor Kasir as Operator Kasir (React UI)
    participant ModulPOS as Aplikasi POS (useCart)
    participant ThermalMod as Modul: thermalPrinter.ts
    participant BrowserAPI as Web Serial / Web Bluetooth API
    participant Hardware as Hardware Printer Thermal & Laci Kas

    Kasir->>ModulPOS: Menekan Tombol "Bayar & Cetak"
    ModulPOS->>ThermalMod: Memanggil fungsi printReceipt(dataTransaksi)
    
    ThermalMod->>ThermalMod: Memulai Buffer Array (Membangun Payload ESC/POS)
    ThermalMod->>ThermalMod: + Reset Printer (ESC @)
    ThermalMod->>ThermalMod: + Rata Tengah (ESC a 1) & Teks Header Toko
    ThermalMod->>ThermalMod: + Rata Kiri (ESC a 0) & Iterasi Item Produk
    ThermalMod->>ThermalMod: + Teks Tebal (ESC E 1) & Total Harga
    ThermalMod->>ThermalMod: + Buka Laci Kas (ESC p 0 25 250)
    ThermalMod->>ThermalMod: + Pemotong Kertas (GS V 66)
    
    ThermalMod->>BrowserAPI: Mengirim Array Uint8Array (Bit & Byte)
    
    alt Menggunakan Kabel USB (Web Serial)
        BrowserAPI->>Hardware: Transmisi Serial via Port COM/USB
    else Menggunakan Nirkabel (Web Bluetooth)
        BrowserAPI->>Hardware: Transmisi BLE via GATT Characteristic
    end
    
    Hardware-->>BrowserAPI: Selesai Mencetak secara Fisik
    BrowserAPI-->>ThermalMod: Konfirmasi Sukses Transmisi
    ThermalMod-->>ModulPOS: State UI "Cetak Berhasil"
    ModulPOS-->>Kasir: Layar Kembali Bersih untuk Transaksi Berikutnya

Teknologi & Infrastruktur (Mekanisme Koneksi)

Keberhasilan fitur ini bertumpu pada penguasaan antarmuka komunikasi tingkat rendah di dalam lingkungan web tingkat tinggi. Berikut adalah komponen pembangun utamanya:

Komponen Arsitektur	Teknologi / Standar	Penjelasan Fungsional
Protokol Bahasa Cetak	ESC/POS (Epson Standard Code)	Tata bahasa universal industri. Mengirimkan sinyal biner ke printer (contoh: `[0x1B, 0x40]` untuk mereset mesin, `[0x0A]` untuk pindah baris / Line Feed).
Konektivitas USB Fisik	Web Serial API (`navigator.serial`)	Memungkinkan browser Chrome/Edge modern di PC/Mac/Android untuk “berbicara” langsung dengan port USB (COM Port) tanpa perlu driver tambahan, memastikan respons instan.
Konektivitas Nirkabel	Web Bluetooth API (`navigator.bluetooth`)	Digunakan khusus untuk printer mobile (belt printer). Berkomunikasi melalui protokol GATT untuk menulis data ke characteristic bluetooth milik printer.
Format Layout Baris	Algoritma Manipulasi String Khusus	Logika khusus di `thermalPrinter.ts` yang dengan cerdas menghitung spasi agar nama produk (“Nasi Goreng Spesial”) dan harga (“Rp 25.000”) sejajar sempurna di ujung kiri dan kanan kertas ukuran 58mm (32 karakter) atau 80mm (48 karakter).
Pemicu Laci Uang	Sinyal Listrik Kick Drawer (Pin 2/5)	Mengirimkan perintah khusus (`ESC p`) ke printer agar printer menyetrumkan pulsa listrik ke kabel RJ11 yang terhubung ke laci kas, melepaskan pelatuk mekanis laci.

Keterkaitan dengan Fitur Lain

Kemampuan mencetak struk tidak berdiri terisolasi, melainkan merespons aksi dari berbagai pemicu di dalam aplikasi Temuya POS:

Modul Transaksi & Kasir (POS): Ini adalah pengguna utama yang paling sering menuntut layanan pencetakan. Setiap kali alur pembayaran diselesaikan di kasir, antarmuka akan secara otomatis memanggil modul printer ini sebagai prosedur tahap akhir sebelum membersihkan meja (keranjang belanja).
Mode Offline & Sinkronisasi: Keistimewaan dari Web Serial API dan Web Bluetooth API adalah mereka tidak memerlukan koneksi internet untuk bekerja. Meskipun internet toko terputus (Mode Offline), modul thermalPrinter.ts akan terus mencetak struk transaksi lokal dari antrean (offline_queue) dengan kecepatan yang sama, menjaga kepercayaan pelanggan bahwa transaksi mereka tetap dicatat secara sah.
Laporan Shift & Penutupan Kas (End of Day): Saat kasir menyelesaikan shift (tutup laci) atau mengeksekusi rekap akhir hari, antarmuka akan memanggil modul printer untuk menghasilkan Laporan Z (Z-Report), yang biasanya dicetak dengan format teks tebal (bold) merangkum ringkasan total penerimaan uang tunai dan kartu untuk disetorkan ke manajer keuangan.

Hal Penting yang Perlu Diketahui

Menangani perangkat keras keras kepala seperti mesin cetak selalu membawa tantangan fisik di dunia nyata. Operator kasir dan teknisi TI yang membantu instalasi harus mematuhi panduan ketat berikut untuk menghindari sakit kepala teknis:

Pembatasan Keamanan Browser: Fitur Web Serial dan Web Bluetooth berada di bawah payung aturan keamanan peramban yang sangat paranoid. Keduanya hanya dapat diaktifkan jika aplikasi Temuya POS diakses menggunakan protokol keamanan tinggi HTTPS. Di lingkungan pengembangan lokal tanpa SSL (localhost), fitur ini mungkin diblokir secara otomatis.
Perilaku Koneksi Ulang: Jangan kaget jika setelah komputer di-restart atau browser ditutup paksa, kasir harus memilih ulang nama printer dari menu pop-up browser. Demi keamanan privasi, browser saat ini tidak diizinkan untuk secara otomatis mengklaim hak akses diam-diam (silent re-connect) ke perangkat USB/Bluetooth pengguna tanpa interaksi tombol dari manusia secara eksplisit.
Tinta Termal vs Lebar Kertas: Ingat, printer kasir tidak menggunakan tinta basah, melainkan membakar kertas termal khusus menggunakan elemen pemanas. Pastikan Anda memilih gulungan kertas yang tepat (ukuran 58mm atau 80mm) pada pengaturan aplikasi POS, karena modul thermalPrinter.ts akan mengubah algoritma perhitungan panjang spasinya berdasarkan opsi lebar kertas ini; ukuran yang salah akan membuat teks tercetak menabrak dan terpotong di tepi kertas.
Kompatibilitas Merek: Walaupun ESC/POS adalah standar luas industri, beberapa merek printer impor dengan harga sangat murah (generik tak bermerek) seringkali memotong kompas dalam fabrikasi chip mereka dan tidak mendukung subset perintah kompleks, seperti pencetakan logo grafis (Raster/BitImage) atau perintah potong otomatis laci kas uang saku (kick drawer). Pastikan menguji coba secara menyeluruh jika menggunakan perangkat kelas entry-level.
Penanganan Karakter Non-Latin: Mengirim teks dengan karakter khusus non-ASCII (misal huruf Mandarin, Thailand, atau emoji) membutuhkan pengaturan code page khusus pada perintah awal (preamble) ESC/POS. Saat ini, sistem dikonfigurasi dan dioptimalkan secara mendalam untuk menangani kumpulan karakter alfabet standar Indonesia (Latin-1/ASCII), yang sangat memadai untuk operasional ritel harian di nusantara.