在高階應用程式中管理系統時間和 RTC

發行項
09/27/2024

重要

這是 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，您必須將 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 用戶端服務時設定系統時間，則會覆寫裝置具有因特網連線的 UTC 時間。您可以停用 NTP 用戶端服務;不過，如果系統時間與 NTP 伺服器時間之間的差異太大，這可能會導致裝置上的雲端更新失敗。

設定時區

系統時間和 RTC 時間會以 GMT/UTC 儲存。您可以呼叫 setenv 函式來更新 TZ 環境變數，然後呼叫 tzset 函式，以變更應用程式所使用的時區。

SetTimeFromLocation 專案示範如何使用反向IP查閱來取得位置資訊，然後取得位置的時間，以及設定裝置時間。此專案是 Azure Sphere 資源庫的一部分，這是未受管理腳本、公用程式和函式的集合。

Azure Sphere OS 支援 TZ 環境變數的一些可能格式，但並非全部支援：

您可以使用或不使用日光節約時間來設定目前的時區（DST）。範例：「EST+5」、“EST+5EDT” 如果當地時區位於 Prime Meridian 以西，則此值為正數，如果它是東部則為負值。
您無法指定 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 取得時間伺服器，則需要額外的參數來指定後援行為。
用戶端會先嘗試連絡主要時間伺服器。如果客戶端無法取得有效的時間伺服器回應，它會嘗試次要時間伺服器（如果指定的話）。
如果指定次要時間伺服器且失敗，或如果透過容錯回復至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。

自訂NTP範例

自定義 NTP 範例 示範如何設定 NTP 用戶端服務，以從多個來源取得時間。

共用方式為