api_pos_printer

pub package pub points

Flutter plugin that drives the integrated thermal printer on Android POS terminals. Two backends are supported out of the box and the plugin auto-detects which one is installed at connect time:

Backend Service package Devices
ipos com.iposprinter.iposprinterservice Telpo, Centerm, MTwo, iPos and most Chinese-OEM POS units.
sunmi woyou.aidlservice.jiuiv5 Sunmi V1 / V2 / P1 / P2 / T1 / T2.

Android only. There is no equivalent service on iOS.

Installation

dependencies:
  api_pos_printer: ^0.1.2

import 'package:api_pos_printer/api_pos_printer.dart';

The plugin already declares the required <queries> entries in its manifest; no extra Android configuration is needed in your host app.

Quick start

final printer = ApiPosPrinter.instance;

// 1. Discover and connect.
final available = await printer.listBackends();
final backend = await printer.connect();           // auto-detects
print('Connected via ${backend.id}');

// 2. Subscribe to hardware events.
printer.statusStream.listen((s) => print('printer: ${s.name}'));

// 3. Print a ticket.
await printer.printText('PERMANENT INNOVATIONS',
    fontSize: 48, alignment: PrintAlignment.center);
await printer.printText('Demo ticket',
    fontSize: 24, alignment: PrintAlignment.center);
await printer.feedPaper(dots: 8);

await printer.printColumns(
  texts: ['Coffee', '2', '4.00'],
  widths: [16, 4, 8],
  aligns: [PrintAlignment.left, PrintAlignment.center, PrintAlignment.right],
);

await printer.printQrCode('https://permanentinnovations.africa', moduleSize: 10);
await printer.performPrint(feedLines: 80);

await printer.disconnect();

API surface

Dart method iPos AIDL Sunmi AIDL
getStatus() getPrinterStatus updatePrinterState (re-mapped)
setAlignment() printerSetAlignment setAlignment
printText() printSpecFormatText printTextWithFont
printColumns() rendered into a single padded line printColumnsText
printQrCode() printQRCode printQRCode
printBitmap(Uint8List) ¹ not exposed printBitmap(Bitmap)
printBarcode() ¹ not exposed printBarCode
printRaw(Uint8List) ¹ not exposed sendRAWData
feedPaper(dots) printerPrintBlankLines(1, dots) lineWrap(dots / 24)
performPrint() printerPerformPrint lineWrap

¹ The iPos AIDL exposed by these LzyHardWareManager-class devices does not include barcode, bitmap or raw byte methods. Calls throw UnsupportedOperationException on the iPos backend.

Status broadcasts (iPos only)

The iPos service broadcasts status changes; they are surfaced through statusStream as PrinterStatus values:

Broadcast action PrinterStatus
…NORMAL_ACTION / …PAPEREXISTS_ACTION / …THP_NORMALTEMP_ACTION normal
…PAPERLESS_ACTION paperless
…THP_HIGHTEMP_ACTION thpHighTemp
…MOTOR_HIGHTEMP_ACTION motorHighTemp
…BUSY_ACTION busy

Picking a specific backend

await printer.connect(backend: PrinterBackend.sunmi);

PrinterBackend.auto is the default and picks the first installed service in this order: ipos, then sunmi.

Adding a new backend

  1. Drop the vendor AIDL into android/src/main/aidl/<vendor>/….
  2. Implement the PrinterBackend Kotlin interface in android/src/main/kotlin/africa/permanentinnovations/api_pos_printer/backend/.
  3. Register the implementation in BackendDetector.autoDetect.

Dart and Kotlin layers are decoupled: Dart only knows about operations, not about which AIDL is being driven.

Limitations

  • Android only.
  • Bluetooth ESC/POS support is not included; this plugin targets devices with an integrated thermal head exposed through a system service.
  • On Sunmi, feedPaper(dots) is approximated to lineWrap(dots / 24) since Sunmi's API only feeds whole lines.

License

MIT — see LICENSE.

Libraries

api_pos_printer