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)
```javascript
// 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
```bash
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
```bash
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()`:

```javascript
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()`:
```javascript
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:
```javascript
// 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:
```javascript
// 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)
```javascript
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
```javascript
// 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`:

```javascript
// 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:
```bash
npm install jsbarcode
```

Implementasi:
```javascript
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.