This document is generated by the Tongyi Lingma
简体中文在这里
This repository will no longer maintain test cases starting from 2024-08-01, only the functionality of the Library will be maintained.
For documentation or using the demo app, please refer to: UniversalPrinter
As of 2024-10-22: In most domestic scenarios, using Gprinter's SDK can meet requirements. Therefore, starting from version 1.3.0, this library has been modularized, and dependencies for other brands' SDKs can be added as needed.
| Package Name | Description | Dependency Method |
|---|---|---|
| GPrinter | Gprinter | com.github.Yiwei099.PrintSupport:GPrinter:$releaseVersion |
| Epson | Epson | com.github.Yiwei099.PrintSupport:Epson:$releaseVersion |
| Bixolon | Bixolon | com.github.Yiwei099.PrintSupport:Bixolon:$releaseVersion |
| PrintSupport | Total Package (Gprinter, Epson, Bixolon) | com.github.Yiwei099.PrintSupport:$releaseVersion |
| libcommon | Base Package (Required) | com.github.Yiwei099.PrintSupport:libcommon:$releaseVersion |
① Integrates multiple brand printer SDKs: Gprinter, Epson, Bixolon, StarX (to be integrated)
② Supported printer brands that have been tested: Gprinter, Epson, Bixolon, Xprinter, Element
③ Supports LAN, USB, Bluetooth communication (specific conditions depend on the printer and the used SDK strategy)
④ Developers only need to focus on print data, not the printing process, reducing the cost of integrating various SDKs
⑤ Automatically establishes connections when printing and destroys them after completion, reducing channel occupancy and ensuring stability
⑥ Built-in task timer periodically polls the task queue to ensure each task is executed, preventing task loss
⑦ Only supports Esc (receipt) and Tsc (label) instructions; other types like dot matrix and A4 printing are not considered
⑧ (New) Gprinter SDK supports automatic verification of printer commands
⑨ Due to limited printers, users can directly pull the source code for debugging
⑩ SDK priority recommendation: Gprinter > Epson > Bixolon > StarX
⑪ Image printing yields better results: DrawingSupport
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
implementation 'com.github.Yiwei099:PrintSupport:$releaseVersion'
Reference: Gprinter Official Website
Detailed test cases can be found in GPrinterActivity.kt
Debugging Status: Esc✅, Tsc✅, LAN✅, USB✅, Bluetooth✅, Esc Image✅, Esc Command✅, Tsc Image✅, Tsc Command✖️
This SDK can communicate with most brands of printers such as Gprinter, Xprinter, Epson, Bixolon, Element
//LAN Communication
val key = "192.168.100.150"
val printer = EscNetGPrinter(context, netKey) // Print Esc
val printer = TscNetGPrinter(context,netKey) // Print Tsc
//USB Communication (SerialNumber is optional)
val usbKey = "vendorId+productId+SerialNumber"
val printer = EscUsbGPrinter(context,vendorId,productId,serialNumber) // Print Esc
val printer = TscUsbGPrinter(context,vendorId,productId,serialNumber) // Print Tsc
//Bluetooth Communication
val macAddress = "66:22:E2:4C:CB:DD"
val printer = EscBtGPrinter(context,macAddress) // Print Esc
val printer = TscBtGPrinter(context,macAddress) // Print Tsc
//Unknown Command Type
//Custom Printer Verification Command
val command :ByteArray = ByteArray()
val unknowBtPrinter = UnKnowBtGPrinter(context,address,command){
//...Parse the returned data from the printer, determine the command type, and return it
return when(data){
...-> Command.Esc
...-> Command.Tsc
else-> null
}
}
//Print as an image
//From version 1.2.0 or 1.2.0-Alpha, if your label content height is not adaptive, specify the label height
val mission = GraphicMission(
bitmapArray,
bitmapHeight:Int = 30,//Label height
bitmapWidth:Int = 40,//Label width
selfAdaptionHeight:Boolean = false,//Fixed height
)
//Print using SDK commands
val mission = CommandMission(escCommand)
//Call addMission
printer.addMission(mission)
printer.onDestroy()
Reference: Epson Official Website
Detailed test cases can be found in EpsonPrinterActivity.kt
Debugging Status: Esc✅, Tsc✖️, LAN✅, USB✅, Bluetooth✖️, Esc Image✅, Esc Command✅ (partial), Tsc Image✅, Tsc Command✖️
Can only communicate with its own brand of printers
//Communication method: LAN/USB/Bluetooth
val interface = Net/Usb/BlueTooth
//Communication address: LAN IP/USB address/Bluetooth address
val target = "192.168.0.1"
//Create printer, optionally specify the Epson printer model
val printer = EpsonPrinter(context,interface,target)
//Print as an image
//From version 1.2.0 or 1.2.0-Alpha, if your label content height is not adaptive, specify the label height
val mission = GraphicMission(
bitmapArray,
bitmapHeight:Int = 30,//Label height
bitmapWidth:Int = 40,//Label width
selfAdaptionHeight:Boolean = false,//Fixed height
)
//Print using SDK commands
val mission = EpsonMission(
mutableListOf<BaseEpsonMissionParam>().apply {
add(CommandMissionParam(getOpenBoxCommandByByteArray()))
}
)
//Call addMission
printer.addMission(mission)
printer.onDestroy()
//Discovery parameters (LAN/Bluetooth/USB), (printer/scanner/input device)
val option = FilterOption()
//Listener for results (returns a single device)
val listener = DiscoveryListener()
//Start discovery
Discovery.start(mContext,option,listener)
//Stop discovery
Discovery.stop()
Reference: Bixolon Official Website
Detailed test cases can be found in BixolonPrinterActivity.kt
Debugging Status: Tsc✅, Esc✖️, LAN✅, USB✖️, Bluetooth✖️, Esc Image✖️, Esc Command✖️, Tsc Image✅, Tsc Command✖️
//Recommended to call during Application initialization
BixolonUtils.getInstance().initLibrary()
//LAN Communication
val key = "192.168.100.155"
val printer = BixolonNetLabelPrinter(mContext)
//Print as an image
//From version 1.2.0 or 1.2.0-Alpha, if your label content height is not adaptive, specify the label height
val mission = GraphicMission(
bitmapArray,
bitmapHeight:Int = 30,//Label height
bitmapWidth:Int = 40,//Label width
selfAdaptionHeight:Boolean = false,//Fixed height
)
printer.addMission(mission)
printer.onDestroy()
//Any existing or non-existing IP address
val ip = "192.168.3.12"
//Create any Bixolon printer
val printer = BixolonNetLabelPrinter(mContext,ip).apply{
setOnFindPrinterCallBack {
it.forEach {content->
//Returned result structure: macAddress + address + port
}
}
}
//Start discovery
printer.startFindPrinter()
Detailed test cases can be found in NativeUsbActivity.kt Compared to Gprinter SDK's USB printing, this method only differs in connection and sending processes; some devices have USB communication issues, so NativeUsb was developed. It does not rely on any SDK for connection and sending but uses Gprinter commands.
//Instantiate printer
val printer = NativeUsbPrinter(
mContext: Context, //Context object
usbDevice: UsbDevice, //USB device instance
commandType:Command, //Command type: ESC/TSC
bufferSize: Int = 16384, //Buffer size
timeOut: Int = 3000, //Timeout
density: DENSITY = LabelCommand.DENSITY.DNESITY1, //Printing density
adjustX: Int = 0, //Left offset
adjustY: Int = 0, //Top offset
)
//Print as an image
//From version 1.2.0 or 1.2.0-Alpha, if your label content height is not adaptive, specify the label height
val mission = GraphicMission(
bitmapArray,
bitmapHeight:Int = 30,//Label height
bitmapWidth:Int = 40,//Label width
selfAdaptionHeight:Boolean = false,//Fixed height
)
//Print using SDK commands
val mission = CommandMission(escCommand)
//Call addMission
printer.addMission(mission)
printer.onDestroy()
The byte command for opening the cash drawer comes from the Gprinter SDK and may not apply to all printers. If the command is invalid, use a tested command array and send it using this library.
//Open cash drawer for Gprinter
printer.addMission(GPrinterMission(GPrinterMission.getOpenBoxCommand()))
//Open cash drawer for other printers, e.g., Epson
printer.addMission(
EpsonMission(
mutableListOf<BaseEpsonMissionParam>().apply {
add(CommandMissionParam(getOpenBoxCommandByByteArray()))
}
)
)
//Byte command for opening cash drawer in Gprinter SDK
private fun getOpenBoxCommandByByteArray(): ByteArray {
return SDKUtils.convertVectorByteToBytes(GPrinterMission.getOpenBoxCommand())
}
① Adjust the width of the generated image to fit within the effective printing range of the label printer
② Refer to the image generation tool: DrawingSupport
③ Common receipt paper sizes are 58mm and 80mm, so the maximum width for images generated by DrawingSupport is 48 * 8 = 384 and 72 * 8 = 576
④ Common label paper sizes are 40 * 30, 40 * 60, 40 * 80; for a 40 * 60 size, width = 40 * 8 = 320, height = 60 * 8 = 480; thus, the image size generated by DrawingSupport should be 320 * 480
Ensure the SDK's JNI is initialized
//Recommended to call during Application initialization
BixolonUtils.getInstance().initLibrary()
① Check if permission has been granted for the current USB device; if not, suggest using a broadcast receiver in the Activity lifecycle to request permission when a USB device is connected (even if the USB connection is unstable, it can automatically reconnect)
② The Gprinter SDK will also automatically request permission, but only when initiating a connection, which might cause missed prints if no connection is initiated
③ Some devices allow setting a USB whitelist, eliminating the need for permission requests
override fun onUsbAttached(intent: Intent) {
intent.getParcelableExtra<UsbDevice>(UsbManager.EXTRA_DEVICE)?.let {usbDevice->
val b = usbManager.hasPermission(usbDevice)
val usbKey = "${usbDevice.vendorId}-${usbDevice.productId}"
if (!b){
val mPermissionIntent = PendingIntent.getBroadcast(this,0,Intent(UsbBroadcastReceiver.ACTION_USB_PERMISSION),0)
usbManager.requestPermission(it, mPermissionIntent)
//No further action required after authorization; the printer will automatically execute the print job
}
}
| Error Code | Explanation |
|---|---|
| 0 | General success |
| -1 | General exception (unknown reason) |
| -2 | Connection failed |
| -3 | Connection error |
| -4 | Print failed |
| -5 | Print error |
| -6 | Disconnection error |
| -7 | Automatic recovery error occurred |
| -8 | Cover open error occurred (cover not closed) |
| -9 | Auto cutter error occurred (paper cut error) |
| -10 | Mechanical error occurred (printer mechanical error) |
| -11 | No paper detected in the roll paper end detector |
| -12 | Unrecoverable error occurred |
| -13 | Syntax error in the requested document |
| -14 | Printer specified by the device ID does not exist |
