蓝牙连接 (TSBleConnect)

蓝牙连接模块提供了完整的蓝牙设备搜索、连接、绑定和管理功能。支持设备扫描、连接状态跟踪、认证、数据准备等完整的连接生命周期管理。

前提条件

iOS 设备支持蓝牙 4.0 (BLE) 或更高版本
应用已获得蓝牙权限（NSBluetoothPeripheralUsageDescription）
蓝牙已启用且处于可用状态
用户 ID 已获取，用于设备绑定和连接

数据模型

TSBleConnectionState

属性名	类型	说明
`eTSBleStateDisconnected`	`NSUInteger`	未连接（初始状态或任何失败/断开后）
`eTSBleStateConnecting`	`NSUInteger`	连接中（正在建立BLE物理连接）
`eTSBleStateAuthenticating`	`NSUInteger`	认证中（正在执行绑定/登录认证）
`eTSBleStatePreparingData`	`NSUInteger`	准备数据中（认证成功后正在获取设备信息）
`eTSBleStateConnected`	`NSUInteger`	已连接且就绪（完全连接，可进行数据操作）

TSScanCompletionReason

属性名	类型	说明
`eTSScanCompleteReasonTimeout`	`NSInteger`	扫描超时
`eTSScanCompleteReasonBleNotReady`	`NSInteger`	蓝牙未准备好
`eTSScanCompleteReasonPermissionDenied`	`NSInteger`	权限被拒绝
`eTSScanCompleteReasonUserStopped`	`NSInteger`	用户主动停止
`eTSScanCompleteReasonSystemError`	`NSInteger`	系统错误
`eTSScanCompleteReasonNotSupport`	`NSInteger`	不支持

TSBleStatus

属性名	类型	说明
`TSBleDisconnected`	`NSInteger`	未连接
`TSBleConnected`	`NSInteger`	已连接（物理连接已建立）
`TSBleReady`	`NSInteger`	已就绪（已连接且打开了Notify/SPP）

TSBluetoothInfo

属性名	类型	说明
`macAddress`	`NSString *`	蓝牙MAC地址（冒号分隔格式，如"DE:82:47:15:28:B0"），可能为nil
`name`	`NSString *`	蓝牙名称，可能为nil
`status`	`TSBleStatus`	蓝牙适配器连接状态

TSBluetoothSystem

属性名	类型	说明
`bleInfo`	`TSBluetoothInfo *`	BLE（低功耗蓝牙）信息
`btInfo`	`TSBluetoothInfo *`	BT（经典蓝牙）信息

TSPeripheralConnectParam

属性名	类型	说明
`userId`	`NSString *`	设备连接的用户ID（必需）
`userInfo`	`TSUserInfoModel *`	设备连接的用户信息模型
`authCode`	`NSString *`	设备绑定时通过扫描二维码获得的随机码
`allowConnectWithBT`	`BOOL`	标识是否允许蓝牙连接
`brand`	`NSString *`	手机品牌信息
`model`	`NSString *`	手机型号信息
`systemVersion`	`NSString *`	手机系统版本

TSPeripheralScanParam

属性名	类型	说明
`userId`	`NSString *`	设备连接的用户ID
`serviceUUIDs`	`NSArray<CBUUID > `	过滤外设的服务UUID数组，nil表示不过滤
`solicitedServiceUUIDs`	`NSArray<CBUUID > `	Solicited Service UUID过滤，nil表示不过滤
`deviceName`	`NSString *`	设备名称过滤，nil表示不过滤
`macAddress`	`NSString *`	MAC地址过滤，nil表示不过滤
`onlyUnconnected`	`BOOL`	是否只返回未连接的外设
`allowDuplicates`	`BOOL`	是否允许重复发现同一设备
`scanTimeout`	`NSInteger`	扫描超时时间（秒），0表示无超时

TSPeripheral

属性名	类型	说明
`systemInfo`	`TSPeripheralSystem *`	系统相关信息（蓝牙外设对象、MAC地址等）
`screenInfo`	`TSPeripheralScreen *`	屏幕相关信息（屏幕尺寸、形状等）
`projectInfo`	`TSPeripheralProject *`	项目相关信息（项目ID、固件版本等）
`capability`	`TSPeripheralCapability *`	设备能力信息
`limitation`	`TSPeripheralLimitations *`	设备功能限制

TSPeripheralSystem

属性名	类型	说明
`peripheral`	`CBPeripheral *`	蓝牙外设对象
`central`	`CBCentralManager *`	蓝牙中心管理器
`uuid`	`NSString *`	外设UUID字符串（只读）
`mac`	`NSString *`	设备MAC地址（冒号分隔标准格式）
`bleName`	`NSString *`	设备蓝牙名称
`RSSI`	`NSNumber *`	蓝牙信号强度
`advertisementData`	`NSDictionary *`	广播数据

TSPeripheralProject

属性名	类型	说明
`projectId`	`NSString *`	项目标识符
`companyId`	`NSString *`	公司标识符（从制造商数据提取）
`brand`	`NSString *`	设备品牌
`model`	`NSString *`	设备型号
`firmVersion`	`NSString *`	固件版本号
`virtualVersion`	`NSString *`	虚拟版本号
`serialNumber`	`NSString *`	设备序列号
`mainProjNum`	`NSString *`	主项目号
`subProjNum`	`NSString *`	子项目号

TSPeripheralScreen

属性名	类型	说明
`shape`	`TSPeriphShape`	设备外形（圆形、正方形、竖屏、横屏等）
`screenSize`	`CGSize`	设备屏幕尺寸（像素）
`screenBorderRadius`	`CGFloat`	设备屏幕圆角半径（像素）
`dialPreviewSize`	`CGSize`	表盘预览图尺寸（像素）
`dialPreviewBorderRadius`	`CGFloat`	表盘预览图圆角半径（像素）
`videoPreviewSize`	`CGSize`	视频预览流尺寸（像素）
`videoPreviewBorderRadius`	`CGFloat`	视频预览流圆角半径（像素）

TSPeripheralCapability

属性名	类型	说明
`featureAbility`	`TSFeatureAbility *`	功能模块能力（粗粒度能力标志）
`messageAbility`	`TSMessageAbility *`	消息通知能力（细粒度消息类型支持）
`dailyActivityAbility`	`TSDailyActivityAbility *`	每日活动能力（细粒度活动类型支持）
`sleepAlgorithm`	`NSInteger`	设备睡眠算法类型（0=最长夜间段，1=仅最长段）

TSFeatureAbility

属性名	类型	说明
`originAbility`	`NSData *`	从设备获取的最原始能力数据
`supportCapabilities`	`TSPeripheralSupportAbility`	设备功能支持标志集
`isSupportStepCounting`	`BOOL`	是否支持计步功能
`isSupportDistanceCounting`	`BOOL`	是否支持距离计数功能
`isSupportCalorieCounting`	`BOOL`	是否支持卡路里计数功能
`isSupportHeartRate`	`BOOL`	是否支持心率监测功能
`isSupportBloodPressure`	`BOOL`	是否支持血压监测功能
`isSupportBloodOxygen`	`BOOL`	是否支持血氧监测功能
`isSupportStress`	`BOOL`	是否支持压力监测功能
`isSupportSleep`	`BOOL`	是否支持睡眠监测功能
`isSupportTemperature`	`BOOL`	是否支持体温监测功能
`isSupportECG`	`BOOL`	是否支持心电图监测功能
`isSupportFemaleHealth`	`BOOL`	是否支持女性健康功能
`isSupportInitiateWorkout`	`BOOL`	是否支持发起运动功能
`isSupportWeightManagement`	`BOOL`	是否支持体重管理功能
`isSupportReminders`	`BOOL`	是否支持提醒功能
`isSupportCallManagement`	`BOOL`	是否支持来电管理功能
`isSupportAppNotifications`	`BOOL`	是否支持应用通知功能
`isSupportMusicControl`	`BOOL`	是否支持音乐控制功能
`isSupportWeatherDisplay`	`BOOL`	是否支持天气显示功能
`isSupportFindMyPhone`	`BOOL`	是否支持查找手机功能
`isSupportAlarmClock`	`BOOL`	是否支持闹钟功能
`isSupportWorldClock`	`BOOL`	是否支持世界时钟功能
`isSupportMapNavigation`	`BOOL`	是否支持地图导航功能
`isSupportShakeCamera`	`BOOL`	是否支持摇一摇拍照功能
`isSupportCameraPreview`	`BOOL`	是否支持相机视频预览功能
`isSupportEWallet`	`BOOL`	是否支持电子钱包功能
`isSupportBusinessCard`	`BOOL`	是否支持电子名片功能
`isSupportPhotoAlbum`	`BOOL`	是否支持相册功能
`isSupportEBook`	`BOOL`	是否支持电子书功能
`isSupportVoiceRecording`	`BOOL`	是否支持录音功能
`isSupportAppStore`	`BOOL`	是否支持应用商店功能
`isSupportMotionGames`	`BOOL`	是否支持体感游戏功能
`isSupportSportUpload`	`BOOL`	是否支持运动上传功能
`isSupportERNIEBot`	`BOOL`	是否支持文心一言功能
`isSupportChatGPT`	`BOOL`	是否支持ChatGPT
`isSupportLoversFeature`	`BOOL`	是否支持情侣功能
`isSupportContacts`	`BOOL`	是否支持联系人功能
`isSupportEmergencyContacts`	`BOOL`	是否支持紧急联系人功能
`isSupportMuslimPrayer`	`BOOL`	是否支持穆斯林祈祷功能
`isSupportQiblaCompass`	`BOOL`	是否支持朝拜指南针功能
`isSupportNFCPayment`	`BOOL`	是否支持NFC支付功能
`isSupportVoiceAssistant`	`BOOL`	是否支持语音助手功能
`isSupportFacePush`	`BOOL`	是否支持表盘推送功能
`isSupportCustomFace`	`BOOL`	是否支持自定义表盘功能
`isSupportSlideshowFace`	`BOOL`	是否支持幻灯片表盘功能
`isSupportDialComponent`	`BOOL`	是否支持表盘组件功能
`isSupportTimeSettings`	`BOOL`	是否支持时间设置功能
`isSupportLanguage`	`BOOL`	是否支持语言设置功能
`isSupportUserInfoSettings`	`BOOL`	是否支持用户信息设置功能
`isSupportDailyActivity`	`BOOL`	是否支持每日活动
`isSupportFirmwareUpgrade`	`BOOL`	是否支持固件升级功能
`isSupportUnitSettings`	`BOOL`	是否支持单位设置功能
`isSupportEarbudsAPIs`	`BOOL`	是否支持EarbudsAPIs
`isSupportAIChat`	`BOOL`	是否支持AI聊天功能
`isSupportAIChatAudioUsingSco`	`BOOL`	AI聊天音频通道是否使用SCO
`isSupportScreenLock`	`BOOL`	是否支持屏幕锁功能
`isSupportGameLock`	`BOOL`	是否支持游戏锁功能

TSDailyActivityAbility

属性名	类型	说明
无公开属性	-	通过方法访问每日活动类型支持情况

TSMessageAbility

属性名	类型	说明
无公开属性	-	通过方法访问消息类型支持情况

TSPeripheralLimitations

属性名	类型	说明
`maxAlarmCount`	`UInt8`	设备支持的最大闹钟数量
`maxContactCount`	`UInt8`	设备支持的最大联系人数量
`maxEmergencyContactCount`	`UInt8`	设备支持的最大紧急联系人数量
`maxPushDialCount`	`UInt8`	设备支持的最大可推送表盘位置个数
`maxInnerDialCount`	`UInt8`	设备预装的表盘数量
`maxWorldClockCount`	`UInt8`	设备支持的最大世界时钟数量
`maxSedentaryReminderCount`	`UInt8`	设备支持的最大久坐提醒数量
`maxWaterDrinkingReminderCount`	`UInt8`	设备支持的最大喝水提醒数量
`maxMedicationReminderCount`	`UInt8`	设备支持的最大吃药提醒数量
`maxCustomReminderCount`	`UInt8`	设备支持的最大自定义提醒数量

枚举与常量

TSPeriphShape

值	说明
`eTSPeriphShapeUnknow`	未知形状
`eTSPeriphShapeCircle`	圆形设备
`eTSPeriphShapeSquare`	正方形设备
`eTSPeriphShapeVerticalRectangle`	纵向长方形设备
`eTSPeriphShapeTransverseRectangle`	横向长方形设备

TSPeripheralSupportAbility

值	说明
`TSPeripheralSupportNone`	不支持任何功能
`TSPeripheralSupportStepCounting`	步数计数
`TSPeripheralSupportDistanceCounting`	距离计数
`TSPeripheralSupportCalorieCounting`	热量计数
`TSPeripheralSupportHeartRate`	心率监测
`TSPeripheralSupportBloodPressure`	血压监测
`TSPeripheralSupportBloodOxygen`	血氧监测
`TSPeripheralSupportStress`	压力监测
`TSPeripheralSupportSleep`	睡眠监测
`TSPeripheralSupportTemperature`	体温监测
`TSPeripheralSupportECG`	心电图监测
`TSPeripheralSupportFemaleHealth`	女性健康
`TSPeripheralSupportInitiateWorkout`	发起运动功能
`TSPeripheralSupportDailyActivity`	每日活动
`TSPeripheralSupportWeightManagement`	体重管理
`TSPeripheralSupportReminders`	活动提醒
`TSPeripheralSupportCallManagement`	来电管理
`TSPeripheralSupportAppNotifications`	应用通知
`TSPeripheralSupportMusicControl`	音乐控制
`TSPeripheralSupportWeatherDisplay`	天气显示
`TSPeripheralSupportFindMyPhone`	寻找手机
`TSPeripheralSupportAlarmClock`	闹钟功能
`TSPeripheralSupportWorldClock`	世界时钟
`TSPeripheralSupportMapNavigation`	地图导航
`TSPeripheralSupportShakeCamera`	摇一摇拍照
`TSPeripheralSupportCameraPreview`	相机视频预览
`TSPeripheralSupportEWallet`	电子钱包
`TSPeripheralSupportBusinessCard`	电子名片
`TSPeripheralSupportPhotoAlbum`	相册功能
`TSPeripheralSupportEBook`	电子书功能
`TSPeripheralSupportVoiceRecording`	录音功能
`TSPeripheralSupportAppStore`	应用商店
`TSPeripheralSupportMotionGames`	体感游戏
`TSPeripheralSupportSportUpload`	上传运动类型到设备
`TSPeripheralSupportERNIEBot`	文心一言
`TSPeripheralSupportChatGPT`	ChatGPT
`TSPeripheralSupportLoversFeature`	情侣功能
`TSPeripheralSupportContacts`	联系人功能
`TSPeripheralSupportEmergencyContacts`	紧急联系人
`TSPeripheralSupportMuslimPrayer`	穆斯林祈祷提醒
`TSPeripheralSupportQiblaCompass`	朝拜指南针
`TSPeripheralSupportNFCPayment`	NFC支付
`TSPeripheralSupportVoiceAssistant`	语音助手
`TSPeripheralSupportFacePush`	表盘功能
`TSPeripheralSupportCustomFace`	自定义表盘
`TSPeripheralSupportSlideshowFace`	幻灯片表盘
`TSPeripheralSupportTimeSettings`	时间设置
`TSPeripheralSupportLanguageSettings`	语言设置
`TSPeripheralSupportUserInfoSettings`	用户信息设置
`TSPeripheralSupportFirmwareUpgrade`	固件升级
`TSPeripheralSupportUnitSettings`	单位设置
`TSPeripheralSupportEarbudsAPIs`	支持耳机仓接口
`TSPeripheralSupportDialComponent`	支持表盘组件化
`TSPeripheralSupportAIChat`	支持AI聊天
`TSPeripheralSupportAIChatAudioUsingSco`	AI聊天音频通道使用SCO
`TSPeripheralSupportScreenLock`	屏幕锁
`TSPeripheralSupportGameLock`	游戏锁

回调类型

回调类型	参数	说明
`TSScanDiscoveryBlock`	`TSPeripheral *peripheral`	发现新设备时触发，在主线程执行
`TSScanCompletionBlock`	`TSScanCompletionReason reason, NSError *error`	扫描完成时触发，包含完成原因与可选错误
`TSBleConnectionStateCallback`	`TSBleConnectionState connectionState`	连接状态变化时触发，用于进度UI更新
`TSBleConnectionCompletionBlock`	`TSBleConnectionState connectionState, NSError *error`	连接完成时触发，包含最终状态与可选错误

接口方法

获取当前蓝牙连接状态

- (void)getConnectState:(TSBleConnectionStateCallback)completion;

参数	类型	说明
`completion`	`TSBleConnectionStateCallback`	返回当前连接状态的回调

获取蓝牙设备的当前连接状态。可从任何线程安全调用，回调始终在主线程执行。

id<TSBleConnectInterface> bleConnect = /* 获取接口实例 */;

[bleConnect getConnectState:^(TSBleConnectionState connectionState) {
    switch (connectionState) {
        case eTSBleStateDisconnected:
            TSLog(@"设备未连接");
            break;
        case eTSBleStateConnecting:
            TSLog(@"正在连接...");
            break;
        case eTSBleStateAuthenticating:
            TSLog(@"正在认证...");
            break;
        case eTSBleStatePreparingData:
            TSLog(@"正在准备数据...");
            break;
        case eTSBleStateConnected:
            TSLog(@"设备已连接且就绪");
            break;
    }
}];

开始搜索蓝牙设备

- (void)startSearchPeripheral:(NSTimeInterval)timeout
           discoverPeripheral:(TSScanDiscoveryBlock)discoverPeripheral
                   completion:(TSScanCompletionBlock)completion;

参数	类型	说明
`timeout`	`NSTimeInterval`	扫描超时时间（秒），0表示使用默认超时时间（30秒）
`discoverPeripheral`	`TSScanDiscoveryBlock`	发现新设备时触发的回调
`completion`	`TSScanCompletionBlock`	扫描完成或超时时的回调

开始搜索蓝牙设备。搜索过程持续进行，直到超时、调用stopSearchPeripheral或连接成功。所有回调都在主线程执行。

id<TSBleConnectInterface> bleConnect = /* 获取接口实例 */;

[bleConnect startSearchPeripheral:30.0
                discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"发现设备: %@", peripheral.systemInfo.bleName);
    TSLog(@"MAC地址: %@", peripheral.systemInfo.mac);
    TSLog(@"信号强度: %@", peripheral.systemInfo.RSSI);
} completion:^(TSScanCompletionReason reason, NSError *error) {
    switch (reason) {
        case eTSScanCompleteReasonTimeout:
            TSLog(@"扫描超时");
            break;
        case eTSScanCompleteReasonUserStopped:
            TSLog(@"用户停止扫描");
            break;
        case eTSScanCompleteReasonBleNotReady:
            TSLog(@"蓝牙未准备好");
            break;
        case eTSScanCompleteReasonPermissionDenied:
            TSLog(@"权限被拒绝");
            break;
        default:
            if (error) {
                TSLog(@"扫描出错: %@", error.localizedDescription);
            }
            break;
    }
}];

使用高级参数开始搜索蓝牙设备

- (void)startSearchPeripheralWithParam:(TSPeripheralScanParam *)param
                    discoverPeripheral:(TSScanDiscoveryBlock)discoverPeripheral
                            completion:(TSScanCompletionBlock)completion;

参数	类型	说明
`param`	`TSPeripheralScanParam *`	扫描参数，包含过滤条件（UUID、名称、MAC）、超时等
`discoverPeripheral`	`TSScanDiscoveryBlock`	发现新设备时触发的回调
`completion`	`TSScanCompletionBlock`	扫描完成回调，包含完成原因与可选错误

使用高级参数开始搜索蓝牙设备。支持按服务UUID、设备名称、MAC地址等条件过滤。

id<TSBleConnectInterface> bleConnect = /* 获取接口实例 */;

TSPeripheralScanParam *scanParam = [[TSPeripheralScanParam alloc] init];
scanParam.userId = @"user123";
scanParam.deviceName = @"MyDevice";
scanParam.scanTimeout = 30;
scanParam.allowDuplicates = YES;

[bleConnect startSearchPeripheralWithParam:scanParam
                       discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"发现设备: %@", peripheral.systemInfo.bleName);
} completion:^(TSScanCompletionReason reason, NSError *error) {
    if (reason == eTSScanCompleteReasonTimeout) {
        TSLog(@"扫描超时");
    }
}];

停止搜索蓝牙设备

- (void)stopSearchPeripheral;

停止搜索蓝牙设备。即使未在扫描也可安全调用。应在连接成功后或退出搜索界面时调用。

id<TSBleConnectInterface> bleConnect = /* 获取接口实例 */;

[bleConnect stopSearchPeripheral];

前提条件​

数据模型​

TSBleConnectionState​

TSScanCompletionReason​

TSBleStatus​

TSBluetoothInfo​

TSBluetoothSystem​

TSPeripheralConnectParam​

TSPeripheralScanParam​

TSPeripheral​

TSPeripheralSystem​

TSPeripheralProject​

TSPeripheralScreen​

TSPeripheralCapability​

TSFeatureAbility​

TSDailyActivityAbility​

TSMessageAbility​

TSPeripheralLimitations​

枚举与常量​

TSPeriphShape​

TSPeripheralSupportAbility​

回调类型​

接口方法​

获取当前蓝牙连接状态​

开始搜索蓝牙设备​

使用高级参数开始搜索蓝牙设备​

停止搜索蓝牙设备​