时间服务使用指南
固件使用指南
概述
对于 IoT 设备而言,时间是一个重要概念,对于日程等功能十分关键。有两个相关的时间概念:
- 网络时间:即当前的协调世界时 (Universal Time Coordinated,简称 UTC)
- 时区:表示相对于 UTC 的偏移量
- 夏令时(根据配置的时区自动调整夏令时)
要了解更多关于时间服务的信息,请参阅此文档。
ESP RainMaker 时间工具 API 概述
ESP RainMaker 提供的时间工具 API 具有以下功能:
- 使用 SNTP(Simple Network Time Protocol,简单网络时间协议)同步网络时间,确保时间准确。
- 检查并等待时间更新,确保设备的系统时间准确。
- 使用 POSIX 格式或位置字符串配置和获取时区设置。
- 根据配置的时区自动调整夏令时(DST)。
- 获取包含时区和夏令时信息的格式化本地时间字符串,用于日志记录和日程功能。
- 提供准确的时间同步和时区信息,支持日程和自动化功能。
如需了解详细的实现和 API 参考,请参阅 ESP RainMaker 文档:Utilities。这些 API 简化了开发人员的时间处理,确保 IoT 设备在不同的时区和地区可靠运行。
使用指南
网络时间
网络时间通常通过 SNTP 获取。ESP RainMaker 在 ESP-IDF 中对 SNTP 组件进行了封装,并提供了接口。
提供的 API 如下:
| 函数 | 描述 |
|---|---|
esp_err_t esp_rmaker_time_sync_init(esp_rmaker_time_config_t *config) | 初始化时间同步 |
bool esp_rmaker_time_check(void) | 检查时间是否已同步 |
esp_err_t esp_rmaker_time_wait_for_sync(uint32_t ticks_to_wait) | 等待时间同步 |
提示
如果在传递给 esp_rmaker_node_init() 的 esp_rmaker_config_t 中设置了 enable_time_sync=true,则 esp_rmaker_time_sync_init() 会被内部调用。
esp_rmaker_config_t rainmaker_cfg = {
.enable_time_sync = true, // 启用时间同步
// 其他配置参数
};
esp_rmaker_node_init(&rainmaker_cfg);
时区
-
ESP-IDF 提供了使用
TZ变量和tz_set()API 设置时区的功能。 -
有关 TZ 变量的详细信息,请参阅 GNU libc 文档。
-
ESP RainMaker 在此基础上提供了一层封装,支持多种方式设置时区。
-
有两个与时区相关的主要变量:
- 时区: 用户友好的时区字符串(如
Asia/Shanghai),广泛用于 iOS、安卓等主流系统中。使用 API 设置此变量时,系统会根据对应的映射关系自动设置 POSIX 时区。如需了解完整的支持值列表,请查看有效时区值。 - POSIX 时区: 时区字符串,遵循 GNU libc 的 TZ 变量文档中第一或第二种格式。此字符串包含了时区名称(例如 CST)、与 UTC 的偏移量,以及夏令时的开始和结束时间。甚至可以使用此格式创建自定义时区。
- 时区: 用户友好的时区字符串(如
夏令时
根据配置的时区,ESP RainMaker 会自动管理夏令时,以确保日程事件不受影响。
设置时区的各种方法总结如下:
C 语言 API
C 语言 API 将时区存储在 NVS 中。因此,即使设备重启后,调用 esp_rmaker_time_sync_init() 也会自动设置时区。
| 函数 | 描述 |
|---|---|
esp_err_t esp_rmaker_time_set_timezone(const char *tz) | 使用时区字符串设置时区 |
esp_err_t esp_rmaker_time_set_timezone_posix(const char *tz_posix) | 使用 POSIX 格式字符串设置时区 |
配置选项
| 配置选项 | 描述 |
|---|---|
CONFIG_ESP_RMAKER_DEF_TIMEZONE | 设置时区区域字符串。默认值为空(UTC)。如果使用任意 C API 设置了时区,其设置值将覆盖此配置选项。 |
RainMaker 服务
RainMaker 提供了一个可选的服务,允许通过手机应用程序等客户端设置时区。通过以下命令启用此服务:
esp_err_t esp_rmaker_timezone_service_enable(void);
这会将以下服务添加到节点配置中:
JSON 载荷(点击折叠/展开)
{
"name": "Time",
"params": [{
"data_type": "string",
"name": "TZ",
"properties": [
"read",
"write"
],
"type": "esp.param.tz"
},
{
"data_type": "string",
"name": "TZ-POSIX",
"properties": [
"read",
"write"
],
"type": "esp.param.tz_posix"
}
],
"type": "esp.service.time"
}
对应参数(带示例值):
JSON 载荷(点击折叠/展开)
{
"Time": {
"TZ": "America/Los_Angeles",
"TZ-POSIX": "PST8PDT,M3.2.0,M11.1.0"
}
}