天文定时

天文定时 是指根据设备所在区域的 日出和日落 的时间来设置动作的定时方案。该定时方案可用于路灯和庭院灯等场景。

功能描述

• 支持一条日出相关的定时。
• 支持一条日落相关的定时。
• 支持单次和周循环。
• 设备每次拉取定时，会一次性拉取 28 天 的日出日落定时。即使之后设备离线了，定时任务仍然可以被执行。

工作原理

工作时序图

天文定时任务更新机制

• 设备上电联网后，向云端请求一次定时任务。
• 云端通知定时任务有更新后，设备向云端请求一次定时任务。
• 设备每周（24*7 小时）向云端请求一次定时任务。
• 如果设备保存的日出日落数据只剩一周的数据了，此时请求的周期会变成 12 个小时一次。

异常处理机制

假设设备本地保存的定时如下：

周循环规则：仅周一到周五循环

• 打开定时任务后，设备一直处于断网

  假设当前日期是 2024 年 2 月 2 日。

  设备会根据周循环规则，按照最后一次定时的时间执行，直到设备联网成功后任务更新。即当前会按照 2024 年 1 月 26 日的日出日落数据来执行定时任务。

• 设备离线后断电，上电后设备还是处于离线

  假设断电前时间是 2024 年 1 月 4 日，设备上电后的时间是 2024 年 1 月 5 日。

  • 设备有本地 RTC，上电后设备内部的时间恢复到 2024 年 1 月 5 日，则会按照 2024 年 1 月 5 日的日出日落数据来执行定时任务。
  • 设备没有本地 RTC，上电后设备内部的时间恢复到初始时间 1970 年 1 月 1 日，则等到设备的时间运行到 2024 年 1 月 4 日之后才会执行天文定时任务。

开发指导

由于每个模组上的资源不一样，并不会打开所有功能，您需要检查 tuya_iot_config.h 并确认如下宏定义是否已经定义：

#define ENABLE_ASTRO_TIMER 1

关联头文件

• tuya_cloud_com_defs.h

使用方法

1. 如需启用该功能，前往 涂鸦开发者平台 创建产品，进入产品开发界面。在 设备交互 页面选择面板时，选择一个支持天文定时的面板。

   如果您选择的面板不支持天文定时的功能但是您有需求，或者您不知道什么面板支持天文定时，请联系您的涂鸦客户经理，或者 提交工单 反馈。

2. 在 设备初始化 时，应用注册 Obj 类 DP 处理回调 和 Raw 类 DP 处理回调，在回调函数中处理指令。

3. 定时任务初始化、增加、删除或者修改，TuyaOS 框架都会自行处理，应用无感知。

4. 到了执行定时任务的时间后，框架会通过 DP 指令回调函数来通知应用。接收 DP 数据结构体 中指令来源 cmd_tp 是 DP_CMD_TIMER。

常见问题

面板上出现的日出日落时间刚好反过来了，或者出现日出日落时间偏差？

一般是设备实际存在的区域和 App 账号所属的区域不在同一个服务区导致的。即设备在中国区，但是 App 账号属于欧洲区。此时，云端根据设备所在地方（中国区）的经纬度拉取日出日落时间，最终显示到面板上出现了偏差。