@amitkhare/capacitor-cat-printer 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Amit Kumar Khare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# Capacitor Cat Printer Plugin
+
+A Capacitor plugin for printing to Cat thermal printers (and compatible devices) via Bluetooth Low Energy (BLE).
+
+## 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
+
+```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 Setup
+
+### 1. Add Permissions to AndroidManifest.xml
+
+Add these permissions **before** the `<application>` tag in `android/app/src/main/AndroidManifest.xml`:
+
+```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">
+
+    <!-- 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" />
+
+    <!-- Bluetooth permissions for Android 12+ -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+    <!-- 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" />
+
+    <!-- Declare BLE feature -->
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+
+    <application>
+        <!-- ... -->
+    </application>
+</manifest>
+```
+
+**Important:** The `tools:remove="android:maxSdkVersion"` attribute is required to ensure location permissions work on Android 12+.
+
+## Usage
+
+### Import
+
+```typescript
+import { CatPrinter, PaperWidth } from 'capacitor-cat-printer';
+```
+
+### Scan for Printers
+
+```typescript
+// Scan for 5 seconds
+const result = await CatPrinter.scan({ duration: 5000 });
+console.log('Found devices:', result.devices);
+
+// Each device has: { name: string, address: string, rssi: number }
+```
+
+### Connect to a Printer
+
+```typescript
+await CatPrinter.connect({
+  address: 'AA:BB:CC:DD:EE:FF',  // Bluetooth MAC address
+  paperWidth: PaperWidth.MM_58   // 384px for 58mm, 576px for 80mm
+});
+```
+
+### Check Connection Status
+
+```typescript
+const status = await CatPrinter.isConnected();
+if (status.connected) {
+  console.log('Connected to:', status.address);
+  console.log('Paper width:', status.paperWidth);
+}
+```
+
+### Print Text
+
+```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)
+});
+```
+
+### 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)
+});
+```
+
+### Feed Paper
+
+```typescript
+await CatPrinter.feedPaper({ pixels: 100 });
+```
+
+### Disconnect
+
+```typescript
+await CatPrinter.disconnect();
+```
+
+## Event Listeners
+
+### Scan Results (Real-time)
+
+```typescript
+const listener = await CatPrinter.addListener('scanResult', (device) => {
+  console.log('Found device:', device.name, device.address, device.rssi);
+});
+
+// Remove listener when done
+listener.remove();
+```
+
+### Connection State Changes
+
+```typescript
+await CatPrinter.addListener('connectionState', (state) => {
+  if (state.connected) {
+    console.log('Connected to:', state.address);
+  } else {
+    console.log('Disconnected');
+  }
+});
+```
+
+### Print Progress
+
+```typescript
+await CatPrinter.addListener('printProgress', (progress) => {
+  console.log(`${progress.percent}% - ${progress.status}: ${progress.message}`);
+  // status: 'processing' | 'printing' | 'feeding' | 'done' | 'error'
+});
+```
+
+### Remove All Listeners
+
+```typescript
+await CatPrinter.removeAllListeners();
+```
+
+## API Reference
+
+### 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 |
+
+### Interfaces
+
+```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
+}
+```
+
+### Constants
+
+```typescript
+const PaperWidth = {
+  MM_58: 384,   // 58mm paper width
+  MM_80: 576    // 80mm paper width
+};
+```
+
+## Complete Example
+
+```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);
+  }
+}
+```
+
+## Supported Printers
+
+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`
+
+Many generic thermal printers from AliExpress/Amazon use this protocol.
+
+## Troubleshooting
+
+### 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
+
+### 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
+
+### Print quality issues
+- Increase `energy` for darker prints (0.6-0.8 recommended)
+- Use `quality: 4` for best quality (slower)
+- Enable `dither: true` for images with gradients
+- Adjust `threshold` for black/white conversion (lower = more black)
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,44 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "khare.catprinter.plugin"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    
+    <!-- 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" />
+    
+    <!-- Bluetooth permissions for Android 12+ -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    
+    <!-- Location permission required for BLE scanning on Android 6-11 -->
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    
+    <!-- Declare BLE feature -->
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+    <uses-feature android:name="android.hardware.location.gps" android:required="false"/>
+    <uses-feature android:name="android.hardware.bluetooth" android:required="false"/>
+    
+</manifest>