DS3231 RTC clock with Arduino and ESP32

Why you need an external clock

Boards count the milliseconds since you switched them on (millis()) and that's all: a data logger, an irrigation timer or a clock with a display needs to know the real date and time. The ESP32 can get them from the internet, but only if Wi-Fi is available. The DS3231 keeps them in a chip with its own battery: seconds, minutes, hours, day, month and year, with leap years already taken care of (the datasheet guarantees it up to 2100).

How accurate it is

Cheap clocks use an external crystal whose speed changes with temperature. The DS3231 has the crystal and temperature compensation in the same package: it measures the temperature every 64 seconds and corrects itself. 2 ppm means 2 seconds per million: do the math and it comes to about 5 seconds a month and a little over a minute a year. Over the whole range from −40 to +85 °C, the datasheet gives ±2 minutes a year. On top of that comes crystal aging, ±1 ppm in the first year.

What the Adafruit 3013 module looks like

The pins

DS3231 figures (datasheet)

How to wire it

Example 1: clock with the chip temperature

// RTC DS3231: on first power-up (or if the battery has run flat) it sets the computer's time,
// then every second it prints the date, the time and the chip temperature.
// Same sketch for Arduino UNO (SDA = A4, SCL = A5) and ESP32 (SDA = GPIO 21, SCL = GPIO 22).
// Library: Adafruit RTClib.
#include <RTClib.h>

RTC_DS3231 rtc;

void setup() {
  Serial.begin(115200);
  if (!rtc.begin()) {
    Serial.println("DS3231 not found: check VCC, GND, SDA and SCL");
    while (true) delay(1000);
  }
  if (rtc.lostPower()) {
    // the clock has stopped: set it to the time the sketch was compiled
    rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));
    Serial.println("Time set from the computer");
  }
}

void loop() {
  DateTime t = rtc.now();
  char line[24];
  snprintf(line, sizeof(line), "%02d/%02d/%04d %02d:%02d:%02d",
           t.day(), t.month(), t.year(), t.hour(), t.minute(), t.second());
  Serial.print(line);
  Serial.print("   chip temperature: ");
  Serial.print(rtc.getTemperature(), 2);
  Serial.println(" C");
  delay(1000);
}

The first time, the clock takes the time when you compiled the sketch (so it lags by the few seconds it takes to upload it). After that it doesn't touch it again: lostPower() is true only if the oscillator has stopped, for example at first power-up or with a flat or missing battery.

Example 2: alarm once a minute

// RTC DS3231 as an alarm clock: alarm 1 fires every minute (when the seconds go back to 0)
// and pulls the SQW/INT pin low; the pin is connected to an interrupt input on the board.
// Same sketch for Arduino UNO and ESP32. Library: Adafruit RTClib.
#include <RTClib.h>

#ifdef ARDUINO_ARCH_ESP32
const int PIN_SQW = 27;        // ESP32: any GPIO that accepts interrupts
#else
const int PIN_SQW = 2;         // UNO: external interrupt INT0
#endif

RTC_DS3231 rtc;
volatile bool wakeUp = false;

#ifdef ARDUINO_ARCH_ESP32
void IRAM_ATTR onAlarm() { wakeUp = true; }
#else
void onAlarm() { wakeUp = true; }
#endif

void setup() {
  Serial.begin(115200);
  if (!rtc.begin()) {
    Serial.println("DS3231 not found");
    while (true) delay(1000);
  }
  if (rtc.lostPower()) rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));

  pinMode(PIN_SQW, INPUT_PULLUP);              // SQW/INT is open-drain: it needs the pull-up
  attachInterrupt(digitalPinToInterrupt(PIN_SQW), onAlarm, FALLING);

  rtc.writeSqwPinMode(DS3231_OFF);             // SQW/INT used as the alarm output
  rtc.disableAlarm(2);
  rtc.clearAlarm(1);
  rtc.clearAlarm(2);
  // fires when the seconds are 0, that is once a minute
  rtc.setAlarm1(DateTime(0, 0, 0, 0, 0, 0), DS3231_A1_Second);
  Serial.println("Alarm set: one message at the start of every minute");
}

void loop() {
  if (wakeUp) {
    wakeUp = false;
    rtc.clearAlarm(1);                          // releases SQW/INT, ready for the next minute
    DateTime now = rtc.now();
    Serial.print("Wake up! It's ");
    Serial.print(now.hour());
    Serial.print(':');
    if (now.minute() < 10) Serial.print('0');
    Serial.println(now.minute());
  }
}

SQW is open-drain: it pulls the pin low when the alarm fires and then lets it go. That is why you need a pull-up (here the board's internal one, INPUT_PULLUP) and you have to call clearAlarm(1), otherwise the pin stays low. With DS3231_A1_Hour or DS3231_A1_Date the alarm becomes daily or monthly.

The battery

The Adafruit 3013 takes a 3 V lithium CR1220; Adafruit estimates it lasts five years or more. CR2032 and CR1220 cells are not rechargeable: Energizer gives a maximum reverse current of 1 µA, and Panasonic asks for a diode and a series resistor if there is any risk of something charging them. Some cheap modules with a CR2032 holder have a circuit on the board that charges it from Vin: before fitting a CR2032 to a module you don't know, check the seller's schematic. The rechargeable versions (LIR2032) are a different thing: 3.7 V and charged at 4.2 V.

Common mistakes