蓝牙连接（TSBleConnect）

本模块提供完整的蓝牙设备连接生命周期管理能力，包括设备扫描、连接、重连、断开、解绑及蓝牙适配器信息查询。连接过程细分为物理连接、认证、数据准备、就绪四个阶段，支持细粒度状态跟踪与进度回调。所有回调均在主线程执行。

前提条件

项目已集成 TopStepComKit SDK，并完成基础初始化。
Info.plist 中已声明蓝牙权限：NSBluetoothAlwaysUsageDescription（iOS 13+）。
设备蓝牙硬件已开启，系统蓝牙权限已授权。
调用连接/重连接口前，需先通过扫描接口获取到 TSPeripheral 对象。
连接参数 TSPeripheralConnectParam 必须通过 initWithUserId: 初始化，不可使用 init / new。

数据模型

TSPeripheral

外设设备信息类，聚合设备蓝牙系统信息、屏幕信息、项目信息、能力信息及功能限制信息。

属性名	类型	说明
`systemInfo`	`TSPeripheralSystem *`	蓝牙系统信息，含外设对象、MAC地址、蓝牙名称等
`screenInfo`	`TSPeripheralScreen *`	屏幕信息，含尺寸、形状、圆角等
`projectInfo`	`TSPeripheralProject *`	项目信息，含固件版本、序列号等
`capability`	`TSPeripheralCapability *`	设备能力容器，含功能支持标志
`limitation`	`TSPeripheralLimitations *`	设备功能数量限制信息

TSPeripheralSystem

外设系统级信息模型。

属性名	类型	说明
`peripheral`	`CBPeripheral *`	CoreBluetooth 外设对象
`central`	`CBCentralManager *`	蓝牙中心管理器，可为 nil
`uuid`	`NSString *`	外设 UUID 字符串（只读），peripheral 为空时返回 nil
`mac`	`NSString *`	设备 MAC 地址（冒号分隔，如 `DE:82:47:15:28:B0`）
`bleName`	`NSString *`	设备蓝牙广播名称，可为 nil
`RSSI`	`NSNumber *`	信号强度（RSSI），可为 nil
`advertisementData`	`NSDictionary *`	广播数据字典，包含服务 UUID、制造商数据等，可为 nil

TSPeripheralProject

外设项目信息模型，所有属性均可为 nil。

属性名	类型	说明
`projectId`	`NSString *`	项目唯一标识符
`companyId`	`NSString *`	公司标识符，通常为4位十六进制字符串（如 `6A6A`）
`brand`	`NSString *`	设备品牌名称，最大16字符
`model`	`NSString *`	设备型号，最大16字符
`firmVersion`	`NSString *`	固件版本号，通常遵循语义化版本（如 `1.0.0`）
`serialNumber`	`NSString *`	设备序列号，每台设备唯一
`mainProjNum`	`NSString *`	主项目号（仅 FitCloudKit 场景使用）
`subProjNum`	`NSString *`	子项目号（仅 FitCloudKit 场景使用）

TSPeripheralScreen

外设屏幕信息模型。

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

TSPeripheralCapability

设备能力容器，组合多个细粒度能力模块。

属性名	类型	说明
`featureAbility`	`TSFeatureAbility *`	粗粒度功能模块支持标志（是/否）
`messageAbility`	`TSMessageAbility *`	细粒度消息类型支持详情，可为 nil
`dailyActivityAbility`	`TSDailyActivityAbility *`	细粒度每日活动类型支持，可为 nil
`aiAbility`	`TSPeripheralAIAbility *`	固件声明的、区分设备/App 发起方向的 AI 场景能力
`sleepAlgorithm`	`NSInteger`	睡眠算法类型：0=LongestNight，1=LongestOnly

TSFeatureAbility

设备功能支持标志类。核心属性如下：

属性名	类型	说明
`originAbility`	`NSData *`	设备原始能力数据，最大16字节，可为 nil
`supportCapabilities`	`TSPeripheralSupportAbility`	解析后的功能支持位标志集合
`isSupportStepCounting`	`BOOL`	是否支持步数计数（只读）
`isSupportHeartRate`	`BOOL`	是否支持心率监测（只读）
`isSupportBloodPressure`	`BOOL`	是否支持血压监测（只读）
`isSupportBloodOxygen`	`BOOL`	是否支持血氧监测（只读）
`isSupportSleep`	`BOOL`	是否支持睡眠监测（只读）
`isSupportAlarmClock`	`BOOL`	是否支持闹钟功能（只读）
`isSupportAppNotifications`	`BOOL`	是否支持应用通知（只读）
`isSupportDailyActivity`	`BOOL`	是否支持每日活动（只读）
`isSupportFirmwareUpgrade`	`BOOL`	是否支持固件升级（只读）
`isSupportFacePush`	`BOOL`	是否支持表盘推送（只读）
`isSupportCustomFace`	`BOOL`	是否支持自定义表盘（只读）
`isSupportAIChat`	`BOOL`	是否支持 AI 聊天（只读）
`isSupportEarbudsAPIs`	`BOOL`	是否支持耳机仓接口（只读）
`isSupportDeviceLog`	`BOOL`	是否支持获取设备日志（只读）

其余只读能力属性按功能分组如下：

分组	属性
健康	`isSupportDistanceCounting`, `isSupportCalorieCounting`, `isSupportHRV`, `isSupportStress`, `isSupportTemperature`, `isSupportECG`, `isSupportFemaleHealth`, `isSupportInitiateWorkout`, `isSupportWeightManagement`
智能	`isSupportReminders`, `isSupportCallManagement`, `isSupportMusic`, `isSupportWeatherDisplay`, `isSupportFindMyPhone`, `isSupportWorldClock`, `isSupportMapNavigation`, `isSupportShakeCamera`, `isSupportCameraPreview`, `isSupportEWallet`, `isSupportBusinessCard`, `isSupportPhotoAlbum`, `isSupportEBook`, `isSupportVoiceRecording`, `isSupportAppStore`, `isSupportMotionGames`, `isSupportWorkoutPush`
AI 与社交	`isSupportERNIEBot`, `isSupportChatGPT`, `isSupportLoversFeature`, `isSupportContacts`, `isSupportEmergencyContacts`
宗教与硬件	`isSupportMuslimPrayer`, `isSupportQiblaCompass`, `isSupportNFCPayment`, `isSupportVoiceAssistant`, `isSupportSlideshowFace`, `isSupportDialComponent`
系统与扩展	`isSupportTimeSettings`, `isSupportLanguage`, `isSupportUserInfoSettings`, `isSupportUnitSettings`, `isSupportAIChatAudioUsingSco`, `isSupportScreenLock`, `isSupportGameLock`, `isSupportEqualizer`, `isSupportOfflineMap`, `isSupportEpo`

TSPeripheralAIAbility 与 TSPeripheralFeature

属性名	类型	说明
`deviceInitiatedScenes`	`TSPeripheralAIScene`	可由设备发起的 AI 音频流场景
`appInitiatedScenes`	`TSPeripheralAIScene`	可由 App 发起的 AI 音频流场景
`preferredAIVendor`	`TSAIVendor`	设备建议的 AI 方案商；未知表示未上报
`supportedFeatures`	`TSFeatureOptions`	Provider 无关的顶层功能位集合

TSPeripheralLimitations

设备功能数量限制。值为 0 表示不支持该功能；值为 255（TSUnLimitNum）表示无数量限制。

属性名	类型	说明
`maxAlarmCount`	`UInt8`	最大闹钟数量（只读）
`maxContactCount`	`UInt8`	最大联系人数量（只读）
`maxEmergencyContactCount`	`UInt8`	最大紧急联系人数量（只读）
`maxPushDialCount`	`UInt8`	最大可推送自定义表盘数量（只读）
`maxInnerDialCount`	`UInt8`	预装表盘数量（只读）
`maxWorldClockCount`	`UInt8`	最大世界时钟数量（只读）
`maxSedentaryReminderCount`	`UInt8`	最大久坐提醒数量（只读）
`maxWaterDrinkingReminderCount`	`UInt8`	最大喝水提醒数量（只读）
`maxMedicationReminderCount`	`UInt8`	最大吃药提醒数量（只读）
`maxCustomReminderCount`	`UInt8`	最大自定义提醒数量（只读）
`maxAIResponseTextBytes`	`NSUInteger`	AI 应答文本允许的最大 UTF-8 字节数

TSPeripheralConnectParam

设备连接参数对象，必须通过 initWithUserId: 初始化。

属性名	类型	说明
`userId`	`NSString *`	用户 ID（必填，不可为空）
`authCode`	`NSString *`	扫描二维码获得的绑定认证码
`connectTimeout`	`NSInteger`	连接与鉴权超时；非正数使用默认 30 秒
`maxReconnectCount`	`NSInteger`	异常断开后的自动重连次数；非正数使用默认 5 次
`shouldAutoSetTime`	`BOOL`	连接成功后是否自动设置设备时间，默认 `NO`
`shouldAutoSetLanguage`	`BOOL`	连接成功后是否自动设置设备语言，默认 `NO`
`extraParam`	`TSConnectExtraParam *`	按 Provider 传入的补充参数

补充参数子类：TSFitConnectExtraParam.allowConnectWithBT；TSNpkConnectExtraParam.gender、age、height、weight；TSBudsConnectExtraParam.aiLicense、aiVendor。

TSPeripheralScanParam

高级扫描参数对象。

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

TSBluetoothSystem

完整蓝牙系统信息模型。

属性名	类型	说明
`bleInfo`	`TSBluetoothInfo *`	BLE（低功耗蓝牙）适配器信息，可为 nil
`btInfo`	`TSBluetoothInfo *`	BT（经典蓝牙）适配器信息，iOS 上通常为 nil

TSBluetoothInfo

单个蓝牙适配器信息。

属性名	类型	说明
`macAddress`	`NSString *`	MAC 地址（冒号分隔格式），iOS 隐私限制下可为 nil
`name`	`NSString *`	蓝牙名称，不可用时为 nil
`status`	`TSBleStatus`	适配器连接状态

枚举与常量

TSPeripheralAIScene

TSPeripheralAISceneNone、TSPeripheralAISceneChat、TSPeripheralAISceneRecording、TSPeripheralAISceneCallRecording、TSPeripheralAISceneTranslation、TSPeripheralAISceneRideHailing、TSPeripheralAISceneWatchFace、TSPeripheralAISceneQuestionAnswer、TSPeripheralAISceneTranslationSelf、TSPeripheralAISceneTranslationPeer，以及组合值 TSPeripheralAISceneAll。

TSFeatureOptions

顶层功能位包括：TSFeatureNone、TSFeatureDailyActivity、TSFeatureHeartRate、TSFeatureHeartRateVariability、TSFeatureBloodPressure、TSFeatureBloodOxygen、TSFeatureStress、TSFeatureSleep、TSFeatureTemperature、TSFeatureElectrocardiogram、TSFeatureFemaleHealth、TSFeatureWorkout、TSFeatureCompanionWorkout、TSFeatureWeightManagement、TSFeatureReminder、TSFeatureCallManagement、TSFeatureMessageNotification、TSFeatureMusic、TSFeatureWeather、TSFeaturePeripheralFind、TSFeatureAlarmClock、TSFeatureWorldClock、TSFeatureNavigation、TSFeatureCamera、TSFeatureECardBag、TSFeaturePayment、TSFeaturePhotoAlbum、TSFeatureEBook、TSFeatureVoiceRecording、TSFeatureAppStore、TSFeatureMotionGame、TSFeatureContact、TSFeatureLovers、TSFeaturePrayer、TSFeatureQiblaCompass、TSFeatureAIChat、TSFeatureVoiceAssistant、TSFeatureDial、TSFeatureTime、TSFeatureLanguage、TSFeatureUserInfo、TSFeatureFirmwareUpgrade、TSFeatureUnit、TSFeatureDeviceSetting、TSFeaturePeripheralLock、TSFeatureBattery、TSFeatureANC、TSFeatureEqualizer、TSFeatureVolume、TSFeatureWearDetection、TSFeatureStorage、TSFeaturePeripheralControl、TSFeaturePeripheralLog。

TSPeripheralSupportAbility 的新增位为：TSPeripheralSupportDistanceCounting、TSPeripheralSupportCalorieCounting、TSPeripheralSupportHRV、TSPeripheralSupportStress、TSPeripheralSupportTemperature、TSPeripheralSupportFemaleHealth、TSPeripheralSupportInitiateWorkout、TSPeripheralSupportWeightManagement、TSPeripheralSupportReminders、TSPeripheralSupportCallManagement、TSPeripheralSupportMusic、TSPeripheralSupportWeatherDisplay、TSPeripheralSupportFindMyPhone、TSPeripheralSupportWorldClock、TSPeripheralSupportMapNavigation、TSPeripheralSupportShakeCamera、TSPeripheralSupportCameraPreview、TSPeripheralSupportEWallet、TSPeripheralSupportBusinessCard、TSPeripheralSupportPhotoAlbum、TSPeripheralSupportEBook、TSPeripheralSupportVoiceRecording、TSPeripheralSupportAppStore、TSPeripheralSupportMotionGames、TSPeripheralSupportWorkoutPush、TSPeripheralSupportERNIEBot、TSPeripheralSupportChatGPT、TSPeripheralSupportLoversFeature、TSPeripheralSupportContacts、TSPeripheralSupportEmergencyContacts、TSPeripheralSupportMuslimPrayer、TSPeripheralSupportQiblaCompass、TSPeripheralSupportNFCPayment、TSPeripheralSupportVoiceAssistant、TSPeripheralSupportSlideshowFace、TSPeripheralSupportTimeSettings、TSPeripheralSupportLanguageSettings、TSPeripheralSupportUserInfoSettings、TSPeripheralSupportUnitSettings、TSPeripheralSupportDialComponent、TSPeripheralSupportAIChatAudioUsingSco、TSPeripheralSupportScreenLock、TSPeripheralSupportGameLock、TSPeripheralSupportEqualizer、TSPeripheralSupportOfflineMap、TSPeripheralSupportEpoGnss。

TSBleConnectionState — 蓝牙连接状态

枚举值	原始值	说明
`eTSBleStateDisconnected`	`0`	未连接（初始状态或任何失败/断开后）
`eTSBleStateConnecting`	`1`	连接中（正在建立 BLE 物理连接）
`eTSBleStateAuthenticating`	`2`	认证中（正在执行绑定/登录认证）
`eTSBleStatePreparingData`	`3`	准备数据中（认证成功后正在获取设备信息）
`eTSBleStateConnected`	`4`	已连接且就绪（可进行数据操作）

状态流转（成功）： Disconnected → Connecting → Authenticating → PreparingData → Connected

状态流转（任意阶段失败）： 任意状态 → Disconnected（错误详情通过完成回调传递）

TSScanCompletionReason — 扫描完成原因

枚举值	原始值	说明
`eTSScanCompleteReasonTimeout`	`1000`	扫描超时
`eTSScanCompleteReasonBleNotReady`	`1001`	蓝牙未准备好
`eTSScanCompleteReasonPermissionDenied`	`1002`	权限被拒绝
`eTSScanCompleteReasonUserStopped`	`1003`	用户主动停止
`eTSScanCompleteReasonSystemError`	`1004`	系统错误
`eTSScanCompleteReasonNotSupport`	`1005`	不支持

TSBleStatus — 蓝牙适配器连接状态

枚举值	原始值	说明
`TSBleDisconnected`	`0`	未连接
`TSBleConnected`	`1`	已连接（物理连接已建立）
`TSBleReady`	`2`	已就绪（已连接且 Notify/SPP 已打开，可进行数据通信）

TSPeriphShape — 外设外形

枚举值	原始值	说明
`eTSPeriphShapeUnknow`	`0`	未知形状
`eTSPeriphShapeCircle`	`1`	圆形
`eTSPeriphShapeSquare`	`2`	正方形
`eTSPeriphShapeVerticalRectangle`	`3`	纵向长方形
`eTSPeriphShapeTransverseRectangle`	`4`	横向长方形

TSAIVendor — AI 方案商类型

枚举值	原始值	说明
`TSAIVendorUnknown`	`0`	未指定 AI 方案商（默认值，非 Buds 设备使用）
`TSAIVendorStarBurst`	`1`	StarBurst AI 方案
`TSAIVendorMltCloud`	`2`	MltCloud AI 方案

TSPeripheralSupportAbility — 设备功能支持位标志（节选）

枚举值	位偏移	说明
`TSPeripheralSupportNone`	—	不支持任何功能
`TSPeripheralSupportStepCounting`	bit 0	步数计数
`TSPeripheralSupportHeartRate`	bit 3	心率监测
`TSPeripheralSupportBloodPressure`	bit 4	血压监测
`TSPeripheralSupportBloodOxygen`	bit 5	血氧监测
`TSPeripheralSupportSleep`	bit 7	睡眠监测
`TSPeripheralSupportECG`	bit 9	心电图监测
`TSPeripheralSupportDailyActivity`	bit 12	每日活动
`TSPeripheralSupportAlarmClock`	bit 22	闹钟功能
`TSPeripheralSupportAppNotifications`	bit 18	应用通知
`TSPeripheralSupportFacePush`	bit 44	表盘推送
`TSPeripheralSupportCustomFace`	bit 45	自定义表盘
`TSPeripheralSupportFirmwareUpgrade`	bit 50	固件升级
`TSPeripheralSupportAIChat`	bit 54	AI 聊天
`TSPeripheralSupportEarbudsAPIs`	bit 52	耳机仓接口
`TSPeripheralSupportDeviceLog`	bit 59	获取设备日志

完整位标志定义详见 TSFeatureAbility.h，共支持 60+ 个功能位，底层类型为 uint64_t。

回调类型

回调类型	签名	说明
`TSScanDiscoveryBlock`	`void(^)(TSPeripheral * peripheral)`	扫描发现新设备时触发，在主线程回调
`TSScanCompletionBlock`	`void(^)(TSScanCompletionReason reason, NSError * _Nullable error)`	扫描结束时触发，包含结束原因及可选错误
`TSBleConnectionStateCallback`	`void(^)(TSBleConnectionState connectionState)`	连接状态变化时触发（可多次），在主线程回调，不含错误信息
`TSBleConnectionStateBlock`	`void(^)(TSBleConnectionState connectionState)`	连接器级持久状态监听
`TSCompletionBlock`	`void(^)(BOOL success, NSError * _Nullable error)`	通用操作完成回调，含成功标志及可选错误

接口方法

获取当前蓝牙连接状态

- (void)getConnectState:(TSBleConnectionStateCallback)completion;

参数名	类型	说明
`completion`	`TSBleConnectionStateCallback`	返回当前连接状态的回调，在主线程执行

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

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

监听持续连接状态

- (void)registerConnectionStateDidChanged:(nullable TSBleConnectionStateBlock)completion;

该监听报告连接中、鉴权中、准备数据、连接完成及后续设备/系统断连。传 nil 注销。单次连接方法的 completion 只报告该请求的最终成功或失败，不替代此监听。

检查设备是否已连接

- (BOOL)isConnected;

线程安全，可从任意线程调用。返回 YES 表示设备处于 eTSBleStateConnected 状态。

if ([bleConnect isConnected]) {
    TSLog(@"设备已连接，可执行数据操作");
} else {
    TSLog(@"设备未连接，请先扫描并连接设备");
}

开始扫描蓝牙设备（基础）

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

参数名	类型	说明
`timeout`	`NSTimeInterval`	扫描超时秒数，传 `0` 使用默认超时（30秒）
`discoverPeripheral`	`TSScanDiscoveryBlock`	每发现一台新设备触发一次，在主线程回调
`completion`	`TSScanCompletionBlock`	扫描结束时触发，包含结束原因及可选错误

NSMutableArray<TSPeripheral *> *deviceList = [NSMutableArray array];

[bleConnect startSearchPeripheral:15.0
               discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"发现设备：%@，MAC：%@，RSSI：%@",
          peripheral.systemInfo.bleName,
          peripheral.systemInfo.mac,
          peripheral.systemInfo.RSSI);
    [deviceList addObject:peripheral];
} completion:^(TSScanCompletionReason reason, NSError *error) {
    if (reason == eTSScanCompleteReasonTimeout) {
        TSLog(@"扫描超时，共发现 %lu 台设备", (unsigned long)deviceList.count);
    } else if (reason == eTSScanCompleteReasonUserStopped) {
        TSLog(@"用户停止扫描");
    } else if (error) {
        TSLog(@"扫描出错：%@", error.localizedDescription);
    }
}];

开始扫描蓝牙设备（高级参数）

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

参数名	类型	说明
`param`	`TSPeripheralScanParam *`	高级扫描参数，支持 UUID/蓝牙名称/MAC 过滤、超时、重复发现等
`discoverPeripheral`	`TSScanDiscoveryBlock`	每发现一台新设备触发一次，在主线程回调
`completion`	`TSScanCompletionBlock`	扫描结束时触发，包含结束原因及可选错误

TSPeripheralScanParam *param = [[TSPeripheralScanParam alloc] init];
param.userId = @"user_123456";
param.bleName = @"TopWatch";         // 只扫描蓝牙名称为 TopWatch 的设备
param.onlyNamedPeripherals = YES;    // 只返回蓝牙名称非空的设备
param.scanTimeout = 20;              // 20 秒超时
param.allowDuplicates = NO;

[bleConnect startSearchPeripheralWithParam:param
                        discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"发现目标设备：%@，MAC：%@",
          peripheral.systemInfo.bleName,
          peripheral.systemInfo.mac);
} completion:^(TSScanCompletionReason reason, NSError *error) {
    TSLog(@"扫描结束，原因：%ld，错误：%@", (long)reason, error.localizedDescription);
}];

停止扫描蓝牙设备

- (void)stopSearchPeripheral;

无参数。即使当前未在扫描也可安全调用，扫描超时时 SDK 会自动调用。

// 用户点击停止按钮或退出扫描页面时调用
[bleConnect stopSearchPeripheral];
TSLog(@"已停止扫描");

连接蓝牙设备

- (void)connectWithPeripheral:(TSPeripheral *)peripheral
                        param:(TSPeripheralConnectParam *)param
                   completion:(TSCompletionBlock)completion;

参数名	类型	说明
`peripheral`	`TSPeripheral *`	扫描阶段获取的目标外设对象
`param`	`TSPeripheralConnectParam *`	连接参数，包含用户 ID、用户信息、认证码等
`completion`	`TSCompletionBlock`	本次请求最终结果，只调用一次；中间状态由持久监听报告

TSPeripheralConnectParam *param = [[TSPeripheralConnectParam alloc] initWithUserId:@"user_123456"];
param.brand = @"Apple";
param.model = @"iPhone 15 Pro";
param.systemVersion = @"iOS 17.0";

[bleConnect connectWithPeripheral:targetPeripheral
                            param:param
                       completion:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"连接成功");
    } else {
        TSLog(@"连接失败：%@", error.localizedDescription);
    }
}];

通过 MAC 地址连接

- (void)connectWithMacAddress:(NSString *)macAddress
                        param:(TSPeripheralConnectParam *)param
                   completion:(TSCompletionBlock)completion;

参数名	类型	说明
`macAddress`	`NSString *`	目标设备 MAC；SDK 会先在内部扫描匹配设备
`param`	`TSPeripheralConnectParam *`	连接参数
`completion`	`TSCompletionBlock`	本次请求最终结果，只调用一次

TSPeripheralConnectParam *param = [[TSPeripheralConnectParam alloc] initWithUserId:@"user_123456"];

[bleConnect connectWithMacAddress:@"AA:BB:CC:DD:EE:FF"
                            param:param
                       completion:^(BOOL success, NSError *error) {
    TSLog(@"MAC 连接结果：%@", success ? @"成功" : error.localizedDescription);
}];

断开当前连接

- (void)disconnectCompletion:(TSCompletionBlock)completion;

参数名	类型	说明
`completion`	`TSCompletionBlock`	断开结果回调，在主线程执行

断开后绑定信息保留，可重新调用 connectWithPeripheral:param:completion: 或 MAC 地址入口连接。

[bleConnect disconnectCompletion:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"已成功断开连接，绑定信息已保留");
    } else {
        TSLog(@"断开失败：%@", error.localizedDescription);
    }
}];

解绑当前设备

- (void)unbindPeripheralCompletion:(TSCompletionBlock)completion;

参数名	类型	说明
`completion`	`TSCompletionBlock`	解绑结果回调，在主线程执行

解绑后清除所有配对信息，再次使用须调用 connectWithPeripheral:param:completion: 重新绑定。

[bleConnect unbindPeripheralCompletion:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"设备解绑成功，所有配对信息已清除");
        // 跳转至扫描页面引导用户重新绑定
    } else {
        TSLog(@"解绑失败：%@", error.localizedDescription);
    }
}];

获取蓝牙适配器信息

- (void)getBluetoothInfo:(void(^)(TSBluetoothSystem * _Nullable bluetoothInfo, NSError * _Nullable error))completion;

参数名	类型	说明
`completion`	`void(^)(TSBluetoothSystem * _Nullable, NSError * _Nullable)`	返回蓝牙系统信息的回调，在主线程执行

[bleConnect getBluetoothInfo:^(TSBluetoothSystem *bluetoothInfo, NSError *error) {
    if (error) {
        TSLog(@"获取蓝牙信息失败：%@", error.localizedDescription);
        return;
    }

    // BLE 信息
    TSBluetoothInfo *bleInfo = bluetoothInfo.bleInfo;
    if (bleInfo) {
        TSLog(@"BLE 名称：%@，MAC：%@，状态：%ld",
              bleInfo.name,
              bleInfo.macAddress ?: @"不可用（iOS 隐私限制）",
              (long)bleInfo.status);
    }

    // 经典蓝牙信息（iOS 上通常为 nil）
    TSBluetoothInfo *btInfo = bluetoothInfo.btInfo;
    if (btInfo) {
        TSLog(@"BT 名称：%@，状态：%ld", btInfo.name, (long)btInfo.status);
    } else {
        TSLog(@"经典蓝牙信息不可用（iOS 平台限制）");
    }
}];

注意事项

连接参数初始化：TSPeripheralConnectParam 禁用了 init / new / copy，必须使用 initWithUserId: 初始化，userId 不可为空字符串。
回调分工：连接 completion 只回调一次最终结果；所有中间阶段与后续断连统一由 registerConnectionStateDidChanged: 报告。
恢复连接：已绑定设备继续使用统一的 connectWithPeripheral:param:completion:；旧版 reconnectWithPeripheral: 已移除。
扫描电量消耗：扫描会持续消耗系统资源，应在连接成功后或退出扫描界面时立即调用 stopSearchPeripheral；超时触发后 SDK 会自动停止，无需手动再次调用。
断开 vs 解绑：disconnectCompletion: 仅断开物理连接并保留绑定信息；unbindPeripheralCompletion: 会清除全部配对信息。
iOS MAC 地址限制：出于系统隐私策略，iOS 平台无法获取设备 MAC 地址，TSBluetoothInfo.macAddress 及 TSPeripheralSystem.mac 在部分场景下可能为 nil，请做好判空处理。
经典蓝牙信息：在 iOS 平台，TSBluetoothSystem.btInfo 通常为 nil，请勿依赖此字段做业务判断。
线程安全：isConnected 和 getConnectState: 可从任意线程安全调用；所有回调均保证在主线程执行，可直接操作 UI。
功能能力检查：在调用具体功能模块接口前，建议先通过 TSFeatureAbility 的对应 isSupport* 属性确认设备支持该功能，避免无效调用。
设备限制：使用闹钟、联系人、表盘等功能时，应先读取 TSPeripheralLimitations 对应字段进行上限校验；值为 0 表示不支持，值为 255（TSUnLimitNum）表示无限制。

前提条件​

数据模型​

TSPeripheral​

TSPeripheralSystem​

TSPeripheralProject​

TSPeripheralScreen​

TSPeripheralCapability​

TSFeatureAbility​

TSPeripheralAIAbility 与 TSPeripheralFeature​

TSPeripheralLimitations​

TSPeripheralConnectParam​

TSPeripheralScanParam​

TSBluetoothSystem​

TSBluetoothInfo​

枚举与常量​

TSPeripheralAIScene​

TSFeatureOptions​

TSBleConnectionState — 蓝牙连接状态​

TSScanCompletionReason — 扫描完成原因​

TSBleStatus — 蓝牙适配器连接状态​

TSPeriphShape — 外设外形​

TSAIVendor — AI 方案商类型​

TSPeripheralSupportAbility — 设备功能支持位标志（节选）​

回调类型​

接口方法​

获取当前蓝牙连接状态​

监听持续连接状态​

检查设备是否已连接​

开始扫描蓝牙设备（基础）​

开始扫描蓝牙设备（高级参数）​

停止扫描蓝牙设备​

连接蓝牙设备​

通过 MAC 地址连接​

断开当前连接​

解绑当前设备​

获取蓝牙适配器信息​

注意事项​