Awesome

DS1302 RTC (Real Time Clock) library for Arduino

This is a 3-wire DS1302 RTC (Real Time Clock) library for Arduino.

Library features

• libc <time.h> compatible
• Read/write date/time struct tm
• Set/get Unix epoch UTC time_t
• Set/get time (hours, minutes, seconds)
• Set/get date and time (hour, min, sec, mday, mon, year, wday)
• Read / write 31 Bytes battery backupped RTC RAM.
• Programmable trickle charge to charge super-caps / lithium batteries.
• Optimized IO interface for Atmel AVR platform.

DS1302 specifications

IMPORTANT NOTES:

• The DS1302 RTC time may deviate >1 minute each day, so this device is not recommended for designs with high precision requirements.
• The high precision DS3231 I2C RTC is recommended for new designs.
• The 3-wire interface is NOT compatible with SPI.

Examples

Arduino IDE | File | Examples | Erriez DS1302 RTC:

• Alarm: Program one or more software alarms
• Benchmark: Benchmark library
• RAM: Read/write RTC RAM.
• SetBuildDateTime: Set build date/time
• SetGetDateTime: Set/get date and time
• SetGetTime: Set/get time
• SetTrickleCharger: Program trickle battery/capacitor charger
• Terminal and Python script to set date time
• Test: Regression test
• WriteRead: Regression test

Documentation

• Online HTML
• Doxygen PDF
• DS1307 datasheet

Usage

Initialization

#include <ErriezDS1302.h>

// Connect DS1302 data pin to Arduino DIGITAL pin
#if defined(ARDUINO_ARCH_AVR)
#define DS1302_CLK_PIN      2
#define DS1302_IO_PIN       3
#define DS1302_CE_PIN       4
#elif defined(ARDUINO_ARCH_ESP8266)
#define DS1302_CLK_PIN      D4
#define DS1302_IO_PIN       D3
#define DS1302_CE_PIN       D2
#elif defined(ARDUINO_ARCH_ESP32)
#define DS1302_CLK_PIN      0
#define DS1302_IO_PIN       4
#define DS1302_CE_PIN       5
#else
#error #error "May work, but not tested on this target"
#endif

// Create RTC object
ErriezDS1302 rtc = ErriezDS1302(DS1302_CLK_PIN, DS1302_IO_PIN, DS1302_CE_PIN);

void setup()
{
    // 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  0=Sunday, 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
}

Write to RTC RAM

// Write Byte to RTC RAM
rtc.writeByteRAM(0x02, 0xA9);

// Write buffer to RTC RAM
uint8_t buf[NUM_DS1302_RAM_REGS] = { 0x00 };
rtc.writeBufferRAM(buf, sizeof(buf));

Read from RTC RAM

// Read byte from RTC RAM
uint8_t dataByte = rtc.readByteRAM(0x02);

// Read buffer from RTC RAM
uint8_t buf[NUM_DS1302_RAM_REGS];
rtc.readBufferRAM(buf, sizeof(buf));

Set Trickle Charger

Please refer to the datasheet how to configure the trickle charger.

// Disable (default)
rtc.writeRegister(DS1302_REG_TC, DS1302_TCS_DISABLE);

// Minimum 2 Diodes, 8kOhm
rtc.writeRegister(DS1302_REG_TC, 0xAB);

// Maximum 1 Diode, 2kOhm
rtc.writeRegister(DS1302_REG_TC, 0xA5);

Set RTC date and time using Python

Flash Terminal example.

Set COM port in examples/Terminal/Terminal.py Python script.

Run Python script:

// Install Pyserial
python3 pip -m pyserial

// Set RTC date and time
python3 Terminal.py

Pin configuration

Note: ESP8266 pin D4 is high during a power cycle / reset / flashing which may corrupt RTC registers. For this reason, pins D2 and D4 are swapped.

API changes v1.0.0 to v2.0.0

The API has been changed to make RTC libraries compatible with libc time.h. This makes it easier to calculate with date/time and port the application to different platforms. See changes below:

| v1.0.0 | v2.0.0 | | -------------------------------* | -----------------------------------------------------------* | | DS1302_DateTime | struct tm | | | clearOscillatorStopFlag() merged into clockEnable() | | isHalted() | bool clockEnable(bool enable) | | halt() | void isRunning() | | setDateTime() | void write(struct tm *dt) | | getDateTime() | bool read(struct tm *dt) | | getEpochTime() | time_t getEpoch() | | | void setEpoch(time_t t) | | writeProtect() | Removed | | isProtected() | Removed | | | void setDateTime(uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t wday) | | | void getDateTime(uint8_t *hour, uint8_t *min, uint8_t *sec, uint8_t *mday, uint8_t *mon, uint16_t *year, uint8_t *wday) | | ErriezDS3231Debug | class removed to reduce flash size |

Library dependencies

• Wire.h
• Terminal.ino requires ErriezSerialTerminal library.

Library installation

Please refer to the Wiki page.

More Arduino Libraries from Erriez

• Erriez Libraries