低功耗设备 DP 缓存下发

更新时间:2024-06-25 03:20:38下载pdf

对低功耗设备而言,其常规功能主要是上报设备状态和一些重要信息。但是在一些场景中,用户需要远程设置设备参数或者控制设备。此时,需要云端下发相应功能点(data point,DP)对设备进行控制,但 DP 命令下发时,低功耗设备可能因为 处在休眠状态而接收不到指令
为了解决该问题,涂鸦针对低功耗设备提供了可先将 DP 缓存至云端,等待设备从休眠中醒来后 主动去云端获取指令 的方案。该方案降低了设置低功耗产品参数的失败率,同时也简化了用户操作。

该方案需要等待设备醒来后获取指令,适用于对设置参数和控制的实时性要求并不高的场景。

功能描述

获取缓存 DP 的大致流程如下:

  1. App 将 DP 指令发送给云端。

  2. 云端缓存 DP 指令。

  3. 设备从休眠中醒来后,从云端查询并获取指令。

  4. 设备根据 DP 指令进行动作,并上报相应 DP 状态。

  5. 云端在设备取走缓存指令后,自动删除缓存指令。也就是说,如果没有新的缓存指令,设备下次再来查询时返回的是空。

流程图

App云端设备低功耗 DP 缓存功能开启用户在面板上进行设置-操作调用缓存指令接口,将 DP发送给云端缓存成功定时唤醒/外部唤醒查询缓存指令返回数据删除缓存根据指令进行操作上报当前执行后的设备状态通知指令已同步更新状态opt[有缓存指令]App云端设备

开发指导

关联头文件

  • smart_frame.h

使用方法

如果想要启用该功能,请先前往 涂鸦开发者平台 创建产品,进入产品开发界面。在 功能定义 > 高级功能 处,为产品开启 低功耗 DP 缓存下发 高级能力。

  • 开启低功耗 DP 缓存下发功能后,面板下发的控制指令只会走缓存通道,即使设备在线也是如此。
  • 如果采用您的自定义面板,需要面板支持发送 DP 到云端缓存的功能。

如果您在高级能力中没有找到 低功耗 DP 缓存下发 能力,是因为该产品方案并未绑定这些高级能力。如果您有需求,请联系您的涂鸦客户经理,或者 提交工单 申请绑定。

低功耗设备 DP 缓存下发

在设备唤醒且连云成功后,您可以调用 查询低功耗缓存 DP 接口去云端查询缓存数据。

API 说明

查询低功耗缓存 DP

  • 返回值返回 OPRT_OK 代表与云端通讯正常,但是不代表获取到缓存 DP。
  • 当出参 obj_dps 或者 raw_dps 有值时,才代表获取到缓存 DP。

调用该指令可从云端获取缓存 DP。

/**
* @brief Definition of received structured dp
*/
typedef struct {
    /** see DP_CMD_TYPE_E */
    DP_CMD_TYPE_E cmd_tp;
    /** see DP_TRANS_TYPE_T */
    DP_TRANS_TYPE_T dtt_tp;
    /** if(NULL == cid) then the cid represents gwid */
    CHAR_T *cid;
    /** mb id */
    CHAR_T *mb_id;
    /** count of dp */
    UINT_T dps_cnt;
    /** the dp data */
    TY_OBJ_DP_S dps[0];
} TY_RECV_OBJ_DP_S;

/**
* @brief Definition of structured dp
*/
typedef struct {
    /** dp id */
    BYTE_T dpid;
    /** data len */
    UINT_T len;
    /** dp value, see TY_OBJ_DP_VALUE_U */
    BYTE_T* data;
} TY_RAW_DP_S;

/**
* @brief Definition of received raw dp
*/
typedef struct {
    /** see DP_CMD_TYPE_E */
    DP_CMD_TYPE_E cmd_tp;
    /** see DP_TRANS_TYPE_T */
    DP_TRANS_TYPE_T dtt_tp;
    /** if(NULL == cid) then the cid represents gwid */
    CHAR_T *cid;
    /** mb id */
    CHAR_T *mb_id;

    /** count of dp */
    UINT_T dps_cnt;
    /** the dp data */
    TY_RAW_DP_S dps[0];
} TY_RECV_MULTI_RAW_DP_S;

/**
* @brief Query dp for low power
*
* @param[in] dps:想要查询的 dpid
* @param[in] cnt:想要查询的 dpid 个数
* @param[out] obj_dps:缓存的 OBJ DP 数据信息
* @param[out] raw_dps:缓存的 RAW DP 数据信息
*
* @note This API is used for querying DP for low power
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
OPERATE_RET sf_dp_low_power_query(IN CONST UCHAR_T *dps, IN CONST UINT_T cnt,
                                  OUT TY_RECV_OBJ_DP_S **obj_dps, OUT TY_RECV_MULTI_RAW_DP_S **raw_dps);

参考示例

示例代码可参考框架内自带的 TuyaOS 示例集合 中的 service_query_lowpower_dp/example_query_lowpower_dp.c

常见问题

一个设备可否缓存多个 DP?

可以。

重复设置同一个 DP,会缓存所有设置吗?

不会,只会缓存同一设备、同一 DP 最后设置的一条指令。

如果有多个 RAW DP 缓存,能否一次性拉取?

TuyaOS 3.6.0 及以上支持。如果框架版本低于 3.6.0,对于透传类型(RAW)DP 来说,每调用一次接口仅支持拉取一个缓存。对象类型(OBJ)DP 一直支持一次性拉取多个 DP 缓存。