Wiring & Test

Being that the DS3231 is an I2C real time clock, it works with any and all Feathers using the SDA/SCL lines and can share those pins with other I2C devices that do not have the same I2C device

The DS3231 has a default I2C address of 0x68 and cannot be changed

Download RTCLib

For the RTC library, we'll be using a fork of JeeLab's excellent RTC library RTClib - a library for getting and setting time from an RTC (originally written by JeeLab, our version is slightly different so please only use ours to make sure its compatible!)

To begin reading data, you will need to download Adafruit's RTCLib from our github repository. You can do that by visiting the github repo and manually downloading or, easier, just click this button to download the zip

Rename the uncompressed folder RTCLib and check that the RTCLib folder contains RTCLib.cpp and RTCLib.h

Place the RTCLib library folder your arduinosketchfolder/libraries/ folder.
You may need to create the libraries subfolder if its your first library. Restart the IDE.

We also have a great tutorial on Arduino library installation at:
http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use

First RTC Test

The first thing we'll demonstrate is a test sketch that will read the time from the RTC once a second. We'll also show what happens if you remove the battery and replace it since that causes the RTC to halt.

So to start, remove the battery from the holder while the Feather is not powered from a lipoly battery or plugged into USB.

Wait 3 seconds and then replace the battery. This resets the RTC chip.

Load Demo

Open up File->Examples->RTClib->ds3231 and upload to your Feather wired up to the RTC

Upload to your Feather and check the serial console @ 9600 baud. After a few seconds, you'll see the report that the Feather noticed this is the first time the DS3231 has been powered up, and will set the time based on the Arduino sketch.

Unplug your Arduino plus RTC for a few seconds (or minutes, or hours, or weeks) and plug back in.

Next time you run it you won't get the same "RTC lost power" message, instead it will come immediately and let you know the correct time!

From now on, you wont have to ever set the time again: the battery will last 5 or more years.

Reading the Time

Now that the RTC is merrily ticking away, we'll want to query it for the time. Lets look at the sketch again to see how this is done.

Download: file
void loop () {
    DateTime now = rtc.now();
    
    Serial.print(now.year(), DEC);
    Serial.print('/');
    Serial.print(now.month(), DEC);
    Serial.print('/');
    Serial.print(now.day(), DEC);
    Serial.print(" (");
    Serial.print(daysOfTheWeek[now.dayOfTheWeek()]);
    Serial.print(") ");
    Serial.print(now.hour(), DEC);
    Serial.print(':');
    Serial.print(now.minute(), DEC);
    Serial.print(':');
    Serial.print(now.second(), DEC);
    Serial.println();

There's pretty much only one way to get the time using the RTClib, which is to call now(), a function that returns a DateTime object that describes the year, month, day, hour, minute and second when you called now().

There are some RTC libraries that instead have you call something like RTC.year() and RTC.hour() to get the current year and hour. However, there's one problem where if you happen to ask for the minute right at 3:14:59 just before the next minute rolls over, and then the second right after the minute rolls over (so at 3:15:00) you'll see the time as 3:14:00 which is a minute off. If you did it the other way around you could get 3:15:59 - so one minute off in the other direction.

Because this is not an especially unlikely occurrence - particularly if you're querying the time pretty often - we take a 'snapshot' of the time from the RTC all at once and then we can pull it apart into day() or second() as seen above. Its a tiny bit more effort but we think its worth it to avoid mistakes!

We can also get a 'timestamp' out of the DateTime object by calling unixtime which counts the number of seconds (not counting leapseconds) since midnight, January 1st 1970

Download: file
    Serial.print(" since midnight 1/1/1970 = ");
    Serial.print(now.unixtime());
    Serial.print("s = ");
    Serial.print(now.unixtime() / 86400L);
    Serial.println("d");

Since there are 60*60*24 = 86400 seconds in a day, we can easily count days since then as well. This might be useful when you want to keep track of how much time has passed since the last query, making some math a lot easier (like checking if its been 5 minutes later, just see if unixtime() has increased by 300, you dont have to worry about hour changes).

This guide was first published on Mar 20, 2016. It was last updated on Mar 20, 2016. This page (Wiring & Test) was last updated on Jul 17, 2019.