XinJieSmartFramework iOS接口文档

概述

XinJieManage 是智能戒指蓝牙管理 SDK，提供蓝牙连接、设备控制、健康数据获取等功能。

依赖框架： - Foundation - UIKit - CoreBluetooth

依赖第三方库： - BabyBluetooth

常量定义

协议定义

XinJieDelegate

蓝牙代理协议，用于接收设备状态变化和硬件信息回调。

可选方法

1. 硬件属性回调

- (void)completionResultObject:(BlueResultObject *)model;

说明： 返回戒指的硬件属性，包括真实MAC地址

前提条件： 固件版本 > 0.26.03.2.1

参数： - model - 硬件属性对象

2. 连接状态变化

- (void)statusChange:(NSNumber *)connected;

说明： 设备连接状态变化回调

参数： - connected - 1表示已连接，0表示已断开

类接口

XinJieManage

智能戒指蓝牙管理类（单例）

属性

初始化方法

1. 获取单例

+ (instancetype)shareXinJieManageBluetooth;

说明： 获取 XinJieManage 共享实例（单例模式）

返回值： XinJieManage 实例

2. 配置用户信息

- (void)configUserID:(NSString *)userID
             userKey:(NSString *)userKey
         filterName:(NSString *)filterName;

说明： 配置连接所需的用户信息（必须在连接前调用）

参数： - userID - 用户ID - userKey - 用户密钥 - filterName - 用于过滤蓝牙信号的设备名称

连接管理

1. 获取虚拟MAC地址

- (NSString *)fecthVirtualConnectMac;

说明： 获取当前连接戒指的虚拟MAC地址（iOS系统加密后的地址）

返回值： 虚拟MAC地址字符串

2. 查找特征值

- (CBCharacteristic *)findCharacteristicByUUIDString:(NSString *)characteristic;

说明： 根据UUID字符串查找对应的特征值对象

参数： - characteristic - 特征值UUID，例如：@“4249B001-2827-458E-B34C-CB6FAF92F42C”

返回值： CBCharacteristic 对象或 nil

3. 添加代理

- (void)addBlockArray:(NSObject *)delegate;

说明： 添加回调代理对象

参数： - delegate - 代理对象

4. 移除代理

- (void)removeBlockArray:(NSObject *)delegate;

说明： 移除回调代理对象

参数： - delegate - 要移除的代理对象

5. 设置特征值监听

- (void)setBlockOnDiscoverCharacteristicsAtChannel:(NSString *)channelOnPeropheralView
                                             block:(void (^)(CBPeripheral *peripheral,
                                                          CBService *service,
                                                          NSError *error))block;

说明： 设置特征值发现回调

参数： - channelOnPeropheralView - 服务通道 - block - 回调block，参数：外设对象、服务对象、错误信息

6. 检查连接模式

- (void)checkScanOrConnect;

说明： 检查是否有已连接过的设备，决定是扫描还是直接连接

7. 判断自动连接

- (BOOL)isAutoLink;

说明： 判断是否开启自动连接

返回值： YES为自动连接，NO为手动连接

8. 判断连接状态

- (BOOL)isConnected;

说明： 判断当前是否已连接设备

返回值： YES表示已连接，NO表示未连接

9. 停止扫描

- (void)stopScan;

说明： 停止蓝牙扫描

10. 断开连接

- (void)disconnected;

说明： 断开当前蓝牙连接

11. 连接设备

- (void)connectToPeripheral:(CBPeripheral *)peripheral;

说明： 连接指定外设

参数： - peripheral - 要连接的外设对象

12. 自动连接

- (void)autoConnectByUUID;

说明： 通过UUID自动连接已保存的设备

设备信息获取

1. 同步时间

- (void)synchronizeTime_ring:(void (^)(CBCharacteristic *characteristic, NSError *error))block;

说明： 将当前手机时间同步到蓝牙戒指

回调参数： - characteristic - 写入的特征值 - error - 错误信息（成功为nil）

2. 获取设备时间

- (void)fetchTime_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取蓝牙设备当前时间

回调数据：

@{
    @"timestamp": @(时间戳)
}

3. 获取固件版本

- (void)fetchRingversion_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取戒指固件版本信息

回调数据：

@{
    @"Ringversion": @"版本号字符串"
}

4. 获取电量

- (void)fetchBatteryLevel_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取戒指当前电量

回调数据：

@{
    @"BatteryLevel": @"电量百分比"
}

5. 获取充电状态

- (void)fetchBatteryChargingStatus_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取当前是否在充电

回调数据：

@{
    @"isBatteryCharging": @(YES/NO)
}

6. 获取真实MAC地址

- (void)fetchiOSRealMac_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 通过特征值获取戒指的真实MAC地址（iOS专用）

前提条件： 固件版本 > 0.26.03.2.1

回调数据：

@{
    @"realMacAddress": @"真实MAC地址"
}

7. 获取芯片状态

- (void)fetchGoodOrBad_ring:(void (^)(CBCharacteristic *characteristic, NSError *error))block;

说明： 获取心率、运动、体温芯片的通讯状态

测试指示灯说明： - 绿灯3秒 → 正常 - 红外灯3秒 → 异常（人眼不可见） - 红灯3秒 → 异常

注意： 仅在未充电状态下进行测试

设备控制

1. 关机

- (void)shutdown_ring:(void (^)(CBCharacteristic *characteristic, NSError *error))block;

说明： 发送关机指令

2. 恢复出厂

- (void)reset_ring:(void (^)(CBCharacteristic *characteristic, NSError *error))block;

说明： 恢复设备出厂设置

⚠️ 警告： 此操作将清除所有设备数据

3. 设置自动连接

- (void)autoLinkSetting_ring:(BOOL)autoLink;

说明： 设置是否自动连接

参数： - autoLink - YES为开启自动连接，NO为关闭

自动测试设置

1. 设置心率测试间隔

- (void)heartSetting_ring:(int)setValue
             finishBlock:(void (^)(CBCharacteristic *characteristic, NSError *error))finishBlock;

说明： 设置心率自动测试的时间间隔

参数： - setValue - 间隔时间（分钟）

示例：

[[XinJieManage shareXinJieManageBluetooth] heartSetting_ring:10 finishBlock:^(CBCharacteristic *characteristic, NSError *error) {
    if (error) {
        NSLog(@"设置失败: %@", error);
    } else {
        NSLog(@"心率测试间隔已设置为10分钟");
    }
}];

2. 设置血氧测试间隔

- (void)bloodSetting_ring:(int)setValue
              finishBlock:(void (^)(CBCharacteristic *characteristic, NSError *error))finishBlock;

说明： 设置血氧自动测试的时间间隔

参数： - setValue - 间隔时间（分钟）

3. 设置压力测试间隔

- (void)pressSetting_ring:(int)setValue
              finishBlock:(void (^)(CBCharacteristic *characteristic, NSError *error))finishBlock;

说明： 设置压力自动测试的时间间隔

参数： - setValue - 间隔时间（分钟）

健康数据获取

1. 获取最新步数

- (void)fetchLastStep_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取最新的计步数据

回调数据：

@{
    // JSON格式的步数数据
}

2. 汇总最新数据

- (void)fetchLastOtherValue_ring:(void (^)(NSDictionary *result, NSError *error))block;

说明： 获取各类型健康数据的最新汇总值

回调数据：

@{
    // JSON格式的汇总数据
}

3. 获取触摸阈值

- (void)fetchTouchthreshold_ring:(void (^)(CBCharacteristic *characteristic, NSError *error))block
                   respondBlock:(void (^)(NSDictionary *result, NSError *error))respondBlock;

说明： 获取触摸阈值数据

参数： - block - 写入成功回调 - respondBlock - 数据响应回调

4. 批量获取数据

- (void)fetchBatchDataFromBluetooth:(BOOL)requestAll
                      timestampMap:(NSDictionary *)timestampMap
                         showLoading:(BOOL)showLoading;

说明： 批量获取戒指存储的健康数据

参数： - requestAll - YES表示获取所有类型，NO表示获取指定类型 - timestampMap - 时间戳映射字典 objc @{ @"1": @(1773825946), // 计步数据起始时间戳 @"2": @(1773825942) // 心率数据起始时间戳 } - showLoading - 是否显示加载提示

数据类型说明： | dataType | 数据类型 | |———-|———-| | 1 | 计步 | | 2 | 心率 | | 3 | RR间期 | | 4 | 压力 | | 5 | 血氧 | | 6 | 体温 | | 7 | 睡眠 |

5. 获取指定类型数据

- (void)fetchLatestDataByType:(NSInteger)dataType
               startTimestamp:(NSInteger)timestamp
                    maxRetries:(int)maxRetries;

说明： 获取指定类型的批量数据

参数： - dataType - 数据类型 - 1 = 计步 - 2 = 心率 - 3 = RR间期 - 4 = 压力 - 5 = 血氧 - 6 = 体温 - 7 = 睡眠 - timestamp - 开始时间戳（最长7天内的数据） - maxRetries - 最大重试次数

辅助方法

提取数据值

- (NSNumber *)fetchValueByData:(NSData *)oriData subRange:(NSRange)subRange;

说明： 从原始数据中提取指定范围的值（私有方法）

参数： - oriData - 原始数据 - subRange - 数据范围

返回值： 提取的数值

使用示例

基本初始化和连接

#import "XinJieManage.h"

// 1. 配置SDK
[[XinJieManage shareXinJieManageBluetooth] configUserID:@"your_user_id"
                                                userKey:@"your_user_key"
                                              filterName:@"Ring"];

// 2. 设置代理
[[XinJieManage shareXinJieManageBluetooth] addBlockArray:self];

// 3. 开始扫描连接
[[XinJieManage shareXinJieManageBluetooth] checkScanOrConnect];

// 4. 实现代理方法
- (void)statusChange:(NSNumber *)connected {
    if ([connected boolValue]) {
        NSLog(@"设备已连接");
    } else {
        NSLog(@"设备已断开");
    }
}

获取电量信息

[[XinJieManage shareXinJieManageBluetooth] fetchBatteryLevel_ring:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"获取失败: %@", error.localizedDescription);
    } else {
        NSString *batteryLevel = result[@"BatteryLevel"];
        NSLog(@"当前电量: %@%%", batteryLevel);
    }
}];

批量获取健康数据

// 获取所有类型数据
[[XinJieManage shareXinJieManageBluetooth] fetchBatchDataFromBluetooth:YES
                                                          timestampMap:@{}
                                                             showLoading:YES];

// 或获取指定类型数据
NSInteger startTime = [[NSDate date] timeIntervalSince1970] - 7 * 24 * 3600; // 7天前
[[XinJieManage shareXinJieManageBluetooth] fetchLatestDataByType:1
                                                    startTimestamp:startTime
                                                         maxRetries:5];

设置自动测试间隔

// 设置每10分钟测量一次心率
[[XinJieManage shareXinJieManageBluetooth] heartSetting_ring:10
                                                   finishBlock:^(CBCharacteristic *characteristic, NSError *error) {
    if (!error) {
        NSLog(@"心率自动测试已设置为10分钟间隔");
    }
}];

断开连接

// 停止扫描
[[XinJieManage shareXinJieManageBluetooth] stopScan];

// 断开连接
[[XinJieManage shareXinJieManageBluetooth] disconnected];

常见问题

Q: 如何获取真实MAC地址？

A: 需要满足以下条件： 1. 固件版本 > 0.26.03.2.1 2. 调用 fetchiOSRealMac_ring: 方法

Q: 批量数据能获取多长时间？

A: 最长支持获取7天内的数据。

Q: 自动连接如何使用？

A: 调用 autoLinkSetting_ring:YES 开启自动连接，设备会自动连接上次成功的设备。

Q: 如何判断设备是否已连接？

A: 调用 isConnected 方法，或实现 XinJieDelegate 协议的 statusChange: 方法监听连接状态。

版本历史

联系方式

如有问题，请联系技术支持。