Gestire l'ora di sistema e l'orologio in tempo reale in applicazioni di alto livelloManage system time and the RTC in high-level applications

L'orologio in tempo reale viene usato per mantenere aggiornata l'ora in un dispositivo Azure Sphere in caso di perdita dell'alimentazione e se il dispositivo non ha accesso a una connessione di rete dopo il riavvio.The RTC (real-time clock) is used to keep time on an Azure Sphere device when the device loses power and has no access to a network connection after the device reboots. In questo modo il dispositivo può mantenere aggiornata l'ora durante un'interruzione dell'alimentazione, anche se non ha accesso a un server NTP.This allows the device maintain time during a power loss even if it doesn't have access to an NTP server.

Se si imposta l'ora di sistema, non viene mantenuta in caso di interruzione dell'alimentazione per il dispositivo.If you set the system time, it does not persist when the device loses power. Per rendere persistente l'ora in caso di interruzione dell'alimentazione, è necessario chiamare la funzione Applibs clock_systohc.To persist the time during power loss, you must call the Applibs function clock_systohc. Quando si chiama clock_systohc, viene eseguito il push dell'ora di sistema all'orologio in tempo reale.When clock_systohc is called, the system time is pushed to the RTC.

Requisiti dell'orologio in tempo realeRTC requirements

Le applicazioni che usano l'orologio in tempo reale devono includere i file di intestazione appropriati e aggiungere le impostazioni dell'orologio in tempo reale al manifesto dell'applicazione.Applications that use the RTC must include the appropriate header files and add RTC settings to the application manifest.

File di intestazioneHeader files

Includere l'intestazione rtc nel progetto:Include the rtc header in your project:

 #include <applibs\rtc.h>

Impostazioni del manifesto dell'applicazioneApplication manifest settings

Per usare le API dell'orologio in tempo reale e dell'orologio standard, è necessario aggiungere la funzionalità SystemTime dell'applicazione al manifesto dell'applicazione e quindi impostare il valore su true.To use the RTC and standard clock APIs, you must add the SystemTime application capability to the application manifest and then set the value to true. Nell'argomento Manifesto dell'applicazione di Azure Sphere sono disponibili informazioni più dettagliate sul manifesto dell'applicazione.The Azure Sphere application manifest topic has more details about the application manifest.

{
  "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
 }
}

Ottenere l'ora di sistemaGet the system time

Per ottenere l'ora di sistema, chiamare la funzione clock_gettime standard.To get the system time, call the standard clock_gettime function.

Impostare l'ora di sistemaSet the system time

Per impostare l'ora di sistema, chiamare la funzione clock_settime standard.To set the system time, call the standard clock_settime function.

Sincronizzare l'ora di sistema con l'orologio in tempo realeSynchronize the system time with the RTC

Quando si imposta l'ora di sistema, non viene mantenuta in caso di interruzione dell'alimentazione per il dispositivo.When the system time is set, it does not persist when the device loses power. Per salvare in modo permanente l'ora durante la perdita dell'alimentazione, chiamare la funzione Applibs clock_systohc .To persist the time during power loss, call the Applibs clock_systohc function. Quando si chiama clock_systohc, viene eseguito il push dell'ora di sistema all'orologio in tempo reale.When clock_systohc is called the system time is pushed to the RTC.

Configurare il servizio client NTPConfigure the NTP client service

Il servizio client NTP è abilitato per impostazione predefinita.The NTP client service is enabled by default. Se si imposta l'ora di sistema mentre il servizio client NTP è abilitato, l'ora UTC verrà sovrascritta quando il dispositivo è connesso a Internet.If you set the system time while the NTP client service is enabled, it will overwrite the UTC time when the device has internet connectivity. Il servizio client NTP può essere disabilitato, tuttavia ciò può causare un errore degli aggiornamenti cloud nel dispositivo se la differenza tra l'ora di sistema e l'ora del server NTP è eccessiva.You can disable the NTP client service; however, this can cause cloud updates on the device to fail if the difference between the system time and the NTP server time is too great.

Impostare il fuso orarioSet the time zone

L'ora di sistema e l'ora dell'orologio in tempo reale sono archiviate nel formato GMT/UTC.The system time and the RTC time are stored in GMT/UTC. È possibile modificare il fuso orario usato dall'applicazione chiamando la funzione setenv per aggiornare la variabile di ambiente TZ e quindi chiamando la funzione tzset.You can change the time zone used by your application by calling the setenv function to update the TZ environment variable, and then calling the tzset function.

Il sistema operativo di Azure Sphere supporta alcuni, ma non tutti i possibili formati per la variabile di ambiente TZ:The Azure Sphere OS supports some, but not all, possible formats for the TZ environment variable:

  • Il fuso orario corrente può essere impostato con o senza ora legale.You can set the current time zone with or without Daylight Saving Time (DST). Esempi: "EST+5", "EST+5EDT".Examples: "EST+5", "EST+5EDT". Il valore è positivo se il fuso orario locale è a ovest del meridiano zero e negativo se è a est.This value is positive if the local time zone is west of the Prime Meridian and negative if it is east.
  • Non è possibile specificare la data e l'ora in cui deve essere applicata l'ora legale.You can't specify the date and time when DST should come into effect.
  • Non è possibile specificare un file/database del fuso orario.You can't specify a time zone file/database.

Per mantenere le impostazioni del fuso orario durante un'interruzione dell'alimentazione, è possibile usare l' archiviazione modificabile per archiviare il fuso orario nell'archivio permanente e quindi richiamare l'impostazione quando il dispositivo viene riavviato.To maintain the time zone settings during a power loss, you can use mutable storage to store the time zone in persistent storage and then recall the setting when the device reboots.

Specifica di un server NTPSpecifying an NTP server

Il servizio client NTP può essere configurato in modo da ottenere tempo da più origini.The NTP client service can be configured to obtain time from multiple sources. L'origine dell'ora predefinita è prod.time.sphere.azure.net , come indicato nei requisiti di rete del sistema operativo Azure Sphere.The default time source is prod.time.sphere.azure.net, as noted in the Azure Sphere OS networking requirements.

È possibile specificare che il sistema ottenga l'ora da un server DHCP oppure è possibile specificare l'origine dell'ora nell'applicazione tramite Networking_TimeSync_EnableCustomNTP o Networking_TimeSync_EnableDefaultNTP.You can specify that the system obtain time from a DHCP server, or you can specify the time source in the application via Networking_TimeSync_EnableCustomNTP or Networking_TimeSync_EnableDefaultNTP.

Se configurato per l'utilizzo di DHCP per le origini server temporali, Azure Sphere elaborerà l'opzione DHCP 042 e il client NTP elaborerà solo le prime due voci inviate nell'opzione DHCP, che devono essere elencate in ordine di preferenza.If configured to use DHCP for time server sources, Azure Sphere will process the DHCP option 042 and the NTP client will only process the first two entries sent in the DHCP option, which should be listed in order of preference. Questi verranno considerati come server primario e secondario.These will be considered as a primary server and secondary server.

È anche possibile configurare un server di ora tramite Networking_TimeSync_EnableCustomNTP se si vuole specificare il server di ora primaria e secondaria tramite l'applicazione.You may also configure a time server via Networking_TimeSync_EnableCustomNTP if you would like to specify the primary and secondary time server via the application. La lunghezza massima per ogni nome di dominio completo (FQDN) del server è 255 caratteri.The maximum length for each time server fully qualified domain name (FQDN) is 255 characters.

FallbackFallback

  • Se il client NTP è configurato per ottenere i server temporali tramite DHCP o API, è necessario un parametro aggiuntivo per specificare il comportamento di fallback.If the NTP client is configured to obtain the time server(s) via DHCP or API, an additional parameter is required to specify fallback behavior.

  • Il client tenterà prima di contattare il server dell'ora primaria.The client will attempt to contact the primary time server first. Se il client non è in grado di ottenere una risposta del server temporale valida, proverà il server di ora secondaria (se specificato).If the client fails to obtain a valid time server response, it will try the secondary time server (if specified).

  • Se viene specificato un server di ora secondario che ha esito negativo o se l'opzione per eseguire il fallback alle impostazioni predefinite del sistema operativo tramite Networking_NtpOption_FallbackServerEnabled non riesce, il sistema contatterà quindi l'origine dell'ora del sistema operativo predefinita prod.Time.Sphere.Azure.NET.If a secondary time server is specified and it fails, or if the option to fall back to OS defaults via Networking_NtpOption_FallbackServerEnabled fails, the system will then contact the default OS time source prod.time.sphere.azure.net.

    • L'intervallo di sincronizzazione di 24 ore successivo verrà restituito dal sistema operativo e tenterà di eseguire una query sul server di ora primaria.On the next 24-hour time sync interval the OS will go back and attempt to query the primary time server.
  • Se è stato specificato Networking_NtpOption_FallbackServerDisabled , il sistema operativo continuerà a eseguire una query sul server primario e secondario ogni 15 secondi fino a quando non sarà stato correttamente sincronizzato con uno dei server temporali.If you specified Networking_NtpOption_FallbackServerDisabled , the OS will continue to query the primary and secondary server every 15 seconds until it has successfully synchronized with one of the time servers.

Dispositivi multihomedMultihomed devices

Le impostazioni del server ora sono un'impostazione globale, non un'impostazione per interfaccia.The time server settings are a global setting, not a per interface setting. Se il dispositivo Azure Sphere è multihome e entrambe le interfacce ottengono le informazioni sul server NTP tramite DHCP, il set di opzioni di WINS DHCP elaborato più di recente ha la priorità.If the Azure Sphere device is multihomed and both interfaces obtain NTP server information via DHCP, the most recently processed DHCP NTP set of options wins.

Esempio di ora di sistemaSystem time sample

L' esempio di ora di sistema illustra come gestire l'ora di sistema e usare l'orologio in tempo reale dell'hardware.The System Time sample shows how to manage the system time and use the hardware RTC. L'applicazione di esempio imposta l'ora di sistema e quindi usa la clock_systohc funzione per sincronizzare l'ora di sistema con l'RTC.The sample application sets the system time and then uses the clock_systohc function to synchronize the system time with the RTC.

Esempio di NTP personalizzatoCustom NTP sample

L' esempio personalizzato NTP Mostra come configurare il servizio client NTP per ottenere tempo da più origini.The Custom NTP sample shows how to configure the NTP client service to obtain time from multiple sources.