本地倒计时功能开发实践

更新时间：2018-11-30 14:34:56

简介

本文提供了一个插座本地倒计时功能的开发案例，开发者可以参考本文，实现任意设备的本地倒计时功能。
“本地倒计时”是指，由App页面向设备端下发“开始倒计时”的任务后，设备端开始根据本地时钟，执行倒计时任务。
要实现本地倒计时的效果，设备端和APP端需要按照本文推荐的方式进行实现。

设备端：按照平台标准数据格式，实现倒计时任务的增删改。
APP端：在公版App中，或平台给自定义App提供的设备界面中，如“灯”“开关”，可以直接使用倒计时功能，如下图位置：

单路倒计时

1. 概述

如果该设备中，只有一个功能需要支持倒计时，可以使用该方案，如单路插座。
单路倒计时：

2. 准备工作

控制台中注册您的产品，详细参考 产品注册，本文以插座为例。在 功能定义 中，需要选择标准功能“倒计时”（CountDown），倒计时属性的数据结构：JSON对象
例子：
CountDown: {
IsRunning: 0(bool，0：没有倒计时，1：正在倒计时，),
TimeLeft: 200（int，秒数，最大值为23h59m59s对应的秒数）,
PowerSwitch: 0(bool，代表倒计时时间到了后，开关要执行的动作，0为关闭，1为打开)
Timestamp: "1535644800000"(string类型的UTC时间戳，调用设置接口时的当前时间戳，用于同步时间)
}
功能名称：本地倒计时
标识符：CountDown
类型：JSON

3. 设计原理

如何实现本地倒计时：

• APP上设定时间，点击开始倒计时，会将上面所述的CountDown通过云端下发到设备端；

• 设备端收到CountDown后，根据TimeLeft和PowerSwitch的内容，开始执行倒计时，并且在倒计时时间到了之后，执行PowerSwitch中的开关动作；

• 倒计时的动作执行后，将下发时的CountDown中的IsRunning设置为0，再将CountDown上报到云端（不用修改CountDown中除IsRunning外的其他字段）；

• 若设备中途断电，在上电后，需要将CountDown中的IsRunning设置为0，然后上报CountDown到云端。

如何取消本地倒计时功能：

• 将之前收到的CountDown中的IsRunning设置为0下行到设备端

• 设备端会回复CountDown（IsRunning=0）至云端

一些说明：

• APP设置了一个200s后关闭电源的动作，set时候传的数据应为：
  CountDown: {
  IsRunning: 1(bool，0：没有倒计时，1：正在倒计时，),
  TimeLeft: 200（int，秒数，最大值为23h59m59s对应的秒数）,
  PowerSwitch: 0(bool，代表倒计时时间到了后，开关要执行的动作，0为关闭，1为打开)
  Timestamp: "1535644800000"(string类型的UTC时间戳，调用设置接口时的当前时间戳，用于同步时间)
  }

• APP收到set成功的返回响应后，跳转到开始倒计时的页面，开始正常倒计时

• 此时若退出APP，50s后再打开APP进入设备控制界面或本地倒计时插件，那么此时显示的剩余时间应为：
  200 - （当前本地时间戳 - set时候传递的本地时间戳）= 200 - 50 = 150s

4. 设备端开发

以下时间案例中，设备每次收到云端下行的指令会立即回复CountDown做出响应，同时创建一个绑定至定时器服务函数app_timer_expired_handle()的定时器，等到本地倒计时时间耗尽时，该定时器服务函数会自动调用，CountDown属性中的IsRunning修改成0上行至云端，同时上报设备PowerSwitch属性，即宣告本地倒计时完成。

/*
 * the handler of property changed
 * alink method: thing.service.property.set
 */
static int thing_prop_changed(const void *thing_id, const char *property, void *ctx)
{
    int ret = -1;
    app_context_t *app_ctx = (app_context_t *)ctx;
    APP_TRACE("property \"%s\" changed", property);

    if (strstr(property, app_ctx->prop_countdown) != 0) {
        /* post property
        * result is response_id; if response_id = -1, it is fail, else it is success.
        * response_id by be compare in post_property_cb.
        */
        int powerSwitch[1] = {0};
        int timeLeft[1] = {0};
        int isRunning[1] = {0};

        /* Get property value of "CountDown" */
        linkkit_get_value(linkkit_method_get_property_value, thing_id, app_ctx->prop_countdown_pwrsw, powerSwitch, NULL);
        APP_TRACE("app get property value, PowerSwitch = %d", powerSwitch[0]);

        linkkit_get_value(linkkit_method_get_property_value, thing_id, app_ctx->prop_countdown_timelf, timeLeft, NULL);
        APP_TRACE("app get property value, TimeLeft = %d", timeLeft[0]);

        linkkit_get_value(linkkit_method_get_property_value, thing_id, app_ctx->prop_countdown_isrun, isRunning, NULL);
        APP_TRACE("app get property value, IsRunning = %d", isRunning[0]);

        /* Start or stop timer according to "IsRunning" */
        if (isRunning[0] == 1) {
            app_timer_start(app_ctx->timerHandle, timeLeft[0]);
            /* temp powerswitch value to app context */
            app_ctx->powerSwitch_Target = powerSwitch[0];
        } else if (isRunning[0] == 0) {
            app_timer_stop(app_ctx->timerHandle);
        }

        /* Post property "CountDown" to response request from cloud*/
        ret = linkkit_post_property(thing_id, property, post_property_cb);
        if (ret != SUCCESS_RETURN) {
            APP_TRACE("app post property \"%s\" failed", property);
            return ret;
        }
        APP_TRACE("app post property \"%s\" succeed", property);

        /* Set property "PowerSwitch" then post */
        ret = linkkit_set_value(linkkit_method_set_property_value, app_ctx->thing, app_ctx->prop_powerswitch,
                                &app_ctx->powerSwitch_Actual, NULL);
        if (ret != SUCCESS_RETURN) {
            APP_TRACE("app set property \"%s\" failed", app_ctx->prop_powerswitch);
            return ret;
        }

        ret = linkkit_post_property(app_ctx->thing, app_ctx->prop_powerswitch, post_property_cb);
        if (ret != SUCCESS_RETURN) {
            APP_TRACE("app post property \"%s\" failed", app_ctx->prop_powerswitch);
            return ret;
        }
        APP_TRACE("app post property \"%s\" succeed", app_ctx->prop_powerswitch);
    } else if (strstr(property, app_ctx->prop_powerswitch) != 0) {
        int powerSwitch[1] = {0};

        /* Get property value of "PowerSwitch" */
        linkkit_get_value(linkkit_method_get_property_value, thing_id, app_ctx->prop_powerswitch, powerSwitch, NULL);
        APP_TRACE("app get property value, PowerSwitch = %d", powerSwitch[0]);

        /* Trigger powerswitch action, just set value here */
        app_ctx->powerSwitch_Actual = powerSwitch[0];

        /* Set property "PowerSwitch" then post */
        ret = linkkit_set_value(linkkit_method_set_property_value, app_ctx->thing, app_ctx->prop_powerswitch,
                                &app_ctx->powerSwitch_Actual, NULL);
        if (ret != SUCCESS_RETURN) {
            APP_TRACE("app set property \"%s\" failed", app_ctx->prop_powerswitch);
            return ret;
        }

        ret = linkkit_post_property(app_ctx->thing, app_ctx->prop_powerswitch, post_property_cb);
        if (ret != SUCCESS_RETURN) {
            APP_TRACE("app post property \"%s\" failed", app_ctx->prop_powerswitch);
            return ret;
        }
        APP_TRACE("app post property \"%s\" succeed", app_ctx->prop_powerswitch);
    }

    return 0;
}

多路倒计时

1.概述

与单路倒计时不同的是，多路倒计时可以同时对多个设备上的布尔值设定本地倒计时任务，如多路插座。
多路倒计时：

2.准备工作

数据结构说明

功能名称：倒计时列表
标识符：CountDownList
类型：JSON
CountDownList: {
Target: "PowerSwitch"(string，当次设置操作指定的布尔值的identifier),
Contents: "PowerSwitch-1-1-123-1535644800000,LightSwitch-0-1-456-1535644800000"(string, 该设备的所有倒计时任务字符串，具体格式说明见下方)
XXX1:0(bool,该产品已有的布尔类型标准属性),
XXX2:0(bool,该产品已有的布尔类型标准属性)
}
CountDownList本身是可选的标准属性
Target和Contents为CountDownList的必选属性
二者都是string类型（最大长度为2048字节）
Target和Contents期望后台数据加上，不用开发者自己添加
XXX1和XXX2为当前产品已有的标准布尔属性，可以由开发者随意添加或删除

注意：如果功能定义里有CountDownList，但CountDownList里除了Target和Contents外没有别的布尔属性，那么属于异常情况，应该报错提示

设备端同学注意：前端设置完以后，XX1 XX2 这边的值默认是0，设备端不需要Care这个。仅关注Contents里内容即可

字段说明

Target

类型：string
属性名：操作对象
是否必选：是
长度：2048
当次操作的布尔值类型的标准属性
为什么要有这个字段？假设第一次设置一个倒计时任务：PowerSwitch-1-1-1000-1535644800000，那么1分钟后，要设置第二个倒计时任务：PowerSwitch-1-1-1000-1535644800000,Enable-0-1-2000-1535644800000，如果没有这个Target字段指定的属性，那么第一次设置的倒计时任务的时间将又从1000s开始计时

Contents

类型：string
属性名：倒计时命令
是否必选：是
长度：2048
因为本次的需求是同时设置多个布尔值属性的倒计时任务，且当前没有数组类型的数据，故采用一个string来存放设备的所有倒计时任务
例子："PowerSwitch-1-1-123-1535644800000,LightSwitch-0-1-456-1535644800000"
不同布尔值的倒计时任务用逗号来分隔
用-来分隔一个属性倒计时任务的不同字段
每一条倒计时任务的格式说明：
以PowerSwitch-0-1-1535644800000为例
第一位：PowerSwitch 设备上某一个布尔值的identifier
第二位：0 倒计时到了之后要执行的布尔值动作，可选值仅有0和1
第三位：1 当前这一条倒计时任务的执行状态，可选值仅有0和1，0代表倒计时时间已到，1代表倒计时时间还未到
第四位：123 代表设置的倒计时时间段，单位为s，最大可以设置为23时59分59秒，最小为1秒，不能设置为0。当设置为0时，插件侧应进行报错提示。
第五位：1535644800000 代表设置该倒计时任务时，App侧的当前时间戳。这个字段是用来重新展示倒计时列表时（例如退出设备面板后过一会儿又再进入面板），展示最新的剩余倒计时时间。

点击倒计时按钮时

1.如果当前产品的功能定义里有CountDownList属性，那么此时走新的倒计时列表逻辑，在当前组件展示倒计时列表相关界面
2.如果当前产品的功能定义里没有CountDownList属性，但是有CountDown属性，那么则走以前的倒计时插件逻辑。

点击某个倒计时任务的撤销

1.App删除Contents字段里对应identifier的任务，同时设置Target为这个identifier，上报云端，下发给设备端。
2.设备端收到新的CountDownList属性，发现Target指定了一个identifier，但是Contents里却没有这个identifier，那么删除正在执行的identifier对应的倒计时任务，不影响其余的倒计时任务。

3.场景举例说明

1.点击倒计时按钮
2.检查tsl，发现CountDownList里还有额外的XXX1，XXX2属性
3.倒计时列表弹层展示XXX1、XXX2的中文名称列表
4.选择其中一个属性，例如PowerSwitch，展示设置时间和动作界面，设定好时间(1000s)和动作(打开)
5.设置Target: "PowerSwitch", 设置Contents: "PowerSwitch-1-1-1000-1535644800000"，下发给云端
6.设备端收到CountDown后，解析Contents和Target内容，设置实际的定时任务
7.此时又设置了第二个属性XXX2，Contents为："PowerSwitch-1-1-1000-1535644800000,XXX2-0-1-2000-1535644800000",Target:"XXX2"
8.1000s到了之后，第一个PowerSwitch倒计时任务结束，设备端删除Contents里PowerSwitch这一条任务，同时设置Target为PowerSwitch，将整个CountDownList属性上报到云端，插件侧查询CountDown属性，发现Contents里没有Target指定的布尔属性，代表PowerSwitch倒计时任务已执行，进而提示PowerSwitch倒计时任务执行完毕
注意：整个插件和设备端上报云端的过程中，CountDownList里的XXX1和XXX2等布尔属性可以设置为任意符合布尔属性的值