时控策略

Topic

与操作指令的Topic相同

上行： indicate/dev/{productKey}/{sn}
下行： indicate/server/{productKey}/{sn}
QoS：1

全量覆盖

全量覆盖时，设备端需要停止执行并清空原有的全部策略，然后开始执行报文中下发的策略。

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "SET",
        "tasks": [
            {
                // 任务ID，由平台统一生成，避免设备端生成后还需要通知平台的问题
                "taskId": "123",
                // 任务状态，1-启用，0-禁用
                "enable": 1,
                // 任务优先级，默认为1，
                // 如果存在更高优先级的任务为启用状态，则所有优先级较低的都禁用。
                // 例如：存在10个任务优先级为1，5个任务优先级为2，1个任务优先级为3，则在优先级为3的任务生效期间，另外15个任务全部不执行。
                // 任务生效的意思是，当前时间在startTime和endTime之间，并且enable=1
                "priority": 1,
                // 生效时间，为空表示立刻生效
                "startTime": 1710957600,
                // 过期时间，为空表示永不过期，过期后网关需要将enable改为0
                "endTime": 1729447200,
                "cycle": {
                    // simple-简单模式，cron-cron表达式，trigger-触发模式
                    "mode": "simple",
                    // 是否随夏令时偏移
                    "dstEnable": 1,
                    // sunrise-日升，sunset-日落，10:00:00-时间点
                    "time": "10:00:00",
                    // once-执行一次，day-按天循环，week-按星期循环，month-按月循环
                    "period": "week",
                    // cycle=week时需要设置
                    "weekday": [1, 3, 4, 6, 7],
                    // cycle=month时需要设置
                    "monthday": [1, 15, 25]
                },
                // 操作指令数组，依次执行各条命令
                "actions": [{
                    "method": "operate",
                    "payload": {
                        "method": "FORCESWITCH",
                        "ForceSwitch": 0, 
                        "groupid": "3_1"
                    }
                }, {
                    "method": "operate_raw",
                    "payload": {
                        "addr": "1_1",
                        "portid": "1",
                        "meteraddr": "1",
                        "functionid": "Switch", 
                        "value": 1
                    }
                }]
            },
            {
                "taskId": "124",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": {
                    "mode": "cron",
                    "dstEnable": 1,
                    // cron表达式
                    "cron": "0 0/15 * * * ?"
                },
                "actions": [{
                    "method": "operate_raw",
                    "payload": {
                        "addr": "1_1",
                        "portid": "1",
                        "meteraddr": "1",
                        "functionid": "Switch", 
                        "value": 1
                    }
                }]
            },
            {
                "taskId": "125",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": {
                    // 触发模式
                    "mode": "trigger",
                    "dstEnable": 1,
                    // 触发器，详见下面说明
                    "trigger": { ... }
                    "period": "week",
                    "weekday": [1, 3, 4, 6, 7],
                    "monthday": [1, 15, 25]
                },
                "actions": [{ ... }]
            }
        ]
    }
}

一级属性	二级属性	三级属性	四级属性	说明	备注
payload				对象，报文内容
	cmd			SET - 全量设置策略 ADD - 新增策略 DELETE - 删除策略 UPDATE - 修改策略 ENABLE_ALL - 全部启用/禁用 ENABLE - 启用/禁用指定策略 CLEAR - 清空策略 READ_ALL - 读取全部策略 READ - 读取指定策略
	tasks			数组，策略内容
		taskId		字符串，任务ID，由平台生成和下发，以保证平台和设备的数据一致性，避免设备设备生成taskId后还要告知平台的问题。
		enable		数值，1-启用，0-禁用
		priority		任务优先级，当高优先级任务生效时，所有较低优先级的任务都失效
		startTime		数值，策略生效时间戳，为空表示立刻生效
		endTime		数值，策略过期时间戳，为空表示永不过期
		cycle		对象，定时任务周期设置
			mode	字符串，设置模式 ”simple” - 简单模式 “cron” - cron模式
			dstEnable	数值，执行时间点是否随夏令时偏移 1 - 是 0 - 否
			time	字符串，执行时间 ”sunrise” - 日升 ”sunset” - 日落 ”10:00:00” - 时间点	simple模式
			trigger	对象，触发条件	trigger模式
			period	字符串，循环模式 once - 执行一次 day - 按天循环 week - 按周循环 month - 按月循环	simple/trigger模式
			weekday	数组，周几执行，1表示周一，7表示周日，period=week时必填	simple/trigger模式 + week循环
			monthday	数组，每月几号执行，1表示当月第1天，period=month时必填	simple/trigger模式 + month循环
			cron	字符串，cron表达式	cron模式
		actions		数组，需要执行的动作，内容参照操作指令operate/operate_raw/transport

触发条件trigger

通过多级and / or嵌套来设置触发条件。（此处借鉴了MongoDB的查询脚本语法）

and / or：数组，数组内的各条件取和/取或
addr / groupid：用来定位子设备的ID
prop：属性名，其中$是固定占位符，表示当前时间
op：操作符，GT-大于，GTE-大于等于，LT-小于，LTE-小于等于，NE-不等于，EQ-等于，EX-存在，NEX-不存在
value：值

"trigger": {
    "or": [
       {
          "and": [
             { "addr": "1_1", "op": "GT", "prop": "Ua", "value": 220 },
             { "groupid": 1, "op": "LT", "prop": "Ua", "value": 250 }
          ]
       },
       {
          "and": [
             {"op": "GT", "prop": "${time}", "value": "10:00:00"},
             {"op": "LT", "prop": "${time}", "value": "18:00:00"}
          ]
       }
    ]
}

新增策略

允许同时新增多条策略
新增前先判断各taskId是否已经存在，如果已存在某个taskId，应当拒绝执行，并报错errcode:"5010"

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "ADD",
        "tasks": [
            {
                "taskId": "124",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": { ... }
                "actions": [ ... ]
            },
            {
                "taskId": "125",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": { ... }
                "actions": [ ... ]
            }
        ]
    }
}

删除策略

允许同时删除多条策略
删除前需要先判断各taskId是否存在，如果不存在，应当拒绝执行，并报错errcode:"5009"

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "DELETE",
        "tasks": [
            {
                "taskId": "125"
            },
            {
                "taskId": "126"
            }
        ]
    }
}

修改策略

允许同时修改多条策略
修改前需要先判断各taskId是否存在，如果不存在，应当拒绝执行，并报错errcode:"5009"

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "UPDATE",
        "tasks": [
            {
                "taskId": "124",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": { ... }
                "actions": [ ... ]
            },
            {
                "taskId": "125",
                "enable": 1,
                "priority": 1,
                "startTime": 1710957600,
                "endTime": 1729447200,
                "cycle": { ... }
                "actions": [ ... ]
            }
        ]
    }
}

启用/禁用策略

全部启用/禁用

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "ENABLE_ALL",
        // 1-启用，0-禁用
        "enable": 1
    }
}

对多条策略进行启用/禁用
设备需要判断多条策略是否都存在，只要有一条不存在，就应当拒绝执行，并返回errcode:"5009"

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "ENABLE",
        "tasks": [
            {
                "taskId": "124",
                "enable": 0
            },
            {
                "taskId": "125",
                "enable": 1
            }
        ]
    }
}

清空策略

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "CLEAR"
    }
}

读取策略

READ_ALL - 读取全部策略

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "READ_ALL"
    }
}

READ - 有选择地读取多条策略
如果其中某个taskId不存在，报错errcode:"5009"

{
    "msgid": 628131887239491584,
    "method": "schedule",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "READ",
        "tasks": [
            {
                "taskId": "124"
            },
            {
                "taskId": "125"
            }
        ]
    }
}

上报执行结果

设备端在执行任务后，需要通过event将执行结果上报给平台。

如果是同步执行的命令，子设备返回成功/失败的结果，或者超时未回复，则网关将成功/失败结果上报；
如果是异步执行的命令，无法实时获取结果，只需要上报成功，表示报文已经发送即可，因为这类异步执行的命令，实际是否执行成功原本就会有一套事件event上报机制，无需在此反馈结果。

{
    "msgid": 567,
    "method": "event",
    "sn": "123456",
    "timestamp": 1638869890,
    "payload": {
        "events": [
            {
                // 事件编码，固定为schedule，表示定时任务执行结果
                "code": "schedule",
                // 网关SN / 仪表SN / 仪表addr
                "addr": "a123",
                // 事件发生位置，METER-仪表 / GATEWAY-网关，
                // 无endpoint属性时，平台默认为METER
                "endpoint": "METER",
                // 执行结果
                "payload": {
                    // 1-成功，0-失败
                    "res": 0,
                    // 错误编码参考在线文档
                    // http://101.37.151.118:20003/docs/appendix/errcode.html
                    "errcode": "1001",
                    // 设备端执行的任务详情快照，避免平台端策略修改导致无法追溯。
                    "task": {
                        "taskId": "124",
                        "enable": 1,
                        "priority": 1,
                        "startTime": 1710957600,
                        "endTime": 1729447200,
                        "cycle": { ... }
                        "actions": [ ... ]
                    }
                }
            }
        ]
    }
}

错误编码

以下仅列出文档中用到的错误码，更多错误码参考在线文档：中台协议错误码清单

5009 - 任务不存在

{
    "msgid": 123,
    "method": "schedule",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "5009",
    "timestamp": 1638869890
}

5010 - 任务已存在

{
    "msgid": 123,
    "method": "schedule",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "5010",
    "timestamp": 1638869890
}

Last modified: 18 四月 2025