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。