Real-Time Clock (RTC) Calendar Functionality#

RTC Operation as a Calendar#

The Calendar block extends the Real-Time Clock (RTC) into a full date and time engine. Instead of just counting ticks, it tracks human-readable fields such as seconds, minutes, hours, days, months, and years.

Key Features#

Automatic rollover: When a field reaches its maximum (for example, 59 seconds), it increments the next higher field.
Leap year handling: The block internally accounts for February 29 every four years, consistent with the Gregorian calendar rules.
Century rollover: Counting capability extends up to 400 years.
Triggers: Supports millisecond and second periodic triggers, which can be used for lightweight scheduling or system “heartbeats.”
Always-on operation: Because the Calendar sits in the Ultra-Ultra-Low-Power (UULP) domain, it continues running during Deep Sleep and Standby.

For most applications, the Calendar block eliminates the need to keep time manually in firmware. Developers can rely on the Calendar hardware to maintain long-term timekeeping in low current consumption.

Note: Although the Calendar hardware supports up to four centuries of date tracking, this capability is constrained by the UNIX/Epoch 32-bit time format, which represents valid timestamps only between 1970 and 2038.
Therefore, when using Software Development Kit (SDK) Epoch-based conversions, only century values 1 and 2 (corresponding roughly to years 1900–2099) are applicable.

API References and Example Implementations#

The WiSeConnect SDK exposes a set of Calendar APIs in sl_si91x_calendar.h. These functions wrap the register-level details and provide an application-friendly interface.

Core APIs#


API	Description
`sl_si91x_calendar_init()`	Powers up the RTC domain, programs the low-frequency clock period (based on resistor-capacitor (RC) or crystal (XTAL) 32 kHz), and starts the RTC so the calendar block can begin timekeeping.
`sl_si91x_calendar_deinit()`	Powers down the RTC domain and stops the calendar clock.
`sl_si91x_calendar_set_date_time()`	Sets the current date and time.
`sl_si91x_calendar_get_date_time()`	Reads the current date and time.
`sl_si91x_calendar_build_datetime_struct()`	Builds a datetime structure for configuration.
`sl_si91x_calendar_register_sec_trigger_callback()`	Registers a callback for the 1-second periodic trigger.
`sl_si91x_calendar_register_msec_trigger_callback()`	Registers a callback for the millisecond periodic trigger.
`sl_si91x_calendar_convert_unix_time_to_calendar_datetime()`	Converts a UNIX timestamp into a calendar structure.
`sl_si91x_calendar_convert_calendar_datetime_to_unix_time()`	Converts a calendar structure into a UNIX timestamp.

API Documentation#

The complete API documentation can be found at https://docs.silabs.com/wiseconnect/latest/wiseconnect-api-reference-guide-si91x-peripherals/calendar

Reference Example#

The reference example for calendar peripheral usage can be found at https://github.com/SiliconLabs/wiseconnect/tree/master/examples/si91x_soc/peripheral/sl_si91x_calendar

Note: Time in many systems is traditionally represented as a signed 32-bit integer (time_t), which overflows on January 19, 2038. The SiWG917 Calendar conversion APIs instead use an unsigned 32-bit type (uint32_t), extending the valid range to February 7, 2106. The Calendar hardware itself can continue to keep time beyond this date, but applications requiring longer ranges must implement custom 64-bit conversion logic.