Awesome

DS1307 high precision I2C RTC library for Arduino

This is a DS1307 I2C RTC library for Arduino.

DS1307

Library features

libc <time.h> compatible
Read/write date/time struct tm
Set/get Unix epoch UTC time_t
Set/get time (hour, min, sec)
Set/get date and time (hour, min, sec, mday, mon, year, wday)
Control SQW signal (disable / 1Hz / 4096Hz / 8192Hz / 32768Hz)
Full RTC register access

Hardware

Any Arduino hardware with a TWI interface and Wire.h support.

Pins

Pins board - DS1307	VCC	GND	SDA	SCL	SQW
Arduino UNO (ATMega328 boards)	5V	GND	A4	A5	D2 (INT0)
Arduino Mega2560	5V	GND	D20	D21	D2 (INT4)
Arduino Leonardo	5V	GND	D2	D3	D7 (INT6)
Arduino DUE (ATSAM3X8E)	3V3	GND	20	21	2
ESP8266	3V3	GND	GPIO4 (D2)	GPIO5 (D1)	GPIO0 (D3)
ESP32	3V3	GND	GPIO21	GPIO22	GPIO0

Note: Tested ESP8266 / ESP32 boards:

ESP8266 boards: ESP12F / WeMos D1 & R2 / Node MCU v2 / v3
ESP32 boards: WeMos LOLIN32 / LOLIN D32

Other unlisted MCU's may work, but are not tested.

Examples

Arduino IDE | Examples | Erriez DS1307 RTC:

Alarm Software alarm
Bare Bare example without a library
DumpRegisters Dump registers for debugging
SetBuildDateTime Set build date/time
SetGetDateTime Set/get date and time
SetGetTime Set/get time
SQWInterrupt 1Hz SQW interrupt pin
Terminal Serial terminal example
Test Regression test
WriteRead Write/read struct tm

Documentation

Usage

Initialization

#include <Wire.h>
#include <ErriezDS1307.h>

// Create RTC object
ErriezDS1307 rtc;

void setup()
{
    // Initialize TWI with a 100kHz (default)
    Wire.begin();
    Wire.setClock(100000);
    
    // Initialize RTC
    while (!rtc.begin()) {
        Serial.println(F("RTC not found"));
        delay(3000);
    }
}

Check oscillator status at startup

// Check oscillator status
if (!rtc.isRunning()) {
    // Error: RTC oscillator stopped. Date/time cannot be trusted. 
    // Set new date/time before reading date/time.

    // Enable oscillator
    rtc.clockEnable(true);
}

Set time

// Write time to RTC
if (!rtc.setTime(12, 0, 0)) {
    // Error: Set time failed
}

Get time

uint8_t hour;
uint8_t minute;
uint8_t second;

// Read time from RTC
if (!rtc.getTime(&hour, &minute, &second)) {
    // Error: RTC read failed
}

Set date and time

// Write RTC date/time: 13:45:09  31 December 2019  2=Tuesday
if (!rtc.setDateTime(13, 45, 9,  31, 12, 2019,  2) {
    // Error: RTC write failed
}

Get date and time

uint8_t hour;
uint8_t min;
uint8_t sec;
uint8_t mday;
uint8_t mon;
uint16_t year;
uint8_t wday;

// Read RTC date/time
if (!rtc.getDateTime(&hour, &min, &sec, &mday, &mon, &year, &wday) {
    // Error: RTC read failed
}

// hour: 0..23
// min: 0..59
// sec: 0..59
// mday: 1..31
// mon: 1..12
// year: 2000..2099
// wday: 0..6 (0=Sunday .. 6=Saturday)

Write date/time struct tm

struct tm dt;

dt.tm_hour = 12;
dt.tm_min = 34;
dt.tm_sec = 56;
dt.tm_mday = 29;
dt.tm_mon = 1; // 0=January
dt.tm_year = 2020-1900;
dt.tm_wday = 6; // 0=Sunday

if (!rtc.write(&dt)) {
    // Error: RTC Read failed
}

Read date/time struct tm

struct tm dt;

// Read RTC date/time
if (!rtc.read(&dt)) {
    // Error: RTC read failed
}

Read Unix Epoch UTC

time_t t;

// Read Unix epoch UTC from RTC
if (!rtc.getEpoch(&t)) {
    // Error: RTC read failed
}

Write Unix Epoch UTC

// Write Unix epoch UTC to RTC
if (!rtc.setEpoch(1599416430UL)) {
    // Error: Set epoch failed
}

Square Wave Out (SQW)

rtc.setSquareWave(SquareWaveDisable);	// Disable
rtc.setSquareWave(SquareWave1024Hz);	// 1024Hz
rtc.setSquareWave(SquareWave4096Hz);	// 4096Hz
rtc.setSquareWave(SquareWave8192Hz);	// 8192Hz
rtc.setSquareWave(SquareWave32768Hz);	// 32768Hz

Library dependencies

Wire.h
Terminal.ino requires ErriezSerialTerminal library.

Library installation

Please refer to the Wiki page.

More Arduino Libraries from Erriez

Erriez Libraries