蓝牙单点

更新时间：2024-03-19 03:17:06下载pdf

本文介绍用于蓝牙设备与手机一对一相连的 蓝牙单点 技术。

准备工作

系统要求：蓝牙使用需要安卓 4.3 以及以上版本。

Manifest 权限：

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

蓝牙权限检测：每次扫描和连接前，都要进行检测，否则 App 无法正常使用蓝牙。
- App 在使用蓝牙连接或者扫描操作前，需要检查 App 定位权限是否被允许。
- 检查蓝牙状态是否为开启。
  
  该部分检查逻辑，商用照明 SDK 未提供 API，您可自行检测。

扫描设备

开始扫描

待配网的蓝牙设备向周围发送蓝牙广播包，SDK 会根据协议对广播包进行解析，从而发现周围的涂鸦蓝牙单点设备和双模设备等。

蓝牙设备扫描前需要进行权限检测，只有 具备权限才能正常扫描。

蓝牙是否打开。
应用是否具有定位权限。

接口说明

void startLeScan(LeScanSetting setting, BleScanResponse response);

参数说明

参数	类型	说明
setting	LeScanSetting	扫描的设置
response	BleScanResponse	扫描结果的回调，不能为空

构建类说明

LeScanSetting.Builder 用于构建需要扫描设备的设置。

方法名	参数	说明	是否必需
setTimeout()	long	设置超时时间，默认：40000，单位：毫秒	可选
addScanType()	ScanType	`SINGLE`：点对点蓝牙设备 `SIG_MESH`：标准蓝牙 Mesh 设备	必需，至少一个
setRepeatFilter()	boolean	重复过滤，默认：`true`	可选

示例代码

LeScanSetting scanSetting = new LeScanSetting.Builder()
        .setTimeout(60000) // 扫描的超时时间：ms
        .addScanType(ScanType.SINGLE) // 若需要扫描蓝牙设备，则只需要添加 ScanType.SINGLE
        // .addScanType(ScanType.SIG_MESH) 可同时添加其他类型设备
        .build();

// 开始扫描
ThingOSBLE.operator().startLeScan.startLeScan(scanSetting, new BleScanResponse() {
    @Override
    public void onResult(ScanDeviceBean bean) {
        // 回调扫描的结果 TODO
    }
});

回调说明

ScanDeviceBean 说明

属性	类型	说明
id	String	扫描 ID 通常由 UUID 组成，可以唯一区别设备
name	String	扫描到的蓝牙名称，一般为空
providerName	String	取值为 `SingleBleProvider` 则表示只开发单点设备，您无需关注该字段
data	byte[]	原始数据
configType	String	`config_type_single`：单点设备 `config_type_wifi`：双模设备
productId	String	产品 ID
uuid	String	设备 UUID，设备唯一码
mac	String	设备 MAC 地址，不可作为唯一码
isbind	boolean	设备是否被绑定，能回调的均为未配网的设备
flag	int	bit0：是否支持 5G，表明双模设备是否支持 5G Wi-Fi bit2：是否分享设备 bit3：是否⽀持蓝牙兜底配网设备 bit4：是否是扫码配网设备
address	String	设备地址
deviceType	int	设备类型，用于区分不同协议的设备，您无需关注该字段

deviceType 表示待配网设备类型。若带有 Wi-Fi 的双模设备，参考双模配网，蓝牙设备参考蓝牙配网。

deviceType 值	configType	设备类型
200	config_type_single	蓝牙设备
300	config_type_single	蓝牙设备
301	config_type_wifi	Wi-Fi + 蓝牙双模设备
304	config_type_wifi	Wi-Fi + 蓝牙双模设备（支持蓝牙兜底配网）
400	config_type_single	蓝牙设备
401	config_type_wifi	Wi-Fi + 蓝牙双模设备
404	config_type_wifi	Wi-Fi + 蓝牙双模设备（支持蓝牙兜底配网）

查询设备名称

扫描到目标设备以后，可以通过查询显示产品配置的名称和图标。

接口说明

void getActivatorDeviceInfo(String productId, String uuid, String mac, IThingDataCallback<ConfigProductInfoBean> callback);

参数说明

参数	类型	说明
productId	String	`ScanDeviceBean.getProductId`
uuid	String	`ScanDeviceBean.getUuid`
mac	String	`ScanDeviceBean.getMac` 该值一般设备为 `null`，只有某些品类有值

示例代码

ThingOSActivator.deviceActivator().getActivatorDeviceInfo(
    scanDeviceBean.getProductId(),
    scanDeviceBean.getUuid(),
    scanDeviceBean.getMac(),
    new IThingDataCallback<ConfigProductInfoBean>() {
        @Override
        public void onSuccess(ConfigProductInfoBean result) {

        }

        @Override
        public void onError(String errorCode, String errorMessage) {

        }
});

回调说明

ConfigProductInfoBean 说明

属性	类型	说明
name	String	产品名称，云端配置，一般是用户首次创建产品时的名称
icon	String	产品图标

停止扫描

当退出配网页面或者在执行设备入网时，建议停止设备扫描，以防止扫描影响到配网过程。

接口说明

void stopLeScan();

示例代码

ThingOSBLE.operator().stopLeScan();

单点设备配网

开始单点设备入网

扫描到的设备的 configType 属性取值为 config_type_single 表示单点蓝牙设备，config_type_wifi 为双模设备。

接口说明

void startActivator(BleActivatorBean bleActivatorBean, IBleActivatorListener listener);

参数说明

参数	类型	说明
bleActivatorBean	BleActivatorBean	需要连接的设备的参数集合
listener	IBleActivatorListener	配网结果的回调

BleActivatorBean 用于存放需要配网设备的参数以及设置。

属性	类型	说明	是否必需
homeId	long	当前配网所在区域对应的关系 ID，获取方式参考获取区域对应的关系 ID。	必需
uuid	String	设备 UUID，通过扫描可以查询。	必需
address	String	设备地址，通过扫描可以查询。	可选
productId	String	产品 ID，通过扫描可以查询。	可选
deviceType	Integer	设备类型，通过扫描可以查询。	必需
isShare	boolean	是否为共享设备，通过扫描可以查询，默认为 `false`。	可选
timeout	long	配网总超时，配网超时失败以该参数为准。单位：毫秒，默认：`60000`。	可选

示例代码

// mScanDeviceBean 来自于扫描回调的 ScanDeviceBean
BleActivatorBean bleActivatorBean = new BleActivatorBean(mScanDeviceBean);

bleActivatorBean.homeId = 123456; // homeId
bleActivatorBean.address = mScanDeviceBean.getAddress(); // 设备地址
bleActivatorBean.deviceType = mScanDeviceBean.getDeviceType(); // 设备类型
bleActivatorBean.uuid = mScanDeviceBean.getUuid(); // UUID
bleActivatorBean.productId = mScanDeviceBean.getProductId(); // 产品 ID
bleActivatorBean.isShare = (mScanDeviceBean.getFlag() >> 2) & 0x01 == 1; // 设备是否为共享类型的标志

// 开始配网
ThingOSActivator.activator().newBleActivator().startActivator(bleActivatorBean, new IBleActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功
    }

    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 配网失败
    }
});

取消单点设备入网

配网过程中终止配网。

接口说明

void stopActivator(String uuid);

参数说明

参数	类型	说明
uuid	String	扫描到的设备的 UUID，即 `ScanDeviceBean.uuid`

示例代码

ThingOSBLE.manager().stopBleConfig("uuid");

双模设备配网

双模设备入网

双模设备扫描到后，可以进行入网激活扫描到的设备。configType 属性取值为 config_type_single 表示单点蓝牙设备，config_type_wifi 为双模设备。

接口说明

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

参数说明

参数	类型	说明
multiModeActivatorBean	MultiModeActivatorBean	需要配网的双模设备参数集合
listener	IMultiModeActivatorListener	配网结果回调

MultiModeActivatorBean 说明

属性	类型	说明
deviceType	Integer	设备类型，可以通过扫描查询。
uuid	String	设备 UUID，可以通过扫描查询。
address	String	设备地址，可以通过扫描查询。
mac	String	设备 MAC 地址，可以通过扫描查询。
ssid	String	Wi-Fi SSID。
pwd	String	Wi-Fi 密码。
token	String	配网 Token，获取 Token 的方式与 Wi-Fi 设备配网一致，参考获取 Token。
homeId	long	当前配网所在区域对应的关系 ID，参考获取区域对应的关系 ID。
timeout	long	配网总超时，配网超时失败以该参数为准，单位为毫秒。

若未说明，一般设备只支持 2.4G 频段 Wi-Fi 配网，部分设备支持 5G。您可以根据 ScanDeviceBean.flag 进行判定。

示例代码

// mScanDeviceBean 来自于扫描回调的 ScanDeviceBean
MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean(mScanDeviceBean);

// mScanDeviceBean 来自于扫描回调的 ScanDeviceBean
multiModeActivatorBean.deviceType = mScanDeviceBean.getDeviceType(); // 设备类型
multiModeActivatorBean.uuid = mScanDeviceBean.getUuid(); // 设备 uuid
multiModeActivatorBean.address = mScanDeviceBean.getAddress(); // 设备地址
multiModeActivatorBean.mac = mScanDeviceBean.getMac(); // 设备 MAC 地址
multiModeActivatorBean.ssid = "WIFI_2.4G"; // Wi-Fi SSID
multiModeActivatorBean.pwd = "WIFI_PASSWORD"; // Wi-Fi 密码
multiModeActivatorBean.token = "abcd1234"; // 获取的 Token
multiModeActivatorBean.homeId = ; // 当前配网所在区域对应的关系 ID
multiModeActivatorBean.timeout = 120000; // 超时时间

// 开始配网
ThingOSActivator.activator().newMultiModeActivator().startActivator(multiModeActivatorBean, new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功
    }

    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 配网失败
    }
});

回调说明

DeviceBean：表示设备信息数据类型，参考 DeviceBean 数据模型。
Object handle：handle 返回类型是实体对象 ConfigErrorBean，参数说明如下：

参数类型说明

name String 设备名称

errorCode String 错误码

devId String 设备 ID

iconUrl String 设备图标

errorMsg String 错误信息

参数	类型	说明
name	String	设备名称
errorCode	String	错误码
devId	String	设备 ID
iconUrl	String	设备图标
errorMsg	String	错误信息

双模设备入网优化

该接口在配网过程中，会一直和设备保持蓝牙连接。如果设备在连接路由器（连云激活）过程中出现错误，会将错误上报给 App。
待配网设备的应用固件使用的 TuyaOS 版本号，不能低于 3.6.1。

接口说明

用户和上述一致，区别在于接口回调，适用于双模设备，包含蓝牙兜底配网设备（Plug&Play）。

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IExtMultiModeActivatorListener listener);

示例代码

ThingOSActivator.activator().newMultiModeActivator().startActivator(multiModeActivatorBean, new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功
    }

    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 配网失败
    }
    public void onActivatorStatePauseCallback(PauseStateData stateData) {
        //设备上报的数据，包含设备是否没有连上路由器等，具体含义见参数说明
    }
});

参数说明

PauseStateData

参数	说明
uuid	通用唯一标识符（UUID）
configStage	配网阶段
status	阶段状态

详细说明

configStage	说明	阶段状态说明
0	配网阶段激活	`0`：获取配网信息成功 `1`：配网信息错误
1	代理激活阶段	`0`：获取代理激活信息成功 `1`：配网信息错误
2	联网阶段	`0`：连接路由器成功 `1`：联网信息错误 `2`：找不到路由器 `3`：路由器密码错误 `4`：连接路由器失败 `5`：DHCP 失败
3	激活阶段	`1`：激活信息错误 `6`：连云失败 `7`：获取 URL 失败 `8`：激活接口失败 `9`：激活成功

取消双模设备配网

如果在配网过程中终止了配网，若设备已经进行到云端激活阶段，虽然取消设备配网，但可能仍然配网成功。

接口说明

ThingOSActivator.activator().newMultiModeActivator().stopActivator(uuid);

参数说明

参数	类型	说明
devUuid	String	扫描到的设备的 UUID

示例代码

ThingOSActivator.activator().newMultiModeActivator().stopActivator("uuidxxxx");

双模设备蓝牙兜底配网

部分双模设备拥有蓝牙兜底配网能力。用户使用 App 通过手机蓝牙，将设备连云所需信息传输给待配网设备，设备会尝试连接 Wi-Fi。若激活云端链路失败，会启动本地连接模式，使用手机蓝牙直接与设备通信。

判断扫描到的设备是否拥有蓝牙兜底配网能力，可以通过 ScanDeviceBean 的 getDeviceType() 方法查询。返回值为 404 或 304，则表示该设备拥有蓝牙兜底配网能力。其它结果则表示没有该能力。

接口说明

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

MultiModeActivatorBean 说明

参数	类型	说明
homeId	long	当前配网所在区域对应的关系 ID，参考获取区域对应的关系 ID
uuid	String	需要配网的设备 UUID
deviceType	int	设备类型
address	String	设备地址
timeout	long	设备配网超时总时长，单位为 ms
phase1Timeout	long	设备连云激活配网超时时长，默认：60000，单位：ms
ssid	String	需要连接的 Wi-Fi SSID
pwd	String	需要连接的 Wi-Fi 密码，若无密码则传空字符串
token	String	从云端查询的账号身份认证信息，获取 Token 的方式与 Wi-Fi 设备配网一致，参考获取 Token
mac	String	设备 MAC 地址

若未说明，一般设备只支持 2.4G 频段 Wi-Fi 配网，部分设备支持 5G。可以根据 ScanDeviceBean.flag 进行判定。

示例代码

// scanDeviceBean 为蓝牙扫描到的设备信息回调
MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean(scanDeviceBean);
// 设置 Wi-Fi 的 SSID
multiModeActivatorBean.ssid = "SSID_xxx";
// 设置 Wi-Fi 的密码
multiModeActivatorBean.pwd = "pwd_xxx";
// 设置设备 UUID
multiModeActivatorBean.uuid = scanDeviceBean.getUuid();
// 设置设备类型
multiModeActivatorBean.deviceType = scanDeviceBean.getDeviceType();
// 设置设备 MAC 地址
multiModeActivatorBean.mac = scanDeviceBean.getMac();
// 设置设备地址
multiModeActivatorBean.address = scanDeviceBean.getAddress();
// 设置 HomeID
multiModeActivatorBean.homeId = "homeId_xxx";
// 设置获取到的 Token
multiModeActivatorBean.token = "token_xxx";
// 设置配网总超时，单位：ms
multiModeActivatorBean.timeout = 120 * 1000L;
// 设置仅 Wi-Fi 连接的超时，单位：ms
multiModeActivatorBean.phase1Timeout = 60 * 1000L;

// 配网结果回调
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功
    }
    @Override
    public void onFailure(int code, String error, Object handle) {
        // 配网失败
    }
};

// 开始配网
ThingOSActivator.activator().newMultiModeActivator().startActivator(multiModeActivatorBean, listener);

开启连云激活，需要确保设备当前处于蓝牙链路激活状态，即通过蓝牙将连云激活的信息传输给设备。调用 DeviceBean 实例的 getCommunicationOnline(CommunicationEnum.BLE) 方法，可以查询当前设备蓝牙连接状态。只有返回值为 true 时，才能调用开启连云激活的方法。
如果需要判断云端链路是否激活，可以通过 deviceBean.getMeta().get("wifiEnable") 方法，查询设备是否连接 Wi-Fi。结果为 true，则表示云端链路已激活。

蓝牙兜底双模设备连云

上述蓝牙兜底配网设备，如果 Wi-Fi 激活失败，会进入蓝牙本地连接进行操作。此时，若想重新尝试让设备连接 Wi-Fi 进行云端激活，可以调用如下接口。调用时，需要确保设备处于本地蓝牙连接状态且云端链路未激活。

通过 DeviceBean 的 getCommunicationOnline(CommunicationEnum.BLE) 方法，查询本地蓝牙链路是否激活。
使用 deviceBean.getMeta().get("wifiEnable") 查询设备是否激活云端链路。

接口说明

void startWifiEnable(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

参数说明

参数	类型	说明
multiModeActivatorBean	MultiModeActivatorBean	需要重连 Wi-Fi 的设备参数集合
listener	IMultiModeActivatorListener	重连 Wi-Fi 结果的回调

MultiModeActivatorBean 说明

参数	类型	说明
timeout	long	设备重连 Wi-Fi 云端激活超时时长，单位为 ms
ssid	String	需要连接的 Wi-Fi SSID
pwd	String	需要连接的 Wi-Fi 密码，若无密码，则传空字符串
devId	Long	需要开启 Wi-Fi 使能的设备 ID

示例代码

MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean(scanDeviceBean);
multiModeActivatorBean.devId = "devId_xxx"; // 设备 devId
multiModeActivatorBean.ssid = "ssid_xxx"; // 需要连接的 Wi-Fi ssid
multiModeActivatorBean.pwd = "pwd_xxx"; // 需要连接的 Wi-Fi 密码
multiModeActivatorBean.timeout = 120 * 1000L; // 超时时长，单位：ms

// Wi-Fi 重新配网结果回调
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 激活 Wi-Fi，连接云端成功
    }
    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 激活 Wi-Fi，连接云端失败
    }
};

// 开始重新连接 Wi-Fi 并云端激活
ThingOSActivator.activator().newMultiModeActivator().startWifiEnable(multiModeActivatorBean, listener);

蓝牙兜底双模设备直接兜底激活

该接口拥有蓝牙兜底配网能力，可以直接进行蓝牙兜底配网，进入蓝牙本地连接进行操作。

示例代码

// scanDeviceBean 为蓝牙扫描到的设备信息回调
MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean(scanDeviceBean);
// 设置设备 UUID
multiModeActivatorBean.uuid = scanDeviceBean.getUuid();
// 设置设备类型
multiModeActivatorBean.deviceType = scanDeviceBean.getDeviceType();
// 设置设备 MAC 地址
multiModeActivatorBean.mac = scanDeviceBean.getMac();
// 设置设备地址
multiModeActivatorBean.address = scanDeviceBean.getAddress();
// 设置 HomeID
multiModeActivatorBean.homeId = "homeId_xxx";
// 设置获取到的 Token
multiModeActivatorBean.token = "token_xxx";
// 设置配网总超时，单位：ms
multiModeActivatorBean.timeout = 120 * 1000L;
// 设置仅 Wi-Fi 连接的超时，单位：ms
multiModeActivatorBean.phase1Timeout = 60 * 1000L;

// 配网结果回调
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        //配网成功
    }
    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 配网失败
    }
};

// 使用本地蓝牙连接直接激活设备
ThingOSActivator.activator().newMultiModeActivator().startBleActivator(multiModeActivatorBean, listener);

恢复配网

一般在密码错误情况下，可以使用恢复配网，重新传入 Wi-Fi 名称和密码，恢复配网。在配网过程中，SDK 会在指定时间内自动连接设备，如果连接成功，SDK 内部会获取设备状态，上报给业务方。该逻辑只针对新设备固件有效。
待配网设备的应用固件使用的 TuyaOS 版本号，不能低于 3.6.1。

接口说明

/**
 * 恢复配网
 * return -1, 代表失败，不支持恢复配网。0 代表支持配网并触发恢复配网流程
**/
int resumeActivator(@NonNull ResumeActivatorBean multiModeActivatorBean);

参数说明

ResumeActivatorBean

参数	说明
uuid	指定设备 UUID 开始配网
ssid	Wi-Fi 路由器热点名称
pwd	Wi-Fi 路由器热点密码
resumeType	恢复配网的配网类型： `ResumeActivatorBean.RESUME_TYPE_WIFI`：双模配网 `ResumeActivatorBean.RESUME_TYPE_BLE`：双模兜底配网

示例代码

ResumeActivatorBean bean = new ResumeActivatorBean.Builder()
                    .setResumeType(ResumeActivatorBean.RESUME_TYPE_WIFI)
                    .setUuid(param.uuid)
                    .setSsid(param.ssid)
                    .setPassword(param.pwd)
                    .build();
ThingOSActivator.activator().newMultiModeActivator().resumeActivator(bean);

双模设备配网优化方案

双模配网优化方案要求待配网设备的应用固件使用的 TuyaOS 版本号，不能低于 3.6.1。

扫描 Wi-Fi 列表

接口说明

根据蓝牙广播包和 UUID，匹配蓝牙设备建立本地连接，并扫描设备支持的 Wi-Fi 列表。

void queryDeviceConfigState(MultiModeQueryBuilder queryBuilder, IThingResultCallback<List<WiFiInfo>> callback);

参数说明

MultiModeQueryBuilder

参数	说明
homeId	当前配网所在区域对应的关系 ID，参考获取区域对应的关系 ID
timeout	操作超时时间，非必选，可以填 0，单位：ms
scanDeviceBean	来自于扫描回调的广播包 `ScanDeviceBean`

示例代码

MultiModeQueryBuilder queryBuilder = new MultiModeQueryBuilder.Builder()
                .setHomeId(homeId)
                .setTimeout(timeout * 1000)
                .setScanDeviceBean(scandeviceBean)//scandeviceBean 扫描到的广播包，内部会根据 uuid 匹配到蓝牙设备去进行本地蓝牙连接
                .build();
ThingOSActivator.activator().newMultiModeActivator().queryDeviceConfigState(queryBuilder, new IThingResultCallback<List<com.thingclips.smart.android.ble.api.WiFiInfo>>() {
        @Override
        public void onSuccess(List<com.thingclips.smart.android.ble.api.WiFiInfo>result) {
            //获取 Wi-Fi 列表成功
        }
        @Override
        public void onError(String errorCode, String errorMessage) {
            //获取失败
        }
    });

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

接口说明

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

void startOptimizationActivator(@NonNull MultiModeActivatorBuilder activatorBuilder, IMultiModeActivatorListener listener);

参数说明

MultiModeActivatorBuilder

参数	说明
uuid	指定 UUID 开始配网
ssid	Wi-Fi 路由器热点名称
pwd	Wi-Fi 路由器热点密码
timeout	配网超时时间，单位：ms

示例代码

MultiModeActivatorBuilder builder = new MultiModeActivatorBuilder.Builder()
                .setUuid(uuid)
                .setSsid(ssid)
                .setPwd(pwd)
                .setTimeout(120 * 1000)
                .setToken(token)
                .build();
ThingOSActivator.activator().newMultiModeActivator().startOptimizationActivator(builder, new IMultiModeActivatorListener() {
        @Override
        public void onSuccess(DeviceBean deviceBean) {
            //配网成功
        }
        @Override
        public void onFailure(int code, String msg, Object handle) {
            //配网失败，错误码见文末 207206～207223
        }
    });

恢复配网

一般在密码错误情况下，可以使用恢复配网，重新传入 Wi-Fi 名称和密码，恢复配网。在配网过程中，SDK 会在指定时间内自动连接设备。如果连接成功，SDK 内部会获取设备状态，上报给业务方。该逻辑只针对新设备固件有效。

接口说明

/**
 * 恢复配网
 * return -1, 代表失败，不支持恢复配网。0 代表支撑配网并触发恢复配网流程
**/
int resumeActivator(@NonNull ResumeActivatorBean multiModeActivatorBean);

参数说明

ResumeActivatorBean

参数	说明
uuid	指定设备 UUID 开始配网
ssid	Wi-Fi 路由器热点名称
pwd	Wi-Fi 路由器热点密码
resumeType	恢复配网的配网类型。`ResumeActivatorBean.RESUME_TYPE_WIFI`：目前双模配网优化流程固定填写该值，不支持蓝牙兜底配网类型

示例代码

ResumeActivatorBean bean = new ResumeActivatorBean.Builder()
                    .setResumeType(ResumeActivatorBean.RESUME_TYPE_WIFI)//配网优化流程，目前仅支持双模设备(含 PlugPlay)，固定为 RESUME_TYPE_WIFI
                    .setUuid(param.uuid)
                    .setSsid(param.ssid)
                    .setPassword(param.pwd)
                    .build();
ThingOSActivator.activator().newMultiModeActivator().resumeActivator(bean);

停止配网

示例代码

ThingOSActivator.activator().newMultiModeActivator().stopActivator(uuid);

设备操作

本章节介绍已配网的单点设备如何进行状态检测、连接、解绑等。

判断设备在线状态

方式一：采用通用方式查询，方法与 Wi-Fi 设备一致。查询的结果是综合状态，若蓝牙设备添加到网关下面，则蓝牙设备可云端在线。
```
ThingOSDevice.getDeviceBean(devId).getIsOnline();
```
方式二：查询设备蓝牙是否本地连接。通常情况下蓝牙只需要考虑本地状态即可。只有加入蓝牙网关下的蓝牙设备，才需要考虑是否云端在线。
```
ThingOSBLE.manager().isBleLocalOnline(devId);
```

连接离线设备

接口说明

void connectBleDevice(List<BleConnectBuilder> builderList);

参数说明

参数	类型	说明
builderList	List	`BleConnectBuilder` 集合，用于构建需要连接设备的设置

BleConnectBuilder 说明

方法名	参数	说明
setDirectConnect()	boolean	`true`：使用缓存连接，使用缓存普通情况下会增快连接速度 `false`：不使用缓存连接
setDevId()	String	需要连接的设备 ID
setScanTimeout()	Integer	扫描超时时长，单位为毫秒
setLevel()	BleConnectBuilder.Level	`NORMAL`：如果连接资源已满，则将忽略该连接。默认值：`NORMAL` `FORCE`：如果连接资源已满，将释放其它资源以连接到当前设备

示例代码

List<BleConnectBuilder> builderList = new ArrayList<>();

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder();
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder();

bleConnectBuilder1.setDevId(devId1); // 设备 1 的 devId
bleConnectBuilder2.setDevId(devId2); // 设备 2 的 devId

builderList.add(bleConnectBuilder1); // 添加设备 1
builderList.add(bleConnectBuilder2); // 添加设备 2

ThingOSBLE.manager().connectBleDevice(builderList); // 开始连接

断开连接设备

接口说明

void disconnectBleDevice(List<BleConnectBuilder> builderList);

参数说明

参数	类型	说明
builderList	List	`BleConnectBuilder` 集合，用于构建需要断开设备的设置

BleConnectBuilder 说明

方法名	参数	说明
setDevId()	String	需要断开的设备 ID

示例代码

List<BleConnectBuilder> builderList = new ArrayList<>();

builderList.add(new BleConnectBuilder().setDevId(devId1)); // 设备 1 的 devId
builderList.add(new BleConnectBuilder().setDevId(devId2)); // 设备 2 的 devId

ThingOSBLE.manager().disconnectBleDevice(builderList); // 断开连接

设备管理操作

您可以通过设备的操作类，来监听设备状态。该部分与 Wi-Fi 逻辑类似，可参考设备管理了解更多逻辑信息。以下操作均与 Wi-Fi 设备的指令下发一致：

设备信息查询
初始化设备控制
注册设备监听
取消设备监听
设备功能说明
设备重命名
移除设备

蓝牙设备的解绑与 Wi-Fi 使用方式一致，都是调用 ThingOSDevice.newDeviceInstance("devId").removeDevice() 或者 resetFactory()。但是，有以下区别：
- 蓝牙设备除了进行云端移除之外，若设备此时本地连接状态，则会自动移除设备。若此时设备离线，则只会云端移除，设备会仍处于绑定状态。
- 下次想要继续重新绑定设备，用户需要将设备手动置为配网状态。
- SDK 在扫描时，若发现设备处于绑定状态但是云端已解绑，也会进行自动重置。
回收设备资源

固件升级

固件 OTA 升级前，需要先检查固件信息，然后进行升级。

检查固件信息

接口说明

void requestUpgradeInfo(String devId, IRequestUpgradeInfoCallback callback);

参数说明

参数	类型	说明
devId	String	需要升级的设备 ID
callback	IRequestUpgradeInfoCallback	检查回调

示例代码

private IBlueMeshManager getBleMeshManager() {
        IThingBlueMeshPlugin iThingBlueMeshPlugin = PluginManager.service(IThingBlueMeshPlugin.class);
        if (iThingBlueMeshPlugin == null) return null;
        return iThingBlueMeshPlugin.getMeshInstance();
    }

getBleMeshManager().requestUpgradeInfo(mDevID, new IRequestUpgradeInfoCallback() { @Override public void onSuccess(ArrayList<BLEUpgradeBean> bleUpgradeBeans) { } @Override public void onError(String errorCode, String errorMsg) { } });

BLEUpgradeBean 返回固件升级的信息，提供以下信息：

字段	类型	描述
upgradeStatus	Integer	升级状态 `0`：无新版本 `1`：有新版本 `2`：在升级中
version	String	最新版本
currentVersion	String	当前版本
timeout	Integer	超时时间，单位：秒
upgradeType	Integer	`0`：App 提醒升级 `2`：App 强制升级 `3`：检测升级
type	Integer	固件来源 `0`：Wi-Fi 模组 `1`：蓝牙模组 `2`：GPRS 模组 `3`：Zigbee 模组 `9`：MCU 设备
typeDesc	String	来源描述
lastUpgradeTime	long	上次升级时间，单位：毫秒
url	String	新固件下载地址，`type` 取值为 `1` 或 `9` 时有值
fileSize	long	新固件大小
md5	String	新固件 MD5 值

OTA 升级

将检查到的新固件下载到本地后，进行 OTA 升级。

接口说明

void startBleOta(String uuid, int type, String version, String binPackagePath, OnBleUpgradeListener listener);

参数说明

参数	类型	说明
uuid	String	需要升级的设备 UUID，可通过 `deviceBean.getUuid()` 查询
type	int	`0`：蓝牙固件升级，此时 `BLEUpgradeBean.type` 为 `1` `1`：MCU 升级，此时 `BLEUpgradeBean.type` 为 `9`
version	String	新固件版本号
binPackagePath	String	下载到本地的固件的路径
listener	OnBleUpgradeListener	升级进度回调

ThingOSBLE.manager().startBleOta(uuid, type, version, binPackagePath, new OnBleUpgradeListener() {
    @Override
    public void onUpgrade(int percent) {
        // 升级进度，单位为百分比
    }

    @Override
    public void onSuccess() {
        // 升级成功
    }

    @Override
    public void onFail(String errorCode, String errorMsg) {
        // 升级失败
    }
});

错误码

错误码	说明
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 配网传参校验失败
207206	设备状态不可识别
207207	设备不支持获取 Wi-Fi 列表功能
207222	获取设备 Wi-Fi 列表信息失败
207226	获取设备 Wi-Fi 列表为空
207227	获取设备 Wi-Fi 指令下发超时
207209	配网信息错误
207210	无法找到路由器
207211	路由器密码错误
207212	连接路由器失败
207213	DHCP 失败
207214	设备连云信息激活错误
207215	设备连云失败
207216	设备连云激活接口失败
207218	云端接口请求失败
207219	云端 iot-dns 连接失败
207220	设备配网超时
207221	连接设备蓝牙失败

上一篇蓝牙技术体系

下一篇蓝牙 Mesh（SIG）