@amitkhare/capacitor-cat-printer 0.5.0 → 0.5.2

package/README.md

@@ -1,323 +1,306 @@
-# Capacitor Cat Printer Plugin
+# Capacitor Cat Printer
 
-A Capacitor plugin for printing to Cat thermal printers (and compatible devices) via Bluetooth Low Energy (BLE).
+A Capacitor plugin for thermal printers (Cat printers and compatibles) over Bluetooth LE.
 
 ## Features
 
-- Scan for BLE printers
-- Connect/disconnect to printers
-- Print text with customizable font, alignment, and styling
-- Print images with dithering support for better quality
-- Paper feed control
-- Support for 58mm (384px) and 80mm (576px) paper widths
-- Real-time print progress events
-
-## Installation
+- BLE scanning and connection management
+- Text printing with full styling (bold, italic, underline, strikethrough)
+- Rich text with mixed formatting in a single print
+- Image printing with dithering, brightness/contrast adjustments
+- QR codes and barcodes (CODE128, EAN13, UPC, etc.)
+- Table/receipt layout printing
+- Custom font support (TTF/OTF)
+- RTL text support
+- Printer status (battery, paper, charging)
+- Auto-reconnect
+- Dry-run mode for testing
+- 58mm and 80mm paper widths
+
+## Install
 
 ```bash
 npm install capacitor-cat-printer
 npx cap sync android
 ```
 
-For local development:
-```bash
-npm install file:../path/to/capacitor-cat-printer
-npx cap sync android
-```
+## Android Permissions
 
-## Android Setup
-
-### 1. Add Permissions to AndroidManifest.xml
-
-Add these permissions **before** the `<application>` tag in `android/app/src/main/AndroidManifest.xml`:
+Add to `AndroidManifest.xml` before `<application>`:
 
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools">
+<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+```
 
-    <!-- Bluetooth permissions for Android 11 and below -->
-    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
-    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+## Quick Start
 
-    <!-- Bluetooth permissions for Android 12+ -->
-    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
-    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+```typescript
+import { CatPrinter } from 'capacitor-cat-printer';
 
-    <!-- Location permission required for BLE scanning -->
-    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:remove="android:maxSdkVersion" />
-    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:remove="android:maxSdkVersion" />
+// Scan
+const { devices } = await CatPrinter.scan({ duration: 5000 });
 
-    <!-- Declare BLE feature -->
-    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+// Connect
+await CatPrinter.connect({ address: devices[0].address });
 
-    <application>
-        <!-- ... -->
-    </application>
-</manifest>
-```
+// Print
+await CatPrinter.printText({ text: 'Hello World!' });
 
-**Important:** The `tools:remove="android:maxSdkVersion"` attribute is required to ensure location permissions work on Android 12+.
+// Disconnect
+await CatPrinter.disconnect();
+```
 
-## Usage
+## API
 
-### Import
+### Connection
 
 ```typescript
-import { CatPrinter, PaperWidth } from 'capacitor-cat-printer';
-```
+// Scan for printers
+const { devices } = await CatPrinter.scan({ duration: 5000 });
+// devices: [{ name, address, rssi }]
 
-### Scan for Printers
+// Stop scan early
+await CatPrinter.stopScan();
 
-```typescript
-// Scan for 5 seconds
-const result = await CatPrinter.scan({ duration: 5000 });
-console.log('Found devices:', result.devices);
+// Connect
+await CatPrinter.connect({
+  address: 'AA:BB:CC:DD:EE:FF',
+  paperWidth: 384,        // 384 = 58mm, 576 = 80mm
+  timeout: 10000,
+  dryRun: false,          // true = simulate without printing
+  autoReconnect: false
+});
+
+// Check status
+const { connected, address, paperWidth } = await CatPrinter.isConnected();
 
-// Each device has: { name: string, address: string, rssi: number }
+// Disconnect
+await CatPrinter.disconnect();
 ```
 
-### Connect to a Printer
+### Print Text
 
 ```typescript
-await CatPrinter.connect({
-  address: 'AA:BB:CC:DD:EE:FF',  // Bluetooth MAC address
-  paperWidth: PaperWidth.MM_58   // 384px for 58mm, 576px for 80mm
+await CatPrinter.printText({
+  text: 'Hello World!',
+  fontSize: 24,
+  align: 'center',        // 'left' | 'center' | 'right'
+  bold: true,
+  italic: false,
+  underline: false,
+  strikethrough: false,
+  lineSpacing: 1.2,
+  wordWrap: true,         // break at word boundaries
+  rtl: false,             // right-to-left
+  fontPath: '/path/to/font.ttf',  // custom font
+  energy: 0.6,            // 0.0-1.0 darkness
+  quality: 3,             // 1-4
+  feedAfter: 100
 });
 ```
 
-### Check Connection Status
+### Rich Text (Mixed Formatting)
 
-```typescript
-const status = await CatPrinter.isConnected();
-if (status.connected) {
-  console.log('Connected to:', status.address);
-  console.log('Paper width:', status.paperWidth);
-}
-```
-
-### Print Text
+Print text with different styles in the same line:
 
 ```typescript
-await CatPrinter.printText({
-  text: 'Hello World!\n\nThis is a test receipt.',
-  fontSize: 24,           // Font size in pixels (default: 24)
-  align: 'center',        // 'left', 'center', 'right' (default: 'left')
-  bold: false,            // Bold text (default: false)
-  lineSpacing: 1.2,       // Line spacing multiplier (default: 1.2)
-  energy: 0.6,            // Print darkness 0.0-1.0 (default: 0.6)
-  quality: 3,             // Print quality 1-4 (default: 3)
-  feedAfter: 100          // Paper feed after printing in pixels (default: 100)
+await CatPrinter.printRichText({
+  segments: [
+    { text: 'Normal ' },
+    { text: 'Bold', bold: true },
+    { text: ' and ' },
+    { text: 'Italic', italic: true },
+    { text: ' Big', fontSize: 32 }  // per-segment font size
+  ],
+  fontSize: 24,
+  align: 'left',
+  lineSpacing: 1.2,
+  rtl: false,
+  fontPath: '/path/to/font.ttf',
+  energy: 0.6,
+  quality: 3,
+  feedAfter: 100
 });
 ```
 
 ### Print Image
 
 ```typescript
-// Image must be base64 encoded (PNG or JPEG)
 await CatPrinter.printImage({
-  imageBase64: 'iVBORw0KGgoAAAANSUhEUgAA...',  // Base64 image data (without data URL prefix)
-  energy: 0.65,           // Print darkness 0.0-1.0 (default: 0.5)
-  quality: 4,             // Print quality 1-4 (default: 3)
-  feedAfter: 100,         // Paper feed after printing in pixels (default: 100)
-  threshold: 127,         // Black/white threshold 0-255 (default: 127)
-  dither: true            // Use Floyd-Steinberg dithering (default: true)
+  imageBase64: '...',     // base64 PNG/JPEG (no data: prefix)
+  threshold: 127,         // 0-255 for B/W conversion
+  dither: true,           // Floyd-Steinberg dithering
+  brightness: 0,          // -100 to 100
+  contrast: 0,            // -100 to 100
+  invert: false,
+  flipHorizontal: false,
+  flipVertical: false,
+  compress: false,        // for newer printers (GB03+)
+  energy: 0.6,
+  quality: 3,
+  feedAfter: 100
 });
 ```
 
-### Feed Paper
+### QR Code
 
 ```typescript
-await CatPrinter.feedPaper({ pixels: 100 });
+await CatPrinter.printQRCode({
+  data: 'https://example.com',
+  size: 200,
+  errorCorrection: 'M',   // 'L' | 'M' | 'Q' | 'H'
+  align: 'center',
+  energy: 0.6,
+  feedAfter: 100
+});
 ```
 
-### Disconnect
+### Barcode
 
 ```typescript
-await CatPrinter.disconnect();
+await CatPrinter.printBarcode({
+  data: '123456789',
+  type: 'CODE128',        // CODE128, CODE39, EAN13, EAN8, UPC_A, UPC_E, ITF, CODABAR
+  height: 80,
+  showText: true,
+  align: 'center',
+  energy: 0.6,
+  feedAfter: 100
+});
 ```
 
-## Event Listeners
-
-### Scan Results (Real-time)
+### Table / Receipt
 
 ```typescript
-const listener = await CatPrinter.addListener('scanResult', (device) => {
-  console.log('Found device:', device.name, device.address, device.rssi);
+await CatPrinter.printTable({
+  rows: [
+    { columns: [{ text: 'RECEIPT', align: 'center' }], bold: true, fontSize: 28 },
+    { columns: [{ text: '─'.repeat(16), align: 'center' }] },
+    { 
+      columns: [
+        { text: 'Item', width: 60 },           // width as percentage
+        { text: 'Price', width: 40, align: 'right' }
+      ], 
+      bold: true 
+    },
+    { columns: [{ text: 'Coffee' }, { text: '$4.00', align: 'right' }] },
+    { columns: [{ text: 'Muffin' }, { text: '$3.50', align: 'right' }] },
+    { columns: [{ text: '─'.repeat(16), align: 'center' }] },
+    { columns: [{ text: 'Total' }, { text: '$7.50', align: 'right' }], bold: true }
+  ],
+  fontSize: 22,
+  showLines: false,       // horizontal lines between rows
+  lineChar: '-',          // character for lines
+  energy: 0.6,
+  feedAfter: 100
 });
-
-// Remove listener when done
-listener.remove();
 ```
 
-### Connection State Changes
+### Paper Control
 
 ```typescript
-await CatPrinter.addListener('connectionState', (state) => {
-  if (state.connected) {
-    console.log('Connected to:', state.address);
-  } else {
-    console.log('Disconnected');
-  }
-});
+await CatPrinter.feedPaper({ pixels: 100 });
+await CatPrinter.retractPaper({ pixels: 50 });
+await CatPrinter.cancelPrint();
 ```
 
-### Print Progress
+### Auto-Reconnect
 
 ```typescript
-await CatPrinter.addListener('printProgress', (progress) => {
-  console.log(`${progress.percent}% - ${progress.status}: ${progress.message}`);
-  // status: 'processing' | 'printing' | 'feeding' | 'done' | 'error'
+await CatPrinter.setAutoReconnect({
+  enabled: true,
+  maxAttempts: 3,
+  delayMs: 2000
 });
 ```
 
-### Remove All Listeners
+### Printer Info
 
 ```typescript
-await CatPrinter.removeAllListeners();
-```
+// Get printer model
+const model = await CatPrinter.getPrinterModel();
+// { model: 'GB03', isNewKind: true, hasFeedingProblems: false, paperWidth: 384, deviceName: '...' }
 
-## API Reference
+// Get printer status
+const status = await CatPrinter.getPrinterStatus();
+// { connected, batteryLevel, isCharging, hasPaper, firmwareVersion, paperWidth }
 
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `scan(options?)` | Scan for BLE devices |
-| `stopScan()` | Stop ongoing scan |
-| `connect(options)` | Connect to a printer |
-| `disconnect()` | Disconnect from printer |
-| `isConnected()` | Check connection status |
-| `printText(options)` | Print text |
-| `printImage(options)` | Print image |
-| `feedPaper(options?)` | Feed paper |
+// Get raw device info
+const info = await CatPrinter.getDeviceInfo();
+```
 
-### Interfaces
+### Preview (Without Printing)
 
 ```typescript
-interface ScanOptions {
-  duration?: number;  // Scan duration in ms (default: 4000)
-}
-
-interface ConnectOptions {
-  address: string;      // Bluetooth MAC address
-  paperWidth?: number;  // Paper width in pixels (default: 384)
-}
-
-interface PrintTextOptions {
-  text: string;
-  fontSize?: number;      // default: 24
-  align?: 'left' | 'center' | 'right';  // default: 'left'
-  bold?: boolean;         // default: false
-  lineSpacing?: number;   // default: 1.2
-  energy?: number;        // 0.0-1.0, default: 0.6
-  quality?: number;       // 1-4, default: 3
-  feedAfter?: number;     // default: 100
-}
-
-interface PrintImageOptions {
-  imageBase64: string;
-  energy?: number;        // 0.0-1.0, default: 0.5
-  quality?: number;       // 1-4, default: 3
-  feedAfter?: number;     // default: 100
-  threshold?: number;     // 0-255, default: 127
-  dither?: boolean;       // default: true
-}
-
-interface FeedOptions {
-  pixels?: number;  // default: 100
-}
+const preview = await CatPrinter.getPreview({
+  type: 'text',
+  options: { text: 'Preview this', fontSize: 24 }
+});
+// { imageBase64, width, height }
 ```
 
-### Constants
+### Events
 
 ```typescript
-const PaperWidth = {
-  MM_58: 384,   // 58mm paper width
-  MM_80: 576    // 80mm paper width
-};
+// Device found during scan
+CatPrinter.addListener('scanResult', (device) => {
+  console.log('Found:', device.name, device.address);
+});
+
+// Connection state changed
+CatPrinter.addListener('connectionState', (state) => {
+  console.log('Connected:', state.connected);
+});
+
+// Print progress
+CatPrinter.addListener('printProgress', (progress) => {
+  console.log(`${progress.percent}% - ${progress.status}`);
+  // status: 'processing' | 'printing' | 'feeding' | 'done' | 'error'
+});
+
+// Remove all listeners
+await CatPrinter.removeAllListeners();
 ```
 
-## Complete Example
+## Constants
 
 ```typescript
-import { CatPrinter, PaperWidth } from 'capacitor-cat-printer';
-
-async function printReceipt() {
-  try {
-    // Setup listeners
-    CatPrinter.addListener('printProgress', (p) => {
-      console.log(`Printing: ${p.percent}%`);
-    });
-
-    // Scan for printers
-    const { devices } = await CatPrinter.scan({ duration: 5000 });
-    
-    if (devices.length === 0) {
-      console.log('No printers found');
-      return;
-    }
-
-    // Connect to first printer
-    await CatPrinter.connect({
-      address: devices[0].address,
-      paperWidth: PaperWidth.MM_58
-    });
-
-    // Print receipt
-    await CatPrinter.printText({
-      text: `
-        RECEIPT
-        ================
-        Item 1      $10.00
-        Item 2      $15.00
-        ----------------
-        Total       $25.00
-        ================
-        Thank you!
-      `,
-      fontSize: 24,
-      align: 'left',
-      energy: 0.6,
-      quality: 3
-    });
-
-    // Disconnect
-    await CatPrinter.disconnect();
-    
-    console.log('Print complete!');
-  } catch (error) {
-    console.error('Print error:', error);
-  }
-}
-```
+import { PaperWidth, BarcodeType, PrinterModels } from 'capacitor-cat-printer';
 
-## Supported Printers
+PaperWidth.MM_58  // 384
+PaperWidth.MM_80  // 576
+
+BarcodeType.CODE128
+BarcodeType.EAN13
+// etc.
 
-This plugin works with Cat thermal printers and compatible devices that use the same BLE protocol:
-- TX Characteristic: `0000ae01-0000-1000-8000-00805f9b34fb`
-- RX Characteristic: `0000ae02-0000-1000-8000-00805f9b34fb`
+PrinterModels.GB01
+PrinterModels.GB03
+PrinterModels.MX05
+// etc.
+```
 
-Many generic thermal printers from AliExpress/Amazon use this protocol.
+## Supported Printers
 
-## Troubleshooting
+Works with Cat thermal printers and compatibles using BLE characteristics:
+- TX: `0000ae01-0000-1000-8000-00805f9b34fb`
+- RX: `0000ae02-0000-1000-8000-00805f9b34fb`
 
-### No devices found during scan
-1. Ensure Bluetooth is enabled
-2. Ensure Location Services are enabled (required for BLE scanning)
-3. Grant both Bluetooth and Location permissions when prompted
-4. Make sure the printer is powered on and in pairing mode
+Known models: GB01, GB02, GB03, GT01, MX05, MX06, MX08, MX09, MX10, MX11, YT01
 
-### Permission errors
-- On Android 12+, the app needs "Nearby devices" permission
-- On Android 6-11, the app needs Location permission for BLE scanning
-- Check app permissions in Settings > Apps > Your App > Permissions
+## Tips
 
-### Print quality issues
-- Increase `energy` for darker prints (0.6-0.8 recommended)
-- Use `quality: 4` for best quality (slower)
+- Enable Location Services for BLE scanning on Android
+- Use `energy: 0.6-0.8` for darker prints
 - Enable `dither: true` for images with gradients
-- Adjust `threshold` for black/white conversion (lower = more black)
+- Use `quality: 4` for best quality (slower)
+- Lower `threshold` = more black pixels in images
 
 ## License
 

package/android/build.gradle

@@ -38,6 +38,10 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    
+    // ZXing for barcode/QR code generation
+    implementation 'com.google.zxing:core:3.5.2'
+    
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"