thermal_printer_billbay #

A comprehensive Flutter plugin for ESC/POS thermal printers via Bluetooth Classic (SPP).

Supports Android (Bluetooth Classic) and iOS (MFi via ExternalAccessory).

Features #

• Bluetooth Classic (SPP) connection — scan, pair, connect, send
• Full ESC/POS command set — text, bold, underline, reverse, font sizes, alignment
• Arabic text shaping — automatic joining forms, Lam-Alef ligatures, bidi reversal
• Multiple code pages — Win-1256, CP864, CP720, UTF-8, or any custom number
• Paper sizes — 58mm, 72mm, 80mm, 110mm, and custom
• Multi-column rows — grid-based column layout for receipts
• Receipt templates — ready-made invoice builder with items, tax, QR, footer
• Images — print PNG/JPEG/BMP with auto monochrome conversion
• QR codes — native ESC/POS QR commands
• Barcodes — UPC-A, UPC-E, EAN-13, EAN-8, Code 39, ITF, Codabar, Code 93, Code 128
• Horizontal lines — solid, dashed, dotted, double, star, equals
• Paper cut, cash drawer, beep
• Raw bytes pass-through for custom commands

Table of Contents #

1. Installation
2. Android Setup
3. iOS Setup
4. Quick Start
5. Finding Your Printer's Code Page
6. Printing Text
7. Text Styles
8. Arabic Text
9. Multi-Column Rows
10. Horizontal Lines
11. QR Codes
12. Barcodes
13. Images
14. Receipt Templates
15. Paper Cut, Cash Drawer & Beep
16. Full API Reference
17. Distribution Guide

1. Installation #

Option A: Local Path (for development / private use) #

Put the thermal_printer_billbay folder next to your app folder:

my_projects/
  thermal_printer_billbay/    ← this plugin
  my_app/             ← your Flutter app

In your app's pubspec.yaml:

dependencies:
  thermal_printer_billbay:
    path: ../thermal_printer_billbay

Option B: Git Repository (for sharing with team) #

Push thermal_printer_billbay to a Git repo (GitHub, GitLab, Bitbucket), then:

dependencies:
  thermal_printer_billbay:
    git:
      url: https://github.com/YOUR_USERNAME/thermal_printer_billbay.git
      ref: main  # or a specific tag like v1.0.0

Option C: Publish to pub.dev (for public distribution) #

See Section 17: Distribution Guide.

After adding the dependency #

Run in your app folder:

flutter pub get

No additional permission packages needed — the plugin handles Bluetooth permissions internally.

2. Android Setup #

2.1 Permissions #

Add these to your app's android/app/src/main/AndroidManifest.xml (inside the <manifest> tag, before <application>):

<!-- Bluetooth Classic permissions -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>

<!-- Android 12+ Bluetooth permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- Location (required for Bluetooth scanning on Android) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

2.2 Request Permissions at Runtime #

The plugin handles runtime permission requests automatically. Just call:

final printer = ThermalPrinterManager();

// Option A: One-call setup (handles permissions + Bluetooth enable)
final ready = await printer.ensureReady();
if (!ready) return; // permissions denied or Bluetooth off

// Option B: Step by step
final granted = await printer.requestPermissions();
if (!granted) return;

if (!await printer.isBluetoothEnabled()) {
  await printer.enableBluetooth();
}

2.3 Min SDK #

Make sure your android/app/build.gradle has minSdk at least 21:

android {
    defaultConfig {
        minSdk = 21
    }
}

3. iOS Setup #

3.1 Info.plist #

Add these to ios/Runner/Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth to connect to thermal printers</string>

<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.yourprinter.protocol</string>
</array>

Replace com.yourprinter.protocol with your printer's MFi protocol string (check your printer's documentation).

3.2 Set Protocol in Code #

final printer = ThermalPrinterManager();
await printer.setProtocol('com.yourprinter.protocol');

3.3 Important #

iOS only supports MFi-certified printers via the ExternalAccessory framework. Regular Bluetooth printers that are not MFi certified will not work on iOS.

4. Quick Start #

Here is the simplest possible example — setup, connect, print "Hello World", cut paper:

import 'package:thermal_printer_billbay/thermal_printer_billbay.dart';

// 1. Create the printer manager
final printer = ThermalPrinterManager();

// 2. Ensure permissions + Bluetooth are ready
final ready = await printer.ensureReady();
if (!ready) return;

// 3. Get already-paired devices
final devices = await printer.getBondedDevices();
print('Found ${devices.length} paired devices');

// 4. Connect to the first printer (with auto-retry)
final connected = await printer.connectWithRetry(devices.first.address);
if (!connected) {
  print('Failed to connect');
  return;
}

// 4. Build ESC/POS commands
final cmd = EscPosCommands(PaperSize.mm80);
cmd.initialize();
cmd.textLn('Hello World!', useLatin: true);
cmd.feed(3);
cmd.cut();

// 5. Send to printer
await printer.sendBytes(cmd.getBytes());

// 6. Disconnect when done
await printer.disconnect();
printer.dispose();

Scanning for New Devices #

final printer = ThermalPrinterManager();

// Listen for discovered devices
printer.scanResults.listen((device) {
  print('Found: ${device.name} (${device.address})');
});

// Listen for connection changes
printer.connectionState.listen((connected) {
  print('Connected: $connected');
});

// Start scanning (also discovers nearby unpaired devices)
await printer.startScan();

// Stop after 10 seconds
Future.delayed(Duration(seconds: 10), () {
  printer.stopScan();
});

5. Finding Your Printer's Code Page #

This is the most important step for Arabic/special characters.

Every thermal printer has a list of code pages, but the numbers are different for every brand. The same encoding (e.g., Windows-1256 Arabic) might be number 46 on one printer and number 60 on another.

How to Find Your Code Page Number #

1. Print a self-test page: Turn off your printer, then hold the FEED button and turn it on. It will print a page showing all supported code pages with their numbers.

2. Look for Arabic code pages: Find entries like:

   • 46: WPC1256 or 46: Win-1256 (Windows-1256 Arabic)
   • 22: PC864 (IBM Arabic)
   • 41: PC864 (same encoding, different number!)
   • 60: PC1001 (another Arabic page)

3. Use the number from YOUR printer's self-test:

   // If your printer shows "46: Win-1256"
   cmd.setCodePage(CodePage.win1256); // sends ESC t 46
   
   // If your printer shows Arabic at number 41
   cmd.setCodePageRaw(41); // sends ESC t 41
   
   // For UTF-8 mode (Chinese-brand printers often support this)
   cmd.setCodePage(CodePage.utf8); // sends FS .
   

Built-in Code Page Presets #

Custom Code Page #

If your printer uses a different number:

// Your printer has Arabic at position 60
cmd.setCodePageRaw(60);

// Or create a reusable CodePage object
final myCodePage = CodePage.customArabic(60);
cmd.setCodePage(myCodePage);

// Parse from user input (number or name)
cmd.setCodePageFromString('60');      // sends ESC t 60
cmd.setCodePageFromString('PC10001'); // sends FS . (UTF-8)

6. Printing Text #

Basic Text #

final cmd = EscPosCommands(PaperSize.mm80);
cmd.initialize();
cmd.setCodePage(CodePage.win1256);

// Print a line (adds line feed at end)
cmd.textLn('Hello World!', useLatin: true);

// Print text without line feed
cmd.text('Same line... ', useLatin: true);
cmd.textLn('continues here', useLatin: true);

// Print a blank line
cmd.newLine();

// Print Arabic text
cmd.textLn('مرحبا بالعالم');

cmd.feed(3);
await printer.sendBytes(cmd.getBytes());

The useLatin Parameter #

• useLatin: true — Use for English, numbers, symbols. Sends raw ASCII bytes (fast, always works).
• useLatin: false (default) — Use for Arabic or mixed text. Applies Arabic shaping and encodes using the selected code page.

7. Text Styles #

Using textStyled() (recommended) #

textStyled() applies styles, prints the text, then automatically resets styles back to normal:

cmd.initialize();

// Bold centered title
cmd.textStyled('MY STORE',
    PosStyles(align: PrintAlign.center, bold: true, width: 2, height: 2),
    useLatin: true);

// Underlined text
cmd.textStyled('Underlined', PosStyles(underline: true), useLatin: true);

// Double underline
cmd.textStyled('Double underline', PosStyles(doubleUnderline: true), useLatin: true);

// Reverse (white text on black background)
cmd.textStyled('Reversed!', PosStyles(reverse: true), useLatin: true);

// Font B (smaller font, more characters per line)
cmd.textStyled('Small font', PosStyles(fontType: FontType.fontB), useLatin: true);

// Wide text (2x width)
cmd.textStyled('Wide', PosStyles(width: 2), useLatin: true);

// Tall text (2x height)
cmd.textStyled('Tall', PosStyles(height: 2), useLatin: true);

// Combine multiple styles
cmd.textStyled('BIG BOLD',
    PosStyles(bold: true, width: 2, height: 2, align: PrintAlign.center),
    useLatin: true);

Using Manual Style Commands #

For more control, set styles individually:

cmd.setBold(true);
cmd.setFontSize(2, 2);       // width=2, height=2
cmd.setAlign(PrintAlign.center);
cmd.textLn('Custom styled', useLatin: true);

// Reset everything back to normal
cmd.resetStyles();

All Available Styles #

8. Arabic Text #

Basic Arabic Printing #

cmd.initialize();
cmd.setCodePage(CodePage.win1256); // Use the code page that works for YOUR printer

cmd.textLn('مرحبا بالعالم');             // Hello World
cmd.textLn('اختبار الطباعة العربية');     // Arabic printing test

How Arabic Works #

1. Code page tells the printer which character encoding to use
2. Arabic shaping converts letters to their correct joined forms (initial, medial, final, isolated)
3. Bidi reversal flips the text so it prints right-to-left

The plugin handles steps 2 and 3 automatically when you use textLn() without useLatin: true.

Arabic with UTF-8 Mode #

If your printer supports UTF-8 (FS . command), Arabic shaping uses Unicode Presentation Forms (U+FE70-U+FEFF) which gives the best results:

cmd.setCodePage(CodePage.utf8);
cmd.textLn('مرحبا بالعالم');  // Shaped + UTF-8 encoded

Arabic with Win-1256 #

If your printer uses Windows-1256 (common for Epson-compatible printers), the plugin encodes Arabic using a Win-1256 lookup table:

cmd.setCodePage(CodePage.win1256);
cmd.textLn('مرحبا بالعالم');  // Encoded as Win-1256 bytes

Mixed Arabic and English #

cmd.textLn('الفاتورة Invoice');  // Mixed text
cmd.textLn('Hello مرحبا World');

9. Multi-Column Rows #

Use row() to print tabular data. Column widths are proportional (like a 12-column grid):

// Header row
cmd.row([
  PosColumn(text: 'Item', width: 6),
  PosColumn(text: 'Qty', width: 2, align: PrintAlign.center),
  PosColumn(text: 'Price', width: 4, align: PrintAlign.right),
], useLatin: true);

// Data rows
cmd.row([
  PosColumn(text: 'Coffee', width: 6),
  PosColumn(text: '2', width: 2, align: PrintAlign.center),
  PosColumn(text: '5.00', width: 4, align: PrintAlign.right),
], useLatin: true);

Left-Right Alignment #

For simple label-value pairs:

cmd.leftRight('Subtotal:', '45.00', useLatin: true);
cmd.leftRight('Tax (15%):', '6.75', useLatin: true);
cmd.leftRight('TOTAL:', '51.75', useLatin: true);

10. Horizontal Lines #

cmd.hr();                                // ------------------------------------------------
cmd.hr(style: LineStyle.solid);          // ------------------------------------------------
cmd.hr(style: LineStyle.dashed);         // - - - - - - - - - - - - - - - - - - - - - - - -
cmd.hr(style: LineStyle.dotted);         // ................................................
cmd.hr(style: LineStyle.doubleLine);     // ================================================
cmd.hr(style: LineStyle.star);           // ************************************************
cmd.hr(style: LineStyle.equals);         // ================================================

// Custom character
cmd.hr(customChar: '~');                 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The line width is automatically calculated based on your paper size (48 chars for 80mm, 32 for 58mm, etc.).

11. QR Codes #

cmd.printQrCode(
  'https://example.com',
  size: 6,                           // Module size: 1-16 (default: 6)
  errorLevel: QrErrorLevel.medium,   // L, M, Q, H (default: M)
  align: PrintAlign.center,          // Alignment (default: center)
);

QR Error Correction Levels #

12. Barcodes #

cmd.printBarcode(
  '1234567890128',
  BarcodeType.ean13,
  height: 80,          // Barcode height in dots (default: 80)
  width: 2,            // Bar width: 2-6 (default: 2)
  textPosition: 2,     // 0=none, 1=above, 2=below, 3=both
  align: PrintAlign.center,
);

Supported Barcode Types #

13. Images #

Print any image (PNG, JPEG, BMP). It's automatically converted to monochrome and scaled to fit the paper width:

import 'dart:io';

// Load image from file
final imageBytes = await File('path/to/logo.png').readAsBytes();

cmd.printImage(
  imageBytes,
  maxWidth: 384,           // Max width in dots (optional, defaults to paper width)
  threshold: 127,          // Black/white threshold: 0-255 (default: 127)
  align: PrintAlign.center,
);

From Flutter Assets #

import 'package:flutter/services.dart';

final data = await rootBundle.load('assets/logo.png');
final imageBytes = data.buffer.asUint8List();
cmd.printImage(imageBytes);

14. Receipt Templates #

Full Receipt #

final cmd = EscPosCommands(PaperSize.mm80);
cmd.setCodePage(CodePage.win1256);

final receipt = ReceiptTemplate(
  cmd: cmd,
  storeName: 'MY STORE',
  storeAddress: '123 Main Street',
  storePhone: '555-1234',
  storeEmail: '[email protected]',
  currency: '\$',  // Currency symbol before prices
);

receipt.build(
  items: [
    ReceiptItem(name: 'Coffee', quantity: 2, price: 5.00),
    ReceiptItem(name: 'Sandwich', quantity: 1, price: 8.50),
    ReceiptItem(name: 'Cookie', quantity: 3, price: 2.00, discount: 1.00),
  ],
  taxRate: 0.15,              // 15% tax
  discount: 2.0,              // Overall discount amount
  receiptNumber: '001234',
  cashierName: 'Ahmad',
  customerName: 'John',
  footerText: 'Thank you for your purchase!',
  footerTextArabic: 'شكرا لزيارتكم',
  qrData: 'https://mystore.com/receipt/001234',
  barcodeData: '001234',
  cutAfter: true,             // Auto cut paper after receipt
);

await printer.sendBytes(cmd.getBytes());

This prints:

       MY STORE
    123 Main Street
      Tel: 555-1234
    [email protected]
------------------------------------------------
Receipt #:               001234
Date:          2026-02-07 14:30
Cashier:                 Ahmad
Customer:                 John
------------------------------------------------
Item       Qty  Price   Total
- - - - - - - - - - - - - - -
Coffee      2    5.00   10.00
Sandwich    1    8.50    8.50
Cookie      3    2.00    5.00
  Disc: -1.00
- - - - - - - - - - - - - - -
Subtotal:                23.50
Discount:                -2.00
Tax (15%):                3.23
- - - - - - - - - - - - - - -
TOTAL:                   24.73
------------------------------------------------
  Thank you for your purchase!
        شكرا لزيارتكم

        [QR CODE]

       ||||| BARCODE |||||
         001234

Simple Receipt (minimal) #

For a quick receipt without store info:

final cmd = EscPosCommands(PaperSize.mm80);
cmd.initialize();

SimpleReceipt.print(
  cmd,
  title: 'RECEIPT',
  items: [
    ReceiptItem(name: 'Item A', quantity: 2, price: 10.0),
    ReceiptItem(name: 'Item B', quantity: 1, price: 25.0),
  ],
  cutAfter: true,
);

await printer.sendBytes(cmd.getBytes());

Custom Receipt (build your own) #

You can build any layout using the low-level commands:

final cmd = EscPosCommands(PaperSize.mm80);
cmd.initialize();
cmd.setCodePage(CodePage.win1256);

// Header
cmd.textStyled('INVOICE',
    PosStyles(align: PrintAlign.center, bold: true, width: 2, height: 2),
    useLatin: true);
cmd.textStyled('My Company LLC',
    PosStyles(align: PrintAlign.center),
    useLatin: true);
cmd.hr(style: LineStyle.doubleLine);

// Items
cmd.row([
  PosColumn(text: 'Description', width: 6),
  PosColumn(text: 'Qty', width: 2, align: PrintAlign.center),
  PosColumn(text: 'Amount', width: 4, align: PrintAlign.right),
], useLatin: true);
cmd.hr(style: LineStyle.dashed);

cmd.row([
  PosColumn(text: 'Laptop', width: 6),
  PosColumn(text: '1', width: 2, align: PrintAlign.center),
  PosColumn(text: '999.00', width: 4, align: PrintAlign.right),
], useLatin: true);

cmd.hr(style: LineStyle.doubleLine);

// Total
cmd.setBold(true);
cmd.setFontSize(2, 1);
cmd.leftRight('TOTAL:', '\$999.00', useLatin: true);
cmd.resetStyles();

// Arabic footer
cmd.setAlign(PrintAlign.center);
cmd.textLn('شكرا لك');
cmd.setAlign(PrintAlign.left);

// QR code
cmd.printQrCode('https://mycompany.com/inv/12345', size: 5);

cmd.feedAndCut();
await printer.sendBytes(cmd.getBytes());

15. Paper Cut, Cash Drawer & Beep #

Paper Cut #

cmd.cut();                            // Full cut
cmd.cut(mode: CutMode.partial);      // Partial cut (leaves a small strip)
cmd.feedAndCut();                     // Feed 3 lines + full cut
cmd.feedAndCut(lines: 5, mode: CutMode.partial);  // Custom

Cash Drawer #

cmd.openDrawer();                      // Open via pin 2 (default)
cmd.openDrawer(pin: DrawerPin.pin5);   // Open via pin 5

Beep #

cmd.beep();                            // Single beep
cmd.beep(count: 3, duration: 5);       // 3 beeps, each 5 units long

Paper Feed #

cmd.feed(1);     // Feed 1 line
cmd.feed(5);     // Feed 5 lines
cmd.newLine();   // Single line feed

16. Full API Reference #

ThermalPrinterManager #

EscPosCommands #

PaperSize #

17. Distribution Guide #

How to Share This Package #

Option 1: Share the Folder (simplest)

1. Copy the thermal_printer_billbay/ folder to anyone who needs it
2. They put it next to their app folder
3. They add to their pubspec.yaml:

   dependencies:
     thermal_printer_billbay:
       path: ../thermal_printer_billbay
   

4. Run flutter pub get

Option 2: Push to GitHub (recommended for teams)

Step 1: Create a GitHub repo

1. Go to https://github.com/new
2. Name it thermal_printer_billbay
3. Set it to Public or Private
4. Do NOT add a README (we already have one)

Step 2: Push your code

Open a terminal in the thermal_printer_billbay/ folder:

cd thermal_printer_billbay
git init
git add .
git commit -m "Initial release v1.0.0"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/thermal_printer_billbay.git
git push -u origin main

Step 3: Create a version tag (optional but recommended)

git tag v1.0.0
git push origin v1.0.0

Step 4: Others can now use it

# In their pubspec.yaml
dependencies:
  thermal_printer_billbay:
    git:
      url: https://github.com/YOUR_USERNAME/thermal_printer_billbay.git
      ref: v1.0.0  # or 'main' for latest

Option 3: Publish to pub.dev (public packages)

Step 1: Prepare the package

1. Open thermal_printer_billbay/pubspec.yaml
2. Remove or change the publish_to: 'none' line
3. Make sure name, description, and version are set
4. Make sure this README.md exists and is complete

Step 2: Check the package

cd thermal_printer_billbay
dart pub publish --dry-run

Fix any issues it reports.

Step 3: Create a Google account (if you don't have one)

You need a Google account to publish to pub.dev.

Step 4: Publish

dart pub publish

This will open a browser for Google sign-in, then upload the package.

Step 5: Others can now use it

# In their pubspec.yaml
dependencies:
  thermal_printer_billbay: ^1.0.0

Troubleshooting #

"Arabic prints as Chinese/garbage characters" #

Your printer is using the wrong code page. Print a self-test page (hold FEED button while powering on) and find the Arabic code page number. Then use that number:

cmd.setCodePageRaw(YOUR_NUMBER_HERE);

"Cannot find printer" #

• Make sure Bluetooth is turned on
• Make sure the printer is powered on and in pairing mode
• On Android, grant all Bluetooth and Location permissions
• Try pairing the printer first in your phone's Bluetooth settings

"Connection failed" #

• Make sure no other app is connected to the printer
• Turn the printer off and on
• Remove the pairing and re-pair in Bluetooth settings

"Arabic letters are not joined" #

The plugin automatically shapes Arabic text. Make sure you're NOT using useLatin: true for Arabic text:

// WRONG — Arabic won't be shaped
cmd.textLn('مرحبا', useLatin: true);

// CORRECT — Arabic will be shaped automatically
cmd.textLn('مرحبا');

"Image is too dark/light" #

Adjust the threshold value (0=all black, 255=all white):

cmd.printImage(imageBytes, threshold: 100); // Darker
cmd.printImage(imageBytes, threshold: 180); // Lighter

License #

This package is provided as-is for free use. Modify and distribute as needed.