WirelessPrinter SDK Reference

一、引言

1.1、编写目的

• 通过调用本开发包的接口函数，可以轻松实现文字、图片、条码等打印元素的排版和打印，无需了解复杂的打印机打印命令及原理。

• 客户可以使用 SDK 实现打印命令的生成以及打印机通讯。SDK 采用.framework 的形式。使用方法和系统动态框架一样。

  SDK文件：PrinterSDK.framwrok

• WirelessPinter 的主要作用是测试SDK 功能、测试打印机的功能、向客户演示功能以及提供针对 MPT-8 机型的文档打印功能。

• 本使用指南中所有的sample code 都以 Demo 工程中的实际代码为准。当拿到工程时，建议先编译工程进行真机安装，先测试 Demo 中的所有功能，对 Demo 和 SDK 提供的功能有一个大致的了解后再阅读本指南，引入 SDK 到您的工程中。

1.2、预期读者

​ 本文档的预期读者为开发本公司打印机关联的应用程序的用户、开发人员、项目经理、测试人员和文档编写人员，用来对项目涉及的业务知识和系统开发所需解决的问题、满足的需求达成共识。

1.2.1、开发人员要求

使用 WirelessPrinter iOS SDK 进行二次开发，您需要了解：

• 如何使用 framework 动态库（Dynamic Library）或静态库（Static Library）框架
• 稍微了解 CoreBluetooth 框架
• 稍微了解打印机的打印命令
• 了解您的打印机支持的打印命令
• 了解您的打印机支持的通讯模块（蓝牙或者 WiFi）
• 了解真机调试
• 若需要引入 PrinterCommandSwift.framework ,需要具备 Objective-C 和 Swift 联合编程经验

1.3、文中特殊的定义和缩写

1.3.1、定义

characteristic：BLE 蓝牙的特征值

services：BLE 蓝牙的服务

RSSI：BLE 蓝牙的信号强度

Dispatcher：通讯调度员，管理打印机的 WiFi 和 Bluetooth 4.0 通讯

1.3.2、缩写

BLE：蓝牙4.0、低功耗蓝牙，区别于4.0以前的传统蓝牙

SDK：指 PrinterCommand.framework，PrinterDispatch.framework， PrinterCommandSwift.framework

打印命令：SDK的作用是生成打印机能够直接识别执行的打印命令。在打印机行业中，打印命令种类繁多。在其他地方，你可能看到以指令集、协议、语言等类似的概念来表示打印命令，在这里统一规定为打印命令。

1.4、参考资料

• 《 esc-pos product v10.5.pdf 》
• 《 TSPL_TSPL2_Programming.pdf 》

二、SDK 更新及变化

变更类型：（A 增加），（ M 修订），（ D 删除）

三、开发环境配置

3.1、SDK 版本要求

Demo 工程运行在 iOS 8.0 及以上的机型上，但是 SDK 最低支持 iOS 5.0起。

3.2 、SDK 引入工程

3.2.1 Objective-C 用户

• Should Import：

  • PrinterSDK.framework


• 解压提供的 WirelessPrinter Demo 工程

• 在解压后的工程目录找到 PrinterSDK.framework，拖动到您的工程中。

• 检查和设置编译项

  • 点击工程

  • 点击 Targets 中的应用名字

  • 点击 General 选项卡

  • 检查Link Binary With Libraries一项，是否包含所需要的 framework，没有则手动添加。

  • 在Build Setting选项卡找到Other Link Flags 一项，填入 -ObjC，如图：

    注意：由于 SDK 中使用了 Category ，所以使用SDK时需要该编译项。

    

• 在要使用 SDK 的类文件中引入 SDK 框架：

  #import <PrinterSDK/PrinterSDK.h>
  

• 如果用到的指令在 PrinterCommandSwift.framework 中

  @import PrinterCommandSwift;
  

  ​

• 愉快的使用 SDK

3.2.2 Swift 用户

PrinterCommandSwift.framework 使用了 Swift 语言编写，当前支持 CPCL、DPL 指令集，需要配合 PrinterCommand.framework 进行连接打印机和处理图片等相关操作。

• Should Import：

  • PrinterSDK.framework
  • PrinterCommandSwift.framework


左边使用 Swift 调用，右边使用 Objective-C 调用

• 引用框架文件流程

  • 点击工程
  • 点击 Targets 中的应用名字
  • 点击 General 选项卡
  • 找到Embedded Binaries一项，点击 '+' 号添加所需要的 framework 动态库！
  • 检查Link Binary With Libraries一项，是否包含所需要的 framework，没有则添加。所有需要引入的动态库和静态库都要能在这里看到。
  • 简单说，framework 动态库库要同时出现在Embedded Binaries和Link Binary With Libraries两项中，静态库只需要出现在后一项中。
  • 一般添加Embedded Binaries中时，会自动添加到Link Binary With Libraries。当编译出现问题时，尝试删除这两项中的 framework 连接，重新添加。

• Should Import In Swift File

• import PrinterCommandSwift
  

• Should Import In OC-Swift Bridge Header File

  #import <PrinterSDK/PrinterSDK.h>
  

• 愉快的使用 SDK

3.3、 真机运行和调试


• 真机运行时，您需要修改 Bundle Identifier 和 Team 项
• Bundle Identifier 是程序包的唯一标识符，可以修改为任意字符串，但不能和 Apple 服务器已有记录的标志符冲突
• Team 选择您的 iOS 开发者帐号

3.4 、Archive 上架

• 当通过 Archive 打包准备上线 App Store 时，请将您的应用中的Enable Bitcode设置为NO.

四、WirelessPrinter Demo 介绍

4.1、 通过指令组合打印

根据不同的指令集不同，大致上提供了一下功能：

• 打印各式条形码
• 打印二维码
• 打印文本或者带格式的文本
• 打印图片（黑白图片、半色调图片）
• 打印小票（预定义格式的小票）

通过本 Demo，您可以了解到：

• 如何导入、链接和使用 PrinterSDK.framework 框架

• 如何通过 Bluetooth 4.0和 便携式 BLE 蓝牙打印机进行通讯

• 如何通过 WiFi 和便携式 WiFi 打印机进行通讯

• 如何使用打印机指令集中的基础指令，并根据自己的需求分装成为功能

  • Demo 中在 PTFunctionESC.m、PTFunctionTSPL.m 等类中演示了如何将基础指令封装形成功能，以便能够执行打印条形码、二维码、图片、文本等功能。
  • Demo 中在 PTTesESC.m、PTTestTSPL.m、PTTestCPCL.swift 等类中展示了测试打印机功能和 SDK 功能的函数。

4.2、 通过模板打印

​ 通过模板打印，电子面单的样式已经预先编辑好，只需要填充相应的数据项，即可打印输出一张面单。这里以申通快递为例，具体代码见 PTTestTSC 类。

1、填充数据

// 使用说明：
// 1. 初始化一个 NSMutableDictionary，在相应的键值下塞入对应的的数据，键值必须是下面样例中用到的键值。
// 2. 如果一个数据项没有数据 那么也需要设置成空字符串@""，比如 [templateDict setObject:@"" forKey:kCollection];
PTLabelTemplate *template = [[PTLabelTemplate alloc] init];
NSMutableDictionary *templateDict = [[NSMutableDictionary alloc] init];

[templateDict setObject:@"363604310467" forKey:LTBarcode];
[templateDict setObject:@"上海 上海市 长宁区" forKey:LTDistributing];
    
[templateDict setObject:@"申大通" forKey:LTReceiver];
[templateDict setObject:@"13826514987" forKey:LTReceiverContact];
[templateDict setObject:@"上海市宝山区共和新路4719弄共和小区12号306室" forKey:LTReceiverAddress];
    
[templateDict setObject:@"快小宝" forKey:LTSender];
[templateDict setObject:@"13826514987\r\n" forKey:LTSenderContact];
[templateDict setObject:@"上海市长宁区北瞿路1178号（鑫达商务楼）1号楼305室" forKey:LTSenderAddress];
    
[templateDict setObject:@"SHENTONG" forKey:LTExpressCompany];
    
NSData *cmdData = [template getShenTongTemplate:templateDict];

2、读入模板

使用时需要把模板文件拖入你的工程中。模板文件是 TXT 纯文本文件。

 NSString *path = [[NSBundle mainBundle] pathForResource:@"ShenTong" ofType:@"txt"];
 NSData *templateData = [template getTemplateDataWithFilePath:path];

3、结合模板和数据

NSMutableData *finalData = [[NSMutableData alloc] initWithData:templateData];
[finalData appendData:cmdData];

4、发送打印

[[PTDispatcher share] sendData:finalData];

4.3、 获取打印机的纸张状态

1、 当连接蓝牙时，必须订阅状态通知。

[[PTDispatcher share] connectBluetooth:peripheral notify:YES]; // 设置为 YES

2、 具体的获取纸张状态详见 Demo。

PTCommandVC 类中 getPaperStatus:方法

五、PrinterDispatch.framework

5.1、支持的通讯方式

• BLE：Bluetooth 4.0及以上，低功耗蓝牙，不支持传统蓝牙（Bluetooth 4.0 以下）
• WiFi：需要在 iOS 系统设置中连接 WiFi 打印机的热点

在一些 iOS 机型上，同时打开蓝牙和 WiFi 会导致蓝牙频繁断线，当频繁断线时，请尝试关闭 iOS 系统的WiFi 以保证蓝牙连接的稳定性。

• [了解如何通过 WiFi 或 Bluetooth 4.0 连接打印机](./html/Dispatch/How to connect with printer.html)

六、PrinterCommand.framework

6.1、支持的打印机指令集

您需要了解所使用的打印机是否支持以下任意一种或多种打印指令集

• [了解如何使用 ESC-POS 指令集](./html/Command/ESC-POS Command Reference.html)

• [了解如何使用 TSC-TSPL 指令集](./html/Command/TSC-TSPL Command Reference.html)

七、支持的打印机

• 打印机至少支持 WiFi 或者BLE 其中一种通讯方式。

• 打印机必须至少支持 ESC 、TSC、CPCL、ZPL、DPL 其中一种打印命令。

八、 PrinterCommandSwift.framework

• Command 部分：（Using Swift）

本框架当前只有指令部分，没有通讯部分和图片处理部分

当您不需要 CPCL 打印命令时，不需要引入此框架

当您需要 CPCL 打印命令时，除了需要引入此框架，还需要引入 PTPrinterSDK.Framework

七、API 导航

• 大致分为 Command、Dispatch、Function 三个部分：

• Command：打印机打印命令部分（Using Objective-C）

• Dispatch：打印机通讯（调度）部分（Using Objective-C、C）