设备控制

更新时间:2024-06-26 01:54:24下载pdf

在简单的应用场景中,控制端 App 仅仅需要对一个设备进行控制。但随着家庭拥有的物联网设备愈加丰富,控制端 App 需要同时控制多个设备。

另外,某些终端设备还需要提供给多人控制。例如,家具式的智能排插需要支持被所有的家人打开或者关闭。因此就出现一个控制端 App 能够控制多个设备端,或者多个用户能够相互控制多个设备的权限管理问题。群组管理、智能场景等概念应运而生。

此章节介绍关于设备控制的内容。

设备功能

  • DeviceBean 类的 dps 属性定义了设备的状态,称作数据点(DP,Data Point)或功能点。

  • dps 数组里,每个 key 对应一个设备功能的 dpIddpValue 为该设备功能的值。

    一款产品的设备功能定义可以在 涂鸦开发者平台 上查看。如下图:

    设备控制

    更多详情,请参考 产品功能

指令格式

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

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

设备功能示例

假设您在涂鸦开发者平台上,查看到一款灯具产品的设备功能有 101、102、103、104、105。其示例代码可能为:

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

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

// 设置 dpId 为 103 的枚举型设备功能示例,作用:设置档位为 2 档
dps = {"103": "2"};

// 设置 dpId 为 104 的数值型设备功能示例,作用:设置温度为 20°
dps = {"104": 20};

// 设置 dpId 为 105 的透传型(byte 数组)设备功能示例,作用:透传红外数据为 1122
dps = {"105": "1122"};

// 多个功能合并发送
dps = {"101": true, "102": "ff5500"};

mDevice.publishDps(dps, new IResultCallback() {
        @Override
        public void onError(String code, String error) {
        // 错误码 11001 有下面几种原因:
        //1:数据类型发送格式错误,例如,String 类型格式发成 Boolean 类型数据。
        //2:不能下发只读类型 DP 数据,参考 SchemaBean getMode,"ro" 是只读类型。
        //3:Raw 格式数据发送的不是 16 进制字符串。
        }
        @Override
        public void onSuccess() {
        }
    });

发送控制命令时,请注意数据类型。例如:

  • 设备功能的数据类型是数值型(value)时,则发送的应该是 {"104": 25},而不是 {"104": "25"}
  • 透传类型传输的 Byte 数组是 16 进制字符串格式,并且必须是偶数位,则发送的应该是 {"105": "0110"},而不是 {"105": "110"}

控制设备

首先,您需要 初始化设备控制。然后,设备控制接口向设备发送控制指令,改变设备状态或功能。

设备控制支持以下三种控制方式:

  • 局域网控制:通过局域网通道实现控制。
  • 云端控制:通过 MQTT 通道和 HTTPS 通道实现控制,您可以通过 isMqttConnected 查询 MQTT 通道的在线状态。
  • 自动方式:在局域网通道、MQTT 通道、HTTPS 通道之间自动选择一个实现控制。

如果设备可以连接到局域网,建议优先通过局域网控制。其次优先选择云端控制方式。

接口说明

  • 局域网控制

    IThingDevice.publishDps(dps, ThingDevicePublishModeEnum.ThingDevicePublishModeLocal, callback);
    
  • 云端控制

    IThingDevice.publishDps(dps, ThingDevicePublishModeEnum.ThingDevicePublishModeInternet, callback);
    
  • 自动控制

    IThingDevice.publishDps(dps, ThingDevicePublishModeEnum.ThingDevicePublishModeAuto, callback);
    

    或者

    IThingDevice.publishDps(dps, callback);
    

    推荐使用 IThingDevice.publishDps(dps, callback) 调用方式。

  • 指定通道控制

    IThingDevice.publishDps(dps, orders, callback);
    

参数说明

参数 说明
dps 设备功能,全称为 data points,通过 JSON 字符串的格式表示,详情请参考 设备功能 章节
callback 返回控制指令是否成功的回调
ThingDevicePublishModeEnum 设备控制方式
orders 通道顺序,可以参考 CommunicationEnum 枚举类。例如,[3 , 1] 指定的是 优先蓝牙控制,蓝牙不在线则选择云端控制

Java 示例

假设,开启一个灯具采用 101 设备功能,则开灯的代码如下:

mDevice.publishDps("{\"101\": true}", new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Toast.makeText(mContext, "开灯失败", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onSuccess() {
        Toast.makeText(mContext, "开灯成功", Toast.LENGTH_SHORT).show();
    }
});
  • 指令下发成功并不是指设备真正操作成功,只是意味着成功发送指令。操作成功会有 DP 数据信息通过 IDevListener onDpUpdate 接口返回。
  • 指令字符串通过 Map<String,Object> 数据格式转成 JSON 字符串。其中,StringObjectdpIddpValue 的键值对。
  • 指令字符串可以一次发送多个 DP 数据。

低功耗设备离线下发配置类 DP

将需要下发给设备的 dps 缓存在云端,待设备唤醒后,设备主动拉取或接收云端推送。

仅适用于低功耗类设备,无需设备在线也可调用。

接口说明

void sendCacheDps(String devId, String dps, long validity, int dpCacheType, IThingDataCallback<Boolean> listener);

参数说明

参数 说明
devId 设备 ID
dps 数据点
validity 缓存有效期(单位:秒,范围:1 ~ 172800)
dpCacheType DP 缓存类型
  • 0:设备主动拉取
  • 1:设备接收云端推送
onSuccess 下发成功回调
onError 下发失败回调

示例代码

Java:

    // validity = 10:在云端缓存 10 秒
    // dpCacheType = 0:设备主动拉取
    // 调用后,该 dps 在云端缓存 10 秒,设备在 10 秒内唤醒,设备主动调用接口拉取缓存的 dps

ThingHomeSdk.getRequestInstance().sendCacheDps("devId", "{\"102\":\"1\",\"125\":\"1\"}", 10, 0, new IThingDataCallback<Boolean>() {
                    @Override
                    public void onSuccess(Boolean result) {
                        Log.i("sendCacheDps", "onSuccess: " + result);
                    }        

                    @Override
                    public void onError(String errorCode, String errorMessage) {
                        Log.i("sendCacheDps", "onError: " + errorMessage);
                    }
                });
            }

查询 MQTT 是否在线

控制设备有多条通道,包括 局域网通道MQTT 通道HTTPS 通道。其中,使用最频繁的是 MQTT 通道。如何判断 MQTT 通道是否正常,需要调用下述接口。

接口说明

boolean isMqttConnected = ThingHomeSdk.getServerInstance().isServerConnect();