定时指令

定时指令让 AIoT 设备的控制指令按预设时间自动触发——例如「30 分钟后关闭净化器」「每天早上 7 点自动开机」。

定时指令建立在 自定义指令集 的控制项指令之上,不是独立指令类型;它通过在指令集页面增开「支持定时」开关与相关配置卡片完成。

1. 能力全景

一条定时指令由三张卡片组成,三者缺一不可:

卡片	回答什么	关键字段
① 定时能力	支持哪些定时动作?	创建定时(add) / 取消定时(delete) / 查询定时(query)
② 定时类型	支持哪些定时模式?	单次定时 / 循环定时(粒度:每天 / 每周 / 工作日 / 周末)
③ 定时执行指令	到点执行哪些控制项?	控制项白名单(勾选可被定时的指令)

三张卡片描述的是同一条控制项在「时间」维度上的扩展面。例如「关机」这条控制项,可以支持「30 分钟后关」(单次)、「每天 22:00 关」(循环)、「查询关机计划」(查询)、「取消定时」(取消)。

2. 端上下发协议

定时指令由平台统一按协议下发给设备,协议 action 命名规范:

action = <控制项编码>_<定时能力>

举例(空气净化器电源控制项 power):

用户 query	action	数据说明
「30 分钟后关机」	power_add	payload 含 targetValue=off、time=相对 30min、type=once
「每天早上 8 点开机」	power_add	payload 含 targetValue=on、time=08:00、type=daily
「取消关机定时」	power_delete	payload 含 taskId 或 targetValue=off
「查一下有什么定时」	power_query	无 payload,设备端返回定时清单

下发示例(JSON):

{
  "action": "power_add",
  "params": {
    "type": "daily",       // once / daily / weekly / workday / weekend
    "time": "08:00",       // 单次为相对/绝对时间;循环为 HH:mm
    "targetValue": "on",   // 到点后要执行的控制项目标值
    "weekdays": [1,2,3,4,5]// 仅循环-每周时需要
  }
}

⚠️ 协议对齐要求:设备端开发必须实现 <controlCode>_add / _delete / _query 三个动作;若未实现,定时指令会触发但设备无响应,平台侧无法感知失败。

3. 配置步骤

在 自定义指令集 的指令详情页,勾选「支持定时」后展开配置面板:

3.1 卡片一:定时能力

至少勾选 1 项,推荐三项全开:

• 创建定时(add):必开,否则用户无法「设置定时」;
• 取消定时(delete):推荐开启,支持用户口述取消;
• 查询定时(query):推荐开启,支持用户口述「有哪些定时」。

3.2 卡片二:定时类型

• 单次定时:用户说「30 分钟后」「今晚 10 点」「明天早上 8 点」等一次性时间;
• 循环定时:选择支持的粒度组合:
  • 每天(daily)
  • 每周(weekly,需勾选星期几)
  • 工作日(workday,周一至周五)
  • 周末(weekend,周六周日)

建议:根据设备真实使用场景勾选。以床头灯为例,开启「每天 / 工作日 / 周末」比全开更贴近用户心智。

3.3 卡片三:定时执行指令

从当前指令集下已有的控制项指令中勾选:

• ✅ 可勾选的:亮度、音量、模式、开关、温度等结果状态可预期的控制项;
• ⚠️ 不建议勾选的:
  • 需要用户实时决策的控制项(如「切换到 XX 频道」);
  • 非控制项指令(平台目前不支持非控制项进入定时链路)。

4. 常见示例

示例:空气净化器电源定时

• 控制项:电源(power,SWITCH)
• 勾选定时能力:add / delete / query
• 勾选定时类型:单次 + 每天 + 工作日
• 勾选定时执行指令:电源(自身)

用户 query → 平台行为:

用户 query	匹配	端上收到的 action
「30 分钟后关机」	power + add + once	power_add,type=once,targetValue=off
「每天早上 7 点开机」	power + add + daily	power_add,type=daily,time=07:00,targetValue=on
「工作日晚上 10 点关机」	power + add + workday	power_add,type=workday,time=22:00,targetValue=off
「取消早上 7 点的开机」	power + delete	power_delete,time=07:00,targetValue=on
「有哪些定时」	power + query	power_query

5. 注意事项

1. 协议一致性:设备端未实现 _add / _delete / _query 时,定时指令将「静默失败」。上线前请与设备开发拉通协议,并使用 批量测试 与 端到端测试 双重验证。
2. 循环粒度:「工作日」「周末」两个粒度是平台内置约定,无需在设备端额外维护日历表;设备只需按平台下发的 weekdays 数组执行即可。
3. 不支持嵌套定时:平台不允许「定时创建一个定时」这类嵌套 query,识别层会直接拒绝。
4. 静默场景:若定时到点需要无声执行(如深夜关机不播报),请参见 静默指令 中的双开关联动方案。

6. 相关链接

• 上级导航:自定义指令集
• 前置概念:控制项指令(维度 ② / ③)
• 联动主题:静默指令 · 指令的测试和调优
• 端上技能:AIoT 指令控制