蓝牙技术体系

涂鸦蓝牙有三条技术方案。蓝牙设备与手机一对一相连的 蓝牙单点，涂鸦自研的蓝牙拓扑通信 涂鸦 Mesh 和蓝牙技术联盟发布的蓝牙拓扑通信 蓝牙 Mesh。除了以上三种之外，还有一些多协议设备也会使用到蓝牙技术，比如同时具备 Wi-Fi 能力和蓝牙能力的 双模、多模设备，也可以使用蓝牙进行配网，当然 Wi-Fi 设备原本的配网仍然可用。

蓝牙技术分类	产品举例
蓝牙单点	体脂秤、手环、温控器、电动牙刷、门锁、防丢器等
蓝牙 Mesh	一路、二路、五路等灯泡、插座、传感器等蓝牙 Mesh 子设备
涂鸦 Mesh	与蓝牙 Mesh 产品类似，协议为涂鸦自研
双模、多模设备	蓝牙 Mesh 网关、IPC 设备以及新版多协议 Wi-Fi 设备等均有可能

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

• 配网

  • 扫描发现设备
  • 设备配网

• 配网后的设备操作

  • 检查设备当前连接状态
  • 连接设备
  • 设备操作
  • 解绑设备

准备工作

手机系统要求

蓝牙使用需要 Android 4.3 以及以上版本，SDK 从 Android 4.4 开始支持。

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" />

使用蓝牙前需要检测权限已被授予

• APP 在使用蓝牙连接或者扫描操作前 需要检查 APP 定位权限是否被允许。
• 检查蓝牙状态是否为开启。

该部分检查逻辑，SDK 未提供 API，开发者可自行检测。每次扫描和连接前都要进行检测，否则 APP 无法正常使用蓝牙。

扫描设备

开始扫描

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

再次提醒：蓝牙设备扫描前需要进行权限检测，只有具备权限才能正常扫描
1、蓝牙是否打开
2、应用是否具有定位权限

接口说明

void startLeScan(LeScanSetting setting, TyBleScanResponse response);

参数说明

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

构建类说明

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

方法名	参数	说明	是否必需
setTimeout()	long	设置超时时间 默认：40000；单位：毫秒	可选
addScanType()	ScanType	SINGLE: 点对点蓝牙设备; MESH: 涂鸦自研协议的Mesh设备; SIG_MESH: 标准蓝牙Mesh设备。	必需
setRepeatFilter()	boolean	重复过滤，默认：true	可选

示例代码

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

TuyaOSBLE.operator().startLeScan(leScanSetting, new TyBleScanResponse() {
    @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 :是否⽀持蓝牙再配网设备
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, ITuyaDataCallback<ConfigProductInfoBean> callback);

参数说明

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

示例代码

TuyaOSActivator.deviceActivator().getActivatorDeviceInfo(
        scanDeviceBean.getProductId(), // productId
        scanDeviceBean.getUuid(), // uuid
        scanDeviceBean.getMac(), // mac
        new ITuyaDataCallback<ConfigProductInfoBean>() {
            @Override
            public void onSuccess(ConfigProductInfoBean result) {
                // 获取设备信息成功
            }

            @Override
            public void onError(String errorCode, String errorMessage) {
                // 获取设备信息失败
            }
        }
);

回调说明

ConfigProductInfoBean 说明

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

停止扫描

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

接口说明

void stopLeScan();

代码示例

TuyaOSBLE.operator().stopLeScan();

单点设备配网

开始单点设备入网

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

接口说明

void startActivator(BleActivatorBean bleActivatorBean, IBleActivatorListener listener);

参数说明

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

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

属性	类型	说明	是否必需
homeId	long	当前家庭 ID	必需
uuid	String	设备uuid，通过扫描可以获取	必需
address	String	设备地址， 通过扫描可以获取	可选
productId	String	产品ID，通过扫描可以获取	可选
deviceType	Integer	设备类型，通过扫描可以获取	必需
isShare	boolean	是否为共享设备，通过扫描可以获取，默认：false	可选
timeout	long	配网总超时，配网超时失败以该参数为准。 单位：毫秒，默认：60000	可选

代码示例

BleActivatorBean bleActivatorBean = new BleActivatorBean();

// mScanDeviceBean 来自于扫描回调的 ScanDeviceBean
bleActivatorBean.homeId = 123456; // homeId
bleActivatorBean.address = mScanDeviceBean.getAddress(); // 设备地址
bleActivatorBean.deviceType = mScanDeviceBean.getDeviceType(); // 设备类型
bleActivatorBean.uuid = mScanDeviceBean.getUuid(); // UUID
bleActivatorBean.productId = mScanDeviceBean.getProductId(); // 产品ID

// 配网的结果监听
IBleActivatorListener listener = new IBleActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功，回调的 DeviceBean 数据说明 与WIFI的设备配网一致参见WiFI设备的配网回调说明。
    }

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

// 开始配网
TuyaOSActivator.activator().newBleActivator().startActivator(bleActivatorBean, listener);

取消单点设备入网

配网过程中终止配网。

接口说明

void stopActivator(String uuid);

参数说明

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

示例代码

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

双模设备配网

双模设备入网

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

接口说明

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

参数说明

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

MultiModeActivatorBean 说明

属性	类型	说明
homeId	long	将设备添加到指定 ID 的家庭中
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	当前家庭 homeId
timeout	long	配网总超时，配网超时失败以该参数为准。单位：毫秒

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

token: 获取 token 的方式与 Wi-Fi 设备配网一致，见 Wi-Fi 部分配网获取 Token获取 Token

代码示例

MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();

// scanDeviceBean 为蓝牙扫描回调的设备信息
// 设置设备地址
multiModeActivatorBean.address = scanDeviceBean.getAddress();
// 设置产品 UUID
multiModeActivatorBean.uuid = scanDeviceBean.getUuid();
// 设备mac
multiModeActivatorBean.mac = scanDeviceBean.getMac();
// 设置设备类型
multiModeActivatorBean.deviceType = scanDeviceBean.getDeviceType();
// 设置 HomeID
multiModeActivatorBean.homeId = "homeId_xxx";
// 设置配网超时时长，单位：ms
multiModeActivatorBean.timeout = 60 * 1000L;
// 从云端获取的 token
multiModeActivatorBean.token = "token_xxx";
// 设备需要连接的 Wi-Fi SSID
multiModeActivatorBean.ssid = "ssid_xxx";
// 设备需要连接的 Wi-Fi 密码
multiModeActivatorBean.pwd = "pwd_xxx";
// 配网结果的监听
IMultiModeActivatorListener listener = new IMultiModeActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {
        // 配网成功
    }
    @Override
    public void onFailure(int code, String msg, Object handle) {
        // 配网失败
    }
};
// 开始配网
TuyaOSActivator.activator().newMultiModeActivator().startBleActivator(
        multiModeActivatorBean, listener);

回调说明

DeviceBean说明
见DeviceBean 数据模型

取消双模设备配网

配网中终止配网，若设备已经进行到云端激活中，虽取消设备配网但可能会配网成功。

接口说明

void stopActivator(String uuid);

参数说明

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

示例代码

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

双模设备蓝牙兜底配网

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

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

接口说明

void startActivator(MultiModeActivatorBean multiModeActivatorBean, IMultiModeActivatorListener listener);

入参说明

MultiModeActivatorBean

参数	类型	说明
homeId	long	将设备添加到指定 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	从云端获取的账号身份认证信息
mac	String	设备 mac 地址

若未说明，一般设备只支持 2.4G 频段WIFI配网，部分设备支持 5G。可以根据 ScanDeviceBean.flag 进行判定。
token: 获取 token 的方式与 Wi-Fi 设备配网一致，见 Wi-Fi 部分配网获取 Token

代码示例

// scanDeviceBean 为 BLE 扫描到的设备信息回调
MultiModeActivatorBean multiModeActivatorBean = new MultiModeActivatorBean();
// 设置 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;
// 设置连云激活的超时，单位：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) {
        // 配网失败
    }
};

// 开始配网
IMultiModeActivator mMultiModeActivator = TuyaOSActivator.activator().newMultiModeActivator();
mMultiModeActivator.startActivator(multiModeActivatorBean, listener);

判断配网成功的设备是否通过蓝牙兜底能力来激活，可以通过回调的 DeviceBean 的 getCommunicationOnline(CommunicationEnum.BLE) 方法指定查询 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();
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 并云端激活
TuyaOSActivator.activator().newMultiModeActivator().startWifiEnable(multiModeActivatorBean, listener);

蓝牙设备操作

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

本节概要

1. 操作设备包含设备状态查询
2. 设备连接
3. 设备发送指令
4. 修改设备
5. 解绑设备

判断设备在线状态

通过通用方式查询 与 Wi-Fi 设备一致（此状态是综合状态，若蓝牙设备添加到网关下面 则蓝牙设备可云端在线）

TuyaOSDevice.getDataInstance().getDeviceBean(devId).getIsOnline();

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

TuyaOSBLE.manager().isBleLocalOnline(devId);

通常情况下蓝牙只需要考虑本地状态即可。只有加入蓝牙网关下的蓝牙设备才需要考虑是否云端在线。

连接设备

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

【注意】连接方法需要在主线程中调用

接口说明

void connectBleDevice(List<BleConnectBuilder> builderList);

参数说明

参数	类型	说明
builderList	List	BleConnectBuilder集合

构建类说明

BleConnectBuilder用于构建需要连接设备的设置。

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

示例代码

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

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder(); // 存放需要连接的设备1信息
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder(); // 存放需要连接的设备2信息

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

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

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

断开连接设备

可主动断开已连接的设备。

【注意】连接方法需要在主线程中调用

接口说明

void disconnectBleDevice(List<BleConnectBuilder> builderList);

参数说明

参数	类型	说明
builderList	List	BleConnectBuilder 集合

构建类说明

BleConnectBuilder用于构建需要断开设备的设置。

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

示例代码

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

BleConnectBuilder bleConnectBuilder1 = new BleConnectBuilder(); // 存放需要断开连接的设备1信息
BleConnectBuilder bleConnectBuilder2 = new BleConnectBuilder(); // 存放需要断开连接的设备2信息

bleConnectBuilder1.setDevId("DevId_1"); // 设置需要断开连接的设备1的 DevId
bleConnectBuilder2.setDevId("DevId_2"); // 设置需要断开连接的设备2的 DevId
// 可以添加更多需要断开连接的设备

TuyaOSBLE.manager().connectBleDevice(builderList); // 断开连接

设备操作

可以通过设备的操作类进行监听设备状态。该部分与 Wi-Fi 逻辑类似，可先参考获取更多逻辑信息 Wi-Fi 设备操作。

• 设备信息获取

  与 Wi-Fi 设备的指令下发一致 设备信息获取

• 初始化设备控制

  与 Wi-Fi 设备的指令下发一致 初始化设备控制

• 注册设备监听

  与 Wi-Fi 设备的指令下发一致 注册设备监听

• 取消设备监听

  与 Wi-Fi 设备的指令下发一致 取消设备监听

• 设备功能点说明

  与 Wi-Fi 设备的指令下发一致 设备功能点说明

• 设备重命名

  与 Wi-Fi 设备的指令下发一致 设备重命名

• 移除设备

  与 Wi-Fi 设备的指令下发一致 移除设备

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

• 回收设备资源

  与 Wi-Fi 设备的指令下发一致 回收设备资源

错误码

错误码	说明
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 配网传参校验失败