Manage system time and the RTC on Azure Sphere

BETA feature

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 enable beta APIs, include the appropriate header files, and add RTC settings to the application manifest.

Enable beta APIs

Complete the steps in beta API features to enable your app to use beta APIs for Azure Sphere.

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. 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": [],
    "Gpio": [],
    "Uart": [],
    "WifiConfig": false,
    "NetworkConfig": false,
    "SystemTime": 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 function clock_systohc. 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 OTA 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 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 when DST should come into effect.
  • You can't set the offset in minutes or seconds, only in hours.
  • You can't specify a timezone file/database.

To maintain the timezone settings during a power loss, you can use mutable storage to store the timezone in persistent storage and then recall the setting when the device reboots.

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.