Java SDK

The Java SDK supports native Android applications and connects to printers over Bluetooth Classic / SPP.

Installation

The SDK is published on the GitLab Maven Registry.

Add the repository

repositories {
    maven {
        url 'https://gitlab.com/api/v4/projects/35052067/packages/maven'
    }
}

repositories {
    maven("https://gitlab.com/api/v4/projects/35052067/packages/maven")
}

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/35052067/packages/maven</url>
  </repository>
</repositories>

Add dependencies

Choose the dependencies for the command languages you need:

dependencies {
    // CPCL Commands
    implementation 'com.printer.psdk:fat-generic-cpcl-bluetooth-classic:0.1.8-GA'

    // ESC Commands
    implementation 'com.printer.psdk:fat-generic-esc-bluetooth-classic:0.1.8-GA'

    // TSPL Commands
    implementation 'com.printer.psdk:fat-generic-tspl-bluetooth-classic:0.1.8-GA'
}

Quick start

1. Get a Bluetooth device

// Option 1: Find by Bluetooth scanning
BluetoothDevice device = getIntent().getParcelableExtra("device");

// Option 2: Using MAC Find by address
BluetoothDevice device = BluetoothAdapter.getDefaultAdapter()
    .getRemoteDevice(bluetoothAddress);

2. Establish a connection

Connection connection = ClassicBluetooth.getInstance()
    .createConnection(device, new ConnectListener() {
        @Override
        public void onConnectSuccess(ConnectedDevice connectedDevice) {
            // Connected
            Log.d("PSDK", "Connected: " + connectedDevice.getName());
        }

        @Override
        public void onConnectFailed(Exception e) {
            // Connection failed
            Log.e("PSDK", "Connection failed: " + e.getMessage());
        }

        @Override
        public void onDisconnect() {
            // Disconnected
            Log.d("PSDK", "Disconnected");
        }
    });

3. Listen for printer responses

DataListener.with(connectedDevice).listen(new ListenAction() {
    @Override
    public void action(byte[] bytes) {
        // Handle data returned by the printer
        String response = new String(bytes);
        Log.d("PSDK", "Printer response: " + response);
    }
});

ESC command usage

ESC commands are widely used by thermal receipt printers. See the ESC command reference for details.

Complete printing workflow

Recommended sequence:

Wake the printer
Enable the printer
Print the image
Position the paper (not needed for continuous paper)
End the print job

GenericESC esc = PrintUtil.getInstance().esc();
esc.wakeup();
esc.enable();
esc.image(EImage.builder()
        .image(new AndroidSourceImage(bitmap))
        // .compress(true) // Enable compression for printers that support it
        .build());
esc.position();
esc.stopJob();
safeWrite(esc);

Print commands

Wake the printer

esc.wakeup();

Enable the printer

esc.enable();

Print an image

esc.image(EImage.builder()
        .image(new AndroidSourceImage(bitmap))
        .build());

Position the paper

esc.position();

End the print job

esc.stopJob();

Configuration commands

Set shutdown timeout

// Set shutdown timeout (Units: Minutes, Integer values only)
esc.setShutdownTime(10);

Set print density

// Set print density (0:Low density 1:Medium density 2:High density)
esc.thickness(3);

Set paper type (A4)

esc.paperType(
    EPaperType.builder()
        .type(EPaperType.Type.CONTINUOUS_REEL_PAPER)
        .build()
);

Set paper type (Q series)

esc.paperTypeQ3(
    EGetPaperTypeQ3.builder()
        .type(EGetPaperTypeQ3.Type.GAP)
        .build()
);

Query commands

// Query printer information
esc.info();

// Query printer status
esc.state();

// Query battery level
esc.batteryVolume();

// Query Bluetooth name
esc.name();

// Query firmware version
esc.printerVersion();

// Query MAC Address
esc.mac();

// Query SN Number
esc.sn();

// Query printer model
esc.model();

Unsolicited reports

Device status reports

When an abnormal condition occurs, the printer sends a two-byte status message to the application.

Header	Status type	Meaning
0xFF	0x00	Printer normal
0xFF	0x01	Overheated
0xFF	0x02	Cover open
0xFF	0x04	Out of paper
0xFF	0x08	Low voltage

Paper type reports

The device sends a report when the detected paper does not match the paper type configured by the application:

Header	Status type	Meaning
0xFE	0x01	Fanfold black mark paper
0xFE	0x02	Continuous roll paper
0xFE	0x03	Adhesive gap labels

Print cancellation reports

Header	Status type	Meaning
0xFD	0x01	Start clearing the current page’s print job
0xFD	0x02	Current print job cleared

CPCL command usage

CPCL commands are used by portable label printers. See the CPCL command reference for details.

Basic printing

GenericCPCL cpcl = CPCL.generic(connectedDevice);
cpcl.page(new CPCLPage().width(576).height(400))
    .text(new CPCLText().x(50).y(50).content("商品标签"))
    .barcode(new CBar().x(50).y(150).content("1234567890"))
    .print(new CPrint())
    .write();

Complete label example

GenericCPCL cpcl = CPCL.generic(connectedDevice);
cpcl.page(new CPage().width(576).height(400).copies(1))
    // Set bold
    .bold(true)
    // Print title text
    .text(CText.builder()
        .font(Font.TSS24)
        .textX(50).textY(30)
        .content("商品标签")
        .build())
    .bold(false)
    // Draw a separator line
    .line(CLine.builder()
        .x1(30).y1(70)
        .x2(546).y2(70)
        .width(2)
        .build())
    // Product information
    .text(CText.builder()
        .font(Font.TSS24)
        .textX(30).textY(90)
        .content("名称: 有机苹果")
        .build())
    .text(CText.builder()
        .font(Font.TSS24)
        .textX(30).textY(130)
        .content("规格: 500g/袋")
        .build())
    .text(CText.builder()
        .font(Font.TSS24)
        .textX(30).textY(170)
        .content("价格: ￥25.90")
        .bold(true)
        .build())
    // 1D barcode
    .bar(CBar.builder()
        .x(80).y(220)
        .codeType(CodeType.CODE128)
        .height(50)
        .lineWidth(1)
        .content("6901234567890")
        .build())
    // QR code
    .qrcode(CQRCode.builder()
        .x(400).y(90)
        .width(5)
        .level(CorrectLevel.M)
        .content("https://example.com/product")
        .build())
    // Rectangular outline
    .box(CBox.builder()
        .x1(20).y1(20)
        .x2(556).y2(380)
        .width(2)
        .build())
    .print(new CPrint())
    .write();

Font options

Font enum	-dot matrix size	Description
Font.TSS16	16	16-dot matrix font
Font.TSS20	20	20-dot matrix font
Font.TSS24	24	24-dot matrix font (recommended)
Font.TSS28	28	28-dot matrix font
Font.TSS32	32	32-dot matrix font
Font.TSS24_MAX1	48	24-dot font at 2× scale
Font.TSS24_MAX2	72	24-dot font at 3× scale

Barcode type

Type enum	Description
CodeType.CODE128	Code 128 (recommended)
CodeType.CODE39	Code 39
CodeType.CODE93	Code 93
CodeType.EAN8	EAN-8
CodeType.EAN13	EAN-13
CodeType.UPCA	UPC-A
CodeType.UPCE	UPC-E
CodeType.CODABAR	Codabar
CodeType.I2OF5	Interleaved 2 of 5

Query commands

// Query printer status
cpcl.status().write();

// Query SN Number
cpcl.sn().write();

// Query printer model
cpcl.model().write();

// Query firmware version
cpcl.version().write();

// Query battery level
cpcl.batteryVolume().write();

TSPL command usage

TSPL commands are used by label and barcode printers. See the TSPL command reference for details.

Basic printing

GenericTSPL tspl = TSPL.generic(connectedDevice);
tspl.page(new TPage().width(60).height(40))
    .gap(true)
    .direction(TDirection.builder()
        .direction(Direction.UP)
        .mirror(Mirror.NO_MIRROR)
        .build())
    .cls()
    .text(TText.builder()
        .x(50).y(50)
        .font(Font.TSS24)
        .content("标签内容")
        .build())
    .print(1)
    .write();

Complete label example

GenericTSPL tspl = TSPL.generic(connectedDevice);
tspl.page(new TPage().width(60).height(40))
    .gap(true)
    .direction(TDirection.builder()
        .direction(Direction.UP)
        .mirror(Mirror.NO_MIRROR)
        .build())
    .density(8)
    .speed(4)
    .cls()
    // Title
    .text(TText.builder()
        .x(180).y(30)
        .font(Font.TSS24)
        .xmulti(2).ymulti(2)
        .content("商品标签")
        .build())
    // Separator line
    .bar(TBar.builder()
        .x(30).y(80)
        .width(420).height(2)
        .build())
    // Product information
    .text(TText.builder()
        .x(30).y(100)
        .font(Font.TSS24)
        .content("品名: 有机苹果")
        .build())
    .text(TText.builder()
        .x(30).y(140)
        .font(Font.TSS24)
        .content("规格: 500g/袋")
        .build())
    .text(TText.builder()
        .x(30).y(180)
        .font(Font.TSS24)
        .isBold(true)
        .content("价格: ￥25.90")
        .build())
    // 1D barcode
    .barcode(TBarCode.builder()
        .x(80).y(220)
        .codeType(CodeType.CODE_128)
        .height(60)
        .showType(ShowType.BELOW)
        .content("6901234567890")
        .build())
    // QR code
    .qrcode(TQRCode.builder()
        .x(380).y(90)
        .cellWidth(4)
        .correctLevel(CorrectLevel.M)
        .content("https://example.com")
        .build())
    // Border
    .box(TBox.builder()
        .x(20).y(20)
        .xEnd(460).yEnd(310)
        .lineWidth(2)
        .build())
    .print(1)
    .write();

Page setup

// Set page dimensions (Units: mm)
tspl.page(new TPage().width(60).height(40));

// Set gap paper
tspl.gap(true);

// Set black mark paper
tspl.bline();

// Set continuous paper
tspl.continuous();

// Set print direction
tspl.direction(TDirection.builder()
    .direction(Direction.UP)    // UP/DOWN
    .mirror(Mirror.NO_MIRROR)   // NO_MIRROR/MIRROR
    .build());

// Set density (0-15)
tspl.density(8);

// Set speed (1-6)
tspl.speed(4);

// Clear the buffer
tspl.cls();

Drawing graphics

// Filled rectangle
tspl.bar(TBar.builder()
    .x(50).y(100)
    .width(200).height(2)
    .build());

// Rectangular outline
tspl.box(TBox.builder()
    .x(50).y(50)
    .xEnd(300).yEnd(200)
    .lineWidth(2)
    .build());

// Diagonal line
tspl.line(TLine.builder()
    .x(50).y(50)
    .xEnd(300).yEnd(200)
    .lineWidth(2)
    .build());

// Draw a circle
tspl.circle(TCircle.builder()
    .x(200).y(200)
    .diameter(100)
    .lineWidth(2)
    .build());

// Ellipse
tspl.ellipse(TEllipse.builder()
    .x(200).y(200)
    .width(150).height(80)
    .lineWidth(2)
    .build());

// Inverted area
tspl.reverse(TReverse.builder()
    .x(50).y(50)
    .width(200).height(100)
    .build());

Query commands

// Query printer status
tspl.state().write();

// Query SN Number
tspl.sn().write();

// Query battery level
tspl.batteryVolume().write();

// Query firmware version
tspl.version().write();

Configuration commands

// Set shutdown timeout (Minutes)
tspl.setOffTime(30);

// Get shutdown timeout
tspl.getOffTime();

// Set thermal transfer mode
tspl.ribbon(true);

// Set direct thermal mode
tspl.ribbon(false);

// Enable cutter
tspl.cut(true);

// Enable tear-off
tspl.tear(true);

// Enable peel-off
tspl.peel(true);

// Learn paper
tspl.detect();

// Print a self-test page
tspl.selfTest();

Font options

Font enum	Font name	Description
Font.TSS12	TSS12.BF2	12-dot matrix
Font.TSS16	TSS16.BF2	16-dot matrix
Font.TSS20	TSS20.BF2	20-dot matrix
Font.TSS24	TSS24.BF2	24-dot matrix (recommended)
Font.TSS28	TSS28.BF2	28-dot matrix
Font.TSS32	TSS32.BF2	32-dot matrix

Barcode type

Type enum	Description
CodeType.CODE_128	Code 128 (recommended)
CodeType.CODE_39	Code 39
CodeType.CODE_93	Code 93
CodeType.CODE_ITF	ITF
CodeType.CODE_EAN8	EAN-8
CodeType.CODE_EAN13	EAN-13
CodeType.CODE_UPCA	UPC-A
CodeType.CODE_UPCE	UPC-E
CodeType.CODE_CODABAR	Codabar

Permission configuration

Add the following to AndroidManifest.xml:

<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" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Example projects

For complete examples, see: