iOS 电子纸设备刷图SDK - 支持NFC/蓝牙绑定、多算法抖点处理、Prism设备专属刷图
BrushSDK 是一款专为 iOS 平台设计的电子纸设备刷图SDK，核心解决电子纸设备的绑定、图像预处理、刷图指令下发等核心问题。SDK 支持两种设备绑定方式（NFC/二维码蓝牙）、三种图像抖点算法（暖色调/冷色调/色阶）、普通设备/Prism设备差异化刷图流程，适配多种电子纸设备型号（包含单屏/双面桌牌、手机壳等设备）。
BrushSDKDemo.xcodeproj 文件BrushSDK/
│
├── Core/ # 核心工具层（Demo 中核心逻辑封装）
│ ├── XTDeviceConfig.h/m # 设备配置模型（存储/读取/判断设备信息）
│ ├── XTImageDitherUtils.h/m # 图像抖点处理工具（多算法转换）
│ ├── NFCHelper.h/m # NFC通信核心（绑定/刷图/指令下发）
│ ├── XTBleWriteHelper.h/m # 蓝牙通信核心（绑定/刷图/设备扫描）
│ ├── UtilsMacros.h # 全局宏定义（算法常量）
├── Controllers/ # 界面层（Demo 中可直接复用的业务页面）
│ ├── MainViewController.h/m # 设备管理主界面（绑定/刷图入口）
│ ├── PrismBrushController.h/m # Prism设备刷图页面
│ ├── BrushScreenController.h/m # 普通设备刷图预览（算法切换/指令下发）
├── Resources/ # 资源文件（Demo 中国际化/宏定义）
│ ├── Localizable.strings # 国际化文案
核心API文档
1. XTDeviceConfig（设备配置模型）
// 导入头文件
#import "XTDeviceConfig.h"
// 读取本地缓存的设备配置
XTDeviceConfig *deviceConfig = [XTDeviceConfig readLocalCfg];
// 保存设备配置到本地缓存
[XTDeviceConfig saveLocalCfg:deviceConfig];
// 判断当前设备是否为 Prism 设备
BOOL isPrism = [XTDeviceConfig isPrismDevice];
// 判断是否为双面桌牌双面板（双屏）设备
BOOL isDoubleScreen = [deviceConfig isNameCardDevice];
// 判断是否为手机壳设备
BOOL isPhoneCase = [deviceConfig isPhoneCaseDevice];
// 判断非手机壳设备是否需要蓝牙传输
BOOL isBleTransfer = [deviceConfig isBluetoothTransferWhenNFCReading];
2. XTImageDitherUtils（图像抖点工具）
// 导入头文件
#import "XTImageDitherUtils.h"
#import "UtilsMacros.h" // 包含算法类型常量
// 图像抖点转换（生成设备可识别数据）
UIImage *originalImage = [UIImage imageNamed:@"test.png"];
UIImage *previewImage = nil;
NSData *imageData = [XTImageDitherUtils convertToUploadData:originalImage
previewImage:&previewImage
deviceCfg:deviceConfig
algType:ALG_TYPE_WARM];
// 生成上传数据数组（蓝牙刷图需要）
NSMutableArray *uploadDataArr = [XTImageDitherUtils getUploadDataFromDitherImage:previewImage
deviceCfg:deviceConfig];
3. NFCHelper（NFC 通信工具）
// 导入头文件
#import "NFCHelper.h"
// 获取NFC单例实例
NFCHelper *nfcHelper = [NFCHelper shareInstance];
// 读取 NFC 设备配置（绑定设备）
NSString *bindResult = [nfcHelper getDeviceConfig:@"请将设备贴近NFC区域" isNeedScanTip:YES];
// NFC 下发刷图指令（单屏设备/手机壳设备）
NSString *brushResult = [nfcHelper importImageToDevice:@"正在刷图..."
imageData:imageData
imageDataXT:uploadDataArr
screenCfg:deviceConfig
imageSectionNumber:0 // 单屏设备固定传0
pin:nil
PageSize:490
IntervalTime:50];
4. XTBleWriteHelper（蓝牙通信工具）
// 导入头文件
#import "XTBleWriteHelper.h"
// 获取蓝牙单例实例
XTBleWriteHelper *bleHelper = [XTBleWriteHelper shareInstance];
// 扫描指定 MAC 地址的蓝牙设备（绑定设备）
[bleHelper startScanWithTargetMac:@"设备MAC地址" completion:^(XTDeviceConfig *config, NSError *error) {
if (!error) {
// 绑定成功，保存配置
[XTDeviceConfig saveLocalCfg:config];
} else {
NSLog(@"蓝牙绑定失败：%@", error.localizedDescription);
}
}];
// 蓝牙下发刷图指令（单屏设备）
[bleHelper importImageDataToDeviceWithImageHexDataArr:uploadDataArr
deviceConfig:deviceConfig
sendSize:244 // 固定值244，手机壳设备可传490
writeImageBlock:^(BOOL success, NSString *error) {
if (success) {
NSLog(@"蓝牙刷图成功");
} else {
NSLog(@"蓝牙刷图失败：%@", error);
}
} advData:^(NSString *RSSI, NSString *power, NSString *version) {
// 设备状态回调
NSLog(@"信号强度：%@，功率：%@，版本：%@", RSSI, power, version);
}];
// 蓝牙下发刷图指令（双面板/双屏设备 - 专用API）
/**
* @brief 导入双面图像数据到设备（双面板写屏+刷屏操作）
* @param hexDataArrA A面图像数据的十六进制分包数组（已按指定大小拆分的数据包）
* @param hexDataArrB B面图像数据的十六进制分包数组（已按指定大小拆分的数据包）
* @param deviceConfig 写屏时的设备配置信息（用于校验与当前连接设备是否匹配）
* @param sendSize 每次发送的分包大小（需根据设备性能调整，建议244或490；490适用于手机壳设备）
* @param writeImageBlock 写图操作完成后的回调Block
* @param advData 蓝牙广播数据（RSSI/电量/版本）的回调Block
*/
[bleHelper importImageDataToDeviceWithImageHexDataArrA:hexDataArrA // A面（左屏）数据
hexDataArrB:hexDataArrB // B面（右屏）数据
deviceConfig:deviceConfig
sendSize:244
writeImageBlock:^(BOOL success, NSString *error) {
if (success) {
NSLog(@"双屏蓝牙刷图成功");
} else {
NSLog(@"双屏蓝牙刷图失败：%@", error);
}
} advData:^(NSString *RSSI, NSString *power, NSString *version) {
// 设备状态回调
NSLog(@"信号强度：%@，功率：%@，版本：%@", RSSI, power, version);
}];
配置说明
1. Info.plist 权限配置
需在项目的 Info.plist 中添加以下权限配置（Demo 工程中已配置，可直接拷贝）：
<!-- NFC 权限 -->
<key>NFCReaderUsageDescription</key>
<string>需要NFC权限以绑定和刷图电子纸设备</string>
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
<string>TAG</string>
</array>
<!-- 蓝牙权限 -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限以绑定和刷图电子纸设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙权限以绑定和刷图电子纸设备</string>
<!-- 相册权限 -->
<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册以选择刷图图片</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>需要保存权限以存储刷图预览图</string>
2. 算法类型常量配置
从 Demo 的 UtilsMacros.h 中拷贝以下算法常量定义：
// XTEnum.h 中定义（Demo 中已封装）
#define ALG_TYPE_WARM @"WARM" // 暖色调抖动算法
#define ALG_TYPE_COLD @"COLD" // 冷色调抖动算法
#define ALG_TYPE_COLOR @"COLOR" // 色阶算法
使用流程
1. 环境准备（基于 SDK 开发）
- 真机测试（模拟器不支持 NFC/蓝牙功能）
- 电子纸设备（普通设备/Prism设备/单屏/双面桌牌/手机壳）
- 开启设备的 NFC/蓝牙功能
- 确保项目已配置好开发者证书（可正常运行到真机）
2. SDK 核心调用流程
// 完整调用流程示例
#import "XTDeviceConfig.h"
#import "XTImageDitherUtils.h"
#import "NFCHelper.h"
#import "XTBleWriteHelper.h"
#import "UtilsMacros.h"
- (void)completeBrushFlow {
// 1. 读取设备配置（无配置则先绑定）
XTDeviceConfig *deviceConfig = [XTDeviceConfig readLocalCfg];
if (!deviceConfig) {
NSLog(@"请先绑定设备");
return;
}
// 2. 选择原始图片
UIImage *originalImage = [UIImage imageNamed:@"test.png"];
// 3. 图像抖点处理
UIImage *previewImage = nil;
NSData *imageData = [XTImageDitherUtils convertToUploadData:originalImage
previewImage:&previewImage
deviceCfg:deviceConfig
algType:ALG_TYPE_WARM];
NSMutableArray *uploadDataArr = [XTImageDitherUtils getUploadDataFromDitherImage:previewImage
deviceCfg:deviceConfig];
// 4. 判断设备类型，选择对应的传输方式刷图
if ([deviceConfig isPhoneCaseDevice]) {
// 手机壳设备：使用NFC传输
NFCHelper *nfcHelper = [NFCHelper shareInstance];
NSString *result = [nfcHelper importImageToDevice:@"正在刷图..."
imageData:imageData
imageDataXT:uploadDataArr
screenCfg:deviceConfig
imageSectionNumber:0
pin:nil
PageSize:490
IntervalTime:50];
if ([result containsString:@"成功"]) {
NSLog(@"刷图成功");
} else {
NSLog(@"刷图失败：%@", result);
}
} else {
// 非手机壳设备：使用蓝牙传输
XTBleWriteHelper *bleHelper = [XTBleWriteHelper shareInstance];
[bleHelper importImageDataToDeviceWithImageHexDataArr:uploadDataArr
deviceConfig:deviceConfig
sendSize:244
writeImageBlock:^(BOOL success, NSString *error) {
if (success) {
NSLog(@"刷图成功");
} else {
NSLog(@"刷图失败：%@", error);
}
} advData:^(NSString *RSSI, NSString *power, NSString *version) {}];
}
}
设备适配与特殊处理
1. 传输方式说明
根据设备类型选择对应的传输方式：
- 手机壳设备：
- 通过
isPhoneCaseDevice 方法判定为手机壳设备时
- 传输工具固定使用
NFCHelper
- 非手机壳设备：
- 通过
isBluetoothTransferWhenNFCReading 方法判定为非手机壳设备时
- 可先通过 NFC 完成绑定，传输工具使用
XTBleWriteHelper
- 也可以先通过
XTBleWriteHelper 扫描完成绑定，传输工具使用 XTBleWriteHelper
2. 一些常见的设备编号对照表
设备编号
设备型号
特殊说明
102
1.69充电宝
无特殊要求
105
4寸工牌
无特殊要求
120
4寸相册
无特殊要求
121
3.97色柔性屏蓝牙工牌
无特殊要求
单双屏设备使用说明
提示：SDK 中双屏设备特指「双面桌牌双面板电子纸设备」，单屏为常规电子纸设备；双屏设备需使用专属的蓝牙刷图API，不可复用单屏API。
1. 单双屏设备判断
// 读取设备配置
XTDeviceConfig *deviceConfig = [XTDeviceConfig readLocalCfg];
// 判断是否为双屏（双面桌牌）设备
if ([deviceConfig isNameCardDevice]) {
NSLog(@"当前设备为双屏双面桌牌设备 - 需使用双屏专用API");
// 执行双屏刷图逻辑
} else {
NSLog(@"当前设备为单屏设备 - 使用单屏API");
// 执行单屏刷图逻辑
}
2. 单屏设备刷图（常规流程）
// 单屏设备蓝牙刷图示例
[bleHelper importImageDataToDeviceWithImageHexDataArr:singleUploadDataArr
deviceConfig:deviceConfig
sendSize:244
writeImageBlock:^(BOOL success, NSString *error) {
if (success) {
NSLog(@"单屏蓝牙刷图成功");
} else {
NSLog(@"单屏蓝牙刷图失败：%@", error);
}
} advData:^(NSString *RSSI, NSString *power, NSString *version) {
// 设备状态回调
NSLog(@"信号强度：%@，功率：%@，版本：%@", RSSI, power, version);
}];
3. 双屏设备刷图（双面板专用API）
// 双屏设备蓝牙刷图示例（A/B面同时刷图）
XTDeviceConfig *deviceConfig = [XTDeviceConfig readLocalCfg];
if ([deviceConfig isNameCardDevice]) {
// 1. 准备A/B面图像数据（需分别处理）
NSMutableArray *hexDataArrA = [XTImageDitherUtils getUploadDataFromDitherImage:previewAImage
deviceCfg:deviceConfig];
NSMutableArray *hexDataArrB = [XTImageDitherUtils getUploadDataFromDitherImage:previewBImage
deviceCfg:deviceConfig];
// 2. 调用双屏专用API刷图
[bleHelper importImageDataToDeviceWithImageHexDataArrA:hexDataArrA
hexDataArrB:hexDataArrB
deviceConfig:deviceConfig
sendSize:244
writeImageBlock:^(BOOL success, NSString *error) {
if (success) {
NSLog(@"双屏（A/B面）刷图成功");
} else {
NSLog(@"双屏刷图失败：%@", error);
}
} advData:^(NSString *RSSI, NSString *power, NSString *version) {
// 设备状态回调
NSLog(@"信号强度：%@，功率：%@，版本：%@", RSSI, power, version);
}];
}
支持与联系
- 📧 邮箱：lingzhengqi@seekink.com