RTC DS3231 with Ardunio

Most embedded systems require some kind of real time clock for different timing events. Recently a client wanted a chicken coop controller. Central to the implementation is an Adafruit DS3231 Precision RTC Breakout. This board uses Maxim’s DS3231 Integrated Real Time Clock.

The DS3231 is an extremely accurate real-time clock with an integrated temperature compensated crystal oscillator and crystal. This device supports battery backup to maintain timekeeping when main power is interrupted. This device maintains seconds, minutes, hours, day, date, month, and year information that includes leap year corrections. The DS3231 also has two programmable time of day alarms that trigger an interrupt output when the specified time occurs. The DS3231 interface is I²C.

The chicken coop controller included an Ardunio UNO, Adafruit DS3231 precision real-time clock (RTC), Pololu 5V 1A regulator, 2-channel relay module, AC light dimmer (forward phase) module, 12V linear actuator, and a 12V battery. The Ardunio sketch was to:

• At sunrise retract the linear actuator for 3 minutes.
• 1-hour after sunrise turn on lights at 100% brightness
• Leave lights at 100% brightness for 12.5 hours, then gradually dim over a 1-hour period.
• At sunset extent the linear actuator for 3 minutes.

Looking at the requirements, all events except the dimming occur on the minute boundary (sunrise, sunset, actuator time, lights on full time). The DS3231 has two alarms. One alarm works down to the second and the other alarm works down to the minute. The need for an alarm to occur on seconds boundary is driven by the light dimming over a 1-hour period. The light dimming uses the 8-bit PWM control. Using all of the PWM control states (256) over 1-hour period has the PWM value updating every 14 seconds (255 down to 0). Since light dimming needs an alarm to occur every 14 seconds, alarm 1 was selected for light control and alarm 2 for actuator control.

The next alarm time is determined by adding the seconds, minutes, hours, and days to a time. For example if the next alarm is to occur in 3 minutes from now, 3 minutes is added to the current time. An add time function was developed to support this sketch. The time is added to the appropriate parameter and then rollover values are tested and updated. When adjusting months the code continues to loop through rollovers until all adjustments are made.

Function to Add time

// function to add time to input time
void addTime(ts *t, int secs, int mins, int hours, int days) {
  boolean adjustMonths = true;
  
  // add time then adjust for rollovers
  t->sec += secs;
  t->min += mins;
  t->hour += hours;
  t->mday += days; 

  // adjust date/time based on rollovers
  if (t->sec >= 60) {
    t->min += t->sec / 60;
    t->sec %= 60;
  }
  if (t->min >= 60) {
    t->hour += t->min / 60;
    t->min %= 60;
  }
  if(t->hour >= 24) {
    t->mday = t->hour / 24;
    t->hour %= 24;
  }

  // adjust months
  while(adjustMonths) {
    switch(t->mon) {
      case 1:
      case 3:
      case 5:
      case 7:
      case 8:
      case 10:
      case 12:
        if (t->mday > 31) {
          t->mday -= 31;
          t->mon += 1;
          if (t->mon > 12) {
            t->mon = 1;
            t->year += 1;
          }
        }
        else
          adjustMonths = false;
        break;
      case 4:
      case 6:
      case 9:
      case 11:
        if (t->mday > 30) {
          t->mday -= 30;
          t->mon += 1;
        }
        else
          adjustMonths = false;
      case 2:
        if (t->year % 4 == 0) {   // leap year, don't worry about % 400
          if (t->mday > 29) {
            t->mday -= 29;
            t->mon += 1;
          }
          else
            adjustMonths = false;
        }
        else
          if (t->mday > 28) {
            t->mday -= 28;
            t->mon += 1;
          }
          else
            adjustMonths = false;
        break;
    }
  }
}

In setting the alarm the developer must enable all values (seconds, minutes, hours, date) up to the desired match (i.e. if alarm is on a hour value, then seconds, and minutes must also be enabled).

When the time matches the enabled alarm parameters then the DS3231 INT/ pin goes active low. Since the I²C Adruino library uses interrupts to communicate, this sketch polls this DS3231 pin instead of using an interrupt. During the polling each alarm is checked and the proper flag(s) is(are) set.

One final item with the DS3231 is the control register used to enable/disable alarms and set other parameters. This register is not readable. If the alarms or other controls are enabled at different times in the code, then a “shadow” register is needed to maintain the current control register state. For example is you are enabling alarm 2 you don’t know the current state of alarm 1 unless you maintain an internal variable in your code.

Finally the library select to support the DS3231 was ds3231FS by Petre Rodan. This library provided an interface to setting the alarms.