📦 BlueThermal Plus --- Flutter Bluetooth Thermal Printer Plugin

A high-performance Flutter plugin for printing to thermal printers over Bluetooth Low Energy (BLE) and Bluetooth Classic (SPP) on Android and iOS.

Built with a clean transport-layer architecture for reliability, scalability, and production-grade stability.

✨ Features

• BLE printing with MTU-aware chunking\
• Bluetooth Classic (SPP) support\
• Automatic MTU negotiation\
• Smart data chunking & retry system\
• Auto-disconnect after print\
• Real-time device discovery events\
• Unified transport interface\
• Epson ePOS SDK transport on iOS (optional SDK install)\
• Production tested

📱 Supported Platforms

Platform	BLE	Classic	Epson ePOS
Android	✅	✅	❌
iOS	✅	✅ (MFi)	✅

🧠 Architecture

Flutter → TransportRouter → PrinterTransportManager → (BleTransport / ClassicTransport / EpsonEposTransport)

🚀 Installation

dependencies:
  blue_thermal_plus: ^0.1.1

Then run:

flutter pub get

📡 Basic Usage

import 'package:blue_thermal_plus/blue_thermal_plus.dart';

final printer = BlueThermalPlus();
await printer.startScan();
await printer.connect(deviceId: deviceId);
await printer.printRawBytes(bytes);

⚙️ BLE Config Example

await printer.configure(const PrinterConfig(
  ble: BleConfig(
    chunkSize: 200,
    chunkDelayMs: 10,
    autoDisconnectMs: 3000,
  ),
));

🧾 Epson TM-P80II on iOS

Epson printers such as TM-P80II_001379 should use the iOS Epson ePOS SDK transport instead of the Zebra BLE UUID transport:

final printer = BlueThermalPlus();

await printer.configure(PrinterProfiles.epsonTmP80II);
await printer.startScan(transport: PrinterTransport.epson);
await printer.connect(
  deviceId: device.id,
  transport: PrinterTransport.epson,
);
await printer.printRawBytes(bytes, transport: PrinterTransport.epson);

The Epson SDK binary is not bundled or published with this package. Download Epson ePOS SDK for iOS from Epson and copy libepos2.xcframework to the consuming app:

your_app/ios/Frameworks/libepos2.xcframework

If you are developing this plugin locally, you can also place it in:

blue_thermal_plus/ios/Frameworks/libepos2.xcframework

Then run pod install in the iOS app:

cd ios
pod install

If the printer uses Bluetooth Classic MFi, add Epson's external accessory protocol in the app Info.plist:

<key>UISupportedExternalAccessoryProtocols</key>
<array>
  <string>com.epson.escpos</string>
</array>

Keep com.zebra.rawport in the same array if your app also supports Zebra. For BLE Epson discovery, use EpsonPortType.bluetoothLe; for mixed discovery, the default profile uses EpsonPortType.all.

For TCP discovery/printing on iOS, your app may also need the local network privacy keys used by iOS 14+:

<key>NSLocalNetworkUsageDescription</key>
<string>This app uses the local network to discover and connect to printers.</string>

If the Epson SDK is missing, PrinterTransport.epson remains available but emits an error event explaining that libepos2.xcframework was not found.

📢 Events

scanStarted, deviceFound, connected, ready, status, error, disconnected

🧪 Testing

Flutter contract tests + native core logic + real device integration.

👨‍💻 Author

Mateus Polonini Cardoso

📄 License

MIT