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

發行項
08/09/2023

RTC (系統時鐘) 用來在裝置電力中斷且裝置重新開機後無法存取網路連線時，在 Azure 球體裝置上保留時間。這樣一來，即使裝置無法存取 NTP 伺服器，也能在電源中斷期間維護時間。

如果您設定系統時間，當裝置斷電時，系統不會持續使用。若要在斷電期間持續使用時間，您必須呼叫 Applibs 函數clock_systohc。當clock_systohc稱為時，系統時間會推送到 RTC。

RTC 需求

使用 RTC 的應用程式必須包含適當的頁首檔案，並將 RTC 設定新增至應用程式資訊清單。

頁首檔案

在專案中包含 rtc 頁首：

 #include <applibs\rtc.h>

應用程式資訊清單設定

若要使用 RTC 和標準時鐘 API，您必須將應用程式功能新 SystemTime 增至應用程式資訊清單，然後將值設為 true 。 Azure 球體應用程式資訊清單具有更多有關應用程式資訊清單的詳細資料。

{
  "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 球體圖庫的一部分，它是未相關腳本、公用程式和函數的集合。

Azure 球體 OS 支援 TZ 環境變數的部分，但並非所有可能的格式：

您可以設定目前時區，包含或不含日光節約時間 (DST) 。範例：「EST+5」、「EST+5EDT」。如果本機時區是 Meridian 主要的西部，且如果是東部，則此值為正值。
您無法指定 DST 生效的日期和時間。
您無法指定時區檔案/資料庫。

若要在電源中斷期間維護時區設定，您可以使用可靜音儲存空間將時區儲存在持續性儲存空間中，然後在裝置重新開機時回收設定。

指定 NTP 伺服器

NTP 用戶端服務可以設定為從多個來源取得時間。預設的時間來源是 prod.time.sphere.azure.net ，如 Azure 球體 OS 網路需求中所述。

NTP 用戶端每 15 秒會嘗試同步處理一次，直到同步處理成功為止。成功同步處理時間之後，它會嘗試每 24 小時重新同步處理一次時間。當 Azure 球體執行時間同步處理時，會先使用 32678-61000 之間的隨機 UDP 用戶端來源埠。如果此埠失敗，Azure 球體會嘗試使用埠 124 做為 UDP 用戶端來源埠。

您可以指定系統從 DHCP 伺服器取得時間，也可以透過 Networking_TimeSync_EnableCustomNTP 或 Networking_TimeSync_EnableDefaultNtp 函數指定應用程式中的時間來源。

如果設定為使用 DHCP 做為時間伺服器來源，Azure 球體會處理 DHCP 選項 042，而 NTP 用戶端只會處理 DHCP 選項中傳送的前兩個專案，且應依喜好設定列出。這些伺服器將被視為主要伺服器和次要伺服器。

如果您想要透過應用程式指定主要和次要時間伺服器，也可以透過 Networking_TimeSync_EnableCustomNTP 設定時間伺服器。每次伺服器完整功能變數名稱 (FQDN) 的長度上限為 255 個字元。

後備

如果 NTP 用戶端設定為透過 DHCP 或 API 取得時間伺服器，則需要額外的參數來指定後援行為。
用戶端會先嘗試連絡主要時間伺服器。如果用戶端無法取得有效的時間伺服器回應，它會嘗試次要時間伺服器 (如果指定) 。
如果指定次要時間伺服器時失敗，或是無法回復到作業系統預設 Networking_NtpOption_FallbackServerEnabled 值的選項，則系統會連絡預設的作業系統時間來源 prod.time.sphere.azure.net。
- 在接下來的 24 小時同步處理間隔中，作業系統會返回並嘗試查詢主要時間伺服器。
如果您指定 Networking_NtpOption_FallbackServerDisabled，作業系統會每 15 秒繼續查詢主要和次要伺服器，直到成功與其中一個時間伺服器同步處理為止。

多重連線裝置

時間伺服器設定是全域設定，而不是每個介面設定。如果 Azure 球體裝置已多重連線，且兩個介面都透過 DHCP 取得 NTP 伺服器資訊，則最近處理的 DHCP NTP 選項組會優先。

系統時間範例

[系統時間] 範例示範如何管理系統時間及使用硬體 RTC。範例應用程式會設定系統時間，然後使用該 clock_systohc 函數來同步處理系統時間與 RTC。

自訂 NTP 樣本

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

共用方式為