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
• 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:2.0.10'
}

Bluetooth

Bluetooth permission

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

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

if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.BLUETOOTH}, MainActivity.PERMISSION_BLUETOOTH);
} 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'>http://www.developpeur-web.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 AndroidMenifest.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), 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'>http://www.developpeur-web.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 AndroidMenifest.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), 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'>http://www.developpeur-web.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 color='black'>Some text</font> : black text - white background

• <font color='bg-black'>Some text</font> : white text - black background

• <font color='red'>Some text</font> : red text - white background (Not working on all printer)

• <font color='bg-red'>Some text</font> : white text - red background (Not working on all printer)

Bold

<b></b> tag allows you to change the font weight.

• <b>Some text</b>

Underline

<u></u> tag allows you to underline the text.

• <u>Some text</u> text underlined
• <u type='double'>Some text</u> text double-strike (Not working on all printer)

Image

<img></img> tag allows you to print image. Inside the tag you need to write a hexadecimal string of an image.

Use PrinterTextParserImg.bitmapToHexadecimalString to convert Drawable, BitmapDrawable or Bitmap to hexadecimal string.

• <img>hexadecimal string of an image</img>

⚠ WARNING ⚠ : This tag has several constraints :

• A line that contains <img></img> can have only one alignment tag and it must be at the beginning of the line.
• <img> must be directly preceded by nothing or an alignment tag ([L][C][R]).
• </img> must be directly followed by a new line \n.
• You can't write text on a line that contains <img></img>.

Barcode

<barcode></barcode> tag allows you to print a barcode. Inside the tag you need to write the code number to print.

• <barcode>451278452159</barcode> : (12 numbers)
  Prints a EAN13 barcode (height: 10mm, width: ~70% printer width, text: displayed below).
• <barcode type='ean8'>4512784</barcode> : (7 numbers)
  Prints a EAN8 barcode (height: 10mm, width: ~70% printer width, text: displayed below).
• <barcode type='upca' height='20'>4512784521</barcode> : (11 numbers)
  Prints a UPC-A barcode (height: 20mm, width: ~70% printer width, text: displayed below).
• <barcode type='upce' height='25' width='50' text='none'>512789</barcode> : (6 numbers)
  Prints a UPC-E barcode (height: 25mm, width: ~50mm, text: hidden).
• <barcode type='128' width='40' text='above'>DantSu</barcode> : (string)
  Prints a barcode 128 (height: 10mm, width: ~40mm, text: displayed above).

⚠ WARNING ⚠ : This tag has several constraints :

• A line that contains <barcode></barcode> can have only one alignment tag and it must be at the beginning of the line.
• <barcode> must be directly preceded by nothing or an alignment tag ([L][C][R]).
• </barcode> must be directly followed by a new line \n.
• You can't write text on a line that contains <barcode></barcode>.

QR Code

<qrcode></qrcode> tag allows you to print a QR code. Inside the tag you need to write the QR code data.

• <qrcode>http://www.developpeur-web.dantsu.com/</qrcode> : Prints a QR code with a width and height of 20 millimeters.
• <qrcode size='25'>123456789</qrcode> : Prints a QR code with a width and height of 25 millimeters.

⚠ WARNING ⚠ : This tag has several constraints :

• A line that contains <qrcode></qrcode> can have only one alignment tag and it must be at the beginning of the line.
• <qrcode> must be directly preceded by nothing or an alignment tag ([L][C][R]).
• </qrcode> must be directly followed by a new line \n.
• You can't write text on a line that contains <qrcode></qrcode>.

Class list

Class : com.dantsu.escposprinter.connection.bluetooth.BluetoothPrintersConnections

Static Method : selectFirstPaired()

Easy way to get the first bluetooth printer paired / connected.

• return BluetoothConnection

Method : getList()

Get a list of bluetooth printers.

• return BluetoothConnection[]

Class : com.dantsu.escposprinter.connection.usb.UsbPrintersConnections

Static Method : selectFirstConnected()

Easy way to get the first USB printer connected.

• return UsbConnection

Method : getList()

Get a list of USB printers.

• return UsbConnection[]

Class : com.dantsu.escposprinter.EscPosPrinter

Constructor : EscPosPrinter(DeviceConnection printer, int printerDpi, float printingWidthMM, int nbrCharactersPerLine [, EscPosCharsetEncoding charsetEncoding])

• param DeviceConnection printer : Instance of a connected printer
• param int printerDpi : DPI of the connected printer
• param float printerWidthMM : Printing width in millimeters
• param int printerNbrCharactersPerLine : The maximum number of medium sized characters that can be printed on a line.
• param EscPosCharsetEncoding charsetEncoding (optional) : Set the charset encoding.

Method : disconnectPrinter()

Close the connection with the printer.

• return Printer : Fluent interface

Method : getNbrCharactersPerLine()

Get the maximum number of characters that can be printed on a line.

• return int

Method : getPrinterWidthMM()

Get the printing width in millimeters

• return float

Method : getPrinterDpi()

Get the printer DPI

• return int

Method : getPrinterWidthPx()

Get the printing width in dot

• return int

Method : getPrinterCharSizeWidthPx()

Get the number of dot that a printed character contain

• return int

Method : mmToPx(float mmSize)

Convert the mmSize variable from millimeters to dot.

• param float mmSize : Distance in millimeters to be converted
• return int : Dot size of mmSize.

Method : printFormattedText(String text)

Print a formatted text and feed paper (20 millimeters). Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• return Printer : Fluent interface

Method : printFormattedTextAndCut(String text)

Print a formatted text, feed paper (20 millimeters) and cut the paper. Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• return Printer : Fluent interface

Method : printFormattedText(String text, float mmFeedPaper)

Print a formatted text and feed paper (mmFeedPaper millimeters). Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param float mmFeedPaper : Millimeter distance feed paper at the end.
• return Printer : Fluent interface

Method : printFormattedTextAndCut(String text, float mmFeedPaper)

Print a formatted text, feed paper (mmFeedPaper millimeters) and cut the paper. Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param float mmFeedPaper : Millimeter distance feed paper at the end.
• return Printer : Fluent interface

Method : printFormattedTextAndOpenCashBox(String text, float mmFeedPaper)

Print a formatted text, feed paper (mmFeedPaper millimeters), cut the paper and open the cash box. Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param float mmFeedPaper : Millimeter distance feed paper at the end.
• return Printer : Fluent interface

Method : printFormattedText(String text, int dotsFeedPaper)

Print a formatted text and feed paper (dotsFeedPaper dots). Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param int dotsFeedPaper : Distance feed paper at the end.
• return Printer : Fluent interface

Method : printFormattedTextAndCut(String text, int dotsFeedPaper)

Print a formatted text, feed paper (dotsFeedPaper dots) and cut the paper. Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param int dotsFeedPaper : Distance feed paper at the end.
• return Printer : Fluent interface

Method : printFormattedTextAndOpenCashBox(String text, int dotsFeedPaper)

Print a formatted text, feed paper (dotsFeedPaper dots), cut the paper and open the cash box. Read the "Formatted Text : Syntax guide" section for more information about text formatting options.

• param String text : Formatted text to be printed.
• param int dotsFeedPaper : Distance feed paper at the end.
• return Printer : Fluent interface

Method : bitmapToBytes(Bitmap bitmap)

Convert Bitmap object to ESC/POS image.

• param Bitmap bitmap : Instance of Bitmap
• return byte[] : Bytes contain the image in ESC/POS command

Class : com.dantsu.escposprinter.textparser.PrinterTextParserImg

Static Method : bitmapToHexadecimalString(Printer printer, Drawable drawable)

Convert Drawable instance to a hexadecimal string of the image data.

• param Printer printer : A Printer instance that will print the image.
• param Drawable drawable : Drawable instance to be converted.
• return String : A hexadecimal string of the image data. Empty string if Drawable cannot be cast to BitmapDrawable.

Static Method : bitmapToHexadecimalString(Printer printer, BitmapDrawable bitmapDrawable)

Convert BitmapDrawable instance to a hexadecimal string of the image data.

• param Printer printer : A Printer instance that will print the image.
• param BitmapDrawable bitmapDrawable : BitmapDrawable instance to be converted.
• return String : A hexadecimal string of the image data.

Static Method : bitmapToHexadecimalString(Printer printer, Bitmap bitmap)

Convert Bitmap instance to a hexadecimal string of the image data.

• param Printer printer : A Printer instance that will print the image.
• param Bitmap bitmap : Bitmap instance to be converted.
• return String : A hexadecimal string of the image data.

Static Method : bytesToHexadecimalString(byte[] bytes)

Convert byte array to a hexadecimal string of the image data.

• param byte[] bytes : Bytes contain the image in ESC/POS command.
• return String : A hexadecimal string of the image data.

Static Method : hexadecimalStringToBytes(String hexString)

Convert hexadecimal string of the image data to bytes ESC/POS command.

• param String hexString : Hexadecimal string of the image data.
• return byte[] : Bytes contain the image in ESC/POS command.

Class : com.dantsu.escposprinter.EscPosCharsetEncoding

Constructor : EscPosCharsetEncoding(String charsetName, int escPosCharsetId)

• param charsetName Name of charset encoding (Ex: ISO-8859-1)
• param escPosCharsetId Id of charset encoding for your printer (Ex: 6)

Contributing

Please fork this repository and contribute back using pull requests.

Any contributions, large or small, major features, bug fixes, are welcomed and appreciated but will be thoroughly reviewed