WirelessPrinter SDK Reference

一、引言

1.1、編寫目的

• 通過調用本開發(fā)包的接口函數，可以輕松實現文字、圖片、條碼等打印元素的排版和打印，無需了解復雜的打印機打印命令及原理。

• 客戶可以使用 SDK 實現打印命令的生成以及打印機通訊。SDK 采用.framework 的形式。使用方法和系統(tǒng)動態(tài)框架一樣。

  SDK文件：PrinterSDK.framwrok

• WirelessPinter 的主要作用是測試SDK 功能、測試打印機的功能、向客戶演示功能以及提供針對 MPT-8 機型的文檔打印功能。

• 本使用指南中所有的sample code 都以 Demo 工程中的實際代碼為準。當拿到工程時，建議先編譯工程進行真機安裝，先測試 Demo 中的所有功能，對 Demo 和 SDK 提供的功能有一個大致的了解后再閱讀本指南，引入 SDK 到您的工程中。

1.2、預期讀者

? 本文檔的預期讀者為開發(fā)本公司打印機關聯(lián)的應用程序的用戶、開發(fā)人員、項目經理、測試人員和文檔編寫人員，用來對項目涉及的業(yè)務知識和系統(tǒng)開發(fā)所需解決的問題、滿足的需求達成共識。

1.2.1、開發(fā)人員要求

使用 WirelessPrinter iOS SDK 進行二次開發(fā)，您需要了解：

• 如何使用 framework 動態(tài)庫（Dynamic Library）或靜態(tài)庫（Static Library）框架
• 稍微了解 CoreBluetooth 框架
• 稍微了解打印機的打印命令
• 了解您的打印機支持的打印命令
• 了解您的打印機支持的通訊模塊（藍牙或者 WiFi）
• 了解真機調試
• 若需要引入 PrinterCommandSwift.framework ,需要具備 Objective-C 和 Swift 聯(lián)合編程經驗

1.3、文中特殊的定義和縮寫

1.3.1、定義

characteristic：BLE 藍牙的特征值

services：BLE 藍牙的服務

RSSI：BLE 藍牙的信號強度

Dispatcher：通訊調度員，管理打印機的 WiFi 和 Bluetooth 4.0 通訊

1.3.2、縮寫

BLE：藍牙4.0、低功耗藍牙，區(qū)別于4.0以前的傳統(tǒng)藍牙

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

打印命令：SDK的作用是生成打印機能夠直接識別執(zhí)行的打印命令。在打印機行業(yè)中，打印命令種類繁多。在其他地方，你可能看到以指令集、協(xié)議、語言等類似的概念來表示打印命令，在這里統(tǒng)一規(guī)定為打印命令。

1.4、參考資料

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

二、SDK 更新及變化

變更類型：（A 增加），（ M 修訂），（ D 刪除）

三、開發(fā)環(huán)境配置

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 動態(tài)庫！
  • 檢查Link Binary With Libraries一項，是否包含所需要的 framework，沒有則添加。所有需要引入的動態(tài)庫和靜態(tài)庫都要能在這里看到。
  • 簡單說，framework 動態(tài)庫庫要同時出現在Embedded Binaries和Link Binary With Libraries兩項中，靜態(tài)庫只需要出現在后一項中。
  • 一般添加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 開發(fā)者帳號

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 等類中演示了如何將基礎指令封裝形成功能，以便能夠執(zhí)行打印條形碼、二維碼、圖片、文本等功能。
  • 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:@"上海 上海市 長寧區(qū)" forKey:LTDistributing];
    
[templateDict setObject:@"申大通" forKey:LTReceiver];
[templateDict setObject:@"13826514987" forKey:LTReceiverContact];
[templateDict setObject:@"上海市寶山區(qū)共和新路4719弄共和小區(qū)12號306室" forKey:LTReceiverAddress];
    
[templateDict setObject:@"快小寶" forKey:LTSender];
[templateDict setObject:@"13826514987\r\n" forKey:LTSenderContact];
[templateDict setObject:@"上海市長寧區(qū)北瞿路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、發(fā)送打印

[[PTDispatcher share] sendData:finalData];

4.3、 獲取打印機的紙張狀態(tài)

1、 當連接藍牙時，必須訂閱狀態(tài)通知。

[[PTDispatcher share] connectBluetooth:peripheral notify:YES]; // 設置為 YES

2、 具體的獲取紙張狀態(tài)詳見 Demo。

PTCommandVC 類中 getPaperStatus:方法

五、PrinterDispatch.framework

5.1、支持的通訊方式

• BLE：Bluetooth 4.0及以上，低功耗藍牙，不支持傳統(tǒng)藍牙（Bluetooth 4.0 以下）
• WiFi：需要在 iOS 系統(tǒng)設置中連接 WiFi 打印機的熱點

在一些 iOS 機型上，同時打開藍牙和 WiFi 會導致藍牙頻繁斷線，當頻繁斷線時，請嘗試關閉 iOS 系統(tǒng)的WiFi 以保證藍牙連接的穩(wěn)定性。

• [了解如何通過 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）