Source: https://mokxi.com/libraries/ds3231-rtc
Updated: 2026-11-17

Libraries / Data and time

Arduino library · Data and time

# DS3231-RTC: set and read a DS3231 clock with Unix times

Yes. You can use the DS3231-RTC library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Real-time clock, DS3231). The example below, "Set a DS3231 from a Unix time and read a DateTime back", runs on the Arduino Uno R3.

Run the example in Mokxi See the calls

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

## What DS3231-RTC does

The DS3231 is a battery-backed real-time clock that keeps good time when the Arduino is off, and it has a temperature sensor that corrects its own crystal. The DS3231-RTC library by Frank Häfele talks to it over I2C, so on an Uno it needs only power, ground, SDA on A4 and SCL on A5.

The library puts everything in a namespace called DS3231. You make two objects, DS3231::RTClib for reading the time and DS3231::DS3231 for setting it and for the alarms and temperature. Reading gives you a DateTime with the year, month, day, hour, minute and second, plus a Unix time.

The simplest way to set the clock is one call, setEpoch(), which takes a Unix time in seconds since 1970 and is read as UTC. Unix times behave the same on every board here, the 8-bit AVR boards included, so a sketch that sets the clock from a timestamp works the same on all of them.

Library Manager name | DS3231-RTC

Author | Frank Häfele (hasenradball)

Include | #include <DS3231-RTC.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-RTC.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "DS3231-RTC" by Frank Häfele (hasenradball) from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add DS3231-RTC to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.0, so a sketch written here builds there too.

What to know in the simulator: time_t counts from 1970 on every board here, AVR included, so setEpoch() and getUnixTime() use Unix times everywhere. The 32 kHz pin is not driven.

- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- 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::RTClib myRTC

The reader. Its now() call fetches the current time from the chip.

### DS3231::DS3231 Clock

The clock itself, for setting the time, reading the temperature and using the alarms.

### Clock.begin()

Starts the I2C connection to the chip. Call Wire.begin() first.

### Clock.setEpoch(timestamp)

Sets every field of the clock from a Unix time, read as UTC unless you pass true as a second argument.

### DS3231::DateTime now = myRTC.now()

Reads the time once into a DateTime, so every field in it belongs to the same moment.

### now.getHour()

One field of the DateTime. getYear(), getMonth(), getDay(), getMinute() and getSecond() work the same way.

### now.getUnixTime()

The time as seconds since 1 January 1970, which is easy to subtract or compare.

### now.strf_DateTime(buffer, sizeof(buffer))

Writes the date and time as text into a char buffer. Pass a format such as "%H:%M:%S" as a third argument to choose the layout.

### Clock.getTemperature()

The chip’s own temperature in degrees Celsius, to a quarter of a degree.

### Clock.oscillatorCheck()

True when the oscillator has not stopped since the clock was last set, so the time can be trusted.

## Example: Set a DS3231 from a Unix time and read a DateTime back

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

sketch.ino · Arduino Uno R3

### 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

Open it in the editor, wired and ready to run

## Common errors and how to fix them

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

The sketch calls setEpoch() on every start, which overwrites what the chip kept. Set the clock once, then remove that line and upload the sketch again. The coin cell keeps the time while the board is off.

### The time is off by whole hours

setEpoch() reads its Unix time as UTC. Add your time zone offset in seconds to the timestamp, or pass true as the second argument to use the board’s local time zone setting.

### The hours or the date are wrong after a power cut

Check oscillatorCheck() at start-up. It reports false when the clock lost power and stopped, which means the coin cell is flat or missing and the time must be set again.

## Keep going

### Parts

- Real-time clock, DS3231

### More data and time libraries

- QRCode
- Madgwick
- PID
- TimerOne
- MsTimer2
- Low-Power
- RTClib
- DS1307RTC
- ResponsiveAnalogRead
- DS3232RTC
- EnviroDIY_DS3231
- uRTCLib
- Ds1302
- Chrono

Every built-in library · Open the editor

## Try DS3231-RTC without installing anything

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

Start building free

Open the editor
