Source: https://mokxi.com/libraries/rtclib
Updated: 2026-11-02

Libraries / Data and time
Arduino library · Data and time

# RTClib: keep the date and time with a DS3231 or DS1307

RTClib is Adafruit’s library for real-time clock modules, the coin-cell boards that keep counting while the Arduino is off. It covers the DS3231 (accurate to a couple of minutes a year thanks to its temperature-compensated crystal), the cheaper DS1307 that drifts more, and the PCF8523 and PCF8563. All of them sit on I2C at 0x68 or nearby.

Open the example in the editor See the calls

Built in on Mokxi: #include <RTClib.h> and it builds, with nothing to install. Free, and no account needed.

## What RTClib does

Everything comes back as a DateTime: rtc.now() returns one, and it has year(), month(), day(), hour(), minute(), second() and dayOfTheWeek(), plus unixtime() for arithmetic. Add or subtract a TimeSpan to work out "in 90 minutes" or "how long since". The DS3231 also reports its own temperature and has two alarms.

Setting the clock is the step people get wrong. The usual line is rtc.adjust(DateTime(F(__DATE__), F(__TIME__))), which sets it to the moment the sketch was compiled. Run that only when the clock has lost its time (lostPower() on a DS3231, !isrunning() on a DS1307), or every reset will set the clock back to the compile time.

Library Manager name | RTClib

Author | Adafruit

Include | #include <RTClib.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, Real-time clock, DS1307

## Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <RTClib.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "RTClib" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add RTClib to lib_deps in PlatformIO. Mokxi follows the calls of release 2.1.4, so a sketch written here builds there too.

What to know in the simulator: RTC_PCF8523 and RTC_PCF8563 are here with their datasheets’ registers, and Mokxi has no part for either, so their begin() finds nothing.

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.

### RTC_DS3231 rtc;

A DS3231 module. RTC_DS1307 rtc; for a DS1307, and RTC_Millis for a software clock with no chip.

### rtc.begin()

Starts I2C and checks the chip answers. Returns false when it does not, the cue to print "Couldn’t find RTC".

### rtc.lostPower()

On a DS3231, true when the clock stopped at some point (a new module, or a flat coin cell) and needs setting. The DS1307 has isrunning() instead.

### rtc.adjust(DateTime(F(__DATE__), F(__TIME__)))

Sets the clock, here to the time the sketch was compiled. DateTime(2026, 11, 1, 9, 30, 0) sets an exact time.

### DateTime now = rtc.now();

Reads the current date and time from the chip.

### now.dayOfTheWeek()

The day of the week from 0 (Sunday) to 6, for indexing an array of day names.

### now.unixtime()

Seconds since January 1, 1970, for comparing two times or logging.

### DateTime later = now + TimeSpan(0, 1, 30, 0);

Date arithmetic: days, hours, minutes and seconds added to a DateTime.

### rtc.getTemperature()

The DS3231’s own temperature in degrees Celsius, in quarter-degree steps.

## Example: Real-time clock

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3

Open it in the editor, wired and ready to run · Real-time clock: the project page

## Common errors and how to fix them

### Couldn't find RTC

begin() got no answer on I2C. Check SDA and SCL go to the board’s I2C pins (A4 and A5 on an Uno), that the module has power and ground, and run an I2C scanner to see whether 0x68 shows up.

### The time resets to the same moment every time the board restarts

rtc.adjust() runs on every start-up. Wrap it in if (rtc.lostPower()) or if (!rtc.isrunning()) so it only runs when the clock really needs setting.

### The date reads 2165/165/165 or similar nonsense

The library read 0xFF from every register, meaning the chip is not answering properly. Recheck the wiring and pull-ups, and make sure the object type matches the chip (RTC_DS3231 or RTC_DS1307).

### The clock loses its time whenever the power is unplugged

The coin cell is flat, missing or in backward. Fit a fresh CR2032 (or the LIR2032 some modules are designed for) and set the clock once more.

## Projects that use RTClib

Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.

DS3231 real-time clock on I2C A DS3231 clock module on A4 and A5 keeps the date and time; RTClib reads it once a second and prints the date, the time and the day of the week. Clock and memory A DS1307 and a 24LC256 on one I2C bus: the time written to EEPROM once a second, acknowledge polling through every write cycle, and the log read back. Christmas countdown A DS3231 keeps the date and an eight-digit MAX7219 display in the window counts the days, hours, minutes and seconds to Christmas, then flashes 25.12. New Year's countdown A DS3231 and a four-digit display count down to midnight on New Year’s Eve, then a ring of WS2812B LEDs bursts into fireworks and the display shows the new year. Automatic pet feeder A DS3231 clock opens an MG996R food gate at three meal times a day, with a chirp first, the next meal on an I2C LCD and a FEED NOW button. Alarm clock with a timer on a four-digit display A DS1307 keeps the time on a four-digit display driven by a 74HC595 (8, 13, 12).

## Keep going

### Learn

- Arduino DS3231 Clock With a TM1637 Display
- I2C Scanner for Arduino and ESP32, and Fixes

### Parts

- Real-time clock, DS3231
- Real-time clock, DS1307

### More data and time libraries

- QRCode
- Madgwick
- PID
- TimerOne
- MsTimer2
- Low-Power
- DS1307RTC
- DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics)

Every built-in library · Open the editor

## Try RTClib without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor