getInstance
Obtain the singleton. First call must pass a Context.
static UPrinterManager getInstance(Context context)Parameters
| Name | Type | Description |
|---|---|---|
| context | Context | Prefer Application Context. |
Returns
UPrinterManager singleton.
Overview
K388 Printer SDK is the unified Android entry for Urovo K388 / K388Pro printers. The public class is com.urovo.printer.UPrinterManager.
Version history
- 2.4.3: Connection/register rigor (must
connectbefore persistent registers & local RFID); BLE Notify CCCD + write-busy fix; shared status/register frame helpers + unit tests;rfidWriteResult(int); all publicPrinterException/IllegalArgumentExceptionmessages are English; JAR:UK388PrintLibrary_v2.4.3.jar. - 2.4.2: Renamed page-builder
printByte()tobuildPageBytes()(image jobs; does not send). JAR:UK388PrintLibrary_v2.4.2.jar. - 2.4.1: Renamed page-builder
print()tobuildCpcl()so it is not confused withprintByText(send). JAR:UK388PrintLibrary_v2.4.1.jar. - 2.4.0: Unified Local + BLE entry. API docs grouped by shared / BLE / local / persistent registers / CPCL helpers. Page-builder CPCL fixes (
BAR-SENSE-LEFT, QR rotate,FORM/PRINTtail, barcode width). Persistent register getters (getPrintDarkness/getPrintMode/getMultiPrintDelay/getRewindPrint/getAutoReprint), plussetAutoReprintandprintSelfTest. JAR:UK388PrintLibrary_v2.4.0.jar(aligned withgetSDKVersion()).
Capabilities
- Local printer via
connect() - BLE printer via
connect(mac) - CPCL helper APIs: wrappers for common CPCL commands (page setup / draw / print builders)
printByText: send a full print job string; supports CPCL / ZPL / ESC / TSPL- Persistent register settings
- Local-only RFID
Typical scenarios
- On-device label printing (local)
- External BLE label printer + optional scan-to-print
- Firmware
.updupgrade
Requirements
| Item | Requirement |
|---|---|
| Platform | Android |
| Min version | API 24 (Android 7.0)+ |
| Language | Java |
| Dependency | UK388PrintLibrary_v2.4.3.jar (or project AAR/module) |
| Auth | None |
Integration
Add dependency
gradle
implementation files('libs/UK388PrintLibrary_v2.4.3.jar')Permissions
- Local: device print service / LocalSocket (device-specific)
- BLE (Android 12+):
BLUETOOTH_CONNECT(and location/scan as required by target SDK)
Initialize
java
UPrinterManager pm = UPrinterManager.getInstance(context.getApplicationContext());No auth token is required.
Quick Start
java
UPrinterManager pm = UPrinterManager.getInstance(getApplicationContext());
pm.connect(); // or pm.connect("AA:BB:CC:DD:EE:FF") for BLE
pm.flushBuffer();
pm.pageSetup(384, 240, 0, 1);
pm.drawText(16, 16, "K388Pro", 2, 0, 0, false, false);
String cpcl = pm.buildCpcl(); // sense/feed from pageSetup gap
boolean ok = pm.printByText(cpcl);BLE: call setConnectionListener / setScanListener before connect(mac) if needed.
You can also skip the CPCL helpers and send a complete job directly:
java
// Full command text: CPCL / ZPL / ESC / TSPL
boolean ok = pm.printByText(fullCommandText);API Reference
APIs are grouped as: Common, BLE-only, Local-only, Persistent registers, CPCL helpers (wrappers for common CPCL commands), then Types.
The CPCL helper methods encapsulate frequently used CPCL commands for building pages. Customers who already have complete print scripts can call printByText directly with full CPCL / ZPL / ESC / TSPL text.
connect
connect() opens the local printer. connect(String) opens BLE by MAC. Modes are mutually exclusive — disconnect before switching.
void connect() throws PrinterException
void connect(String macAddress) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| macAddress | String | BLE MAC, e.g. AA:BB:CC:DD:EE:FF (BLE overload). |
Errors
PrinterException if already connected, upgrading, or open/connect fails.
disconnect
Disconnect the current printer and reset mode to NONE.
void disconnect()isConnected
Whether a printer is connected (local or BLE).
boolean isConnected()Returns
true if connected.
getConnectionMode
Current device channel type.
ConnectionMode getConnectionMode()Returns
NONE / LOCAL / BLE.
getSDKVersion
SDK version string (Local+BLE build).
String getSDKVersion()Returns
Version string.
flushBuffer
Flush the send buffer on the active channel.
void flushBuffer()printByData
Send raw bytes on the active channel. For image jobs (usually with buildPageBytes).
boolean printByData(byte[] data)Parameters
| Name | Type | Description |
|---|---|---|
| data | byte[] | Page bytes from buildPageBytes. |
Returns
true if write accepted; false if disconnected, upgrading, or null data.
printByGzipData
GZIP-frame then send. Optional for large images; do not use for normal text pages.
boolean printByGzipData(byte[] data)Parameters
| Name | Type | Description |
|---|---|---|
| data | byte[] | Raw page bytes (pre-GZIP), usually from buildPageBytes. |
Returns
Same semantics as printByData.
printByText
Send a full print command string as GBK. Accepts complete jobs in CPCL / ZPL / ESC / TSPL. You may pass the string from buildCpcl(), or your own full command text.
boolean printByText(String text)Parameters
| Name | Type | Description |
|---|---|---|
| text | String | Full print command text (CPCL / ZPL / ESC / TSPL), or CPCL from buildCpcl(). |
Returns
true if write accepted; false if disconnected, upgrading, null, or encode failure.
setPrintTime
Print copy count (default 1).
void setPrintTime(int time)Parameters
| Name | Type | Description |
|---|---|---|
| time | int | Print copies / quantity in page header (≥ 1; default 1). |
buildCpcl
Build a CPCL command string for non-image jobs (does not send). Sense/feed comes from pageSetup(..., gap). Use with printByText.
String buildCpcl()Returns
CPCL command string.
buildPageBytes
Build page bytes for image jobs (does not send). Sense/feed comes from pageSetup(..., gap). Use with printByData / printByGzipData.
byte[] buildPageBytes()Returns
Page bytes.
getPrintPrintStr
Return the current built CPCL string buffer (does not run end-of-page logic).
String getPrintPrintStr()Returns
Current CPCL text in the buffer.
version
Page-builder engine version string.
String version()Returns
Engine version.
getPrinterStatus
Query printer status on the active channel.
PrinterStatus getPrinterStatus()Returns
DISCONNECTED if not connected; UNKNOWN_ERROR while upgrading or on bad reply; COMMUNICATION_ERROR if BLE write fails.
getPrinterStatusDescription
Human-readable status text.
String getPrinterStatusDescription()Returns
Status description.
isFirmwareUpgrading
Whether a firmware upgrade is in progress.
boolean isFirmwareUpgrading()Returns
true while upgrading.
getFirmwareVersion
Read firmware version (LOCAL or BLE; must be connected).
String getFirmwareVersion()Returns
Version string, or null on failure / disconnected / upgrading.
upgradeFirmware
Blocking .upd upgrade. Disconnects afterward and waits for reboot (~25 s). Reconnect afterward.
Parameters
| Name | Type | Description |
|---|---|---|
| firmwareFilePath | String | Absolute path to .upd. |
| listener | FirmwareUpgradeListener | Optional; may be null. |
Errors
PrinterException / IllegalArgumentException on invalid file, bad status, or write timeout. Run off the UI thread.
Example
java
pm.upgradeFirmware("/sdcard/firmware.upd", new UPrinterManager.FirmwareUpgradeListener() {
public void onProgress(int sentBytes, int totalBytes) { }
public void onCompleted() { }
});setConnectionListener
Register BLE connection callbacks. Unexpected GATT drops reset internal connect state before this callback. BLE-only.
void setConnectionListener(BleConnectionListener listener)Parameters
| Name | Type | Description |
|---|---|---|
| listener | BleConnectionListener | Pass null to clear. |
setScanListener
Register BLE scan-head notifications (main thread). BLE-only.
void setScanListener(BleScanListener listener)Parameters
| Name | Type | Description |
|---|---|---|
| listener | BleScanListener | Pass null to clear. |
getConnectedAddress
Connected BLE device MAC. Null if not BLE / not connected.
String getConnectedAddress()Returns
MAC or null.
setPrinterStatusListener
Local connection status listener. For BLE use setConnectionListener.
void setPrinterStatusListener(PrinterStatusListener listener)Parameters
| Name | Type | Description |
|---|---|---|
| listener | PrinterStatusListener | Local connect / disconnect / status callbacks. |
rfidWrite
Write RFID memory. Local-only.
boolean rfidWrite(int bank, int password, int offset, byte[] data, int len)Parameters
| Name | Type | Description |
|---|---|---|
| bank | int | Memory bank. |
| password | int | Access password. |
| offset | int | Byte offset (even). |
| data | byte[] | Payload. |
| len | int | Length (even). |
Returns
true on success; false on BLE / upgrading / not connected / failure.
rfidWriteResult
Write RFID and return an int result code (preferred). Local-only; must be connected.
int rfidWriteResult(int bank, int password, int offset, byte[] data, int len)Parameters
| Name | Type | Description |
|---|---|---|
| bank | int | Memory bank. |
| password | int | Access password. |
| offset | int | Byte offset (even). |
| data | byte[] | Payload. |
| len | int | Length (even). |
Returns
0 / RFID_RESULT_OK success; >0 device error; -1 timeout; -2 bad header; -3 bad params; -4 upgrading; -5 BLE / not on local channel.
rfidWriteWithResp
Write RFID and return a result code string (compat). Prefer rfidWriteResult.
String rfidWriteWithResp(int bank, int password, int offset, byte[] data, int len)Parameters
| Name | Type | Description |
|---|---|---|
| bank | int | Memory bank. |
| password | int | Access password. |
| offset | int | Byte offset (even). |
| data | byte[] | Payload. |
| len | int | Length (even). |
Returns
Decimal string of rfidWriteResult (e.g. "0", "-5").
rfidRead
Read RFID memory into data. Local-only.
boolean rfidRead(int bank, int password, int offset, byte[] data, int len)Parameters
| Name | Type | Description |
|---|---|---|
| bank | int | Memory bank. |
| password | int | Access password. |
| offset | int | Byte offset. |
| data | byte[] | Output buffer. |
| len | int | Length. |
Returns
true on success; false on BLE / upgrading / not connected / failure.
setReadPower
Set RFID read power (0–28). Local-only.
boolean setReadPower(int power)Parameters
| Name | Type | Description |
|---|---|---|
| power | int | 0–28. |
Returns
true on success.
Errors
IllegalArgumentException if outside 0–28.
setWritePower
Set RFID write power (0–28). Local-only.
boolean setWritePower(int power)Parameters
| Name | Type | Description |
|---|---|---|
| power | int | 0–28. |
Returns
true on success.
Errors
IllegalArgumentException if outside 0–28.
getReadPower
Read RFID read power. Local-only.
int getReadPower()Returns
Power value; 32767 if BLE / upgrading / unavailable.
getWritePower
Read RFID write power. Local-only.
int getWritePower()Returns
Power value; 32767 if BLE / upgrading / unavailable.
getCurLabelPower
Current label RFID power. Local-only.
int getCurLabelPower()Returns
Power value; 32767 if BLE / upgrading / unavailable.
getRfidCardState
Whether an RFID label is present. Local-only.
boolean getRfidCardState()Returns
true if present; false on BLE / upgrading / absent.
setPrintDarkness
Write register PRINT_DARKNESS and save (persistent).
synchronized boolean setPrintDarkness(int darkness) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| darkness | int | Darkness level for PRINT_DARKNESS: -5 to 5 (inclusive). |
Returns
true on success.
Errors
IllegalArgumentException if outside -5…5; PrinterException if disconnected, upgrading, or I/O fails.
setPrintMode
Write register PRINT_MODE: 0 normal, 1 high speed, 2 low speed.
synchronized boolean setPrintMode(int mode) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| mode | int | 0–2. |
Returns
true on success.
Errors
IllegalArgumentException if outside 0–2; PrinterException if disconnected or I/O fails.
setMultiPrintDelay
Write register PAGE_PRINT_WAIT_DELAY (milliseconds).
synchronized boolean setMultiPrintDelay(int delayMs) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| delayMs | int | ≥ 0. |
Returns
true on success.
Errors
IllegalArgumentException if < 0; PrinterException if disconnected or I/O fails.
setRewindPrint
Write register LABEL_REWIND_PRINT and reset rewind mode.
synchronized boolean setRewindPrint(boolean enable) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| enable | boolean | Enable rewind print. |
Returns
true on success.
Errors
PrinterException if disconnected or I/O fails.
getPrintDarkness
Read register PRINT_DARKNESS. Throws if read fails.
synchronized int getPrintDarkness() throws PrinterExceptionReturns
Darkness value (same scale as setPrintDarkness, typically -5 to 5).
Errors
PrinterException if disconnected or read fails.
getPrintMode
Read register PRINT_MODE (0 normal / 1 high / 2 low).
synchronized int getPrintMode() throws PrinterExceptionReturns
Mode value.
Errors
PrinterException if disconnected or read fails.
getMultiPrintDelay
Read register PAGE_PRINT_WAIT_DELAY (milliseconds).
synchronized int getMultiPrintDelay() throws PrinterExceptionReturns
Delay in ms.
Errors
PrinterException if disconnected or read fails.
getRewindPrint
Read register LABEL_REWIND_PRINT.
synchronized boolean getRewindPrint() throws PrinterExceptionReturns
true if enabled.
Errors
PrinterException if disconnected or read fails.
getAutoReprint
Read register AUTO_REPRINT.
synchronized boolean getAutoReprint() throws PrinterExceptionReturns
true if enabled.
Errors
PrinterException if disconnected or read fails.
setAutoReprint
Write register AUTO_REPRINT and save (persistent).
synchronized boolean setAutoReprint(boolean enable) throws PrinterExceptionParameters
| Name | Type | Description |
|---|---|---|
| enable | boolean | Enable auto reprint. |
Returns
true on success.
Errors
PrinterException if disconnected or I/O fails.
printSelfTest
Print self-test page via register function ui_prn_selftest.
synchronized boolean printSelfTest() throws PrinterExceptionReturns
true if the command was accepted.
Errors
PrinterException if upgrading, disconnected, or I/O fails.
pageSetup
Set page size in dots; clear the page buffer. Four-arg overload also sets rotation and gap mode (applied at print tail).
void pageSetup(int pageWidth, int pageHeight)
void pageSetup(int pageWidth, int pageHeight, int r, int gap)Parameters
| Name | Type | Description |
|---|---|---|
| pageWidth | int | Page width (dots). |
| pageHeight | int | Page height (dots). |
| r | int | 0 none; 1 90°; 2 180°; 3 270°. |
| gap | int | 0 none; 1 gap; 2 left bar; 3 right bar. Used by buildCpcl() / buildPageBytes(). |
drawText
Draw text. Overloads: default font size map; int fontType; String font name.
Parameters
| Name | Type | Description |
|---|---|---|
| text_x / text_y | int | Start position (dots). |
| text | String | Content. |
| fontSize | int | Preset map overload: 1–12 (maps to CPCL fonts). Int/String fontType overloads: multiplier / size field (≥ 1). |
| fontType | int / String | Font id (int) or font name (String) for overload 2/3. |
| rotate | int | 0 / 90 / 180 / 270 (CCW). |
| bold | int | 0 = off; >0 = bold on. |
| reverse | boolean | Inverse text. |
| underline | boolean | Underline. |
drawBarCode
Draw a 1D barcode.
void drawBarCode(int start_x, int start_y, String text, int type, int rotate, int linewidth, int height)Parameters
| Name | Type | Description |
|---|---|---|
| start_x / start_y | int | Start position in dots (≥ 0). |
| text | String | Barcode data. |
| type | int | 0 CODE39; 1 CODE128; 2 CODE93; 3 CODEBAR; 4 EAN8; 5 EAN13; 6 UPCA; 7 UPCE; 8 I2OF5. |
| rotate | int | 0 horizontal; 1 vertical. |
| linewidth | int | Narrow bar width (≥ 1). |
| height | int | Barcode height in dots (≥ 1). |
drawQrCode
Draw a QR code. Non-zero rotate uses VBARCODE.
void drawQrCode(int start_x, int start_y, String text, int rotate, int ver, int lel)Parameters
| Name | Type | Description |
|---|---|---|
| start_x / start_y | int | Start position in dots (≥ 0). |
| text | String | QR content. |
| rotate | int | 0 normal; non-zero vertical. |
| ver | int | Module scale 1–32 (often 6). |
| lel | int | QR version/model 1–40 (size 17+n×4); 0 = auto. |
drawBox
Draw a rectangle box.
void drawBox(int lineWidth, int top_left_x, int top_left_y, int bottom_right_x, int bottom_right_y)Parameters
| Name | Type | Description |
|---|---|---|
| lineWidth | int | Border width. |
| top_left_x / top_left_y | int | Top-left. |
| bottom_right_x / bottom_right_y | int | Bottom-right. |
drawLine
Draw a line.
void drawLine(int lineWidth, int start_x, int start_y, int end_x, int end_y, boolean fullline)Parameters
| Name | Type | Description |
|---|---|---|
| lineWidth | int | Line width. |
| start_x / start_y / end_x / end_y | int | Endpoints. |
| fullline | boolean | Reserved (solid line in current impl). |
drawGraphic
Draw a bitmap (CG path).
void drawGraphic(int start_x, int start_y, Bitmap bmp)Parameters
| Name | Type | Description |
|---|---|---|
| start_x / start_y | int | Origin. |
| bmp | Bitmap | Image. |
drawImageFormFile
Draw an image from a file path (EG path).
void drawImageFormFile(int start_x, int start_y, String filepath)Parameters
| Name | Type | Description |
|---|---|---|
| start_x / start_y | int | Origin. |
| filepath | String | Image path. |
prefeed
Feed before print. 8 dots ≈ 1 mm.
void prefeed(int len)Parameters
| Name | Type | Description |
|---|---|---|
| len | int | Length in dots. |
postfeed
Feed after print. 8 dots ≈ 1 mm.
void postfeed(int len)Parameters
| Name | Type | Description |
|---|---|---|
| len | int | Length in dots. |
alignLeft
Left alignment for following content.
void alignLeft()alignCenter
Center alignment for following content.
void alignCenter()alignRight
Right alignment for following content.
void alignRight()barcodeText
Barcode with human-readable text (Code 128).
Parameters
| Name | Type | Description |
|---|---|---|
| font / size | int | HRI font / size. |
| offset | int | Offset from barcode (dots). |
| rotate | int | 0 horizontal; 1 vertical. |
| width / ratio / height | int | Narrow width, ratio, height. |
| x / y | int | Origin. |
| data | String | Barcode data. |
PrinterStatus
| Value | Meaning |
|---|---|
OK | Ready |
COVER_OPEN | Cover open |
NO_PAPER | Out of paper |
PAPER_ERROR | Paper error |
UNKNOWN_ERROR | Unknown error |
DISCONNECTED | Not connected |
COMMUNICATION_ERROR | Communication failed |
BUSY | Busy |
OVERHEATED | Overheated |
isReady() is true only for OK.
ConnectionMode
| Value | Meaning |
|---|---|
NONE | Not connected |
LOCAL | Local printer |
BLE | BLE channel |
BleConnectionListener
| Callback | Meaning |
|---|---|
| onConnected | BLE connected (deviceAddress) |
| onDisconnected | BLE disconnected (deviceAddress) |
| onConnectFailed | Connect failed (deviceAddress, message) |
BleScanListener
| Callback | Meaning |
|---|---|
| onScanData | Raw scan bytes on main thread (byte[] data) |
PrinterStatusListener
Local status callbacks:
| Callback | Meaning |
|---|---|
| onConnected | Local connected |
| onDisconnected | Local disconnected |
| onStatusChanged | Status changed (PrinterStatus) |
| onError | Error (errorCode, errorMessage) |
FirmwareUpgradeListener
| Callback | Meaning |
|---|---|
| onProgress | Send progress (sentBytes, totalBytes) |
| onCompleted | Completed (includes reboot wait) |
PrinterException
Checked exception for connect, register writes, and firmware upgrade. Optional getErrorCode().
Examples
Local text + barcode
java
pm.connect();
pm.pageSetup(384, 240, 0, 1);
pm.drawText(16, 16, "Item", 2, 0, 0, false, false);
pm.drawBarCode(16, 56, "ABC123", 1, 0, 2, 72);
pm.printByText(pm.buildCpcl());BLE connect + print
java
pm.setConnectionListener(listener);
pm.connect("AA:BB:CC:DD:EE:FF");
pm.pageSetup(384, 200, 0, 1);
pm.drawText(16, 40, "BLE OK", 2, 0, 0, false, false);
pm.printByText(pm.buildCpcl());Image (drawGraphic)
java
pm.pageSetup(bmp.getWidth(), bmp.getHeight(), 0, 1);
pm.drawGraphic(0, 0, bmp);
byte[] data = pm.buildPageBytes();
pm.printByGzipData(data);Notes & FAQ
Notes
- Local and BLE are mutually exclusive;
disconnect()before switching. - Two text paths: (1) CPCL helpers
pageSetup/draw*/buildCpcl()thenprintByText; (2) pass a complete CPCL / ZPL / ESC / TSPL job string toprintByText(GBK). - Image pages:
buildPageBytes()+printByData/printByGzipData. - Persistent register APIs write device registers and save.
- RFID APIs are local-only (fail on BLE).
- Sense commands (
GAP-SENSE/BAR-SENSE-LEFT/BAR-SENSE) are appended atbuildCpcl()/buildPageBytes()tail when using the CPCL helpers.
FAQ
Q: Why does nothing print after drawText?
A: draw* only builds the page. Call buildCpcl() then printByText.
Q: Can I send ZPL / ESC / TSPL without using draw* APIs?
A: Yes. Pass the full command string to printByText. The CPCL helpers are optional wrappers for common CPCL commands.
Q: Can I use RFID over BLE?
A: No. RFID returns false / sentinel / -5 on BLE.
Q: Where is gap set?
A: Set gap in pageSetup(w, h, r, gap) (0 none, 1 gap, 2 left bar, 3 right bar). Then buildCpcl() / buildPageBytes() use that value.
概述
K388 Printer SDK 是 Urovo K388 / K388Pro 打印机的 统一 Android 入口。公开类为 com.urovo.printer.UPrinterManager。
版本变更
- 2.4.3：连接/寄存器严谨化（持久化寄存器与本机 RFID 须先
connect）；BLE Notify CCCD 与写忙碌修复；状态/寄存器帧纯函数与单测；新增rfidWriteResult(int)；对外PrinterException/IllegalArgumentException文案均为英文；JAR：UK388PrintLibrary_v2.4.3.jar。 - 2.4.2：将组页方法
printByte()重命名为buildPageBytes()（图片任务，不下发）。JAR：UK388PrintLibrary_v2.4.2.jar。 - 2.4.1：将组页方法
print()重命名为buildCpcl()，避免与真正下发的printByText混淆。JAR：UK388PrintLibrary_v2.4.1.jar。 - 2.4.0：Local + BLE 统一入口。API 按公用 / 蓝牙特有 / 本地特有 / 持久化寄存器 / CPCL 常用指令封装分组。组页 CPCL 修正（
BAR-SENSE-LEFT、二维码旋转、收尾FORM/PRINT、条码线宽等）。新增持久化寄存器读取（getPrintDarkness/getPrintMode/getMultiPrintDelay/getRewindPrint/getAutoReprint），以及setAutoReprint、printSelfTest。JAR：UK388PrintLibrary_v2.4.0.jar（与getSDKVersion()对齐）。
核心能力
- 本机：
connect() - 蓝牙：
connect(mac) - CPCL 辅助接口：对常用 CPCL 指令的封装（组页 / 绘制 / 生成指令）
printByText：直接下发完整打印指令，支持 CPCL / ZPL / ESC / TSPL- 持久化寄存器设置
- 本机 RFID
典型场景
- 设备本机标签打印
- 外接 BLE 标签机 + 可选扫码打印
- 固件
.upd升级
依赖与环境
| 项 | 要求 |
|---|---|
| 平台 | Android |
| 最低版本 | API 24（Android 7.0）+ |
| 语言 | Java |
| 依赖 | UK388PrintLibrary_v2.4.3.jar（或工程 module） |
| 鉴权 | 无 |
接入
引入依赖
gradle
implementation files('libs/UK388PrintLibrary_v2.4.3.jar')权限
- 本机：设备打印服务 / LocalSocket（视机型）
- BLE（Android 12+）：
BLUETOOTH_CONNECT（以及目标 SDK 要求的扫描/定位权限）
初始化
java
UPrinterManager pm = UPrinterManager.getInstance(context.getApplicationContext());无需鉴权。
快速开始
java
UPrinterManager pm = UPrinterManager.getInstance(getApplicationContext());
pm.connect(); // BLE 则 pm.connect("AA:BB:CC:DD:EE:FF")
pm.flushBuffer();
pm.pageSetup(384, 240, 0, 1);
pm.drawText(16, 16, "K388Pro", 2, 0, 0, false, false);
String cpcl = pm.buildCpcl();
boolean ok = pm.printByText(cpcl);BLE：如需监听，请在 connect(mac) 前设置 setConnectionListener / setScanListener。
也可跳过 CPCL 辅助接口，直接下发完整作业：
java
// 完整指令文本：CPCL / ZPL / ESC / TSPL
boolean ok = pm.printByText(fullCommandText);API 参考
分组：公用接口、蓝牙特有、本地特有、持久化寄存器设置、CPCL 常用指令封装，以及 类型。
CPCL 辅助方法是对常用 CPCL 指令的封装，便于组页。若客户已有完整打印脚本，可直接调用 printByText 传入完整的 CPCL / ZPL / ESC / TSPL 文本。
getInstance
获取单例。首次调用必须传入 Context。
static UPrinterManager getInstance(Context context)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| context | Context | 建议传入 Application Context。 |
返回值
UPrinterManager 单例。
connect
connect() 连接本机打印机；connect(String) 按 MAC 连接 BLE。二者互斥，切换前须 disconnect。
void connect() throws PrinterException
void connect(String macAddress) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| macAddress | String | BLE MAC，如 AA:BB:CC:DD:EE:FF（BLE 重载）。 |
错误码
已连接、升级中或打开/连接失败时抛出 PrinterException。
disconnect
断开当前已连接的打印机，并将模式重置为 NONE。
void disconnect()isConnected
当前是否已连接打印机（本机或 BLE）。
boolean isConnected()返回值
已连接返回 true。
getConnectionMode
返回当前连接的设备类型。
ConnectionMode getConnectionMode()返回值
NONE / LOCAL / BLE。
getSDKVersion
返回 SDK 版本字符串（Local+BLE 统一构建）。
String getSDKVersion()返回值
版本字符串。
flushBuffer
清空当前通道发送缓冲区。
void flushBuffer()printByData
在当前通道发送原始字节。仅用于图片打印（通常配合 buildPageBytes）。
boolean printByData(byte[] data)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| data | byte[] | 来自 buildPageBytes 的页数据。 |
返回值
写入被接受返回 true；未连接、升级中或 data 为 null 返回 false。
printByGzipData
先做 GZIP 组帧再发送。大图可选；普通文字页不要用。
boolean printByGzipData(byte[] data)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| data | byte[] | 原始页数据（GZIP 前），通常来自 buildPageBytes。 |
返回值
语义同 printByData。
printByText
以 GBK 下发完整打印指令字符串。支持 CPCL / ZPL / ESC / TSPL 完整作业。可传入 buildCpcl() 的组页结果，也可直接传入客户自写的完整指令。
boolean printByText(String text)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| text | String | 完整打印指令（CPCL / ZPL / ESC / TSPL），或 buildCpcl() 生成的 CPCL。 |
返回值
写入被接受返回 true；未连接、升级中、null 或编码失败返回 false。
setPrintTime
设置打印次数（默认 1）。
void setPrintTime(int time)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| time | int | 页头打印份数（≥ 1；默认 1）。 |
buildCpcl
生成 CPCL 打印指令字符串（非图片任务用，不下发）。走纸/检测取自 pageSetup(..., gap)。配合 printByText 下发。
String buildCpcl()返回值
CPCL 指令字符串。
buildPageBytes
生成图片任务的页数据字节（不下发）。走纸/检测取自 pageSetup(..., gap)。配合 printByData / printByGzipData 下发。
byte[] buildPageBytes()返回值
页数据字节。
getPrintPrintStr
获取当前已组页的 CPCL 指令字符串（不触发额外结束逻辑）。
String getPrintPrintStr()返回值
当前缓冲中的 CPCL 文本。
version
组页引擎版本字符串。
String version()返回值
引擎版本。
getPrinterStatus
在当前通道查询打印机状态。
PrinterStatus getPrinterStatus()返回值
未连接为 DISCONNECTED；升级中或应答异常为 UNKNOWN_ERROR；BLE 写失败为 COMMUNICATION_ERROR。
getPrinterStatusDescription
返回状态描述文字。
String getPrinterStatusDescription()返回值
状态描述。
isFirmwareUpgrading
是否正在固件升级。
boolean isFirmwareUpgrading()返回值
升级中返回 true。
getFirmwareVersion
读取固件版本。LOCAL 与 BLE 均可（需已连接）。
String getFirmwareVersion()返回值
版本字符串；失败 / 未连接 / 升级中返回 null。
upgradeFirmware
阻塞式 .upd 升级。完成后断开并等待重启（约 25 秒），之后需重新 connect。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| firmwareFilePath | String | .upd 绝对路径。 |
| listener | FirmwareUpgradeListener | 可选；可为 null。 |
错误码
文件无效、状态异常或写入超时时抛出。请在工作线程执行。
示例
java
pm.upgradeFirmware("/sdcard/firmware.upd", new UPrinterManager.FirmwareUpgradeListener() {
public void onProgress(int sentBytes, int totalBytes) { }
public void onCompleted() { }
});setConnectionListener
注册 BLE 连接回调。意外 GATT 断连会先复位内部连接态再回调。仅 BLE。
void setConnectionListener(BleConnectionListener listener)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| listener | BleConnectionListener | 传 null 清除。 |
setScanListener
注册 BLE 扫码头通知回调（主线程）。仅 BLE。
void setScanListener(BleScanListener listener)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| listener | BleScanListener | 传 null 清除。 |
getConnectedAddress
仅 BLE：已连接设备的 MAC；非 BLE 或未连接返回 null。
String getConnectedAddress()返回值
MAC 或 null。
setPrinterStatusListener
本机连接状态监听。BLE 请使用 setConnectionListener。
void setPrinterStatusListener(PrinterStatusListener listener)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| listener | PrinterStatusListener | 本机连接 / 断开 / 状态回调。 |
rfidWrite
写入 RFID 存储区。仅本机。
boolean rfidWrite(int bank, int password, int offset, byte[] data, int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| bank | int | 存储区。 |
| password | int | 访问密码。 |
| offset | int | 字节偏移（偶对齐）。 |
| data | byte[] | 数据。 |
| len | int | 长度（偶对齐）。 |
返回值
成功 true；BLE / 升级中 / 未连接 / 失败为 false。
rfidWriteResult
写入 RFID 并返回 int 结果码（推荐）。仅本机；须已连接。
int rfidWriteResult(int bank, int password, int offset, byte[] data, int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| bank | int | 存储区。 |
| password | int | 访问密码。 |
| offset | int | 字节偏移（偶对齐）。 |
| data | byte[] | 数据。 |
| len | int | 长度（偶对齐）。 |
返回值
0 / RFID_RESULT_OK 成功；>0 设备错误码；-1 超时；-2 响应头非法；-3 参数非法；-4 升级中；-5 BLE / 非本机通道。
rfidWriteWithResp
写入 RFID 并返回结果码字符串（兼容旧接入）。新代码请用 rfidWriteResult。
String rfidWriteWithResp(int bank, int password, int offset, byte[] data, int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| bank | int | 存储区。 |
| password | int | 访问密码。 |
| offset | int | 字节偏移（偶对齐）。 |
| data | byte[] | 数据。 |
| len | int | 长度（偶对齐）。 |
返回值
rfidWriteResult 的十进制字符串（如 "0"、"-5"）。
rfidRead
读取 RFID 到 data。仅本机。
boolean rfidRead(int bank, int password, int offset, byte[] data, int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| bank | int | 存储区。 |
| password | int | 访问密码。 |
| offset | int | 字节偏移。 |
| data | byte[] | 输出缓冲。 |
| len | int | 长度。 |
返回值
成功 true；BLE / 升级中 / 未连接 / 失败为 false。
setReadPower
设置 RFID 读功率（0–28）。仅本机。
boolean setReadPower(int power)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| power | int | 0–28。 |
返回值
成功 true。
错误码
超出 0–28 抛出 IllegalArgumentException。
setWritePower
设置 RFID 写功率（0–28）。仅本机。
boolean setWritePower(int power)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| power | int | 0–28。 |
返回值
成功 true。
错误码
超出 0–28 抛出 IllegalArgumentException。
getReadPower
读取 RFID 读功率。仅本机。
int getReadPower()返回值
功率值；BLE / 升级中 / 不可用时返回 32767。
getWritePower
读取 RFID 写功率。仅本机。
int getWritePower()返回值
功率值；BLE / 升级中 / 不可用时返回 32767。
getCurLabelPower
当前标签 RFID 功率。仅本机。
int getCurLabelPower()返回值
功率值；BLE / 升级中 / 不可用时返回 32767。
getRfidCardState
是否检测到 RFID 标签。仅本机。
boolean getRfidCardState()返回值
有标签 true；BLE / 升级中 / 无标签为 false。
setPrintDarkness
写入寄存器 PRINT_DARKNESS 并保存（持久化）。
synchronized boolean setPrintDarkness(int darkness) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| darkness | int | PRINT_DARKNESS 黑度：-5～5（含端点）。 |
返回值
成功返回 true。
错误码
超出 -5～5 抛出 IllegalArgumentException；未连接、升级中或 I/O 失败抛出 PrinterException。
setPrintMode
写入寄存器 PRINT_MODE：0 正常，1 高速，2 低速。
synchronized boolean setPrintMode(int mode) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| mode | int | 0–2。 |
返回值
成功返回 true。
错误码
超出 0–2 抛出 IllegalArgumentException；未连接或 I/O 失败抛出 PrinterException。
setMultiPrintDelay
写入寄存器 PAGE_PRINT_WAIT_DELAY（毫秒）。
synchronized boolean setMultiPrintDelay(int delayMs) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| delayMs | int | ≥ 0。 |
返回值
成功返回 true。
错误码
< 0 抛出 IllegalArgumentException；未连接或 I/O 失败抛出 PrinterException。
setRewindPrint
写入寄存器 LABEL_REWIND_PRINT 并重置回退模式。
synchronized boolean setRewindPrint(boolean enable) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | boolean | 是否启用回退打印。 |
返回值
成功返回 true。
错误码
未连接或 I/O 失败时抛出 PrinterException。
getPrintDarkness
读取寄存器 PRINT_DARKNESS。读取失败抛出异常。
synchronized int getPrintDarkness() throws PrinterException返回值
黑度值（与 setPrintDarkness 同一量纲，通常 -5～5）。
错误码
未连接或读取失败时抛出 PrinterException。
getPrintMode
读取寄存器 PRINT_MODE（0 正常 / 1 高速 / 2 低速）。
synchronized int getPrintMode() throws PrinterException返回值
模式值。
错误码
未连接或读取失败时抛出 PrinterException。
getMultiPrintDelay
读取寄存器 PAGE_PRINT_WAIT_DELAY（毫秒）。
synchronized int getMultiPrintDelay() throws PrinterException返回值
延时毫秒。
错误码
未连接或读取失败时抛出 PrinterException。
getRewindPrint
读取寄存器 LABEL_REWIND_PRINT。
synchronized boolean getRewindPrint() throws PrinterException返回值
开启返回 true。
错误码
未连接或读取失败时抛出 PrinterException。
getAutoReprint
读取寄存器 AUTO_REPRINT。
synchronized boolean getAutoReprint() throws PrinterException返回值
开启返回 true。
错误码
未连接或读取失败时抛出 PrinterException。
setAutoReprint
写入寄存器 AUTO_REPRINT 并保存（持久化）。
synchronized boolean setAutoReprint(boolean enable) throws PrinterException参数
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | boolean | 是否启用自动补打。 |
返回值
成功返回 true。
错误码
未连接或 I/O 失败时抛出 PrinterException。
printSelfTest
通过寄存器函数 ui_prn_selftest 打印自检页。
synchronized boolean printSelfTest() throws PrinterException返回值
指令下发成功返回 true。
错误码
升级中、未连接或 I/O 失败时抛出 PrinterException。
pageSetup
设置页面尺寸（点）并清空缓冲。四参重载还可设置旋转与间隙/检测（在 print 收尾下发）。
void pageSetup(int pageWidth, int pageHeight)
void pageSetup(int pageWidth, int pageHeight, int r, int gap)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| pageWidth | int | 页宽（点）。 |
| pageHeight | int | 页高（点）。 |
| r | int | 0 不旋转；1 90°；2 180°；3 270°。 |
| gap | int | 0 不走纸；1 标签；2 左黑标；3 右黑标。供 buildCpcl() / buildPageBytes() 收尾使用。 |
drawText
绘制文字。重载：默认字号映射；整型字体类型；字符串字体名。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| text_x / text_y | int | 起始坐标（点）。 |
| text | String | 内容。 |
| fontSize | int | 默认映射重载：1–12（映射到 CPCL 字体）。带 fontType 的重载：字号/倍率（≥ 1）。 |
| fontType | int / String | 字体 id（int）或字体名（String），第 2/3 重载。 |
| rotate | int | 逆时针 0 / 90 / 180 / 270。 |
| bold | int | 0 取消粗体；>0 加粗。 |
| reverse | boolean | 反白。 |
| underline | boolean | 下划线。 |
drawBarCode
绘制一维条码。
void drawBarCode(int start_x, int start_y, String text, int type, int rotate, int linewidth, int height)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| start_x / start_y | int | 起始坐标（点，≥ 0）。 |
| text | String | 条码数据。 |
| type | int | 0 CODE39；1 CODE128；2 CODE93；3 CODEBAR；4 EAN8；5 EAN13；6 UPCA；7 UPCE；8 I2OF5。 |
| rotate | int | 0 水平；1 竖直。 |
| linewidth | int | 窄条宽度（≥ 1）。 |
| height | int | 条码高度（点，≥ 1）。 |
drawQrCode
绘制二维码。rotate 非 0 时使用 VBARCODE。
void drawQrCode(int start_x, int start_y, String text, int rotate, int ver, int lel)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| start_x / start_y | int | 起始坐标（点，≥ 0）。 |
| text | String | 二维码内容。 |
| rotate | int | 0 正常；非 0 竖直。 |
| ver | int | 放大倍数 1–32（常用 6）。 |
| lel | int | 二维码版本型号 1–40（尺寸 17+n×4）；0 表示自动。 |
drawBox
绘制矩形框。
void drawBox(int lineWidth, int top_left_x, int top_left_y, int bottom_right_x, int bottom_right_y)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| lineWidth | int | 边框宽度。 |
| top_left_x / top_left_y | int | 左上角。 |
| bottom_right_x / bottom_right_y | int | 右下角。 |
drawLine
绘制线条。
void drawLine(int lineWidth, int start_x, int start_y, int end_x, int end_y, boolean fullline)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| lineWidth | int | 线宽。 |
| start_x / start_y / end_x / end_y | int | 起终点。 |
| fullline | boolean | 保留参数（当前实现按实线）。 |
drawGraphic
绘制位图（CG 路径）。
void drawGraphic(int start_x, int start_y, Bitmap bmp)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| start_x / start_y | int | 起点。 |
| bmp | Bitmap | 图片。 |
drawImageFormFile
从文件路径绘制图片（EG 路径）。
void drawImageFormFile(int start_x, int start_y, String filepath)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| start_x / start_y | int | 起点。 |
| filepath | String | 图片路径。 |
prefeed
打印前走纸。8 点 ≈ 1 mm。
void prefeed(int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| len | int | 走纸长度（点）。 |
postfeed
打印后走纸。8 点 ≈ 1 mm。
void postfeed(int len)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| len | int | 走纸长度（点）。 |
alignLeft
后续内容左对齐。
void alignLeft()alignCenter
后续内容居中对齐。
void alignCenter()alignRight
后续内容右对齐。
void alignRight()barcodeText
带可读文字的条码（Code 128）。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| font / size | int | 识别符字体 / 字号。 |
| offset | int | 相对条码偏移（点）。 |
| rotate | int | 0 水平；1 竖直。 |
| width / ratio / height | int | 窄条宽、宽窄比、高度。 |
| x / y | int | 起点。 |
| data | String | 条码数据。 |
PrinterStatus
| Value | Meaning |
|---|---|
OK | 就绪 |
COVER_OPEN | 纸仓盖打开 |
NO_PAPER | 缺纸 |
PAPER_ERROR | 纸张错误 |
UNKNOWN_ERROR | 未知错误 |
DISCONNECTED | 未连接 |
COMMUNICATION_ERROR | 通信错误 |
BUSY | 忙 |
OVERHEATED | 过热 |
仅 OK 时 isReady() 为 true。
ConnectionMode
| Value | Meaning |
|---|---|
NONE | 未连接 |
LOCAL | 已连接本机打印机 |
BLE | BLE 通道 |
BleConnectionListener
| Callback | Meaning |
|---|---|
| onConnected | BLE 已连接（deviceAddress） |
| onDisconnected | BLE 已断开（deviceAddress） |
| onConnectFailed | 连接失败（deviceAddress, message） |
BleScanListener
| Callback | Meaning |
|---|---|
| onScanData | 主线程返回扫码原始字节（byte[] data） |
PrinterStatusListener
本机状态回调：
| Callback | Meaning |
|---|---|
| onConnected | 本机已连接 |
| onDisconnected | 本机已断开 |
| onStatusChanged | 状态变化（PrinterStatus） |
| onError | 错误（errorCode, errorMessage） |
FirmwareUpgradeListener
| Callback | Meaning |
|---|---|
| onProgress | 发送进度（sentBytes, totalBytes） |
| onCompleted | 完成（含重启等待） |
PrinterException
用于连接、寄存器写入与固件升级的受检异常。可选 getErrorCode()。
示例
本机文字与条码
java
pm.connect();
pm.pageSetup(384, 240, 0, 1);
pm.drawText(16, 16, "Item", 2, 0, 0, false, false);
pm.drawBarCode(16, 56, "ABC123", 1, 0, 2, 72);
pm.printByText(pm.buildCpcl());BLE 连接并打印
java
pm.setConnectionListener(listener);
pm.connect("AA:BB:CC:DD:EE:FF");
pm.pageSetup(384, 200, 0, 1);
pm.drawText(16, 40, "BLE OK", 2, 0, 0, false, false);
pm.printByText(pm.buildCpcl());图片（drawGraphic）
java
pm.pageSetup(bmp.getWidth(), bmp.getHeight(), 0, 1);
pm.drawGraphic(0, 0, bmp);
byte[] data = pm.buildPageBytes();
pm.printByGzipData(data);注意事项与 FAQ
注意事项
- 本机与 BLE 互斥，切换前先
disconnect()。 - 文字下发两条路径：（1）CPCL 辅助接口
pageSetup/draw*/buildCpcl()再printByText；（2）直接把完整的 CPCL / ZPL / ESC / TSPL 作业字符串传给printByText（GBK）。 - 图片页：
buildPageBytes()+printByData/printByGzipData。 - 持久化寄存器接口会写入设备寄存器并保存。
- RFID 仅本机（BLE 下失败）。
- 使用 CPCL 辅助接口时，检测指令（
GAP-SENSE/BAR-SENSE-LEFT/BAR-SENSE）在buildCpcl()/buildPageBytes()收尾追加。
FAQ
Q：drawText 后为什么不打印？ A：draw* 只组页。需再调用 buildCpcl() 与 printByText。
*Q：不用 draw 能否直接发 ZPL / ESC / TSPL？** A：可以。把完整指令字符串传给 printByText 即可。CPCL 辅助接口是可选的常用 CPCL 封装。
Q：BLE 能用 RFID 吗？ A：不能。BLE 下返回 false / 哨兵值 / -5。
Q：gap 在哪里设置？ A：在 pageSetup(w, h, r, gap) 设置 gap（0 不走纸，1 标签，2 左黑标，3 右黑标），再调用 buildCpcl() / buildPageBytes()。