Calendar Drivers

This Calendar driver provides an interface to set and get the current date and time, and also the alarm functionality.

The following driver variants are available:

  • Calendar Bare-bone Driver: The driver supports setting and getting the current date and time, and alarm functionality with callback handler.

  • Calendar RTOS Driver: The driver is intended for using calendar functions in a Real-Time operating system, i.e. is thread safe.

Calendar Basics and Best Practice

The Calendar driver provides functions to set and get the current date and time. After enabling, an instance of the driver starts counting time from the base date with a resolution of one second. The default base date is 00:00:00 1st of January 1970.

The current date and time is kept internally in a relative form as the difference between the current date and the time, and the base date and time. This means that changing the base year changes current date.

The base date and time defines time "zero" or the earliest possible point in time that the calender driver can describe, this means that current time and alarms cannot be set to anything earlier than this time.

The Calendar driver provides an alarm functionality. An alarm is a software trigger, which fires on a given date and time with given periodicity. Upon firing, the given callback function is called.

An alarm can be in single-shot mode, firing only once at matching time; or in repeating mode, meaning that it will reschedule a new alarm automatically based on the repeating mode configuration. In single-shot mode an alarm is removed from the alarm queue before its callback is called. It allows an application to reuse the memory of an expired alarm in the callback.

An alarm can be triggered on the following events: match on second, minute, hour, day, month, or year. Matching on second means that the alarm is triggered when the value of seconds of the current time is equal to the alarm's value of seconds. This means repeating alarm with match on seconds is triggered with the period of a minute. Matching on minute means that the calendar's minute and seconds values have to match the alarms, the rest of the date-time values are ignored. In repeating mode this means a new alarm every hour. The same logic is applied to match on hour, day, month, and year.

Each instance of the Calendar driver supports an infinite amount of software alarms, only limited by the amount of RAM available.

Below are some application examples for how to use this driver:
  • A source of current date and time for an embedded system

  • Periodical functionality in low-power applications since the driver is designed to use 1Hz clock

  • Periodical function calls in case if it is more convenient to operate with absolute time