Manage system time and the RTC in high-level applications

Article
08/08/2023

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. This allows the device maintain time during a power loss even if it doesn't have access to an NTP server.

If you set the system time, it does not persist when the device loses power. To persist the time during power loss, you must call the Applibs function clock_systohc. When clock_systohc is called, the system time is pushed to the RTC.

RTC requirements

Applications that use the RTC must include the appropriate header files and add RTC settings to the application manifest.

Header files

Include the rtc header in your project:

 #include <applibs\rtc.h>

Application manifest settings

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. Azure Sphere application manifest 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
  }
}

Get the system time

To get the system time, call the standard clock_gettime function.

Set the system time

To set the system time, call the standard clock_settime function.

Synchronize the system time with the RTC

When the system time is set, it does not persist when the device loses power. To persist the time during power loss, call the Applibs clock_systohc function. When clock_systohc is called the system time is pushed to the RTC.

Configure the NTP client service

The NTP client service is enabled by default. 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. 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.

Set the time zone

The system time and the RTC time are stored in GMT/UTC. 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.

The SetTimeFromLocation project shows how to use Reverse IP lookup to get location information, then obtain time for location, and set device time. This project is part of the Azure Sphere Gallery, a collection of unmaintained scripts, utilities, and functions.

The Azure Sphere OS supports some, but not all, possible formats for the TZ environment variable:

You can set the current time zone with or without Daylight Saving Time (DST). Examples: "EST+5", "EST+5EDT". This value is positive if the local time zone is west of the Prime Meridian and negative if it is east.
You can't specify the date and time when DST should come into effect.
You can't specify a time zone file/database.

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.

Specifying an NTP server

The NTP client service can be configured to obtain time from multiple sources. The default time source is prod.time.sphere.azure.net, as noted in the Azure Sphere OS networking requirements.

The NTP client attempts to synchronize time every 15 seconds until a successful sync has occurred. After successfully synchronizing time, it attempts to re-synchronize time once every 24 hours. When Azure Sphere performs time sync, it first uses a random UDP client source port between 32678-61000. If this port fails, Azure Sphere then attempts to use port 124 as the UDP client source port.

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 Function.

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. These will be considered as a primary server and secondary server.

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. The maximum length for each time server fully qualified domain name (FQDN) is 255 characters.

Fallback

If the NTP client is configured to obtain the time servers via DHCP or API, an additional parameter is required to specify fallback behavior.
The client will attempt to contact the primary time server first. If the client fails to obtain a valid time server response, it will try the secondary time server (if specified).
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.
- On the next 24-hour time sync interval the OS will go back and attempt to query the primary time server.
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.

Multihomed devices

The time server settings are a global setting, not a per interface setting. 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.

System time sample

The System Time sample shows how to manage the system time and use the hardware RTC. The sample application sets the system time and then uses the clock_systohc function to synchronize the system time with the RTC.

Custom NTP sample

The Custom NTP sample shows how to configure the NTP client service to obtain time from multiple sources.