1. 蓝牙 BLE

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

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

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

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

1.配网

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

2.配网后的设备操作

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

3.设备升级固件

  • 检测设备版本
  • 升级设备固件 OTA

1.1. 准备工作

手机系统要求

BLE 使用需要 Android 4.3 以及以上版本,TuyaHomesdk 从 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 定位权限是否被允许。
  • 检查蓝牙状态是否为开启。

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

1.2. 扫描设备

1.2.1. 开始扫描

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

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

接口说明

void startLeScan(int timeout, ScanType type, TyBleScanResponse response);

参数说明

参数 类型 说明
timeout int 配网超时时间,单位 ms ,推荐 60s
type ScanType ScanType.SINGLE 表示扫描单点设备
response TyBleScanResponse 扫描结果的回调,不能为空

示例代码

TuyaHomeSdk.getBleOperator().startLeScan(60000, ScanType.SINGLE, new TyBleScanResponse() {
   @Override
   public void onResult(ScanDeviceBean bean) {

   }
});

回调说明

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;bit1:是否后绑定

1.2.2. 查询设备名称

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

接口说明

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

参数说明

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

示例代码

TuyaHomeSdk.getActivatorInstance().getConfigProductInfo(scanDeviceBean.productId, scanDeviceBean.uuid, scanDeviceBean.mac, new ITuyaDataCallback<ConfigProductInfoBean>() {
            @Override
            public void onSuccess(ConfigProductInfoBean result) {

            }

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

            }
        });

回调说明

ConfigProductInfoBean 说明

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

1.2.3. 停止扫描

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

接口说明

void stopLeScan();

代码示例

TuyaHomeSdk.getBleOperator().stopLeScan();

1.3. 单点设备配网

1.3.1. 单点设备入网

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

接口说明

void startBleConfig(long homeId, String devUuid, Map<String, Object> params, ITuyaBleConfigListener configListener);

参数说明

参数 类型 说明
homeId long 当前家庭 homeId
devUuid String 扫描到的设备中 uuid。即 ScanDeviceBean.uuid
params Map 传 null,单点配网不需要该参数
configListener ITuyaBleConfigListener 配网回调,不可为空

代码示例

TuyaHomeSdk.getBleManager().startBleConfig(123456, "abc12345678", null, new ITuyaBleConfigListener() {
   @Override
   public void onSuccess(DeviceBean bean) {
      // 回调的 DeviceBean 数据说明 与WIFI的设备配网一致参见WiFI设备的配网回调说明。
   }

   @Override
   public void onFail(String code, String msg, Object handle) {
      // code msg 说明 见本章节配网错误码
   }
});

1.3.2. 取消单点设备入网

配网过程中终止配网。

接口说明

void stopBleConfig(String devUuid);

参数说明

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

示例代码

TuyaHomeSdk.getBleManager().stopBleConfig("abc12345678");

1.4. 双模设备配网

1.4.1. 双模设备入网

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

接口说明

void startBleConfig(long homeId, String devUuid, Map<String, Object> params, ITuyaBleConfigListener configListener);

参数说明

参数 类型 说明
homeId long 当前家庭 homeId
devUuid String 扫描到的设备中 uuid,即 ScanDeviceBean.uuid
params Map 双模设备需要传网络信息 ssid、pwd、token信息
configListener ITuyaBleConfigListener 配网回调,不可为空

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

代码示例

Map<String, Object> param = new HashMap<>();
param.put("ssid", "Tuya-Wifi-2.4G"); //wifi ssid
param.put("password", "12345678"); //wifi pwd
param.put("token", "xxxxxxxxxxxxx"); // user token
TuyaHomeSdk.getBleManager().startBleConfig(123456, "xyz12345678", param, new ITuyaBleConfigListener() {
    @Override
    public void onSuccess(DeviceBean bean) {
        // 回调的 DeviceBean 数据说明 参见WiFI设备的配网回调。
    }

    @Override
    public void onFail(String code, String msg, Object handle) {
        // code msg 说明 见本章节配网错误码
    }
});

回调说明

DeviceBean说明 见DeviceBean 数据模型

1.4.2. 取消双模设备配网

配网中终止配网。

接口说明

void stopBleConfig(String devUuid);

参数说明

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

示例代码

TuyaHomeSdk.getBleManager().stopBleConfig("xyz12345678");

1.5. 蓝牙设备操作

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

本节概要

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

1.5.1. 判断设备在线状态

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

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

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

TuyaHomeSdk.getBleManager().isBleLocalOnline(devId);

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

1.5.2. 连接设备

若设备处于离线状态 可以调用连接方法 进行设备连接。【注意】连接方法需要在主线程中调用

接口说明


void addScanLinkTaskIds(String idJsonString);

参数说明

参数 类型 说明
idJsonString String devId 集合

示例代码

 List<String> devIdList = new ArrayList<>();
 devIdList.add(devId1); //设备1 devId
 devIdList.add(devId2); //设备2 devId

 String ids = JSONObject.toJSONString(devIdList);
 TuyaHomeSdk.getBleManager().addScanLinkTaskIds(ids);

1.5.3. 断开连接设备

可主动断开已连接的设备。【注意】断开方法需要在主线程中调用

接口说明


void disconnectLinkedIds(String idJsonString);

参数说明

参数 类型 说明
idJsonString String devId 集合

示例代码

 List<String> devIdList = new ArrayList<>();
 devIdList.add(devId1); //设备1 devId
 devIdList.add(devId2); //设备2 devId

 String ids = JSONObject.toJSONString(devIdList);
 TuyaHomeSdk.getBleManager().disconnectLinkedIds(ids);

1.5.4. 设备操作

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

设备信息获取

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

初始化设备控制

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

注册设备监听

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

取消设备监听

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

设备功能点说明

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

设备重命名

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

移除设备

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

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

回收设备资源

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

1.6. 固件升级

升级 OTA 流程

  • 检查固件信息
  • 升级 OTA

1.6.1. 检查固件信息

接口说明

void requestUpgradeInfo(String devId, IRequestUpgradeInfoCallback callback);

参数说明

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

示例代码

TuyaHomeSdk.getMeshInstance().requestUpgradeInfo(mDevID, new IRequestUpgradeInfoCallback() {
    @Override
    public void onSuccess(ArrayList<BLEUpgradeBean> bleUpgradeBeans) {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {
    }
});

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

字段 类型 描述
upgradeStatus int 升级状态,0:无新版本 1:有新版本 2:在升级中
version String 最新版本
currentVersion String 当前版本
timeout int 超时时间,单位:秒
upgradeType int 0:app 提醒升级 2:app 强制升级 3: 检测升级
type int 0:wifi设备 1:蓝牙设备 2:GPRS设备 3:zigbee设备 9:MCU
typeDesc String 模块描述
lastUpgradeTime long 上次升级时间,单位:毫秒
url String 新固件下载地址,type = 1 或者 9 的时候 有值
fileSize long 新固件大小
md5 String 新固件 MD5 值

1.6.2. 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 下载到本地的固件的 path
listener OnBleUpgradeListener 升级进度回调
TuyaHomeSdk.getBleManager().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.7. 错误码

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

results matching ""

    No results matching ""