定时服务
物联网 (IoT) 的核心在于联网设备间的数据交互（如遥测数据和指令传输），但实际应用中往往需要设备具备自主运行能力。
定时服务与 ESP RainMaker 的其他功能一样，完全在节点端以“服务”的形式实现。云端后台仅作为节点和客户端（如手机应用）之间的网关。
定时服务虽然复杂，但已通过 C 语言 API 进行了封装。另外，手机应用也对其进行了抽象处理。
使用场景
通过 ESP RainMaker 的定时服务，可以根据预设时间自动控制设备，提高便利性，节约能源。例如，用户可以设置晚上 6 点开灯，11 点关灯等任务，无需手动操作。无论是智能家居还是工业设备，都可以通过定时功能实现自动化，优化电量使用。
定时服务的特点
- 在指定的确切时间执行动作。支持以下配置：
- 一次性（如：下午 6:30）
- 每周指定日重复（如：周一、周二、周六下午 6:30）
- 每年指定月的指定日期重复（如：1 月、8 月、12 月的 20 日下午 6:30）
- 每年指定日期重复（如：每年 1 月 20 日下午 6:30）
- 在指定时间段后执行动作。（如：从现在起 3 小时后）
- 为不同类型的定时服务添加自定义信息和标志，方便应用识别和区分。（如：预定义定时，默认开关定时等）
- 处理夏令时 (DST) 偏移，适用于已配置时区的情形。更多信息请参见管理夏令时章节。
定时服务依赖于时间服务。因此，必须设置并配置时间服务。否则定时服务不会触发。
参数详情
定时服务包含一个参数，该参数是对象数组。启用该功能将在节点配置中添加以下服务：
JSON 载荷（点击展开/折叠）
{
"name": "Schedule",
"params": [{
"bounds": {
"max": 5
},
"data_type": "array",
"name": "Schedules",
"properties": [
"read",
"write"
],
"type": "esp.param.schedules"
}],
"type": "esp.service.schedule"
}
定时服务的参数默认是一个空数组。max 边界表示节点可以拥有的最大定时服务数量。
添加新定时服务
可以通过如下格式在 setparams 中传递值来添加新的定时服务。该数值通常从客户端发送到云端，或通过本地控制直接发送到节点。
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。 - triggers (对象数组)：定时服务应触发的时间。必须选择提供
m或rsec。- m (uint16): 从零点起的分钟数。例如，6:30 p.m. = 18 * 60 + 30 = 1110。必须提供
"d"或"dd"。- d (uint8)：天数的位图。最低有效位是星期一。[ N/A | 星期日 | 星期六 | 星期五 | 星期二 | 星期三 | 星期四 | 星期一 ]。例如 ，0b00011111 (31) 表示所有工作日。零值表示仅触发一次。
- dd (uint8)：日期 (1-31)。
- mm (uint16，可选)：月份的位图。最低有效位是 1 月。例如，0b00000111 (7) 表示 1 月、2 月、3 月。
- yy (uint16，可选)：年。例如，2023。
- r (bool，可选)：
true表示每年重复。
- rsec (int32)：从现在开始的相对秒数。此项不设置天/日期。必须提供
m或rsec。
- m (uint16): 从零点起的分钟数。例如，6:30 p.m. = 18 * 60 + 30 = 1110。必须提供
- action (对象)：在给定时间要执行的实际操作。此对象的值与设置参数时传递的值相同。例如，要打开灯，将为 "Light"：
{"power": true}。 - info (字符串，可选)：其他附加信息或描述。
- flags (uint32，可选)：通用标志（无符号整数值），可根据用户的要求使用。
- validity (对象，可选)：提供定时服务适用的开始和结束时间。
- start (uint32)：定时服务应生效的时间（纪元秒）。
- end (uint32)：定时服务应失效的时间（纪元秒）。
一旦定时服务添加成功，获取参数时会返回一个类似以下 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操作将重新启用定时服务。
一次性定时服务在执行后会自动禁用。
使用指南
固件
此章节主要介绍定时服务的固件设置和配置。更多内容请参考固件使用指南。
手机应用
手机应用提供了一个非常简单的用户界面，用于各种定时服务操作。更新手机应用后在固件中启用定时服务，即可开始使用。
跨节点定时服务
对于跨多个节点的定时服务，客户端会为这些节点分配一个共同的定时服务 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. 及之后 | 无变化 | 无变化 |