Kasir/Documentation/NiimbotPrinter.md

🖨️ Dokumentasi Integrasi Printer Niimbot

📋 Ringkasan

Aplikasi kasir sekarang mendukung pencetakan QR Code langsung ke printer Niimbot menggunakan library @mmote/niimbluelib yang diadaptasi dari proyek niimblue.

---

🔧 Teknologi & Library

Library Utama

• @mmote/niimbluelib - Library JavaScript untuk komunikasi dengan printer Niimbot
  • Mendukung Web Bluetooth API
  • Mendukung Web Serial API (USB)
  • Encoding gambar ke format printer

Browser Support

Browser	Bluetooth	USB (Serial)
Chrome/Edge (Desktop)	✅	✅
Chrome (Android)	✅	❌
Firefox	❌	❌
Safari	❌	❌

Rekomendasi: Gunakan Chrome atau Edge versi terbaru

---

📁 Struktur File

Kasir/resources/js/
├── composables/
│   └── useNiimbotPrinter.js       # Composable untuk koneksi & print
├── components/
│   ├── NiimbotConnector.vue       # Modal untuk koneksi printer
│   └── BrankasList.vue            # Modifikasi: tambah fitur print Niimbot

---

🚀 Cara Kerja

1️⃣ Alur Koneksi Printer

User klik "Hubungkan Printer" 
  → Modal NiimbotConnector muncul 
  → Pilih metode: Bluetooth / USB
  → Browser munculkan dialog pairing
  → User pilih printer Niimbot
  → Koneksi terjalin
  → Fetch info printer
  → Status: "Terhubung"

2️⃣ Alur Print QR Code

User klik item di Brankas
  → Modal popup dengan QR Code
  → User klik "Cetak ke Niimbot"
  → Cek koneksi printer:
     - Jika belum terhubung → tampilkan modal koneksi
     - Jika sudah terhubung → lanjut
  → Generate canvas dengan QR + info item
  → Encode canvas ke format printer
  → Kirim ke printer via library
  → Status: "Mencetak... X%"
  → Selesai

3️⃣ Komponen Kunci

useNiimbotPrinter.js (Composable)

// State management
- printerClient         // Instance NiimbotClient
- connectionState       // 'disconnected' | 'connecting' | 'connected'
- connectedPrinterName  // Nama printer yang terhubung
- printerInfo          // Info printer (model, serial, dll)
- isPrinting           // Status sedang print
- printProgress        // Progress print (0-100)

// Methods
- initClient(type)     // Init client (bluetooth/serial)
- connect()            // Hubungkan ke printer
- disconnect()         // Putuskan koneksi
- printQRCode(dataUrl, options)  // Print QR code image

NiimbotConnector.vue (Component)

• Modal untuk koneksi/disconnect printer
• Pilih metode: Bluetooth atau USB
• Tampilkan status koneksi
• Tampilkan info printer detail

BrankasList.vue (Modified)

• Tombol "Hubungkan Printer" di header
• Tombol "Cetak ke Niimbot" di modal item
• Tombol "Browser" sebagai fallback
• Alert sukses/error

---

🛠️ Instalasi

1. Install Library

cd "c:\Data\Magang\Toko perhiasan\Kasir"
npm install @mmote/niimbluelib

2. Files Sudah Dibuat

• ✅ resources/js/composables/useNiimbotPrinter.js
• ✅ resources/js/components/NiimbotConnector.vue
• ✅ resources/js/components/BrankasList.vue (modified)

3. Build Assets

npm run build
# atau untuk development
npm run dev

---

📖 Cara Penggunaan

A. Menghubungkan Printer

1. Persiapan Printer:

   • Nyalakan printer Niimbot
   • Pastikan kertas label sudah terpasang
   • Untuk Bluetooth: Aktifkan mode pairing (biasanya tahan tombol power)

2. Di Aplikasi:

   • Buka halaman Brankas
   • Klik tombol "Hubungkan Printer" (di kanan atas)
   • Pilih metode koneksi (Bluetooth/USB)
   • Klik "Hubungkan Printer"
   • Browser akan menampilkan dialog - pilih printer Niimbot Anda
   • Tunggu hingga status berubah "Terhubung"

B. Mencetak QR Code

1. Pilih Item:

   • Klik item yang ingin dicetak QR-nya
   • Modal akan muncul dengan QR Code

2. Cetak:

   • Klik tombol "Cetak ke Niimbot"
   • Jika printer belum terhubung, akan muncul peringatan
   • Progress print akan ditampilkan (Mencetak... X%)
   • Tunggu hingga selesai

3. Alternatif:

   • Klik tombol "Browser" untuk print menggunakan printer biasa

---

⚙️ Konfigurasi Print

Di file BrankasList.vue, fungsi printQR():

await printQRCode(imageDataUrl, {
  density: 3,           // Kepadatan tinta (1-5, default: 3)
  quantity: 1,          // Jumlah cetakan (default: 1)
  labelType: 1,         // Tipe label:
                        //   1 = WithGaps (label dengan jarak)
                        //   2 = Continuous (tanpa jarak)
                        //   3 = WithHoles (dengan lubang)
  printTaskName: 'D110' // Model printer (D110, B21, B1, dll)
                        // Auto-detect jika tidak cocok
});

Ukuran Label

Di fungsi createQRLabelCanvas():

const labelWidth = 384;   // pixel (40mm @ 240dpi)
const labelHeight = 384;  // pixel

Sesuaikan dengan ukuran label Anda:

• 30mm x 30mm ≈ 288 x 288 px
• 40mm x 40mm ≈ 384 x 384 px
• 50mm x 30mm ≈ 480 x 288 px

Rumus: mm × (dpi / 25.4)

• DPI printer Niimbot umumnya: 203 atau 240

---

🐛 Troubleshooting

1. "Browser tidak mendukung koneksi printer"

Solusi:

• Gunakan Chrome atau Edge versi terbaru
• Update browser ke versi terkini
• Pastikan menggunakan HTTPS (Web Bluetooth hanya jalan di HTTPS)

2. "Gagal terhubung ke printer"

Solusi:

• Pastikan printer sudah dinyalakan
• Pastikan Bluetooth/USB aktif
• Coba matikan dan nyalakan ulang printer
• Untuk Bluetooth: pastikan tidak paired ke device lain
• Coba refresh halaman dan ulangi koneksi

3. "Printer terhubung tapi tidak print"

Solusi:

• Periksa kertas label sudah terpasang dengan benar
• Coba disconnect dan connect ulang
• Periksa battery printer (untuk model portable)
• Cek ukuran canvas sesuai dengan ukuran label

4. "Print hasil blur/tidak jelas"

Solusi:

• Tingkatkan density (misal dari 3 ke 4)
• Pastikan threshold image sudah optimal
• Ukuran QR Code jangan terlalu kecil (min 150x150px)

5. "Error: printTaskName not compatible"

Solusi:

• Ganti printTaskName sesuai model printer:
  • D110: 'D110'
  • B21: 'B21'
  • B1: 'B1'
  • Atau hapus parameter, biarkan auto-detect

---

🔍 Debugging

Enable Console Logs

Library sudah dilengkapi logging:

// Di browser console akan muncul:
>> Packet sent: [hex bytes]
<< Packet received: [hex bytes]
Printer connected: { deviceName: "Niimbot-XXXX" }
Printer info fetched: { model: "D110", ... }

Test Print Canvas

Tambahkan debug preview sebelum print:

// Di createQRLabelCanvas, sebelum resolve(canvas):
document.body.appendChild(canvas); // Tampilkan canvas di halaman
canvas.style.border = '1px solid red';

---

📚 Referensi API

useNiimbotPrinter Composable

State (Reactive)

const {
  printerClient,        // NiimbotClient instance
  connectionState,      // 'disconnected' | 'connecting' | 'connected'
  connectedPrinterName, // string
  printerInfo,          // object { model, serial, ... }
  printerMeta,          // object { densityMin, densityMax, ... }
  heartbeatData,        // object { powerLevel, ... }
  isPrinting,           // boolean
  printProgress,        // number (0-100)
  
  // Computed
  isConnected,          // boolean
  isDisconnected,       // boolean
  featureSupport,       // { webBluetooth, webSerial, ... }
} = useNiimbotPrinter();

Methods

// Init client
initClient(type: 'bluetooth' | 'serial'): void

// Connect/Disconnect
connect(): Promise<void>
disconnect(): void

// Print
printQRCode(
  imageDataUrl: string, 
  options?: {
    density?: number,      // 1-5
    quantity?: number,     // jumlah print
    labelType?: number,    // 1=WithGaps, 2=Continuous, 3=WithHoles
    printTaskName?: string // 'D110', 'B21', dll
  }
): Promise<{ success: boolean, message: string }>

// Utils
loadImageToCanvas(dataUrl: string): Promise<HTMLCanvasElement>
applyThreshold(canvas: HTMLCanvasElement, threshold?: number): HTMLCanvasElement

---

🎨 Customization

Ubah Desain Label

Edit fungsi createQRLabelCanvas() di BrankasList.vue:

// Contoh: Tambah logo toko
const logo = new Image();
logo.src = '/path/to/logo.png';
logo.onload = () => {
  ctx.drawImage(logo, 10, 10, 50, 50);
};

// Contoh: Tambah border
ctx.strokeStyle = 'black';
ctx.lineWidth = 2;
ctx.strokeRect(5, 5, labelWidth - 10, labelHeight - 10);

// Contoh: Font custom
ctx.font = 'bold 20px "Courier New"';

Tambah Barcode

Install library barcode:

npm install jsbarcode

Implementasi:

import JsBarcode from 'jsbarcode';

const barcodeCanvas = document.createElement('canvas');
JsBarcode(barcodeCanvas, item.kode_item, {
  format: 'CODE128',
  width: 2,
  height: 40,
});
ctx.drawImage(barcodeCanvas, x, y);

---

📝 Catatan Penting

1. HTTPS Required: Web Bluetooth & Web Serial hanya bekerja di HTTPS (kecuali localhost)
2. User Gesture: Koneksi harus dipicu oleh user action (klik button), tidak bisa otomatis on load
3. One Printer: Satu browser session hanya bisa terhubung ke 1 printer
4. Battery: Printer portable akan disconnect otomatis jika battery rendah
5. Label Size: Sesuaikan ukuran canvas dengan ukuran label fisik untuk hasil optimal

---

🆘 Support

Jika ada masalah:

1. Periksa console browser (F12 → Console)
2. Periksa kompatibilitas browser
3. Periksa dokumentasi printer Niimbot Anda
4. Issue library: https://github.com/MultiMote/niimbluelib

---

📄 License

Menggunakan library @mmote/niimbluelib yang bersifat open-source. Pastikan mematuhi lisensi library saat deploy production.