@ruhiverse/thermal-printer-plugin 1.0.11 → 1.0.15

package/README.md

@@ -136,22 +136,28 @@ Returns a list of connected USB printers.
 
 ## Platform Support
 
-- ✅ Android (USB & Bluetooth)
-- ✅ iOS (USB & Bluetooth - basic implementation)
-- ❌ Web (not supported)
+| Platform | Bluetooth | USB | Printer Discovery |
+| -------- | --------- | --- | ----------------- |
+| Android  | ✅         | ✅   | ✅ (paired + scan) |
+| iOS      | ✅ (MFi & BLE) | ✅ (MFi only) | ✅ (MFi + BLE scan) |
+| Web      | ❌         | ❌   | ❌                 |
 
 ## Android Setup
 
 ### Permissions
 
-The plugin automatically requests the following permissions:
+The plugin declares the following permissions in its `AndroidManifest.xml`:
 
 - `BLUETOOTH`
 - `BLUETOOTH_ADMIN`
 - `BLUETOOTH_CONNECT` (Android 12+)
 - `BLUETOOTH_SCAN` (Android 12+)
+- `ACCESS_FINE_LOCATION` (required for Bluetooth scanning on Android 6-11)
+- `ACCESS_COARSE_LOCATION`
 - `USB_PERMISSION`
 
+The plugin automatically requests Bluetooth permissions at runtime when needed.
+
 ### USB Printing
 
 1. Connect your thermal printer via USB
@@ -160,20 +166,21 @@ The plugin automatically requests the following permissions:
 
 ### Bluetooth Printing
 
-1. Pair your thermal printer with the device via Bluetooth settings
-2. The plugin will automatically find and connect to paired printers
+1. Pair your thermal printer with the device via **Android Settings > Bluetooth**
+2. Use `listBluetoothPrinters()` to get the list of paired devices
+3. Use `printByBluetooth()` with the printer's `address` to print, or omit `address` to use the first paired printer
 
 ## iOS Setup
 
-### Info.plist Configuration
+### Required Info.plist Configuration
 
-Add the following to your app's `Info.plist`:
+Add the following keys to your app's `Info.plist`. **Without these, Bluetooth will not work on iOS.**
 
 ```xml
 <key>NSBluetoothAlwaysUsageDescription</key>
-<string>This app needs Bluetooth access to connect to thermal printers</string>
+<string>This app needs Bluetooth access to connect to thermal printers.</string>
 <key>NSBluetoothPeripheralUsageDescription</key>
-<string>This app needs Bluetooth access to connect to thermal printers</string>
+<string>This app needs Bluetooth access to connect to thermal printers.</string>
 <key>UISupportedExternalAccessoryProtocols</key>
 <array>
     <string>com.epson.escpos</string>
@@ -181,72 +188,70 @@ Add the following to your app's `Info.plist`:
 </array>
 ```
 
-**Note:** iOS implementation may require additional setup based on your printer model. USB printing on iOS requires MFi (Made for iPhone) certification.
+| Key | Required | Description |
+| --- | -------- | ----------- |
+| `NSBluetoothAlwaysUsageDescription` | **Yes** | iOS will silently block Bluetooth access without this. Triggers the permission dialog. |
+| `NSBluetoothPeripheralUsageDescription` | **Yes** | Required for connecting to Bluetooth peripherals (iOS 12 and earlier). |
+| `UISupportedExternalAccessoryProtocols` | **Yes** (for MFi printers) | Lists the protocol strings your printer supports. Update with your printer's protocols. |
 
-## Local Testing
+### iOS Bluetooth Printing
 
-### Testing Locally Before Publishing to npm
+The plugin supports two types of Bluetooth connections on iOS:
 
-1. **Link the plugin locally:**
+**MFi / ExternalAccessory printers (classic Bluetooth):**
+- Requires the printer to be MFi-certified (Made for iPhone)
+- Uses the ExternalAccessory framework
+- Printer must be paired in iOS Settings > Bluetooth
+- Protocol strings must be listed in `UISupportedExternalAccessoryProtocols`
 
-```bash
-cd /Users/apple/Desktop/ionic/workspace/plugin/thermal-printer-plugin
-npm link
-```
+**BLE printers (Bluetooth Low Energy):**
+- Uses CoreBluetooth framework
+- Discovered via BLE scanning (4-second scan)
+- Use the `address` from `listBluetoothPrinters()` when calling `printByBluetooth()`
 
-2. **In your Ionic/Capacitor project (e.g., milkwala project):**
+### iOS USB Printing
 
-```bash
-cd /path/to/milkwala/project
-npm link @ruhiverse/thermal-printer-plugin
-npx cap sync
-```
+USB printing on iOS requires MFi (Made for iPhone) certification for the printer. The printer is accessed through the ExternalAccessory framework.
 
-3. **Build and test:**
+### iOS Troubleshooting
 
-```bash
-# For Android
-npx cap run android
-
-# For iOS
-npx cap run ios
-```
+| Issue | Solution |
+| ----- | -------- |
+| `listBluetoothPrinters()` returns empty | Make sure `NSBluetoothAlwaysUsageDescription` is in your Info.plist and Bluetooth permission is granted |
+| Printer not found (MFi) | Verify the printer's protocol string is listed in `UISupportedExternalAccessoryProtocols` |
+| Printer not found (BLE) | Ensure the printer is powered on and in range. BLE scan runs for 4 seconds |
+| Permission dialog not showing | Delete and reinstall the app to reset permissions |
 
-### Alternative: Using file path
+## Local Development
 
-You can also install directly from the local path:
+### Testing Locally Before Publishing
 
-```bash
-cd /path/to/milkwala/project
-npm install /Users/apple/Desktop/ionic/workspace/plugin/thermal-printer-plugin
-npx cap sync
-```
-
-## Publishing to npm
-
-1. **Login to npm (if not already logged in):**
+1. **Link the plugin locally:**
 
 ```bash
-npm login
-# Use your ruhiverse npm account credentials
+cd path/to/thermal-printer-plugin
+npm link
 ```
 
-2. **Build the plugin:**
+2. **In your Ionic/Capacitor project:**
 
 ```bash
-npm run build
+cd path/to/your-project
+npm link @ruhiverse/thermal-printer-plugin
+npx cap sync
 ```
 
-3. **Publish to npm:**
+3. **Build and test:**
 
 ```bash
-npm publish --access public
+npx cap run android
+npx cap run ios
 ```
 
-4. **After publishing, install in your project:**
+### Alternative: Install from local path
 
 ```bash
-npm install @ruhiverse/thermal-printer-plugin
+npm install path/to/thermal-printer-plugin
 npx cap sync
 ```
 

package/android/src/main/java/com/ruhiverse/thermalprinter/AsyncEscPosPrint.java

@@ -1,7 +1,5 @@
 package com.ruhiverse.thermalprinter;
 
-import android.app.AlertDialog;
-import android.app.ProgressDialog;
 import android.content.Context;
 import android.os.AsyncTask;
 
@@ -28,7 +26,6 @@ public abstract class AsyncEscPosPrint extends AsyncTask<AsyncEscPosPrinter, Int
     protected final static int PROGRESS_PRINTING = 3;
     protected final static int PROGRESS_PRINTED = 4;
 
-    protected ProgressDialog dialog;
     protected WeakReference<Context> weakContext;
     protected OnPrintFinished onPrintFinished;
 
@@ -95,91 +92,14 @@ public abstract class AsyncEscPosPrint extends AsyncTask<AsyncEscPosPrinter, Int
     }
 
     protected void onPreExecute() {
-        if (this.dialog == null) {
-            Context context = weakContext.get();
-
-            if (context == null) {
-                return;
-            }
-
-            this.dialog = new ProgressDialog(context);
-            this.dialog.setTitle("Printing in progress...");
-            this.dialog.setMessage("...");
-            this.dialog.setProgressNumberFormat("%1d / %2d");
-            this.dialog.setCancelable(false);
-            this.dialog.setIndeterminate(false);
-            this.dialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL);
-            this.dialog.show();
-        }
+        // No UI — progress is handled silently
     }
 
     protected void onProgressUpdate(Integer... progress) {
-        switch (progress[0]) {
-            case AsyncEscPosPrint.PROGRESS_CONNECTING:
-                this.dialog.setMessage("Connecting printer...");
-                break;
-            case AsyncEscPosPrint.PROGRESS_CONNECTED:
-                this.dialog.setMessage("Printer is connected...");
-                break;
-            case AsyncEscPosPrint.PROGRESS_PRINTING:
-                this.dialog.setMessage("Printer is printing...");
-                break;
-            case AsyncEscPosPrint.PROGRESS_PRINTED:
-                this.dialog.setMessage("Printer has finished...");
-                break;
-        }
-        this.dialog.setProgress(progress[0]);
-        this.dialog.setMax(4);
+        // No UI — progress is handled silently
     }
 
     protected void onPostExecute(PrinterStatus result) {
-        this.dialog.dismiss();
-        this.dialog = null;
-
-        Context context = weakContext.get();
-
-        if (context == null) {
-            return;
-        }
-
-        switch (result.getPrinterStatus()) {
-            case AsyncEscPosPrint.FINISH_SUCCESS:
-                new AlertDialog.Builder(context)
-                        .setTitle("Success")
-                        .setMessage("Print completed successfully!")
-                        .show();
-                break;
-            case AsyncEscPosPrint.FINISH_NO_PRINTER:
-                new AlertDialog.Builder(context)
-                        .setTitle("No printer")
-                        .setMessage("The application can't find any printer connected.")
-                        .show();
-                break;
-            case AsyncEscPosPrint.FINISH_PRINTER_DISCONNECTED:
-                new AlertDialog.Builder(context)
-                    .setTitle("Broken connection")
-                    .setMessage("Unable to connect the printer.")
-                    .show();
-                break;
-            case AsyncEscPosPrint.FINISH_PARSER_ERROR:
-                new AlertDialog.Builder(context)
-                    .setTitle("Invalid formatted text")
-                    .setMessage("It seems to be an invalid syntax problem.")
-                    .show();
-                break;
-            case AsyncEscPosPrint.FINISH_ENCODING_ERROR:
-                new AlertDialog.Builder(context)
-                    .setTitle("Bad selected encoding")
-                    .setMessage("The selected encoding character returning an error.")
-                    .show();
-                break;
-            case AsyncEscPosPrint.FINISH_BARCODE_ERROR:
-                new AlertDialog.Builder(context)
-                    .setTitle("Invalid barcode")
-                    .setMessage("Data send to be converted to barcode or QR code seems to be invalid.")
-                    .show();
-                break;
-        }
         if(this.onPrintFinished != null) {
             if (result.getPrinterStatus() == AsyncEscPosPrint.FINISH_SUCCESS) {
                 this.onPrintFinished.onSuccess(result.getAsyncEscPosPrinter());

package/dist/docs.json

@@ -53,9 +53,9 @@
       },
       {
         "name": "listBluetoothPrinters",
-        "signature": "() => Promise<{ name: string; address: string; }[]>",
+        "signature": "() => Promise<{ printers: { name: string; address: string; }[]; }>",
         "parameters": [],
-        "returns": "Promise<{ name: string; address: string; }[]>",
+        "returns": "Promise<{ printers: { name: string; address: string; }[]; }>",
         "tags": [],
         "docs": "Get list of paired Bluetooth printers",
         "complexTypes": [],
@@ -63,9 +63,9 @@
       },
       {
         "name": "listUsbPrinters",
-        "signature": "() => Promise<{ name: string; address: string; }[]>",
+        "signature": "() => Promise<{ printers: { name: string; address: string; }[]; }>",
         "parameters": [],
-        "returns": "Promise<{ name: string; address: string; }[]>",
+        "returns": "Promise<{ printers: { name: string; address: string; }[]; }>",
         "tags": [],
         "docs": "Get list of connected USB printers",
         "complexTypes": [],

package/dist/esm/definitions.d.ts

@@ -13,16 +13,20 @@ export interface ThermalPrinterPlugin {
      * Get list of paired Bluetooth printers
      */
     listBluetoothPrinters(): Promise<{
-        name: string;
-        address: string;
-    }[]>;
+        printers: {
+            name: string;
+            address: string;
+        }[];
+    }>;
     /**
      * Get list of connected USB printers
      */
     listUsbPrinters(): Promise<{
-        name: string;
-        address: string;
-    }[]>;
+        printers: {
+            name: string;
+            address: string;
+        }[];
+    }>;
 }
 export interface PrintObject {
     /**

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface ThermalPrinterPlugin {\n  /**\n   * Print text using USB connection\n   * @param printObject Object containing text to print\n   */\n  printByUsb(printObject: PrintObject): Promise<void>;\n\n  /**\n   * Print text using Bluetooth connection\n   * @param printObject Object containing text to print\n   */\n  printByBluetooth(printObject: PrintObject): Promise<void>;\n\n  /**\n   * Get list of paired Bluetooth printers\n   */\n  listBluetoothPrinters(): Promise<{ name: string; address: string }[]>;\n\n  /**\n   * Get list of connected USB printers\n   */\n  listUsbPrinters(): Promise<{ name: string; address: string }[]>;\n}\n\nexport interface PrintObject {\n  /**\n   * Text to print. Supports ESC/POS formatting commands.\n   * Example: \"[C]<b>Hello World</b>\\n[C]This is a test\"\n   */\n  textToPrint: string;\n\n  /**\n   * Optional Bluetooth MAC address of the printer to use.\n   * Only applicable for printByBluetooth.\n   */\n  address?: string;\n\n  /**\n   * Optional USB device name of the printer to use.\n   * Only applicable for printByUsb.\n   */\n  name?: string;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface ThermalPrinterPlugin {\n  /**\n   * Print text using USB connection\n   * @param printObject Object containing text to print\n   */\n  printByUsb(printObject: PrintObject): Promise<void>;\n\n  /**\n   * Print text using Bluetooth connection\n   * @param printObject Object containing text to print\n   */\n  printByBluetooth(printObject: PrintObject): Promise<void>;\n\n  /**\n   * Get list of paired Bluetooth printers\n   */\n  listBluetoothPrinters(): Promise<{ printers: { name: string; address: string }[] }>;\n\n  /**\n   * Get list of connected USB printers\n   */\n  listUsbPrinters(): Promise<{ printers: { name: string; address: string }[] }>;\n}\n\nexport interface PrintObject {\n  /**\n   * Text to print. Supports ESC/POS formatting commands.\n   * Example: \"[C]<b>Hello World</b>\\n[C]This is a test\"\n   */\n  textToPrint: string;\n\n  /**\n   * Optional Bluetooth MAC address of the printer to use.\n   * Only applicable for printByBluetooth.\n   */\n  address?: string;\n\n  /**\n   * Optional USB device name of the printer to use.\n   * Only applicable for printByUsb.\n   */\n  name?: string;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruhiverse/thermal-printer-plugin",
-  "version": "1.0.11",
+  "version": "1.0.15",
   "description": "Capacitor plugin for thermal printing via USB and Bluetooth",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",