Page 1 of 1

【Android】Tuya Beacon 设备 APP SDK 接入指南

Posted: 2024年 Nov 25日 16:20

by root

1. 介绍

BLE（Bluetooth Low Energy）Beacon 是一种基于蓝牙低功耗（BLE）技术的无线通信设备，主要用于短距离广播通信。它通过发送小数据包（广播包）来与周围设备进行交互。通过蓝牙网关，可以实现蓝牙设备的远程控制。

优势：

BLE Beacon 使用蓝牙低功耗技术，能够显著降低功耗。
低成本，相较于 BLE 的设备，芯片成本更低。
通过广播（Advertising）模式传输数据，无需建立连接。
不受手机等终端设备连接数量限制
更加大的群控功能

Tuya 在 Beacon 协议 IoT 设备上有丰富的功能，本文将详细介绍作为 SDK 开发者如何接入 Tuya APP SDK 开发 Beacon 设备。

2. 准备

所需如下：

支持 BLE 的手机/平板等 Android 终端（安卓 4.3 以及以上版本，智能生活 App SDK 从安卓 4.4 开始支持）
Tuya Beacon 设备/开发板
Tuya 蓝牙网关（如需网关控制）

Android 权限：

BLE 扫描权限
BLE 广播权限
定位权限

具体权限相关介绍，可以查看另一篇文章详细说明：https://www.tuyaos.com/viewtopic.php?t=3953

3. 扫描

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

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

蓝牙是否打开。

应用是否具有定位权限。

3.1 发现设备

Code: Select all

void startLeScan(LeScanSetting setting, BleScanResponse response);

参数说明

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

构造类说明

参数说明	类型	参数说明	是否必需
setTimeout()	long	设置超时时间（默认:40000 单位:毫秒)	可选
addScanType()	ScanType	THING_BEACON	必需
setRepeatFilter()	boolean	重复过滤，默认 true	可选

示例代码

Code: Select all

LeScanSetting scanSetting = new LeScanSetting.Builder()
        .setTimeout(60000) // 扫描的超时时间：ms
        .addScanType(ScanType.THING_BEACON) // 若需要扫描Beacon设备，则只需要添加 ScanType.SINGLE
        .build();

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

回调说明
ScanDeviceBean 说明

属性	类型	说明
id	String	扫描 ID 通常由 UUID 组成，可以唯一区别设备
data	byte[]	原始数据
productId	String	产品 ID
uuid	String	设备 UUID，设备唯一码，实际为 mac
mac	String	设备 MAC 地址，不可作为唯一码
isbind	boolean	设备是否被绑定，能回调的均为未配网的设备
deviceType	int	设备类型，用于区分不同协议的设备，您无需关注该字段

3.2 停止发现

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

接口说明

Code: Select all

void stopLeScan();

代码示例

Code: Select all

ThingHomeSdk.getBleOperator().stopLeScan();

3.3 查询设备信息

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

接口说明

Code: Select all

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

参数说明

参数	类型	说明
productId	String	ScanDeviceBean.getProductId
uuid	String	ScanDeviceBean.getUuid
mac	String	ScanDeviceBean.getMac

示例代码

Code: Select all

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

    }

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

    }
});

3. 设备配网

3.1 设备激活

接口说明

扫描到的设备的 configType 属性取值为 CONFIG_TYPE_BEACON 表示 Beacon 蓝牙设备

Code: Select all

// 统一接口
void startActivator(@NonNull BleActivatorBean bleActivatorBean, IBleActivatorListener listener);

// 或者使用单独的接口
void startBeaconActivator(@NonNull BatchBeaconActivatorBean bean, ActivateBLEDeviceListener listener);

示例代码

Code: Select all

BleActivatorBean bleActivatorBean = new BleActivatorBean();

bleActivatorBean.homeId = 123123; // homeId
bleActivatorBean.address = scanDeviceBean.getAddress();
bleActivatorBean.deviceType = scanDeviceBean.getDeviceType();
bleActivatorBean.productId = scanDeviceBean.getProductId();

IBleActivator mBleActivator = ThingHomeSdk.getActivator().newBleActivator();
mBleActivator.startActivator(bleActivatorBean, new IBleActivatorListener() {
    @Override
    public void onSuccess(DeviceBean deviceBean) {

}

@Override
public void onFailure(int code, String msg, Object handle) {

}
});

3.2 停止激活

配网过程中终止配网

接口说明

Code: Select all

void stopActivator(String uuid);

参数说明

参数	类型	说明
uuid	String	扫描到的设备的 UUID，即 ScanDeviceBean.uuid，实际是 mac

示例代码

Code: Select all

ThingHomeSdk.getBleManager().stopBleConfig("uuid");

4. 控制设备

4.1 发送控制指令

示例代码

Code: Select all

void publishDps(String dps, IResultCallback callback);

接口说明
DeviceBean 类的 dps 属性定义了设备的状态，称作数据点（DP，Data Point）或功能点。
dps 数组里，每个 key 对应一个设备功能的 dpId，dpValue 为该设备功能的值。
一款产品的设备功能定义可以在涂鸦开发者平台上查看。如下图：

发送控制指令按照以下格式：

Code: Select all

{
    "(dpId)":"(dpValue)"
}

示例

Code: Select all

// 设置 dpId 为 101 的布尔型设备功能示例，作用：开关打开
dps = {"101": true};

// 设置 dpId 为 102 的字符串型设备功能示例，作用：设置 RGB 颜色为 ff5500
dps = {"102": "ff5500"};

错误码 11001 有下面几种原因：
1：数据类型发送格式错误，例如，String 类型格式发成 Boolean 类型数据。
2：不能下发只读类型 DP 数据，参考 SchemaBean getMode，"ro" 是只读类型。
3：Raw 格式数据发送的不是 16 进制字符串。

4.2 创建群组

设备群组由同一种类型设备组成，是一系列设备的集合。涂鸦提供群组管理能力，您可以创建群组、修改群组名称、管理群组设备、通过群组管理和控制多个设备、解散群组。

【查询可创建群组的设备】

接口说明

Code: Select all

ThingHomeSdk.newHomeInstance(homeId).queryDeviceListToAddGroup(groupId, productId,
        new IThingResultCallback<List<GroupDeviceBean>>() {
               @Override
               public void onSuccess(List<GroupDeviceBean> arrayList) {
               }

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

参数说明

参数	说明
homeId	家庭 ID
groupId	群组 ID:如果这些设备还未创建群组，请设置为 -1,如果这些设备要加入已有的群组，请设置为实际的群组 ID
productId	入口设备的产品 ID（即 Product ID）

【创建一个群组】
接口说明

Code: Select all

ThingHomeSdk.newHomeInstance(mHomeId).createGroup(productId, name, selectedDeviceIds,
        new IThingResultCallback<Long>() {
            @Override
            public void onSuccess(Long groupId) {
                    //返回 groupId
            }

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

参数说明

参数	说明
homeId	家庭 ID
productId	选择创建群组的设备的 PID（即 Product ID）
name	新群组的名称
selectedDeviceIds	选择的设备的 deviceId 列表

【更新保存群组】
在群组中添加或者移除设备后，您需要将交互的结果，同步更新保存到云端。

接口说明

Code: Select all

ThingHomeSdk.newGroupInstance(groupId).updateDeviceList(deviceIds,
        new IResultCallback() {

        @Override
        public void onError(String s, String s1) {

        }

        @Override
        public void onSuccess() {

        }
    });

参数说明

参数	说明
groupId	群组 ID
deviceIds	新增或者移除指定的设备的 ID 列表数组

4.3 群组控制

【初始化群组实例】

接口说明

Code: Select all

IThingGroup mIThingGroup= ThingHomeSdk.newGroupInstance(groupId);

参数说明

参数	说明
groupId	群组 ID

【发送群组控制指令】
接口说明

Code: Select all

mThingGroup.publishDps(String command, IResultCallback listener);

参数说明

参数	说明
command	控制命令

示例代码

Code: Select all

//群组开灯代码片段
LampBean bean = new LampBean();
bean.setOpen(true);
HashMap<String, Object> hashMap = new HashMap<>();
hashMap.put(STHEME_LAMP_DPID_1, bean.isOpen());
mThingGroup.publishDps(JSONObject.toJSONString(hashMap),callback);

控制回调接口

Code: Select all

//注册群组回调事件
mIThingGroup.registerGroupListener(new IGroupListener() {

        @Override
        public void onDpUpdate(long l, String s) {

        }

        @Override
        public void onGroupInfoUpdate(long l) {

        }

        @Override
        public void onGroupRemoved(long l) {

        }
    });

//注销群组回调事件
mIThingGroup.unRegisterGroupListener();

挂在网关下时候，向群组发送控制指令后，如果返回了结果，是指发送给云端成功，并不是指实际控制设备成功。

5. 总结

Tuya APP SDK 对于 Beacon 设备支持较为完善，后续会更新 SDK 开发者文档。如果有任何开发使用上的问题可以下方留言或者联系我们