Objective-C SDK

Objective-C SDK 适用于 iOS 原生应用开发，通过 BLE（低功耗蓝牙）连接打印机设备。

安装

1. 下载 Framework

从 GitHub 下载 Framework：Package Center

2. 导入 Framework

必须导入：

adapter.framework - 设备适配器
father.framework - 核心框架

按需导入：

cpcl.framework - CPCL 指令
esc.framework - ESC 指令
tspl.framework - TSPL 指令

3. 选择 API

根据打印机指令类型导入对应 API：

指令类型	导入头文件
ESC	`IbridgeBleApi`
CPCL	`FscBleApi`
TSPL	`applebleApi`

快速开始

初始化

@interface PrinterVC ()
@property (nonatomic, strong) CBPeripheral *currentConnectedPeripheral;
@property (nonatomic, strong) Lifecycle *lifeCycle;
@end

@implementation PrinterVC

- (void)viewDidLoad {
    [super viewDidLoad];

    // 初始化生命周期
    _lifeCycle = [[Lifecycle alloc] init];
    _lifeCycle.connectedDevice(self.device);
}

ESC 指令使用

ESC 指令广泛用于热敏小票打印机。详细指令说明请参考 ESC 指令文档。

初始化 ESC

#import <esc/esc.h>

@property (nonatomic, strong) AYEscCommand *esc;

- (void)setupESC {
    _esc = [AYEscCommand new];
}

完整打印流程

推荐顺序：

唤醒打印机
使能打印机
打印图片
打印定位（连续纸不需要）
结束打印任务

// 初始化 ESC 指令对象
AYEscCommand *esc = [AYEscCommand new];
// 唤醒指令
[esc wake];
// 使能打印机
[esc enable];
// 打印图片
[esc image:[UIImage imageNamed:@"label.png"] compress:NO mode:Normal];
// 标签打印定位（连续纸不需要定位！）
[esc position];
// 结束打印任务
[esc stopPrintJob];
// 通过蓝牙发送指令
[self.bleHelper writeCommands:esc.commands];

打印指令

唤醒打印机

[esc wake];

使能打印机

[esc enable];

打印图片

typedef NS_ENUM(NSInteger, EImageMode) {
    Normal = 0,      // 正常打印
    DoubleWidth,     // 倍宽打印
    DoubleHeight,    // 倍高打印
    DoubleAll        // 倍宽倍高打印
};

/**
 * 打印图片
 * @param image 图片
 * @param compress 是否压缩
 * @param mode 打印模式
 */
[esc image:image compress:NO mode:Normal];

打印定位

[esc position];

结束打印任务

[esc stopPrintJob];

设置指令

设置关机时间

/**
 * 设置关机时间
 * @param time 关机时间，单位：分钟，不关机传 0
 */
AYEscCommand *esc = [AYEscCommand new];
[esc shutTime:10];
[self.bleHelper writeCommands:esc.commands];
// 设置成功会调用回调 escSettingChange

设置浓度

typedef NS_ENUM(NSInteger, EThickness) {
    EThicknessLow,      // 低浓度
    EThicknessMedium,   // 中浓度
    EThicknessHigh      // 高浓度
};

AYEscCommand *esc = [AYEscCommand new];
[esc thickness:EThicknessMedium];
[self.bleHelper writeCommands:esc.commands];

设置纸张类型（A4）

typedef NS_ENUM(NSInteger, EPaperType) {
    EPaperTypeBlackMark = 0,    // 黑标纸模式
    EPaperTypeContinuous,       // 连续纸模式
    EPaperTypeGap,              // 缝隙纸模式
    EPaperTypeHole,             // 打孔纸模式
    EPaperTypeTattoo,           // 纹身纸模式
    EPaperTypeTattooWrinkles,   // 纹身纸（防皱模式）
};

AYEscCommand *esc = [AYEscCommand new];
[esc paperType:EPaperTypeContinuous];
[self.bleHelper writeCommands:esc.commands];

设置纸张类型（Q1/Q2/Q3/D11/D30/B21/B22）

typedef NS_ENUM(NSInteger, EPaperTypeQX) {
    EPaperTypeQXGap,              // 缝隙纸模式
    EPaperTypeQXBlackMark,        // 黑标纸模式
    EPaperTypeQXContinuous,       // 连续纸模式
};

AYEscCommand *esc = [AYEscCommand new];
[esc paperTypeQX:EPaperTypeQXGap];
[self.bleHelper writeCommands:esc.commands];

查询指令

AYEscCommand *esc = [AYEscCommand new];

// 查询打印机信息
[esc printerInfo];

// 查询打印机状态
[esc state];

// 查询电量
[esc batteryVol];

// 查询蓝牙名称
[esc btName];

// 查询打印固件版本
[esc printerVersion];

// 查询 MAC 地址
[esc mac];

// 查询 SN 号
[esc sn];

// 查询打印型号
[esc printerModel];

// 发送指令
[self.bleHelper writeCommands:esc.commands];

主动上报

设备状态上报

当打印机有异常状态时，会主动向 APP 发送两个字节的状态。结果请参考 Demo 中的 onPrinterAutoReport 回调。

数据头	状态类型	解析
0xFF	0x00	打印机正常
0xFF	0x01	过热
0xFF	0x02	开盖
0xFF	0x04	缺纸
0xFF	0x08	低压

纸张类型上报

设备侦测到实际纸张与 APP 设置纸张类型不匹配时，会主动上报：

数据头	状态类型	解析
0xFE	0x01	折叠黑标纸
0xFE	0x02	连续卷筒纸
0xFE	0x03	不干胶缝隙纸

中止打印任务上报

数据头	状态类型	解析
0xFD	0x01	开始清除当前页面打印任务
0xFD	0x02	清除当前打印任务结束

TSPL 指令使用

TSPL 指令用于标签条码打印机。详细指令说明请参考 TSPL 指令文档。

初始化

#import <tspl/tspl.h>
#import <tspl/GenericTSPL.h>

@property (nonatomic, strong) BasicTSPL *basicTspl;

- (void)setupTSPL {
    _basicTspl = [[BasicTSPL alloc] init];
    _basicTspl.BasicTSPL(_lifeCycle, TSPLPrinter_GENERIC);

    // 设置回调
    __weak typeof(self) weakSelf = self;
    _basicTspl.read = ^(NSData *revData, NSError *error) {
        NSLog(@"打印机回传: %@", revData);
    };

    _basicTspl.bleDidConnectPeripheral = ^(CBPeripheral *peripheral) {
        NSLog(@"连接成功: %@", peripheral.name);
    };

    _basicTspl.bleDidDisconnectPeripheral = ^(CBPeripheral *peripheral, NSError *error) {
        NSLog(@"连接断开: %@", error);
    };
}

打印标签

- (void)printLabel {
    _basicTspl
        // 页面设置
        .page([[TPage alloc] init].width(100).height(180))
        .direction([[TDirection alloc] init].direction(UP_OUT).mirror(NO_MIRROR))
        .gap(true)
        .cut(true)
        .speed(6)
        .density(6)
        .cls()

        // 绘制内容
        .bar([[TBar alloc] init].x(300).y(10).width(4).height(90))
        .bar([[TBar alloc] init].x(30).y(100).width(740).height(4))

        // 打印文字
        .text([[TText alloc] init]
            .x(400).y(25)
            .font(TSS24)
            .xmulti(3).ymulti(3)
            .content(@"上海浦东"))

        // 打印条码
        .barcode([[TBarcode alloc] init]
            .x(50).y(300)
            .type(@"128")
            .height(60)
            .content(@"1234567890"))

        // 执行打印
        .print(1);
}

CPCL 指令使用

CPCL 指令用于便携式标签打印机。详细指令说明请参考 CPCL 指令文档。

初始化

#import <cpcl/cpcl.h>

@property (nonatomic, strong) BasicCPCL *basicCpcl;

- (void)setupCPCL {
    _basicCpcl = [[BasicCPCL alloc] init];
    _basicCpcl.BasicCPCL(_lifeCycle);
}

打印标签

_basicCpcl
    .page([[CPCLPage alloc] init].width(576).height(400))
    .text([[CPCLText alloc] init].x(50).y(50).content(@"商品标签"))
    .barcode([[CPCLBarcode alloc] init].x(50).y(150).content(@"1234567890"))
    .print();

权限配置

在 Info.plist 中添加：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限来连接打印机</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙权限来连接打印机</string>

示例项目

完整示例请参考：

Objective-C SDK

安装

1. 下载 Framework

2. 导入 Framework

3. 选择 API

快速开始

初始化

ESC 指令使用

初始化 ESC

完整打印流程

打印指令

唤醒打印机

使能打印机

打印图片

打印定位

结束打印任务

设置指令

设置关机时间

设置浓度

设置纸张类型（A4）

设置纸张类型（Q1/Q2/Q3/D11/D30/B21/B22）

查询指令

主动上报

设备状态上报

纸张类型上报

中止打印任务上报

TSPL 指令使用

初始化

打印标签

CPCL 指令使用

初始化

打印标签

权限配置

示例项目

参考文档