Java SDK 適合 Android 應用、JVM 工具、網路印表機和經典藍牙連線。接入時先把真實連線包裝成 Device，再讓範本建構 Script 或直接通過寫入管線傳送位元組。

Maven 模組

Maven group 是 com.boxliy.nib。

模組	用途
nib	標準聚合版，適合產品整合。
nib-core	Device、Script、WritePipeline、接收源和查詢分發。
nib-esc-boxliy、nib-tspl-boxliy、nib-cpcl-boxliy	Boxliy 方言建構器和回應解析器。
nib-esc、nib-tspl、nib-cpcl	Aryten 相容方言。
nib-esc-lin8inch、nib-tspl-lin8inch	Lin8inch 方言。
nib-network	TCP/IP 網路印表機連線。
nib-bluetooth	Java 經典藍牙抽象。
Android classic 轉接	倉庫中有 Android 經典藍牙轉接原始碼；是否作為獨立交付模組，以實際交付版本為準。

原始碼中沒有確認到 Java BLE 模組；Android BLE 如需接入，應按交付版本或專案轉接層確認，不要按經典藍牙模組推斷。

Core 物件

Device 是最小裝置合約：

public interface Device {
  String name();
  boolean connected();
  void write(byte[] data) throws IOException;
  byte[] read(int timeoutMs) throws IOException;
  void close() throws IOException;
}

Script 儲存建構好的位元組，提供 binary()、hex()、base64()、string() 和 length()。WritePipeline 負責分片寫入，WriteOptions 配置 ChunkPolicy、WriteMode、取消、逾時和 backpressure，回傳 WriteResult。

預設分片大小來自 NibDefaults.CHUNK_SIZE，目前是 1024 位元組。

第一次列印

Java 的 EscBoxliy 沒有 text() 方法，一般文字請使用 raw(...)：

import com.boxliy.nib.core.Device;
import com.boxliy.nib.esc.EscBoxliy;

Device device = Device.none();

EscBoxliy.of(device)
    .reset()
    .raw("NIB SDK\r\n")
    .feed(2)
    .write();

Device.none() 適合測試指令碼產生，不會連線實際印表機。實際專案裡傳入網路、經典藍牙或 Android classic 連線得到的 Device。

需要先建構指令碼再寫入時：

import com.boxliy.nib.core.WriteOptions;
import com.boxliy.nib.core.WritePipeline;
import com.boxliy.nib.core.WriteResult;
import com.boxliy.nib.tspl.TsplAryten;

byte[] data = TsplAryten.of()
    .size(40, 30)
    .cls()
    .text(20, 20, "NIB SDK")
    .print(1)
    .build()
    .binary();

WriteResult result = WritePipeline.write(
    device,
    data,
    WriteOptions.defaults(),
    null
);

網路列印

nib-network 提供 Network.connect(...)：

import com.boxliy.nib.core.Device;
import com.boxliy.nib.network.Network;

Device device = Network.connect("192.168.1.50", 9100);

預設連線逾時是 10000 ms，也可以呼叫 Network.connect(host, port, timeoutMs)。網路列印前要確認 host、port、逾時、重試和日誌策略；日誌可以記錄端點和位元組長度，但不要記錄敏感列印內容。

Android 和經典藍牙

Java 倉庫裡確認到 nib-bluetooth，並有 Android classic 轉接原始碼。Android classic 接入時通常需要：

1. 按 Android 版本申請藍牙權限。
2. 掃描或選擇已配對裝置。
3. 建立經典藍牙 socket。
4. 包裝成 Device。
5. 使用方言建構器產生 Script。
6. 通過建構器 write() 或 WritePipeline.write(...) 傳送。
7. 頁面銷燬或會話結束時關閉連線。

權限、生命週期和重連邏輯不要寫進列印範本。

接收、查詢和解析

core 提供 ReceiveSource、PollingReceiveSource、CallbackReceiveSource、ReceiveListener、QueryDispatcher、PendingQuery 和 ResponseMatcher。

Boxliy 方言 parser 名稱：

方言	解析器
ESC	EscResponseParser
TSPL	TsplResponseParser
CPCL	CpclResponseParser

狀態、電量、型號、序列號等查詢都應放在會話層統一處理，併為裝置韌體設定合理逾時。

方法与命令清单

下面列出这个语言 SDK 中常用且对接方需要理解的公开入口。构建器方法会生成对应打印机指令；是否能在某台机器上使用，仍以机器固件支持的 ESC、TSPL、CPCL 或 Lin8inch 指令组为准。

Core、连接与写入

对象	方法 / 命令	作用	参数说明
Device / Script	name(), connected(), write(data), read(timeoutMs), close(), binary(), hex(), base64(), string(), length()	抽象真实打印机连接，供模板、写入管线和查询层统一使用。	`timeoutMs` 是读取超时；`Script` 用于查看或保存构建后的字节。
WritePipeline / WriteOptions	write(device, data, options, listener), withChunkPolicy(), withMode(), withCancellationToken(), withTimeout(), withBackpressure()	把已经构建好的字节按分片、超时、取消和流控规则写入设备。	`ChunkPolicy.fixed(size)` 控制分片；listener 接收 `WriteProgress`；返回 `WriteResult`。
PrinterDiscovery / PrinterConnector	scan(), stop(), connect(printer, options), disconnect(), state()	扫描、连接和断开打印机，适合把平台连接层统一成 NIB core。	`ConnectionOptions` 包含 transport、timeoutMs、autoReconnect。
ReceiveSource / QueryDispatcher	start(listener), stop(), accept(data), receive(data), query(matcher, timeoutMs), cancel(), shutdown()	把设备回包接入监听器或查询分发器，用于状态、电量、型号等查询。	`ResponseMatcher` 返回匹配结果；`PendingQuery` 可 `get()` 或带超时等待。

指令构建器

对象	方法 / 命令	作用	参数说明
EscBoxliy / EscAryten	of(), newLine(), location(), image(), line(), cut(), feed(), lineRow(), lineDot(), backLineDot(), enable(), wakeup(), position(), stopJob(), setBTType(), lineDotCut(), thickness(), learnLabelGap(), paperType(), batteryVolume(), info(), model(), version(), printerVersion(), sn(), state(), status(), name(), mac(), reset(), raw(), imageGray(), build(), write(), clear()	生成 ESC/Boxliy 基础指令，适合小票、便携打印机和支持 ESC 的机型。	`of` 可传 device/charset；`raw` 传模板和参数；`write(chunkSize, progress)` 直接写设备。
TsplBoxliy / TsplAryten	of(), size(), gap(), bline(), continuous(), label(), direction(), codePage(), speed(), density(), reference(), offset(), shift(), gapSensor(), ribbon(), cut(), tear(), peel(), detect(), readState(), status(), state(), realtimeStatus(), sn(), sns(), version(), versions(), model(), models(), batteryVolume(), cls(), text(), barcode(), qrcode(), dmatrix(), line(), box(), circle(), ellipse(), image(), print(), raw(), build(), write(), clear()	生成 TSPL 标签指令，适合需要纸张尺寸、坐标、条码和二维码的标签模板。	坐标/尺寸为 int；枚举包括 Direction、Mirror、CodePage、Font、Rotation、BarcodeType、QrLevel。
CpclBoxliy / CpclAryten	of(), begin(), pageWidth(), feed(), gapSense(), barSense(), paperType(), text(), barcode(), qrcode(), line(), box(), bold(), underline(), waterMark(), inverseLine(), image(), form(), print(), status(), realtimeStatus(), sn(), model(), version(), batteryVolume(), raw(), build(), write(), clear()	生成 CPCL 标签指令，适合 CPCL 机型的页面、文字、线条、条码和图片。	纸张、文字、条码、二维码、线框和图片参数与 CPCL 命令一致；`PaperType` 决定 gap/bar sensing。
EscLin8inch	of(), batteryLevel(), extendedModel(), bootVersion(), advancedDensity(), advancedDensityStatus(), grayMode(), mediaProfile(), mediaProfileStatus(), wirelessProvisioning(), wirelessProvisioningStatus(), compressedRasterTransport(), mediaTag(), mediaTagUid(), consumedMediaLength(), remainingMediaLength(), restoreLabelStartPosition(), alternateMotionProfile()	在 ESC 基础上增加 Lin8inch 遥测、介质、配网和光栅传输相关命令。	Lin8inch 扩展多用于查询、介质配置和 WiFi 配网；机型不支持时不要调用。
TsplLin8inch	of(), automaticStatusFeedback(), printCompletion(), printerStatus(), firmwareVersion(), serialNumber(), macAddress(), deviceSpeed(), deviceSelfTest(), thermalStatus(), productId(), versionInfo(), selfTestPage(), modelSetting(), serialSetting(), versionSetting(), gbkCodepage(), utf8Codepage(), gapDetection(), configureStock(), configurePresentation(), twoColorRibbon(), directThermal()	在 TSPL 基础上增加 Lin8inch 状态反馈、介质、色带和出纸配置命令。	传入 boolean、speed、状态 flag、stock sensor、presentation mode、mark/gap 和 offset。

回包解析

对象	方法 / 命令	作用	参数说明
EscResponseParser / TsplResponseParser / CpclResponseParser	parse(raw), parse(query, raw)	把打印机回包解析成状态、电量、文本、MAC、事件或未知响应。	`raw` 为 byte[]；返回对象可读取 type、rawHex、statusFlags、isReady、batteryLevel、text、macAddress、description。

實戰建議

• 先確認機型支援的方言，再選擇 EscBoxliy、TsplBoxliy、CpclBoxliy 或 Aryten/Lin8inch 建構器。
• Android classic 與 JVM classic 連線方式不同，範本層不要依賴平台類。
• 大圖片和連續列印必須通過真實裝置驗證分片大小。
• 混淆時保留交付套件要求保留的公開 SDK API。