DS1307 - Real Time Clock

1. Overview

DS1307 is a commonly used digital real time clock (time keeper). The device keeps track of time (second, minute, hour, month, date and year) with battery backed and I2C interface. This library provides easy to use functions to access DS1307 with TWI interface of Ansteron Board.

The library can work in two modes, binary-coded decimal (default) and decimal. Date and time stored inside DS1307 are in binary-coded decimal (BCD) format and they can be used directly or the library will convert every output into decimal format if decimal mode is selected.

In BCD format, each time value is coded with the 4 high bits as tens decimal place and 4 lower bits are ones decimal place. For example, reading second returns value 0x12 (hex). In BCD mode that is the 12th second, 0x39 is the 39th second.

In Decimal mode, the value will be converted to integer value. For example, 0x12(hex) of the example above will be converted to 0x0C (hex) which equal 12 (decimal).

2. Circuit

The example below is minimal circuit for one DS1307 to work. A small watch crystal 32.768 KHz attached to pin 1 and 2 is needed for timing and the accuracy of time depends on it. One backup battery is connected to pin 3 to provide power, keep the clock running while the main power supply is absence. The two 10K pull-up resistors are optional if the SDA and SCL line are not too long from Ansteron Board. Internal pull-up resistors of Ansteron Board should be enough to keep the lines high.

3. Programming

This library use TWI functions from Standard Library, make sure it is not excluded from the program. Besides, to add DS1307 library into the program, go to menu Build, choose Compiler settings then add the file into Additional libraries section.

Before date and time can be read from DS1307, function DS1307_setup(mode); must be called. The function will initialize TWI interface and set the mode for data, BCD or Decimal. If 0 or DEFAULT is entered, BCD mode will be used. If any value different than that is entered, Decimal mode will be selected. The setting for TWI is also default setting, master mode, 100 KHz bitrate.

The example below will read current time and print onto Serial Interface. Note that each one of time values is printed as hex but users will read as decimal. For new DS1307 chip or after being detached from both power supply and backup battery, the time will not tick until time is updated with valid value or function DS1307_clear_clock_halt(); is called.

Output of the program in Serial Terminal:

4. Functions


Initialize TWI interface for communication with DS1307. TWI interface will be set at default setting, master mode, 100 KHz bitrate and pull-up resistors are also enabled. If input "mode" is zero or DEFAULT, all data will be in BCD format, otherwise data will be Decimal format. TWI settings can be changed if needed. If TWI interface was previously enabled, other functions will work without calling this.




Read second, minute and hours from DS1307. Each data returned will be one byte in BCD format by default. For hour reading, the output value will be in 24 hour mode only. To use 12 hour mode, check if hour is less than or equal 12 that will be AM. If hour is more than 12 then that will be PM and subtract 12 out of hour to get the right value.





Read date, month, year and day of week from DS1307. Each data returned will be one byte in BCD format by default. The value for year will range from 0x00 to 0x99 corresponding to the year 2000 to 2099. Value for day of week will range from 1 to 7 (0x01 to 0x07) for which 1 will be Sunday, 2 will be Monday and so on.

DS1307_set_time(hour, minute, second);

Update the current time of DS1307 with given hour, minute and second. Depend on what format is being used, given hour, minute and second must be in that format. Incorrect values may cause undefined behavior for DS1307.

DS1307_set_date(month, day, year);

Update current date for DS1307 with given values. The format of input values must be the same format is being used. The year value has range from 0 to 99 corresponding to the year 2000 to 2099.


Set day of the week. Value must be between 1 and 7. Value 1 indicates Sunday; value 2 will be Monday and so on.



DS1307 has 56 byte battery backed memory can be used for general purpose. These memory bytes are SRAM and user can read or write them unlimited number of times. Data will be there as long as power is being supplied or backup battery is connected.

Address value range from 0 to 55. These functions read or write one byte at a time.


When DS1307 first start-up from no power (neither supply power or battery), its clock source from crystal oscillator will be disabled by default. Using this function to enable the oscillator and the timer will start ticking. The clock will remain running as long as backup battery is connected.

5. Set time example

Setting the time is only needed for the new chip or once in a while if the time runs off too much. It is a fair amount of work to create a user interface to update the time. However, program can update the time in DS1307 in only two lines of code.

For experimental projects, time can be written to DS1307 at programing time just once. As long as backup battery is connected, the timer will keep running and no frequent time update is needed. The example below can be executed once to write the current time into DS1307. To do this, set the date and time value about 1 minute ahead. Compile and download the program then hold Reset button down. Wait for the time to come (refer a clock or computer) then release Reset button. New date and time will be written to DS1307.