更新时间:2022-02-17 05:53:02下载pdf
涂鸦蓝牙有三条技术方案。蓝牙设备与手机一对一相连的 蓝牙单点,涂鸦自研的蓝牙拓扑通信 涂鸦 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" />
使用蓝牙前需要检测权限已被授予
该部分检查逻辑,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);
本节将会介绍已配网的单点设备,如何进行状态检测、连接、解绑等。
本节概要
通过通用方式查询 与 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 配网传参校验失败 |
该内容对您有帮助吗?
是意见反馈该内容对您有帮助吗?
是意见反馈