通过

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

  • 项目

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

当设备断电或者在重启后无法访问网络连接时，可以使用 RTC（实时时钟）在 Azure Sphere 设备上保持准确的时间。 这样，即使因为断电而无法访问 NTP 服务器，设备仍能维持准确的时间。

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

RTC 要求

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

头文件

在项目中包含 rtc 头：

 #include <applibs\rtc.h>

应用程序清单设置

若要使用 RTC API 和标准时钟 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.netAzure 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 获取时间服务器，则需要附加参数来指定回退行为。

  • 客户端将首先尝试联系主时间服务器。 如果客户端未能获取有效的时间服务器响应，它将尝试辅助时间服务器（如果指定）。

  • 如果指定了辅助时间服务器并且它失败，或者如果通过失败回退到 OS 默认值 Networking_NtpOption_FallbackServerEnabled 的选项，则系统会联系默认的 OS 时间源 prod.time.sphere.azure.net。

    • 在接下来的 24 小时时间同步间隔中，OS 将返回并尝试查询主时间服务器。

  • 如果指定 了Networking_NtpOption_FallbackServerDisabled，OS 将每隔 15 秒继续查询主服务器和辅助服务器，直到它已成功与某个时间服务器同步。

多宿主设备

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

系统时间示例

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

SetTimeFromLocation 项目演示如何使用反向 IP 查找获取位置信息，然后获取位置时间并设置设备时间。 此项目是 Azure Sphere 库的一部分，它是未映射的脚本、实用工具和函数的集合。

自定义 NTP 示例

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