蓝牙技术体系

更新时间:2024-06-26 03:42:40下载pdf

在 App 开发方面,蓝牙主要有以下几种技术方案:

蓝牙类型 说明 设备应用示例
蓝牙单点 蓝牙设备与手机一对一连接单点设备(蓝牙或低功耗蓝牙) 体脂秤、手环、温控器、电动牙刷、门锁等
蓝牙 Mesh 蓝牙技术联盟发布的蓝牙拓扑通信 一路、二路、五路等灯泡、插座、传感器等子设备
涂鸦 Mesh 涂鸦自研的蓝牙拓扑通信 与蓝牙 Mesh 产品类似,通信协议为涂鸦自研
双模设备 一些多协议设备也会使用到蓝牙技术,例如同时具备 Wi-Fi 能力和蓝牙能力的 双模设备 蓝牙 Mesh 网关、IPC 设备、新版多协议 Wi-Fi 设备等

双模配网的蓝牙配网部分,使用的是蓝牙单点技术为设备配网,将放到 蓝牙单点章节 进行说明。

功能描述

蓝牙部分所具备的功能如下:

  • 设备配网
    • 扫描并发现设备
    • 设备配网
  • 设备管理
    • 检查设备当前联网状态
    • 连接设备
    • 设备操作和远程控制
    • 解绑设备
  • 固件升级
    • 检测设备版本
    • 升级设备固件 OTA

所需权限

在 iOS 13 中,苹果将原来蓝牙申请权限用的 NSBluetoothPeripheralUsageDescription 字段,替换为 NSBluetoothAlwaysUsageDescription 字段。在 info.plist 中添加新字段:

<key>NSBluetoothAlwaysUsageDescription</key>
    <string></string>

<key>NSBluetoothPeripheralUsageDescription</key>
    <string></string>

iOS12 适配

iOS 12 使用 [[ThingSmartActivator sharedInstance] currentWifiSSID] 无法查询到 SSID。

在 Xcode 10 中查询 Wi-Fi 信息需要开启相关权限,解决方法:Xcode > [Project Name] > Targets > [Target Name] > Capabilities > Access Wi-Fi Information > ON

蓝牙技术体系

功能入口

类名 说明 能力
ThingSmartBLEManager 单点蓝牙相关类 包含单点蓝牙 SDK 的所有相关功能,包含扫描设备、单点设备配网、双模设备配网、蓝牙设备操作、固件升级、错误码等。
ThingSmartBLEWifiActivator 双模设备配网相关类 包含设备双模配网所需方法。

单点蓝牙设备指的是具有和手机终端 通过蓝牙一对一连接 的设备,例如蓝牙手环、蓝牙耳机、蓝牙音箱等。每个设备最多同时和一个手机进行蓝牙连接,每个手机终端目前 同时连接的蓝牙数量控制在 6 ~ 7 个 内。

监测手机蓝牙状态

接口说明

在用户手机的蓝牙发生状态变化时,例如开启或关闭,可以通过设置代理收到具体的消息。

示例代码

Objective-C:

// 设置代理
[ThingSmartBLEManager sharedInstance].delegate = self;

/**
 * 蓝牙状态变化通知
 *
 * @param isPoweredOn 蓝牙状态,开启或关闭
 */
- (void)bluetoothDidUpdateState:(BOOL)isPoweredOn {
    NSLog(@"蓝牙状态变化: %d", isPoweredOn ? 1 : 0);
}

Swift:

// 设置代理
ThingSmartBLEManager.sharedInstance().delegate = self

/**
 * 蓝牙状态变化通知
 *
 * @param isPoweredOn 蓝牙状态,开启或关闭
 */
func bluetoothDidUpdateState(_ isPoweredOn: Bool) {

}

扫描蓝牙设备

开始扫描

接口说明

处于待连接状态的蓝牙设备都会不停地向四周发蓝牙广播包。客户端作为终端可以发现这些广播包,然后根据广播包中包含的涂鸦设备信息规则,作为目标设备的过滤条件。

/**
 * 开始扫描
 *
 * 如果扫描到未激活设备,结果会通过 ThingSmartBLEManagerDelegate 中的 - (void)didDiscoveryDeviceWithDeviceInfo:(ThingBLEAdvModel *)deviceInfo 返回
 *
 * 如果扫描到激活设备,会自动进行连接入网,不会返回扫描结果
 *
 * @param clearCache 是否清理已扫描到的设备
 */
- (void)startListening:(BOOL)clearCache;

typedef NS_ENUM(NSInteger,ThingBLEScanType){
    ThingBLEScanTypeNoraml = 1 << 0, // 0001 1 普通设备
    ThingBLEScanTypeQRCode = 1 << 1, // 0010 2 支持扫码配网设备
};

/**
 * 开始扫描
 *
 * 如果扫描到未激活设备,结果会通过 ThingSmartBLEManagerDelegate 中的 - (void)didDiscoveryDeviceWithDeviceInfo:(ThingBLEAdvModel *)deviceInfo 返回
 *
 * 如果扫描到激活设备,会自动进行连接入网,不会返回扫描结果
 *
 * @param scanType 扫描类型
 * @param clearCache 是否清理已扫描到的设备
 */
- (void)startListeningWithType:(ThingBLEScanType)scanType cacheStatu:(BOOL)clearCache;

参数说明

参数 说明
clearCache 是否清理已扫描到的设备
scanType 蓝牙扫描类型

示例代码

Objective-C:

// 设置代理
[ThingSmartBLEManager sharedInstance].delegate = self;

// 开始扫描
[[ThingSmartBLEManager sharedInstance] startListening:YES];

//或者使用以下方法 开始扫描
[[ThingSmartBLEManager sharedInstance] startListeningWithType:ThingBLEScanTypeNoraml cacheStatu:YES];

/**
 * 扫描到未激活的设备
 *
 * @param deviceInfo 未激活设备信息 Model
 */
- (void)didDiscoveryDeviceWithDeviceInfo:(ThingBLEAdvModel *)deviceInfo {
    // 成功扫描到未激活的设备
    // 若设备已激活,则不会调用此回调,且会自动进行激活连接
}

Swift:

ThingSmartBLEManager.sharedInstance().delegate = self

ThingSmartBLEManager.sharedInstance().startListening(true)
//或者
ThingSmartBLEManager.sharedInstance().startListening(with: .normal, cacheStatu: true)

/**
 * 扫描到未激活的设备
 *
 * @param uuid 未激活设备 UUID
 * @param productKey 未激活设备产品 key
 */
func didDiscoveryDevice(withDeviceInfo deviceInfo: ThingBLEAdvModel) {
    // 成功扫描到未激活的设备
    // 若设备已激活,则不会走此回调,且会自动进行激活连接
}

ThingBLEAdvModel 说明

属性 类型 说明
uuid NSString 设备 UUID,可以唯一区别设备
productId NSString 产品 ID
mac NSString 设备 MAC 地址,不可作为设备唯一标识码,iOS 为空
isActive Bool 是否被绑定,能回调的均为未配网的设备
isSupport5G Bool 表示低功耗蓝牙设备是否支持通过路由器在 5 GHz 频段上的连接
isProuductKey Bool 是否支持 productKey
bleProtocolV int 设备支持的涂鸦低功耗蓝牙协议版本
isSupportMultiUserShare Bool 是否是共享设备
bleType Enum 设备类型,用于区分不同协议的设备

bleType 表示待配网设备的类型。若取值中带有 Wifi,则表示为双模设备,此时参考下文 双模配网部分。否则为蓝牙设备,此时参考下文对应的蓝牙配网部分。

bleType 取值 设备类型
ThingSmartBLETypeBLE 蓝牙设备
ThingSmartBLETypeBLEPlus 蓝牙设备
ThingSmartBLETypeBLEWifi Wi-Fi 和蓝牙双模设备
ThingSmartBLETypeBLESecurity 蓝牙设备
ThingSmartBLETypeBLEWifiSecurity Wi-Fi 和蓝牙双模设备
ThingSmartBLETypeBLEWifiPlugPlay Wi-Fi 和蓝牙双模设备,并具备 双模设备蓝牙兜底激活 能力
ThingSmartBLETypeBLEZigbee 低功耗蓝牙和 Zigbee 设备
ThingSmartBLETypeBLELTESecurity LET Cat.1 和 Wi-Fi 双模设备
ThingSmartBLETypeBLEBeacon 低功耗蓝牙 Beacon 设备
ThingSmartBLETypeBLEWifiPriorBLE Wi-Fi 和蓝牙双模设备,支持优先走 双模设备蓝牙兜底激活

停止扫描

停止扫描设备,例如退出配网页面或者完成配网流程时,建议停止扫描,以便防止扫描影响到配网过程。

接口说明

/**
 * 停止扫描
 *
 * @param clearCache 是否清理已扫描到的设备
 */
- (void)stopListening:(BOOL)clearCache;

参数说明

参数 说明
clearCache 是否清理已扫描到的设备

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] stopListening:YES];

Swift:

ThingSmartBLEManager.sharedInstance().stopListening(true)

蓝牙单点配网

接口说明

扫描到未激活的设备后,可以进行设备激活并且注册到云端,并记录在家庭下。

/**
 * 激活设备
 * 激活过程会将设备信息注册到云端
 */
- (void)activeBLE:(ThingBLEAdvModel *)deviceInfo
           homeId:(long long)homeId
          success:(void(^)(ThingSmartDeviceModel *deviceModel))success
          failure:(ThingFailureHandler)failure;

参数说明

参数 说明
deviceInfo 设备信息 Model,来源于扫描代理方法返回的结果
homeId 当前家庭 ID
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] activeBLE:deviceInfo homeId:homeId success:^(ThingSmartDeviceModel *deviceModel) {
        // 激活成功

    } failure:^{
        // 激活中的错误
    }];

Swift:

ThingSmartBLEManager.sharedInstance().activeBLE(<deviceInfo: deviceInfo, homeId: homeId, success: { (deviceModel) in
        // 激活成功
        }) {
        // 激活中的错误
        }

双模设备配网

双模设备入网

接口说明

扫描到未激活的设备后,可以使用该方法,将配网信息通过蓝牙通道下发给设备,并等待配网结果回调。

/**
 * connect Bluetooth LE and Wi-Fi device
 * 连接蓝牙 Wi-Fi 设备
 */
- (void)startConfigBLEWifiDeviceWithUUID:(NSString *)UUID
                                  homeId:(long long)homeId
                               productId:(NSString *)productId
                                    ssid:(NSString *)ssid
                                password:(NSString *)password
                                timeout:(NSTimeInterval)timeout
                                 success:(ThingSuccessHandler)success
                                 failure:(ThingFailureHandler)failure;

参数说明

参数 说明
UUID 设备 UUID
homeId 当前家庭 ID
productId 产品 ID
ssid Wi-Fi 路由器热点名称
password Wi-Fi 路由器热点密码
timeout 轮询时间
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEWifiActivator sharedInstance] startConfigBLEWifiDeviceWithUUID:ThingBLEAdvModel.uuid homeId:homeId productId:ThingBLEAdvModel.productId ssid:ssid password:password timeout:100 success:^{
    // 下发成功
    } failure:^{
    // 下发失败
    }];

Swift:

ThingSmartBLEWifiActivator.sharedInstance() .startConfigBLEWifiDevice(withUUID: ThingBLEAdvModel.uuid, homeId: homeId, productId:ThingBLEAdvModel.productId, ssid: ssid, password: password, timeout: 100, success: {
        // 下发成功
    }) {
        // 下发失败
    }

双模设备激活回调

接口说明

配网的结果通过 delegate 方法回调。

目前多个双模设备同时配网时,只支持逐个地配网。若多设备在同一次配网请求中,逐个配网成功,配网成功的回调只执行一次。

示例代码

Objective-C:

- (void)bleWifiActivator:(ThingSmartBLEWifiActivator *)activator didReceiveBLEWifiConfigDevice:(ThingSmartDeviceModel *)deviceModel error:(NSError *)error {
    if (!error && deviceModel) {
            // 配网成功
    }

    if (error) {
            // 配网失败
    }
}

Swift:

func bleWifiActivator(_ activator: ThingSmartBLEWifiActivator, didReceiveBLEWifiConfigDevice deviceModel: ThingSmartDeviceModel?, error: Error?) {
    if (!error && deviceModel) {
            // 配网成功
    }

    if (error) {
            // 配网失败
    }
}

关闭轮询

示例代码

Objective-C:

//在配网结束后调用
[[ThingSmartBLEWifiActivator sharedInstance] stopDiscover];

Swift:

//在配网结束后调用
ThingSmartBLEWifiActivator.sharedInstance() .stopDiscover

双模设备蓝牙兜底激活

部分双模设备拥有蓝牙兜底激活能力。可在设备无法连接 Wi-Fi 路由器,或者 Wi-Fi 路由器无法连接互联网时,将这类设备当成普通蓝牙设备。调用本方法激活设备的蓝牙通道。

可以通过 ThingBLEAdvModelbleType,判断扫描到的设备是否拥有蓝牙兜底配网能力。若值为 ThingSmartBLETypeBLEWifiPlugPlayThingSmartBLETypeBLEWifiPriorBLE,则表示该设备拥有蓝牙兜底配网能力,其它结果则表示没有该能力。

接口说明

/**
 * activates the Bluetooth mode for a dual-mode device
 * 激活双模设备的蓝牙通道
 */
- (void)activatorDualDeviceWithBleChannel:(ThingBLEAdvModel *)advModel
                                   homeId:(long long)homeId
                                    token:(NSString *)token
                                  success:(void(^)(ThingSmartDeviceModel *deviceModel))success
                                  failure:(ThingFailureError)failure;

参数说明

参数 说明
advModel 设备信息 Model,来源于扫描代理方法返回的结果
homeId 当前家庭 ID
token 配网 Token
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] activatorDualDeviceWithBleChannel:advModel homeId:homeId token:token success:^(ThingSmartDeviceModel * _Nonnull device) {
                    // 兜底配网成功
    } failure:^(NSError *error) {
                    // 兜底配网失败
    }];

Swift:

ThingSmartBLEManager.sharedInstance().activatorDualDevice(withBleChannel: advModel, homeId: homeId, token: token) { (ThingSmartDeviceModel) in
            // 兜底配网成功
        } failure: { (Error?) in
            // 兜底配网失败
        }

请对查询到的 token 截取字符串([token substringWithRange:NSMakeRange(2, 8)]),否则会返回 Token 字符串过长的错误。

双模设备连云激活

通过蓝牙兜底方法激活成功的设备,若想重新尝试让设备通过 Wi-Fi 通道进行云端激活,可以调用本接口实现。

调用时,确保设备和 App 处于蓝牙连接状态。可通过 deviceModel.meta 中的 wifiEnable 字段,判断设备是否连云激活成功。默认值为 false,表示设备 Wi-Fi 通道未激活。

接口说明

/**
 * activates the Wi-Fi channel of a dual-mode device for which the Bluetooth channel is activated.
 * 当双模设备蓝牙通道激活成功时,连云激活该设备 Wi-Fi 通道
 */
- (void)activeDualDeviceWifiChannel:(NSString *)devId
                               ssid:(NSString *)ssid
                           password:(NSString *)password
                            timeout:(NSTimeInterval)timeout
                            success:(void(^)(ThingSmartDeviceModel *deviceModel))success
                            failure:(ThingFailureError)failure;

参数说明

参数 说明
devId 设备 ID
ssid Wi-Fi 路由器热点名称
password Wi-Fi 路由器热点密码
timeout 轮询时间
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] activeDualDeviceWifiChannel:devId ssid:ssid password:password timeout:timeout success:^(ThingSmartDeviceModel * _Nonnull device) {
                    // 连云激活成功
    } failure:^(NSError *error) {
                    // 连云激活失败
    }];

Swift:

ThingSmartBLEManager.sharedInstance().activeDualDeviceWifiChannel(devId, ssid: ssid, password: password, timeout: timeout) { (ThingSmartDeviceModel) in
            // 连云激活成功
        } failure: { (Error?) in
            // 连云激活失败
        }

双模配网优化方案

此优化方案会先与设备建立连接,通过设备扫描当前环境 Wi-Fi 列表,扫描出的 Wi-Fi 都是设备支持配网的 Wi-Fi。如此,过滤了设备可能不支持 5G 网络的情况,从而提高用户配网体验,并提高配网成功率。

接入条件

待配网设备的应用固件使用的 TuyaOS 版本号不能低于 3.6.1。

扫描 Wi-Fi 列表

接口说明

根据 UUID,与蓝牙设备建立连接,并扫描设备支持的 Wi-Fi 列表。

- (void)connectAndQueryWifiListWithUUID:(NSString *)UUID
                                success:(ThingSuccessHandler)success
                                failure:(ThingFailureError)failure;

参数说明

参数 说明
UUID UUID
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEWifiActivator sharedInstance] connectAndQueryWifiListWithUUID:UUID success:^{
  // 指令下发成功
} failure:^(NSError *error) {
  // 指令下发失败
}];

Swift:

ThingSmartBLEWifiActivator.sharedInstance().connectAndQueryWifiList(UUID: UUID) { _ in
  // 指令下发成功
} failure: { (Error?) in
  // 指令下发失败
}

设备状态异常回调

接口说明

设备如果不在配网状态,通过 delegate 方法回调。

- (void)bleWifiActivator:(ThingSmartBLEWifiActivator *)activator notConfigStateWithError:(NSError *)error;

示例代码

Objective-C:

- (void)bleWifiActivator:(ThingSmartBLEWifiActivator *)activator notConfigStateWithError:(NSError *)error {
  // 设备不在配网状态
}

Swift:

func bleWifiActivator(_ activator: ThingSmartBLEWifiActivator, notConfigStateWithError error: Error) {
  // 设备不在配网状态
}

扫描 Wi-Fi 列表回调

接口说明

Wi-Fi 列表扫描结果通过 delegate 方法回调。

- (void)bleWifiActivator:(ThingSmartBLEWifiActivator *)activator didScanWifiList:(nullable NSArray *)wifiList uuid:(nullable NSString *)uuid error:(nullable NSError *)error;

示例代码

Objective-C:

- (void)bleWifiActivator:(ThingSmartBLEWifiActivator *)activator didScanWifiList:(NSArray *)wifiList uuid:(NSString *)uuid error:(nonnull NSError *)error{
    if (error) {
    // Wi-Fi 列表扫描失败
    } else {
    // Wi-Fi 列表扫描成功
    }
}

Swift:

func bleWifiActivator(_ activator: ThingSmartBLEWifiActivator, didScanWifiList wifiList: [Any]?, uuid: String?, error: Error?) {
    if let e = error {
      // Wi-Fi 列表扫描失败
    } else {
      // Wi-Fi 列表扫描成功
    }
}

扫描 Wi-Fi 列表后开始配网

接口说明

因扫描 Wi-Fi 列表已经和设备建立连接,为了节省资源,避免重复连接调用以下接口开始配网。

- (void)pairDeviceWithUUID:(NSString *)UUID
                     token:(NSString *)token
                      ssid:(NSString *)ssid
                       pwd:(NSString *)pwd
                   timeout:(long)timeout;

参数说明

参数 说明
UUID UUID
token 配网 Token
ssid Wi-Fi 路由器热点名称
pwd Wi-Fi 路由器热点密码
timeout 配网超时时间

示例代码

Objective-C:

        [[ThingSmartBLEWifiActivator sharedInstance] pairDeviceWithUUID:@"uuid"
                                                                  token:@"token"
                                                                   ssid:@"ssid"
                                                                    pwd:@"password"
                                                                timeout:120];

Swift:

let activator = ThingSmartBLEWifiActivator.sharedInstance()
activator.pairDevice(withUUID: "UUID", token: "token", ssid: "ssid", pwd: "password", timeout: 120)

恢复配网

一般在密码错误情况下,可以使用恢复配网,重新传入 Wi-Fi 名称和密码,恢复配网。

在配网过程中,SDK 会在指定时间内自动连接设备。如果连接成功,SDK 内部会获取设备状态,上报给业务方。此方法只针对新设备固件有效。

接口说明

- (int)resumeConfigBLEWifiDeviceWithActionType:(ThingBLEWifiConfigResumeActionType)actionType
                                   configModel:(ThingBLEWifiConfigModel *)configModel;

参数说明

参数 说明
actionType 配网恢复类型
configModel 配网 Token

ThingBLEWifiConfigModel

参数 说明
UUID UUID
token 配网 Token
ssid Wi-Fi 路由器热点名称
pwd Wi-Fi 路由器热点密码

示例代码

Objective-C:

ThingBLEWifiConfigModel *configModel = [ThingBLEWifiConfigModel new];
configModel.uuid = @"UUID";
configModel.ssid = @"ssid";
configModel.password = @"password";
self.uuid = activatorParam.bleWifiActivatorParams.uuid;
[[ThingSmartBLEWifiActivator sharedInstance] resumeConfigBLEWifiDeviceWithActionType:ThingBLEWifiConfigResumeActionTypeSetWifi configModel:configModel];

Swift:

let model = ThingBLEWifiConfigModel()
model.uuid = "uuid"
model.ssid = "ssid"
model.password = "password"
activator.resumeConfigBLEWifiDevice(with: .setWifi, configModel: model)

蓝牙设备管理

判断设备在线状态

接口说明

查询设备蓝牙是否本地连接。

- (BOOL)deviceStatueWithUUID:(NSString *)uuid;

如果是双模设备,可根据 ThingSmartDeviceModel 里的 isOnline 是否为 true,来判断设备在线:

  • ThingSmartDeviceModel 里的 isOnlinetrue,且上述方法返回 true,判断双模设备为蓝牙在线。
  • ThingSmartDeviceModel 里的 isOnlinetrue,且上述方法返回 false,判断双模设备为 Wi-Fi 在线。

参数说明

参数 说明
uuid 设备 UUID

示例代码

Objective-C:

BOOL isOnline = [ThingSmartBLEManager.sharedInstance deviceStatueWithUUID:uuid];

Swift:

var isOnline:BOOL = ThingSmartBLEManager.sharedInstance().deviceStatue(withUUID: "uuid")

连接离线中的设备

接口说明

若设备处于离线状态,可以调用连接方法进行设备连接。

- (void)connectBLEWithUUID:(NSString *)uuid
                productKey:(NSString *)productKey
                   success:(ThingSuccessHandler)success
                   failure:(ThingFailureHandler)failure;

参数说明

参数 说明
uuid 设备 UUID
productKey 产品 ID
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] connectBLEWithUUID:@"your_device_uuid" productKey:@"your_device_productKey" success:success failure:failure];

Swift:

ThingSmartBLEManager.sharedInstance().connectBLE(withUUID: @"your_device_uuid", productKey: @"your_device_productKey", success: success, failure: failure)

断开已连接的设备

接口说明

若设备处于连接状态,可以调用该方法断开与设备的连接。

- (void)disconnectBLEWithUUID:(NSString *)uuid
                      success:(ThingSuccessHandler)success
                      failure:(ThingFailureError)failure;

参数说明

参数 说明
uuid 设备 UUID
success 成功回调
failure 失败回调

示例代码

Objective-C:

  [[ThingSmartBLEManager sharedInstance] disconnectBLEWithUUID:@"your_device_uuid" success:success failure:failure];

Swift:

  ThingSmartBLEManager.sharedInstance().disconnectBLE(withUUID: @"your_device_uuid", success: success, failure: failure)

查询设备名称

接口说明

当扫描到设备广播包,并获取设备广播包对象后,可以通过该方法查询设备名称。

/**
 * 查询设备名称
 */
- (void)queryDeviceInfoWithUUID:(NSString *)uuid
                      productId:(NSString *)productId
                        success:(ThingSuccessDict)success
                        failure:(ThingFailureError)failure;

参数说明

参数 说明
uuid 设备 UUID
productId 产品 ID
success 成功回调
failure 失败回调

示例代码

Objective-C:

[[ThingSmartBLEManager sharedInstance] queryNameWithUUID:bleAdvInfo.uuid productId:bleAdvInfo.productId success:^(NSDictionary *dict) {
        // 查询设备名称成功

    } failure:^{
        // 查询设备名称失败
    }];

Swift:

ThingSmartBLEManager.sharedInstance().queryName(withUUID: bleAdvInfo.uuid, productId: bleAdvInfo.productId, success: { (dict) in
        // 查询设备名称成功
}, failure: { (error) in
        // 查询设备名称失败
})

设备固件升级

从 3.35.5 版本 SDK 开始,统一了设备固件 OTA 升级的方式。请参考 设备管理-固件升级 了解新的升级方法,从而简化升级过程。

查询设备升级信息

接口说明

- (void)getFirmwareUpgradeInfo:(nullable void (^)(NSArray <ThingSmartFirmwareUpgradeModel *> *upgradeModelList))success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
success 成功回调,设备的固件升级信息列表
failure 失败回调

ThingSmartFirmwareUpgradeModel 数据模型

字段 类型 说明
desc NSString 固件升级的描述文案
typeDesc NSString 设备类型说明
upgradeStatus NSInteger 升级状态:
  • 0:无新版本
  • 1:有新版本
  • 2:在升级中
  • 5:等待设备唤醒
version NSString 新版本使用的固件版本
upgradeType NSInteger 升级类型:
  • 0:App 提醒升级
  • 2:App 强制升级
  • 3:检测升级
url NSString 蓝牙设备的升级固件包下载 URL
fileSize NSString 固件包的大小,单位为字节(byte)
md5 NSString 固件的 MD5
upgradingDesc NSString 固件升级中的提示文案

示例代码

Objective-C:

- (void)getFirmwareUpgradeInfo {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];

    [self.device getFirmwareUpgradeInfo:^(NSArray<ThingSmartFirmwareUpgradeModel *> *upgradeModelList) {
        NSLog(@"getFirmwareUpgradeInfo success");
    } failure:^(NSError *error) {
        NSLog(@"getFirmwareUpgradeInfo failure: %@", error);
    }];
}

Swift:

func getFirmwareUpgradeInfo() {
    device?.getFirmwareUpgradeInfo({ (upgradeModelList) in
        print("getFirmwareUpgradeInfo success")
    }, failure: { (error) in
        if let e = error {
            print("getFirmwareUpgradeInfo failure: \(e)")
        }
    })
}

固件 OTA 升级

接口说明

对于有固件升级的设备,可以通过发送升级固件数据包对设备进行升级。其中,升级固件包需要先请求云端接口,来查询固件信息。

/**
 * 发送 OTA 包,升级固件。升级前,确保设备已通过蓝牙连接
 */
- (void)sendOTAPack:(NSString *)uuid
                pid:(NSString *)pid
            otaData:(NSData *)otaData
            success:(ThingSuccessHandler)success
            failure:(ThingFailureHandler)failure;

参数说明

参数 说明
uuid 设备 UUID
pid 产品 ID
otaData 升级固件的数据
success 成功回调
failure 失败回调

示例代码

Objective-C:

- (void)getFirmwareUpgradeInfo {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];

    [self.device getFirmwareUpgradeInfo:^(NSArray<ThingSmartFirmwareUpgradeModel *> *upgradeModelList) {
        NSLog(@"getFirmwareUpgradeInfo success");
    } failure:^(NSError *error) {
        NSLog(@"getFirmwareUpgradeInfo failure: %@", error);
    }];
}

// 如果有升级,其中 ThingSmartFirmwareUpgradeModel.url 是固件升级包的下载地址
// 根据 URL 下载固件后,将数据转成 data,传给 SDK 进行固件升级
// deviceModel:需要升级的设备 model
// data:下载的固件包
[[ThingSmartBLEManager sharedInstance] sendOTAPack:deviceModel.uuid pid:deviceModel.pid otaData:data success:^{
       NSLog(@"OTA 成功");
    } failure:^{
       NSLog(@"OTA 失败");
}];

Swift:

func getFirmwareUpgradeInfo() {
    device?.getFirmwareUpgradeInfo({ (upgradeModelList) in
        print("getFirmwareUpgradeInfo success");
    }, failure: { (error) in
        if let e = error {
            print("getFirmwareUpgradeInfo failure: \(e)");
        }
    })
}

// 如果有升级,其中 ThingSmartFirmwareUpgradeModel.url 是固件升级包的下载地址
// 根据 URL 下载固件后,将数据转成 data,传给 SDK 进行固件升级
// deviceModel:需要升级的设备 model
// data:下载的固件包
ThingSmartBLEManager.sharedInstance().sendOTAPack(deviceModel.uuid, pid: deviceModel.pid, otaData: data, success: {
    print("OTA 成功");
}) {
    print("OTA 失败");
}

错误码

错误码 说明
1 设备接收的数据包格式错误
2 设备找不到路由器
3 Wi-Fi 密码错误
4 设备连不上路由器
5 设备 DHCP 失败
6 设备连云失败
100 用户取消配网
101 蓝牙连接错误
102 发现蓝牙服务错误
103 打开蓝牙通讯通道失败
104 蓝牙查询设备信息失败
105 蓝牙配对失败
106 配网超时
107 Wi-Fi 信息发送失败
108 Token 失效
109 查询蓝牙加密密钥失败
110 设备不存在
111 设备云端注册失败
112 设备云端激活失败
113 云端设备已被绑定
114 主动断开
115 云端查询设备信息失败
116 设备此时正被其他方式配网
117 OTA 升级失败
118 OTA 升级超时
119 Wi-Fi 配网传参校验失败
120 发送密钥失败
121 发现蓝牙连接对象失败
122 没有蓝牙对象
123 游客不支持强绑定
124 蓝牙通用错误
125 Notify 打开失败
126 硬件加密设备端错误
127 硬件加密云端错误
128 非 Cat.1 设备双模配网失败未输入密码
129 获取 Token 失败
130 配网传参错误
131 查询设备 Wi-Fi 信息失败
132 Plug & Play 兜底激活接口调用失败
133 发送设备激活信息失败
134 设备云端上线失败导致超时
135 查询设备信息指令超时
136 配对指令超时
137 查询设备 Wi-Fi 信息指令超时
138 发送设备激活信息超时
139 激活过程获取云端设备信息失败
140 获取绑定状态 无权限
141 PSK3.0 设备拉取配置证书信息接口请求失败
142 PSK3.0 双模发送 Wi-Fi 指令失败
143 PSK3.0 Plug & Play 连云激活指令发送失败
200 设备 OTA 响应异常
201 设备 OTA 文件校验失败
202 设备 OTA 偏移量异常
203 设备 OTA 大包 ACK 失败
204 设备 OTA 固件发送失败
205 设备 OTA 设备最终返回升级失败
206 设备 OTA 超时
207 大数据传输失败
300 蓝牙发包 MTP 错误
301 Plug & Play 未能发送设备产品信息给设备
400 蓝牙连接超时
401 收到 Zigbee 子设备设备信息错误
402 收到 Zigbee 子设备指令信息错误
403 收到 Zigbee 网关上报的配网错误
404 收到 Zigbee 网关上报的数据解析错误
405 Zigbee 双模配网,下发网关信息失败
406 Zigbee 双模配网,设备回复网关信息无效
407 参数错误
600 设备控制失败,设备正在 OTA 中
601 设备控制失败,设备不在线