From openPicus Wiki
Jump to: navigation, search



The Real Time Clock Calendar (RTCC) is a PIC24F module that permits to keep track of the time with the secondary oscillator. This feature permits handling timed alarm interrupts without any polling by the user task. The RTCC can be seen as an advanced alarm clock since it's alarm can executed not only every day (like any other standard alarm clock) but with different alarm time configurations.

The openPicus framework embedds RTCC helper APIs to permit users to use the RTCC without dealing with PIC internal registers. To use this library it is necessary to enable the flag of "RTCC library" using Wizard Tool of IDE.

RTCC library wizard.png

RTCC Structure

Structure struct tm contains calendar date and time broken down into its components.
The structure contains nine members of type int (in any order), which are:

Member Type Meaning Range
tm_sec int seconds after the minute 0 - 61*
tm_min int minutes after the hour 0 - 59
tm_hour int hours since the midnight 0 - 23
tm_mday int day of the month 1 - 31
tm_mon int months since January 0 - 11
tm_year int years since 1900
tm_wday int days since Sunday 0 - 6
tm_yday int days since January 1 0 - 365
tm_isdst int daylight saving time flag values**

* tm_sec is generally 0-59. The extra range is to accommodate for leap seconds in certain systems.
** The Daylight Saving Time flag (tm_isdst) is greater than zero if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and less than zero if the information is not available.

For example, to assign the values corresponding to the date “April 6, 2013 (Saturday), hour 20:01.02” to a defined structure, the following sequence of commands may be used:

struct tm mytime;
//initialization of mytime
   mytime.tm_hour = 20;
   mytime.tm_min = 1;
   mytime.tm_sec = 2;
   mytime.tm_mday = 6;
   mytime.tm_mon = 3;
   mytime.tm_year = 113;
   mytime.tm_wday = SATURDAY;


Once the user's structure is set up, the information exchange between this structure and the RTCC module register can take place using the following functions:

Name Function Description
 void RTCCGet(struct tm *  rtcc) Reads the actual date/time from the RTCC and puts it inside a struct pointer.

rtcc A pointer to the struct tm variable to write.

 void RTCCSet(struct tm *  rtcc) Sets the date/time for the RTCC and enables the RTCC module.

rtcc A pointer to a struct tm variable, containing the date and the time to set

 void RTCCAlarmConf(struct tm *  rtcc, int  repeats, BYTE  whenToRaise, void(*)()fptr) Function to configure the alarm. It is possible to set the interval for the alarm and if it must be repeated continously.

rtcc A struct tm containing the alarms date/time.
repeats Specifies how many time the alarm must be repeated:

  • REPEAT_NO the alarm must not be repeated.
  • an int comprised between 1-254 - the number of times the alarm must be repeated.
  • REPEAT_INFINITE - the alarm must be repeated forever.

whenToRaise How often the alarm must be raised:

  • EVERY_HALF_SEC the alarm is raised every half second
  • EVERY_SEC the alarm is raised every second
  • EVERY_TEN_SEC the alarm is raised every 10 seconds
  • EVERY_MIN the alarm is raised every minute
  • EVERY_TEN_MIN the alarm is raised every 10 minutes
  • EVERY_HOUR the alarm is raised every hour
  • EVERY_DAY the alarm is raised every day
  • EVERY_WEEK the alarm is raised every week
  • EVERY_MONTH the alarm is raised every month
  • EVERY_YEAR the alarm is raised every year </BR>

fptr Custom user function to execute when alarm event is raised. please use NO_ALRM_EVENT to ignore.

 void RTCCAlarmSet(BYTE run) Activates or deactivates the alarm.


  • OFF Deactivates alarm
  • ON Activates alarm
 BOOL RTCCAlarmStat() Activates or deactivates the alarm.

the status of the alarm event:

  • FALSE no alarm event.
  • TRUE alarm event was triggered. The function is automatically set to FALSE until next alarm event.

RTCC Alarm Notes

The meaning of the flag "EVERY_X" on the function RTCCAlarmConf(...) is that the alarm is raised every time the RTCC clock is the same of your alarm, but ignoring the higher part you don't want.
For example EVERY_HOUR means that every time your minutes are the same of the alarm clock previously set, you will have an alarm:

  • You set alarm at 8:30 and a flag "EVERY_HOUR" then the alarm will raise every hour:
    • 00:30, 01:30, 02:30, and so on....
  • But if you set the flag "EVERY_DAY" instead, your alarm will be raised only at 8:30 of each day


Examples are available on tutorial section

Personal tools