在高级应用程序中管理系统时间和 RTC

项目
08/09/2023

RTC (实时时钟) 用于在设备断电且设备重新启动后无法访问网络连接时保留 Azure Sphere 设备上的时间。这允许设备在断电期间保持时间，即使它无权访问 NTP 服务器。

如果设置系统时间，则当设备断电时，系统时间不会保留。若要在断电期间保留时间，必须调用 Applibs 函数 clock_systohc。调用clock_systohc时，系统会将系统时间推送到 RTC。

RTC 要求

使用 RTC 的应用程序必须包含相应的头文件，并将 RTC 设置添加到应用程序清单。

头文件

在项目中包括 rtc 标头：

 #include <applibs\rtc.h>

应用程序清单设置

若要使用 RTC 和标准时钟 API，必须将应用程序功能添加到 SystemTime 应用程序清单，然后将值设置为 true。 Azure Sphere 应用程序清单提供了有关应用程序清单的更多详细信息。

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App3_RTC",
  "ComponentId" : "bb267cbd-4d2a-4937-8dd8-3603f48cb8f6",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "HardwareAddressConfig": true,
    "Gpio": [],
    "Uart": [],
    "WifiConfig": false,
    "NetworkConfig": false,
    "SystemTime": true,
    "TimeSyncConfig": true
  }
}

获取系统时间

若要获取系统时间，请调用标准 clock_gettime 函数。

设置系统时间

若要设置系统时间，请调用标准 clock_settime 函数。

将系统时间与 RTC 同步

设置系统时间后，当设备断电时，系统时间不会保留。若要在断电期间保留时间，请调用 Applibs clock_systohc 函数。调用clock_systohc时，系统会将时间推送到 RTC。

配置 NTP 客户端服务

默认情况下，NTP 客户端服务处于启用状态。如果在启用 NTP 客户端服务时设置系统时间，它将覆盖设备已建立 Internet 连接的 UTC 时间。可以禁用 NTP 客户端服务;但是，如果系统时间和 NTP 服务器时间之间的差太大，这可能会导致设备上的云更新失败。

设置时区

系统时间和 RTC 时间以 GMT/UTC 格式存储。可以通过调用 setenv 函数来更新 TZ 环境变量，然后调用 tzset 函数来更改应用程序使用的时区。

SetTimeFromLocation 项目演示如何使用反向 IP 查找获取位置信息、获取位置时间以及设置设备时间。此项目是 Azure Sphere 库的一部分，该库是未经维护的脚本、实用工具和函数的集合。

Azure Sphere OS 支持 TZ 环境变量的某些（但不是全部）可能的格式：

可以使用夏令时或不使用夏令时 (DST) 设置当前时区。示例：“EST+5”、“EST+5EDT”。如果本地时区位于主子午线以西，则此值为正值，如果为东部，则为负。
无法指定 DST 生效的日期和时间。
不能指定时区文件/数据库。

若要在断电期间维护时区设置，可以使用可变存储将时区存储在持久存储中，然后在设备重新启动时重新调用该设置。

指定 NTP 服务器

可将 NTP 客户端服务配置为从多个源获取时间。默认时间源为 prod.time.sphere.azure.net，如 Azure Sphere OS 网络要求中所述。

NTP 客户端尝试每 15 秒同步一次，直到成功同步。成功同步时间后，它会尝试每 24 小时重新同步一次时间。当 Azure Sphere 执行时间同步时，它首先使用 32678-61000 之间的随机 UDP 客户端源端口。如果此端口失败，Azure Sphere 会尝试使用端口 124 作为 UDP 客户端源端口。

可以指定系统从 DHCP 服务器获取时间，也可以通过 Networking_TimeSync_EnableCustomNTP 或 Networking_TimeSync_EnableDefaultNTP在应用程序中指定时间源。

如果配置为将 DHCP 用于时间服务器源，Azure Sphere 将处理 DHCP 选项 042，NTP 客户端将仅处理 DHCP 选项中发送的前两个条目，这些条目应按优先顺序列出。这些服务器将被视为主服务器和辅助服务器。

如果要通过应用程序指定主时间服务器和辅助时间服务器，还可以通过 Networking_TimeSync_EnableCustomNTP 配置时间服务器。服务器 (FQDN) 每次完全限定域名的最大长度为 255 个字符。

后备

如果将 NTP 客户端配置为通过 DHCP 或 API 获取时间服务器，则需要其他参数来指定回退行为。
客户端将首先尝试联系主要时间服务器。如果客户端无法获取有效的时间服务器响应，它将尝试辅助时间服务器 (（如果指定) ）。
如果指定了辅助时间服务器但失败，或者通过 Networking_NtpOption_FallbackServerEnabled 回退到 OS 默认值的选项失败，则系统会 prod.time.sphere.azure.net 联系默认 OS 时间源。
- 在接下来的 24 小时时间同步间隔内，OS 将返回并尝试查询主时间服务器。
如果指定 了Networking_NtpOption_FallbackServerDisabled，OS 将继续每 15 秒查询一次主服务器和辅助服务器，直到它与其中一个时间服务器成功同步。

多宿主设备

时间服务器设置是全局设置，而不是每个接口设置。如果 Azure Sphere 设备是多宿主的，并且两个接口都通过 DHCP 获取 NTP 服务器信息，则最近处理的 DHCP NTP 选项集获胜。

系统时间示例

系统时间示例演示如何管理系统时间并使用硬件 RTC。示例应用程序设置系统时间， clock_systohc 然后使用函数将系统时间与 RTC 同步。

自定义 NTP 示例

自定义 NTP 示例演示如何将 NTP 客户端服务配置为从多个源获取时间。

通过