主题
定时指令
定时指令让 AIoT 设备的控制指令按预设时间自动触发——例如「30 分钟后关闭净化器」「每天早上 7 点自动开机」。
定时指令建立在 指令配置 的控制项指令之上,不是独立指令类型;它通过在指令集页面增开「支持定时」开关与相关配置卡片完成。
⚠️ 可配置范围:定时指令描述的是「多长时间后 / 在某个时间点做某事」(如「30 分钟后关机」「每天 8 点开机」),不是「做某事持续多长时间」(如「开机运行 30 分钟」不属于定时指令的能力范围)。
1. 能力全景
一条定时指令由三张卡片组成,三者缺一不可:
| 卡片 | 回答什么 | 关键字段 |
|---|---|---|
| ① 定时能力 | 支持哪些定时动作? | 创建定时(add) / 取消定时(delete) / 查询定时(query) |
| ② 定时类型 | 支持哪些定时模式? | 单次定时 / 循环定时(粒度:每天 / 每周 / 工作日 /周末) |
| ③ 定时执行指令 | 到点执行哪些控制项? | 控制项白名单(勾选可被定时的指令) |
三张卡片描述的是同一条控制项在「时间」维度上的扩展面。例如「关机」这条控制项,可以支持「30 分钟后关」(单次)、「每天 22:00 关」(循环)、「查询关机计划」(查询)、「取消定时」(取消)。
2. 下发协议
定时指令的下发协议按下发方式分为两类。
2.1 IOT 平台下发协议
示例一:绝对/循环时间(cron)——以「每天 8 点把亮度调为 50」为例:
json
{
"intents": [
{
"intent": "设置设备定时",
"domain": "设备定时",
"deviceTimerBody": "【intent:设置亮度;domain:灯】",
"value": "50",
"unit": "度",
"cron": "0 8 * * *"
}
]
}示例二:相对时间(time_point)——以「30 分钟后关灯」为例:
json
{
"intents": [
{
"intent": "设置设备定时",
"domain": "设备定时",
"deviceTimerBody": "【intent:关闭灯;domain:灯】",
"time_point": "【minute:+30】"
}
]
}intent/domain固定为「设置设备定时」「设备定时」;deviceTimerBody:到点后真正要执行的控制项指令(内嵌原指令的 intent / domain);value/unit:执行时的目标值与单位(如无目标值可省略);cron:绝对时间点 / 循环触发时间,采用 cron 表达式;time_point:相对时间(如minute:+30表示 30 分钟后),与 cron 二选一。
2.2 端侧下发协议
端侧直连设备的定时协议,action = <控制项编码>_<定时能力>,时间通过 args 传递:
json
{
"instructions": [
{
"action": "brightness_add",
"args": {
"date": "2026-08-25 23:00:00",
"loop": 0
},
"desc": "晚上十一点把亮度调为50"
}
]
}action:控制项编码 + 定时能力(如brightness_add);args.date:定时触发的绝对时间;args.loop:是否循环(0 = 单次,非 0 表示循环)。
2.3 平台能力区分
不同 IOT 平台 / 端侧对定时能力的支持不一致,配置前需确认:
| 平台 | 创建 | 取消 | 查询 | 循环粒度 | 循环定时的取消 / 查询 |
|---|---|---|---|---|---|
| 小家 | ✅ | ✅ | ✅ | 每小时 / 每天 / 每周 / 每月 | ❌ 循环定时不支持取消和查询 |
| 集贤 | ❌ 不支持定时 | — | — | — | — |
| 端侧设备 | ✅ | ✅ | ✅ | 仅每天一种粒度 | ✅ 循环定时支持查询和取消 |
3. 配置步骤
指令配置完成后,进入指令集详情页的**「定时指令」Tab 页面**进行配置:
3.1 卡片一:定时能力
至少勾选 1 项,推荐三项全开:
- 创建定时(add):必开,否则用户无法「设置定时」;
- 取消定时(delete):推荐开启,支持用户口述取消;
- 查询定时(query):推荐开启,支持用户口述「有哪些定时」。
3.2 卡片二:定时类型
- 单次定时:用户说「30 分钟后」「今晚 10 点」「明天早上 8 点」等一次性时间;
- 循环定时:选择支持的粒度组合(实际可选粒度以第 2.3 节平台能力表为准,如端侧直连仅支持「每天」):
- 每天(daily)
- 每周(weekly,需勾选星期几)
- 工作日(workday,周一至周五)
- 周末(weekend,周六周日)
建议:根据设备真实使用场景勾选。以床头灯为例,开启「每天 / 工作日 / 周末」比全开更贴近用户心智。
3.3 卡片三:定时执行指令
从当前指令集下已有的控制项指令中勾选:
- ✅ 可勾选的:亮度、音量、模式、开关、温度等结果状态可预期的控制项;
- ⚠️ 不建议勾选的:
- 需要用户实时决策的控制项(如「切换到 XX 频道」);
- 非控制项指令(平台目前不支持非控制项进入定时链路)。
4. 常见示例
示例:空气净化器电源定时(端侧直联设备)
- 设备类型:端侧直联设备(定时协议走端侧,
action = <控制项编码>_<定时能力>) - 控制项:电源(power,SWITCH)
- 勾选定时能力:add / delete / query
- 勾选定时类型:单次 + 每天(端侧循环仅支持每天一种粒度)
- 勾选定时执行指令:电源(自身)
用户 query → 平台行为:
| 用户 query | 匹配 | 端上收到的 action | args |
|---|---|---|---|
| 「30 分钟后关机」 | power + add + 单次 | power_add | date = 当前时间 +30min、loop = 0 |
| 「每天早上 7 点开机」 | power + add + 每天 | power_add | date = 07:00、loop = 1(每天循环) |
| 「取消早上 7 点的开机」 | power + delete | power_delete | 定位待取消的定时任务 |
| 「有哪些定时」 | power + query | power_query | 无 args,设备端返回定时清单 |
5. 注意事项
- 协议一致性:
- IOT 平台:下发
设置设备定时intent +deviceTimerBody,由 IOT 平台侧解析执行,设备端无需感知定时逻辑; - 端侧直连:下发
<控制项编码>_<定时能力>(如power_add),需设备端自行实现_add / _delete / _query,否则定时指令将「执行失败」。 - 上线前请与设备 / 平台开发拉通协议,并使用 测试与调优 双重验证。
- IOT 平台:下发
- 不支持嵌套定时:平台不允许「定时创建一个定时」这类嵌套 query,识别层会直接拒绝。
- 静默场景:若定时到点需要无声执行(如深夜关机不播报),请参见 静默指令 中的双开关联动方案。
6. 相关链接
- 上级导航:AIOT 指令总览
- 前置概念:指令配置 · 维度详解
- 联动主题:静默指令 · 测试与调优