Android library for ESC/POS Thermal Printer

Useful library to help Android developers to print with (Bluetooth, TCP, USB) ESC/POS thermal printers.

✨ Supporting

⭐ Star this repository to support this project. You will contribute to increase the visibility of this library 🙂

Table of contents

• Android version
• Tested printers
• Test It !
• Installation
• Bluetooth
• Bluetooth permission
• Bluetooth code example
• TCP
• TCP permission
• TCP code example
• USB
• USB permission
• USB code example
• Charset encoding
• Formatted text : syntax guide
• Class list
• BluetoothPrintersConnections
• UsbPrintersConnections
• EscPosPrinter
• PrinterTextParserImg
• EscPosCharsetEncoding
• Projects using this library
• Contributing

Android version

Developed for SDK version 16 (Android 4.1 Jelly Bean) and above.

Tested printers

1. HOIN HOP H58 Thermal Printer ESC/POS.
2. XPRINTER XP-P300.
3. MUNBYN IMP001.
4. JP-Q2 POS Terminal PDA (Embedded printer is configured as Bluetooth device)
5. MUNBYN ITPP047 (tested over USB)

Test it !

To test this library, it's pretty simple !

• Create a directory and open a terminal inside
• Run git clone https://github.com/DantSu/ESCPOS-ThermalPrinter-Android.git .
• Open the directory with Android Studio
• Test it !

Installation

Step 1. Add the JitPack repository to your build file. Add it in your root /build.gradle at the end of repositories:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step 2. Add the dependency in /app/build.gradle :

dependencies {
    ...
    implementation 'com.github.DantSu:ESCPOS-ThermalPrinter-Android:3.3.0'
}

Bluetooth

Bluetooth permission

Be sure to have <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" /> in your AndroidManifest.xml.

Also, you have to check the bluetooth permission in your app like this :

if (android.os.Build.VERSION.SDK_INT < android.os.Build.VERSION_CODES.S && ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.BLUETOOTH}, MainActivity.PERMISSION_BLUETOOTH);
} else if (android.os.Build.VERSION.SDK_INT < android.os.Build.VERSION_CODES.S && ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADMIN) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.BLUETOOTH_ADMIN}, MainActivity.PERMISSION_BLUETOOTH_ADMIN);
} else if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S && ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.BLUETOOTH_CONNECT}, MainActivity.PERMISSION_BLUETOOTH_CONNECT);
} else if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S && ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.BLUETOOTH_SCAN}, MainActivity.PERMISSION_BLUETOOTH_SCAN);
} else {
    // Your code HERE
}

Bluetooth code example

The code below is an example to write in your activity :

EscPosPrinter printer = new EscPosPrinter(BluetoothPrintersConnections.selectFirstPaired(), 203, 48f, 32);
printer
    .printFormattedText(
        "[C]<img>" + PrinterTextParserImg.bitmapToHexadecimalString(printer, this.getApplicationContext().getResources().getDrawableForDensity(R.drawable.logo, DisplayMetrics.DENSITY_MEDIUM))+"</img>\n" +
        "[L]\n" +
        "[C]<u><font size='big'>ORDER N°045</font></u>\n" +
        "[L]\n" +
        "[C]================================\n" +
        "[L]\n" +
        "[L]<b>BEAUTIFUL SHIRT</b>[R]9.99e\n" +
        "[L]  + Size : S\n" +
        "[L]\n" +
        "[L]<b>AWESOME HAT</b>[R]24.99e\n" +
        "[L]  + Size : 57/58\n" +
        "[L]\n" +
        "[C]--------------------------------\n" +
        "[R]TOTAL PRICE :[R]34.98e\n" +
        "[R]TAX :[R]4.23e\n" +
        "[L]\n" +
        "[C]================================\n" +
        "[L]\n" +
        "[L]<font size='tall'>Customer :</font>\n" +
        "[L]Raymond DUPONT\n" +
        "[L]5 rue des girafes\n" +
        "[L]31547 PERPETES\n" +
        "[L]Tel : +33801201456\n" +
        "[L]\n" +
        "[C]<barcode type='ean13' height='10'>831254784551</barcode>\n" +
        "[C]<qrcode size='20'>https://dantsu.com/</qrcode>"
    );

Below a picture of the receipt printed with the code above :

TCP

TCP permission

Be sure to have <uses-permission android:name="android.permission.INTERNET"/> in your AndroidManifest.xml.

TCP code example

The code below is an example to write in your activity :

new Thread(new Runnable() {
    public void run() {
        try {
            EscPosPrinter printer = new EscPosPrinter(new TcpConnection("192.168.1.3", 9300, 15), 203, 48f, 32);
            printer
                .printFormattedText(
                    "[C]<img>" + PrinterTextParserImg.bitmapToHexadecimalString(printer, getApplicationContext().getResources().getDrawableForDensity(R.drawable.logo, DisplayMetrics.DENSITY_MEDIUM)) + "</img>\n" +
                    "[L]\n" +
                    "[C]<u><font size='big'>ORDER N°045</font></u>\n" +
                    "[L]\n" +
                    "[C]================================\n" +
                    "[L]\n" +
                    "[L]<b>BEAUTIFUL SHIRT</b>[R]9.99e\n" +
                    "[L]  + Size : S\n" +
                    "[L]\n" +
                    "[L]<b>AWESOME HAT</b>[R]24.99e\n" +
                    "[L]  + Size : 57/58\n" +
                    "[L]\n" +
                    "[C]--------------------------------\n" +
                    "[R]TOTAL PRICE :[R]34.98e\n" +
                    "[R]TAX :[R]4.23e\n" +
                    "[L]\n" +
                    "[C]================================\n" +
                    "[L]\n" +
                    "[L]<font size='tall'>Customer :</font>\n" +
                    "[L]Raymond DUPONT\n" +
                    "[L]5 rue des girafes\n" +
                    "[L]31547 PERPETES\n" +
                    "[L]Tel : +33801201456\n" +
                    "[L]\n" +
                    "[C]<barcode type='ean13' height='10'>831254784551</barcode>\n" +
                    "[C]<qrcode size='20'>https://dantsu.com/</qrcode>"
                );
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}).start();

USB

USB permission

Be sure to have <uses-feature android:name="android.hardware.usb.host" /> in your AndroidManifest.xml.

You have to check the USB permission in your app like this :

private static final String ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION";
private final BroadcastReceiver usbReceiver = new BroadcastReceiver() {
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (MainActivity.ACTION_USB_PERMISSION.equals(action)) {
            synchronized (this) {
                UsbManager usbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
                UsbDevice usbDevice = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
                if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
                    if (usbManager != null && usbDevice != null) {
                        // YOUR PRINT CODE HERE
                    }
                }
            }
        }
    }
};

public void printUsb() {
    UsbConnection usbConnection = UsbPrintersConnections.selectFirstConnected(this);
    UsbManager usbManager = (UsbManager) this.getSystemService(Context.USB_SERVICE);
    if (usbConnection != null && usbManager != null) {
        PendingIntent permissionIntent = PendingIntent.getBroadcast(
            this,
            0,
            new Intent(MainActivity.ACTION_USB_PERMISSION),
            android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S ? PendingIntent.FLAG_MUTABLE : 0
        );
        IntentFilter filter = new IntentFilter(MainActivity.ACTION_USB_PERMISSION);
        registerReceiver(this.usbReceiver, filter);
        usbManager.requestPermission(usbConnection.getDevice(), permissionIntent);
    }
}

USB code example

The code below is an example to write in your activity :

EscPosPrinter printer = new EscPosPrinter(new UsbConnection(usbManager, usbDevice), 203, 48f, 32);
printer
    .printFormattedText(
        "[C]<img>" + PrinterTextParserImg.bitmapToHexadecimalString(printer, this.getApplicationContext().getResources().getDrawableForDensity(R.drawable.logo, DisplayMetrics.DENSITY_MEDIUM))+"</img>\n" +
        "[L]\n" +
        "[C]<u><font size='big'>ORDER N°045</font></u>\n" +
        "[L]\n" +
        "[C]================================\n" +
        "[L]\n" +
        "[L]<b>BEAUTIFUL SHIRT</b>[R]9.99e\n" +
        "[L]  + Size : S\n" +
        "[L]\n" +
        "[L]<b>AWESOME HAT</b>[R]24.99e\n" +
        "[L]  + Size : 57/58\n" +
        "[L]\n" +
        "[C]--------------------------------\n" +
        "[R]TOTAL PRICE :[R]34.98e\n" +
        "[R]TAX :[R]4.23e\n" +
        "[L]\n" +
        "[C]================================\n" +
        "[L]\n" +
        "[L]<font size='tall'>Customer :</font>\n" +
        "[L]Raymond DUPONT\n" +
        "[L]5 rue des girafes\n" +
        "[L]31547 PERPETES\n" +
        "[L]Tel : +33801201456\n" +
        "[L]\n" +
        "[C]<barcode type='ean13' height='10'>831254784551</barcode>\n" +
        "[C]<qrcode size='20'>https://dantsu.com/</qrcode>"
    );

Charset encoding

To change charset encoding of the printer, use EscPosCharsetEncoding class :

EscPosPrinter printer = new EscPosPrinter(deviceConnection, 203, 48f, 32, new EscPosCharsetEncoding("windows-1252", 16));

escPosCharsetId may change with printer model. Follow this link to find escPosCharsetId that works with many printers

Formatted text : syntax guide

New line

Use \n to create a new line of text.

Text alignment and column separation

Add an alignment tag on a same line of text implicitly create a new column.

Column alignment tags :

• [L] : left side alignment
• [C] : center alignment
• [R] : right side alignment

Example :

• [L]Some text : One column aligned to left
• [C]Some text : One column aligned to center
• [R]Some text : One column aligned to right
• [L]Some text[L]Some other text : Two columns aligned to left. Some other text starts in the center of the paper.
• [L]Some text[R]Some other text : Two columns, first aligned to left, second aligned to right. Some other text is printed at the right of paper.
• [L]Some[R]text[R]here : Three columns.
• [L][R]text[R]here : Three columns. The first is empty but it takes a third of the available space.

Font

Size

<font></font> tag allows you to change the font size and color. Default size is normal / black.

• <font size='normal'>Some text</font> : Normal size
• <font size='wide'>Some text</font> : Double width of medium size
• <font size='tall'>Some text</font> : Double height of medium size
• <font size='big'>Some text</font> : Double width and height of medium size
• <font size='big-2'>Some text</font> : 3 x width and height
• <font size='big-3'>Some text</font> : 4 x width and height
• <font size='big-4'>Some text</font> : 5 x width and height
• <font size='big-5'>Some text</font> : 6 x width and height

• <font size='big-6'>Some text</font> : 7 x width and height

• `Some te