定时服务
物联网 (IoT) 的核心在于联网设备间的数据交互（如遥测数据和指令传输），但实际应用中往往需要设备具备自主运行能力。
定时服务与 ESP RainMaker 的其他功能一样，完全在节点端以“服务”的形式实现。云端后台仅作为节点和客户端（如手机应用）之间的网关。
定时服务虽然复杂，但已通过 C 语言 API 进行了封装。另外，手机应用也对其进行了抽象处理。
使用场景
通过 ESP RainMaker 的定时服务，可以根据预设时间自动控制设备，提高便利性，节约能源。例如，用户可以设置晚上 6 点开灯，11 点关灯等任务，无需手动操作。无论是智能家居还是工业设备，都可以通过定时功能实现自动化，优化电量使用。
定时功能
- 在指定的确切时间执行动作。支持以下配置：
- 一次性（如：下午 6:30）
- 每周指定日重复（如：周一、周二、周六下午 6:30）
- 每年指定月的指定日期重复（如：1 月、8 月、12 月的 20 日下午 6:30）
- 每年指定日期重复（如：每年 1 月 20 日下午 6:30）
- 在指定时间段后执行动作（如：从现在起 3 小时后）。
- 按日照时间定时（日出/日落）：基于日出日落时间的天文学计算来调度设备操作，支持可配置的时间偏移（例如：日落前 30 分钟、日出时刻）。
- 为不同类型的定时服务添加自定义信息和标志，方便应用识别和区分（如：预定义定时，默认开关定时等）。
- 处理夏令时 (DST) 偏移，适用于已配置时区的情形。更多信息请参见管理夏令时章节。
定时服务依赖于时间服务。因此，必须设置并配置时间服务。否则定时服务不会触发。
参数详情
定时服务包含一个参数，该参数是对象数组。启用该功能将在节点配置中添加以下服务：
JSON 载荷（点击展开/折叠）
{
"name": "Schedule",
"params": [{
"bounds": {
"max": 5
},
"data_type": "array",
"name": "Schedules",
"properties": [
"read",
"write"
],
"type": "esp.param.schedules"
}],
"type": "esp.service.schedule",
"daylight_support": "yes"
}
定时服务的参数默认是一个空数组。max 边界表示节点可以拥有的最大定时服务数量。
daylight_support 属性用于标识设备是否支持按日照时间（日出/日落）定时。该属性可帮助客户端应用自动发现此功能。
添加新定时服务
可以通过如下格式在 setparams 中传递值来添加新的定时服务。该数值通常从客户端发送到云端，或通过本地控制直接发送到节点。
ESP RainMaker 支持三种定时任务触发类型：
- 基于时间的定时：使用
m（从零点 起的分钟数）结合日期/星期模式 - 相对时间定时：使用
rsec（相对于当前时刻的秒数） - 日照时间定时：使用
sr（日出）或ss（日落）并结合地理位置数据 （v1.7.1 及以上版本可用）
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Evening",
"id": "8D36",
"operation": "add",
"triggers": [{
"d": 31,
"m": 1110
}],
"action": {
"Light": {
"power": true
}
}
}]
}
}
每个 JSON 键的详细说明
通用字段（所有定时类型）
- name (字符串)：用户自定义的定时服务名称。
- id (字符串)：定时服务的唯一 ID。（此 ID 仅需在给定用户中唯一，而非全局唯一）。此 ID 由客户端在添加定时服务时生成，用于后续操作。建议使用较短的 ID。
- operation (字符串)：要执行的操作。可能的值为
add、remove、edit、enable和disable。 - action (对象)：在给定时间要执行的实际操作。此对象的值与设置参数时传递的值相同。例如，要打开灯，将为 "Light"：
{"power": true}。 - info (字符串，可选)：其他附加信息或描述。
- flags (uint32，可选)：通用标志（无符号整数值），可根据用户的要求使用。
- validity (对象，可选)：提供定时服务适用的开始和结束时间。
- start (uint32)：定时服务应生效的时间（纪元秒）。
- end (uint32)：定时服务应失效的时间（纪元秒）。
触发类型
triggers 对象数组定义了执行定时服务的时间。请选择以下任意一种触发类型：
1. 基于时间的触发器（绝对时间）
- m（uint16）: 从零点起的分钟数。例如，下午 6:30 = 18 × 60 + 30 = 1110。
- d（uint8，可选）：天数的位图。最低有效位是星期一。
- 位模式：[ N/A | 星期日 | 星期六 | 星期五 | 星期四 | 星期三 | 星期二 | 星期一]
- 示例：
31(0b00011111) = 工作日，96(0b01100000) = 周末，127= 每天 - 值为
0表示仅触 发一次
- dd（uint8，可选）：日期（1–31），用于特定日期定时。
- mm（uint16，可选）：月份的位图。最低有效位是一月。
- 示例：
7(0b00000111) = 一月、二月、三月；4095(0b111111111111) = 全年所有月份 - 重要提示：如果指定了
mm，则必须同时指定yy或r。
- 示例：
- yy（uint16，可选）：具体年份（例如 2023）。当使用
mm而未指定r时，必须提供。 - r（bool，可选）：设为
true表示每年重复（与dd一起使用，可选mm）。当使用mm而未指定yy时，必须提供。
2. 相对触发器（从当前时间起）
- rsec（int32）：从当前时间起的相对秒数。此类型不适用日期或星期设置。
3. 日照触发器（基于日出/日落）自 v1.7.1 起可用
- sr（int16）：日出偏移量（单位：分钟；正值 = 日出后，负值 = 日出前，0 = 精确日出）。
- ss（int16）：日落偏移量（单位：分钟；正值 = 日落后，负值 = 日落前，0 = 精确日落）。
- lat（float）：纬度（十进制度，范围 –90 到 +90，北纬为正）。
- lon（float）：经度（十进制度，范围 -180 到 +180，东经为正）。
- loc（string，可选）：便于识别的人类可读位置名称。
- d（unit8，可选）：星期位图（与基于时间的触发器相同）。
- ts（unit32，系统自动计算）：下次触发时间戳，由系统自动计算，客户端不应提供。
- 每个触发对象只能使用一种触发类型：
m、rsec或sr/ss。 - 对于基于时间的触发器：
m应与d（星期）或dd（日期）之一同时使用。 - 对于基于日期的触发器：如果指定了
mm（月份），则必须同时指定yy（年份）或r（每年重复）。 - 对于日照触发器：只能提供
sr（日出）或ss（日落）中的一个，不可同时指定。 - 日照触发器必须提供地理坐标（
lat、lon）。
一旦定时服务添加成功，获取参数时会返回一个类似以下 JSON 的值。
- 这是从节点发送到云端或手机应用的确认响应。
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Evening",
"id": "8D36",
"enabled": true,
"triggers": [{
"d": 31,
"m": 1110
}],
"action": {
"Light": {
"power": true
}
}
}]
}
}
如上示例所示，响应包含一个 enabled 键，表示定时服务现已启用。
在添加或更新定时服务时，定时服务数组中只需发送单个条目。但在查询时，节点会返回定时服务数组中的所有的定时服务信息。
其他操作
以下所有操作均在客户端（如手机应用）上进行。
编辑
- 用于编辑定时服务所传递的值与添加新定时服务时传递的值类似。
- 指定的 ID 应与现有的定时服务匹配，同时，
operation的值应该设置为edit。 - 可以发送整个对象或仅发送已更改的元素（名称、触发方式或操作）。但是，这些键中的对象必需要完整。
- 如果当前操作是
"action":{"Light": {"power": true, "brightness":90}}； - 现在需要将亮度更改为 100；
- 应该传递
"action":{"Light": {"power": true, "brightness":100}}；
而不是"action":{"Light": {"brightness":100}}。
删除
- 要删除现有定时服务，只需传递
id和operation。以下是一个示例。
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"id": "8D36",
"operation": "remove"
}]
}
}
启用/禁用
- 该载荷与删除操作的载荷相似。当需要暂时禁用定时服务而不是删除它时非常有用。以下是一个示例。
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"id": "8D36",
"operation": "disable"
}]
}
}
传递 enable 操作将重新启用定时服务。
一次性定时服务在执行后会自动禁用。
定时示例
本节提供了 ESP RainMaker 支持的三种定时触发类型的完整示例。
1. 按星期几调度（基于 d 参数）
此类调度使用 d 参数指定每周的哪几天应触定时。
示例：工作日晨间闹钟
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Weekday Alarm",
"id": "WD01",
"operation": "add",
"triggers": [{
"m": 420,
"d": 31
}],
"action": {
"Light": {
"Power": true,
"Brightness": 100
},
"Buzzer": {
"Power": true
}
}
}]
}
}
此定时 仅在工作日（d=31，周一至周五）早上 7:00（420 分钟）触发。
示例：周末夜晚灯光
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Weekend Evening",
"id": "WE01",
"operation": "add",
"triggers": [{
"m": 1140,
"d": 96
}],
"action": {
"Light": {
"Power": true,
"Brightness": 60
}
}
}]
}
}
此定时仅在周末（d=96，周六和周日）晚上 7:00（1140 分钟）触发。
2. 特定日期定时（基于 dd）
这些定时使用 dd 参数指定特定日期，可选地与 mm（月份）和 yy（年份）或 r（每年重复）一起使用。
当使用 mm（月份位图）时，必须同时提供 yy（特定年份）或 r: true（每年重复）。这两个参数中至少要有一个。
示例：每月 1 日生成月度报告
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Monthly Report",
"id": "MR01",
"operation": "add",
"triggers": [{
"m": 540,
"dd": 1,
"mm": 4095,
"r": true
}],
"action": {
"Sensor": {
"Report": true
}
}
}]
}
}
此定时将在每月 1 日上午 9:00 触发，并每年重复执行（mm=4095：所有月份，r=true）。
示例：季度维护
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Quarterly Maintenance",
"id": "QM01",
"operation": "add",
"triggers": [{
"m": 600,
"dd": 15,
"mm": 273,
"r": true
}],
"action": {
"System": {
"Maintenance": true
}
}
}]
}
}
此定时将在每年 1 月、4 月、7 月和 10 月的 15 日上午 10:00 触发（mm=273：0b100010001，r=true）。
示例：特定年份事件
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "New Year 2024",
"id": "NY24",
"operation": "add",
"triggers": [{
"m": 0,
"dd": 1,
"mm": 1,
"yy": 2024
}],
"action": {
"Light": {
"Power": true,
"Brightness": 100,
"Color": "rainbow"
}
}
}]
}
}
此定时将在 2024 年 1 月 1 日凌晨触发，仅执行一次。
3. 日照定时（基于 sr/ss）自 v1.7.1 起可用
此类定时根据地理位置，使用天文计算确定日出（sr）和日落（ss）时间。
示例：日出时浇花
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Morning Garden Water",
"id": "SR01",
"operation": "add",
"triggers": [{
"sr": 30,
"lat": 37.7749,
"lon": -122.4194,
"loc": "San Francisco",
"d": 127
}],
"action": {
"Sprinkler": {
"Power": true,
"Duration": 600
}
}
}]
}
}
此定时将在旧金山每天日出后 30 分钟开始浇花。
示例：日落时开启安全灯
JSON 载荷（点击展开/折叠）
{
"Schedule": {
"Schedules": [{
"name": "Security Lights",
"id": "SS01",
"operation": "add",
"triggers": [{
"ss": -15,
"lat": 51.5074,
"lon": -0.1278,
"loc": "London",
"d": 31
}],
"action": {
"Security_Light": {
"Power": true,
"Brightness": 80
}
}
}]
}
}
此定时将在伦敦每个工作日日落前 15 分钟开启安全灯。
日期模式参考表
以下是 d 参数常用的日期模式值速查表：
| 模式类型 | 数值 | 二进制 | 说明 |
|---|---|---|---|
| 仅星期一 | 1 | 0b0000001 | |
| 仅星期二 | 2 | 0b0000010 | |
| 仅星期三 | 4 | 0b0000100 | |
| 仅星期四 | 8 | 0b0001000 | |
| 仅星期五 | 16 | 0b0010000 | |
| 仅星期六 | 32 | 0b0100000 | |
| 仅星期日 | 64 | 0b1000000 | |
| 工作日 | 31 | 0b0011111 | 周一至周五 |
| 周末 | 96 | 0b1100000 | 周六至周日 |
| 每日 | 127 | 0b1111111 | 全部日期 |
| 单次执行 | 0 | 0b0000000 | 仅执行一次 |
日照作息配置
日照作息功能配置要求：
- 功能启用：需设置
CONFIG_ESP_SCHEDULE_ENABLE_DAYLIGHT和CONFIG_ESP_RMAKER_SCHEDULE_ENABLE_DAYLIGHT参数启用日照作息功能。 - flash 空间：启用后需占用约 15 KB 的 flash 空间。
- 位置数据：需提供地理坐标（经纬度）用于计算。
- 时间服务：必须正确配置时间服务。
日照作息配置需集成至固件项目中，具体设置方法请参阅固件使用指南。
使用指南
固件
此章节主要介绍定时服务的固件设置和配置。更多内容请参考固件使用指南。
手机应用
手机应用提供了一个非常简单的用户界面，用于各种定时服务操作。更新手机应用后在固件中启用定时服务，即可开始使用。
跨节点定时服务
对于跨多个节点的定时服务，客户端会为这些节点分配一个共同的定时服务 ID，以便能够统一查询和归类为一个定时服务任务。
点击定时服务应用程序以查看更多信息和示例。
管理夏令时 (DST)
- 通常，夏令时 (DST) 开始时，时钟向前拨快 1 小时；夏令时结束时，时钟向后拨回 1 小时。
以美国/洛杉矶时区为例
参考来自维基百科: 在美国，夏令时在 3 月的第二个星期日开始，在 11 月的第一个星期日结束，时间在当地时间凌晨两点发生变化。人们所说的“春天向前，秋天向后”就是指，在春天，时钟在凌晨两点拨快到凌晨三 点，而在秋天，时钟在凌晨两点拨回到凌晨一点。
在夏令时切换当天之外的所有日期，定时服务都会在预定的正确时间触发，因为节点会根据指定时区的夏令时自动调整时钟。不过，在夏令时切换期间需要特别留意，因为计划任务可能不会在预期的时间触发：有些时间段会被跳过，而有些时间段则会重复出现。在定时服务切换当天的情况如下：
| 预定时间 | 夏令时开始 （从 2:00 拨快到 3:00） | 夏令时结束 （从 2:00 拨回到 1:00） |
|---|---|---|
| 12:59 a.m. 及之前 | 无变化 | 无变化 |
| 1:00 a.m. 至 1:59 a.m. | 无变化 | 仅在切换之前触发一次。切换后不会再次触发 |
| 2:00 a.m. 至 2:59 a.m. | 延迟 1 小时。在切换日 3:00 至 3:59 a.m. 触发 | 无变化 |
| 3:00 a.m. 及之后 | 无变化 | 无变化 |