The DS3231 library: hours, minutes and alarms from the clock chip
Two different Arduino libraries are both called DS3231 and both use the file name DS3231.h, which is the cause of most confusion around this chip. NorthernWidget’s DS3231 (the one in the Library Manager) has calls like getHour(h12, pm), getMinute(), setSecond() and RTClib::now(). Rinky-Dink Electronics’ DS3231 is a zip download with getTimeStr(), getDateStr() and setTime(h, m, s). A tutorial written for one fails to compile with the other.
Built in on Mokxi: #include <DS3231.h> and it builds, with nothing to install. Free, and no account needed.
What DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics) does
Both talk to the same chip at I2C address 0x68: the Maxim DS3231, a clock with a temperature-compensated crystal that drifts only a minute or two a year and keeps going on its coin cell. Its time is stored as BCD in registers 0x00 to 0x06, its two alarms after that, and its temperature in quarter degrees at 0x11.
The NorthernWidget calls pass bool variables by reference: getHour(h12, pm) fills h12 with whether the chip is in 12-hour mode and pm with the half of the day. Set setClockMode(false) once for a 24-hour clock.
| Library Manager name | DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics) |
|---|---|
| Author | NorthernWidget, Rinky-Dink Electronics |
| Include | #include <DS3231.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Real-time clock, DS3231 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <DS3231.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics)" by NorthernWidget, Rinky-Dink Electronics from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics) to lib_deps in PlatformIO. Mokxi follows the calls of release 1.2.0, so a sketch written here builds there too.
What to know in the simulator: Both libraries use this file name, so one class carries both sets of calls. The Rinky-Dink library is CC BY-NC-SA 3.0 upstream.
ESP32-C3 · Arduino Uno · Arduino Nano · Arduino Mega 2560 · Arduino Leonardo · SparkFun Pro Micro · Arduino Micro · ESP32-C6 · Raspberry Pi Pico · Raspberry Pi Pico W · Seeed XIAO SAMD21 · STM32 · STM32 Nucleo-F411RE · STM32 Blue Pill · micro:bit V2 · Arduino Uno R4 · ESP32 DevKit · ESP32-S3-DevKitC-1 · ESP8266 NodeMCU · Arduino Pro Mini 3.3 V · Seeed XIAO ESP32-C3 · ESP32-C3 SuperMini · Seeed XIAO ESP32-C6 · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display · Seeed XIAO ESP32-S3 · Arduino Nano ESP32 · Arduino Nano RP2040 Connect · Seeed XIAO RP2040 · Waveshare RP2040-Zero · Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
DS3231 myRTC;
The NorthernWidget object. Call Wire.begin() in setup() yourself before using it.
myRTC.getHour(h12, pm)
The hour, filling the two bool variables with the 12/24-hour mode and AM/PM.
myRTC.getMinute()
The minute; getSecond(), getDate(), getMonth(century) and getYear() read the rest.
myRTC.setClockMode(false)
Picks 24-hour mode. Then set each field: setYear(), setMonth(), setDate(), setDoW(), setHour(), setMinute() and setSecond().
myRTC.setClockMode(false);
myRTC.setHour(14);
myRTC.setMinute(30);
myRTC.setSecond(0);myRTC.getTemperature()
The chip’s own temperature in degrees Celsius.
DateTime now = RTClib::now();
NorthernWidget’s RTClib-style read, giving a DateTime with year(), month(), hour() and so on.
DS3231 rtc(SDA, SCL);
The Rinky-Dink object, which takes the I2C pins. Then rtc.begin() in setup().
rtc.getTimeStr()
Rinky-Dink: the time as "hh:mm:ss" text. getDateStr() and getDOWStr() give the date and weekday.
rtc.setTime(12, 0, 0)
Rinky-Dink: sets hours, minutes and seconds; setDate(day, month, year) sets the date.
Example: Set and read a DS3231 the NorthernWidget way
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <Wire.h>
#include <DS3231.h>
DS3231 myRTC;
bool h12, pm, century;
void setup() {
Serial.begin(9600);
Wire.begin();
myRTC.setClockMode(false); // 24-hour
myRTC.setYear(26);
myRTC.setMonth(9);
myRTC.setDate(17);
myRTC.setDoW(4);
myRTC.setHour(13);
myRTC.setMinute(45);
myRTC.setSecond(0);
}
void loop() {
Serial.print("20");
Serial.print(myRTC.getYear());
Serial.print('/');
Serial.print(myRTC.getMonth(century));
Serial.print('/');
Serial.print(myRTC.getDate());
Serial.print(' ');
Serial.print(myRTC.getHour(h12, pm));
Serial.print(':');
Serial.print(myRTC.getMinute());
Serial.print(" day ");
Serial.println(myRTC.getDoW());
DateTime now = RTClib::now();
Serial.print("unix ");
Serial.println(now.unixtime());
Serial.print("Temperature: ");
Serial.print(myRTC.getTemperature());
Serial.println(" C");
delay(1000);
}Wiring
- Arduino Uno R3 A4 to Real-time clock, DS3231 SDA
- Arduino Uno R3 A5 to Real-time clock, DS3231 SCL
- Arduino Uno R3 5V to Real-time clock, DS3231 VCC
- Arduino Uno R3 GND to Real-time clock, DS3231 GND
Common errors and how to fix them
'class DS3231' has no member named 'getTimeStr'
The sketch was written for Rinky-Dink’s DS3231 library but NorthernWidget’s is installed (or the reverse). Install the library the tutorial used, or rewrite the calls for the one you have.
The hour reads 0 to 12 with an odd jump, or the PM flag is always set
The chip is in 12-hour mode. Call setClockMode(false) and set the hour again to switch it to 24-hour time, then read getHour(h12, pm) as before.
Every reading is 165 or 0
Nothing is answering at 0x68, so the reads return all ones or zeros. Check the I2C wiring and power, and call Wire.begin() before the first read with the NorthernWidget library.
Try DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics) without installing anything
Open the example, change the sketch, and keep your version in a free account.