DS1307 real-time clock

The clock chip that every Arduino book used before the DS3231 got cheap, on a small breakout with a coin cell. Aliases: Tiny RTC, RTC module, DS1307 clock.

It keeps the date and the time of day while the board is off, running from its coin cell, off a 32.768 kHz watch crystal. There is no temperature compensation, so a real one drifts with the room by minutes a month; a DS3231 drifts about that much in a year.

Pins

Pin	What it does
GND	Ground.
VCC	Supply, 4.5 to 5.5 V.
SDA	I2C data. The module carries the pull-ups.
SCL	I2C clock.
SQW	Square wave or a plain output, open drain: it needs a pull-up.

The address is 0x68, fixed.

Properties

start is the date and time it holds when the circuit starts, written YYYY-MM-DD HH:MM:SS. halted makes it a brand new chip instead: stopped, at 2000-01-01 00:00:00, until a sketch starts it. The S button on the face sets it to your computer's clock and starts it.

Registers

The time is seven registers from 0x00, in binary coded decimal: twenty-five seconds is 0x25, not 25. These are the same registers, in the same order and with the same 12-hour bit, as the DS3231, so code for one reads the other's time.

Register	Holds
0x00	seconds, and bit 7 is CH, clock halt
0x01 to 0x06	minutes, hours, day of week, date, month, year
0x07	control: OUT in bit 7, SQWE in bit 4, the rate in bits 1 and 0
0x08 to 0x3F	56 bytes of RAM, kept by the coin cell

Clock halt

A new DS1307 comes up with CH set and the clock stopped, and it stays at 2000-01-01 until something writes the seconds register with bit 7 clear. That is what RTClib's isrunning() reads, and why every DS1307 sketch starts like this:

#include "RTClib.h"

RTC_DS1307 rtc;

void setup() {
  Serial.begin(9600);
  if (!rtc.begin()) { Serial.println("No RTC"); while (1); }
  if (!rtc.isrunning()) {
    rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));
  }
}

void loop() {
  DateTime now = rtc.now();
  Serial.print(now.hour()); Serial.print(':');
  Serial.print(now.minute()); Serial.print(':');
  Serial.println(now.second());
  delay(1000);
}

__DATE__ and __TIME__ are the moment the sketch was compiled, so the clock is set to when you pressed Run. rtc.readnvram() and rtc.writenvram() reach the 56 bytes of RAM, and rtc.writeSqwPinMode() sets the SQW pin.

What the model gets right

It is a 5 V chip. Below 4.5 V it switches to its cell and cuts itself off the bus, so on a 3.3 V board (a Pico, an ESP32, a Blue Pill) it keeps time and never answers its address. That is the most common DS1307 question there is, and the part does exactly that.

Writing the seconds register restarts the chip's one-second divider, so a clock set by adjust() ticks a whole second later. The calendar is real: the right number of days in each month and February 29 in every leap year to 2099. SQW gives a 1 Hz, 4.096 kHz or 8.192 kHz square wave, or the level of the OUT bit.

What it does not model

The 32.768 kHz square wave, which would cost 65,536 edges a simulated second; with that rate selected the pin is let go. The crystal's drift: this clock is exact. The coin cell's voltage and life, and the RAM's undefined contents on a new chip, which read as zeros here. The module's other chip: many DS1307 boards also carry an AT24C32 EEPROM at 0x50, and this one does not.

Common mistakes

Running it at 3.3 V and wondering why nothing answers. Forgetting to start it, so it reads 2000-01-01 00:00:00 for ever. Printing the registers without converting from BCD. The DS3231 in the I2C modules article has the same registers and the BCD story in full.