The Swift SDK is suitable for new native iOS and macOS projects. No confirmed Package.swift was found in the source, so this page does not name a specific SwiftPM product. Integrate the corresponding module according to the delivered package import method.

Module contents

Module	Common types
Core	NibScript, NibDevice, NibPen, NibWritePipeline, receive sources, and query dispatch.
BLE	NibBleCentral, NibBleDevice, NibBleConnectionOptions, credit flow control.
Boxliy dialects	NibEscBoxliy, NibTsplBoxliy, NibCpclBoxliy, and response parsers.
Aryten dialects	NibEscAryten, NibTsplAryten, NibCpclAryten.
Image helpers	Image preparation and print helpers available in the delivered version.

Core objects

NibDevice is the minimal device contract:

public protocol NibDevice: AnyObject {
  var name: String { get }
  var connected: Bool { get }

  func write(_ data: Data) throws
  func read(maxLength: Int) throws -> Data
  func close() throws
}

NibScript stores built Data and provides length, string, and hexString. NibWritePipeline handles chunked writes, with a default chunkSize of 512 bytes.

First print

let connectedDevice: NibDevice = /* BLE 或平台设备 */

let script = NibTsplAryten()
  .size(width: 40, height: 30)
  .cls()
  .text(x: 20, y: 20, content: "NIB SDK")
  .print()
  .script

let pipeline = NibWritePipeline()
try pipeline.write(script, to: connectedDevice)

The builder generates the script. NibWritePipeline writes the script to the device in chunks. To change chunk size:

let pipeline = NibWritePipeline(chunkSize: 185)
try pipeline.write(script, to: connectedDevice)

BLE integration

The BLE entry point is NibBleCentral:

let central = NibBleCentral()
try central.startDiscovery(timeout: 10)

// 用户选择 discoveredDevices 里的目标设备后：
let device = try central.connect(
  selectedDevice,
  options: NibBleConnectionOptions()
)

NibBleConnectionOptions can configure serviceUUIDs, writeCharacteristicUUID, readCharacteristicUUID, connection and discovery timeouts, writeMode, credit, and custom flowControl. Write mode is NibBleWriteMode.withResponse or .withoutResponse, with .withoutResponse as the default.

BLE credit flow control

Credit APIs include:

API	Purpose
NibBleCreditOptions	Configures whether credit is enabled, UUIDs, initial credit, MTU, strategy, and fallback.
NibBleLaneCreditWriter	lane-credit strategy.
NibBleSignalCreditWriter	signal-credit strategy.
NibBleFlowControlStrategy	Custom flow-control strategy protocol.

Default UUIDs are FF00 service, FF02 write, FF01 read, and FF03 credit. lane-credit defaults to initial credit 1 and payload overhead 3. signal-credit defaults to initial credit 0 and payload overhead 0. NibBleCreditOptions is disabled by default unless .signalCredit is selected or enabled: true is set explicitly.

Receiving, querying, and dataStream

Core receive types include NibReceiveSource, NibCallbackReceiveSource, NibPollingReceiveSource, and NibReceiveListener. Query types include NibQueryDispatcher<Response>, NibPendingQuery<Response>, and NibResponseMatcher<Response>.

NibReceiveSource provides a dataStream() extension that can convert responses into AsyncStream<Data>:

for await data in device.receiveSource.dataStream() {
  let response = NibTsplResponseParser.parse(query: .status, raw: data)
  if response.isReady {
    break
  }
}

Boxliy dialect parser names:

Dialect	Parser
ESC	NibEscResponseParser
TSPL	NibTsplResponseParser
CPCL	NibCpclResponseParser

Methods and Commands

The tables below list the public entry points integration teams usually need. Builder methods generate printer commands; actual availability still depends on the ESC, TSPL, CPCL, or Lin8inch command family supported by the target firmware.

Core, Connection, and Writing

Object	Method / Command	Purpose	Parameters
NibDevice / NibScript	write(_ data), read(maxLength), close(), length, string, hexString	Abstracts the real printer connection for templates, write pipelines, and query handling.	`maxLength` limits read size; `NibScript` wraps built Data.
NibPen / NibWritePipeline	append(bytes), append(data), append(text), crlf(), clear(), reset(), write(script, to), write(data, to)	Writes built bytes to a device with chunking, timeout, cancellation, and flow-control rules.	`chunkSize` is configured when constructing the pipeline; returns written byte count.
NibBleCentral / NibBleDevice	startDiscovery(), stopDiscovery(), connect(), disconnect(), discover(options), write(), read(), close()	Handles BLE characteristic selection, MTU chunking, credit notifications, and fallback writes.	`NibBleConnectionOptions` configures service/write/read UUIDs, timeouts, writeMode, and credit.
NibReceiveSource / NibQueryDispatcher	start(listener), stop(), accept(), receive(), query(timeout, matcher), wait(), cancel(), shutdown(), dataStream()	Routes device responses into listeners or query dispatchers for status, battery, model, and similar queries.	`matcher` returns a typed response; `wait(timeout:)` waits for query completion.

Command Builders

Object	Method / Command	Purpose	Parameters
NibEscBoxliy / NibEscAryten	reset(), text(), newLine(), bold(), underline(), fontSize(), lineRow(), feed(), lineDot(), backLineDot(), location(), cut(), lineDotCut(), batteryVolume(), info(), model(), version(), printerVersion(), name(), mac(), sn(), state(), status(), enable(), stopJob(), wakeup(), barcode(), qrcode(), image(), raw(), clear()	Builds ESC/Boxliy commands for receipt, portable, and ESC-compatible printers.	Swift ESC directly supports `text`; barcode, QR, and image parameters follow the method signatures.
NibTsplBoxliy / NibTsplAryten	size(), cls(), print(), gap(), text(), barcode(), qrcode(), bitmap(), status(), state(), batteryVolume(), version(), versions(), model(), models(), sn(), sns(), raw(), clear()	Builds TSPL label commands for templates with paper size, coordinates, barcodes, and QR codes.	`text` takes x/y/font/rotation/xMulti/yMulti/content; `bitmap` takes Data or a prepared bitmap.
NibCpclBoxliy / NibCpclAryten	begin(), pageWidth(), text(), barcode(), qrcode(), line(), box(), image(), form(), print(), status(), sn(), model(), version(), batteryVolume(), raw(), clear()	Builds CPCL label commands for page setup, text, lines, barcodes, and images.	`begin` takes height/copies; `line/box` take coordinates and thickness; `image` takes data/byteWidth/height/compress.

Response Parsing

Object	Method / Command	Purpose	Parameters
NibEscResponseParser / NibTsplResponseParser / NibCpclResponseParser	parse(raw), parse(query, raw)	Parses printer responses into status, battery, text, MAC, event, or unknown response objects.	Returned structs include query, type, raw, rawHex, statusByte, statusFlags, isReady, battery, text, and description fields.

Practical recommendations

• Confirm whether the printer model supports ESC, TSPL, or CPCL before choosing a builder.
• Keep BLE permission, scanning, reconnect, and App lifecycle logic in the connection layer.
• The template layer should handle only paper size, coordinates, images, and text content.
• Validate write mode, MTU, credit notifications, large images, and continuous printing on real hardware.