flutter_bt_print

A lightweight Flutter plugin for Bluetooth thermal printing using ESC/POS compatible printers.

This plugin allows Flutter applications to:

• Connect to Bluetooth thermal printers
• Print text
• Print images and files
• Print PDF content after raster conversion
• Manage printer connection state
• Work with most 58mm and 80mm thermal printers

---

✨ Features

• Bluetooth device discovery
• Connect / Disconnect printer
• Print text
• Print image / bitmap
• Print PDF files
• Stream-based connection status
• Optimized for thermal printers (203 DPI)
• Android & iOS support

---

🚀 Getting Started

Add the dependency in your pubspec.yaml:

dependencies:
  flutter_bt_print:

Then run:

flutter pub get

---

⚠️ Important

Before using this package, please check the example project included in this repository.

The example demonstrates:

• Proper permission handling
• Bluetooth connection flow
• PDF to image conversion
• Thermal image processing
• Printing workflow

This is strongly recommended before integrating into production apps.

---

📦 Required Dependencies

This plugin internally or externally works together with:

permission_handler:
rxdart:
file_picker:
printing:
image:

Make sure these packages are added when required in your project.

---

🔐 Permissions Required

Bluetooth printing requires runtime permissions.

---

✅ Android Permissions

Add the following permissions inside:

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android Notes

• Required for Android 8.0+
• Android 12+ requires BLUETOOTH_CONNECT and BLUETOOTH_SCAN
• Location permission is required for Bluetooth device discovery

Make sure permissions are requested at runtime using permission_handler.

---

✅ iOS Permissions

Add the following keys inside:

ios/Runner/Info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect and print to thermal printers.</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with printers.</string>

iOS Notes

• Bluetooth permission prompt appears automatically
• Ensure Bluetooth capability is enabled

---

🖨️ Supported Printers

• ESC/POS compatible Bluetooth printers
• 58mm thermal printers
• 80mm (4-inch) thermal printers
• Common POS thermal printers

---

📄 Printing Workflow (Recommended)

For best results:

PDF → Raster Image (203 DPI)
      → Resize to printer width
      → Grayscale
      → Threshold / Dithering
      → Print

Thermal printers do not support direct PDF rendering.

---

✅ Example Usage

await printer.connect(address);
await printer.printText("Hello World");

For complete implementation, see the example project.

---

⚠️ Notes

• Thermal printers use heat, not ink.
• Paper quality directly affects print darkness.
• Use good quality thermal paper for best results.
• Image-based printing should be optimized before sending to printer.

---

📜 License

MIT License — Free for personal and commercial use.

See the LICENSE file for details.

---

🤝 Contributions

Pull requests and improvements are welcome. Please open an issue before submitting major changes.

---