Page 1 of 5

DS1307 - Arduino library support for the DS1307 I2C Real-Time

Clock
Copyr i ght ( C) 2010 Henni ng Kar l sen. Al l r i ght r eser ved

You can f i nd t he l at est ver si on of t he l i br ar y at ht t p: / / www. henni ngkar l sen. com/ el ect r oni cs

Thi s l i br ar y has been made t o easi l y i nt er f ace and use t he DS1307 RTC wi t h t he Ar dui no wi t hout
needi ng t he Wi r e l i br ar y.

I f you make any modi f i cat i ons or i mpr ovement s t o t he code, I woul d appr eci at e t hat you shar e t he
code wi t h me so t hat I mi ght i ncl ude i t i n t he next r el ease. I can be cont act ed t hr ough
ht t p: / / www. henni ngkar l sen. com/ el ect r oni cs/ cont act . php

Thi s l i br ar y i s f r ee sof t war e; you can r edi st r i but e i t and/ or modi f y i t under t he t er ms of t he
GNU Lesser Gener al Publ i c Li cense as publ i shed by t he Fr ee Sof t war e Foundat i on; ei t her ver si on
2. 1 of t he Li cense, or ( at your opt i on) any l at er ver si on.

Thi s l i br ar y i s di st r i but ed i n t he hope t hat i t wi l l be usef ul , but WI THOUT ANY WARRANTY; wi t hout
even t he i mpl i ed war r ant y of MERCHANTABI LI TY or FI TNESS FOR A PARTI CULAR PURPOSE. See t he GNU
Lesser Gener al Publ i c Li cense f or mor e det ai l s.

You shoul d have r ecei ved a copy of t he GNU Lesser Gener al Publ i c Li cense al ong wi t h t hi s l i br ar y;
i f not , wr i t e t o t he Fr ee Sof t war e Foundat i on, I nc. , 51 Fr ankl i n St , Fi f t h Fl oor , Bost on, MA
02110- 1301 USA




Ver si on: 1. 0 4 Oct 2010 i ni t i al r el ease
1. 1 26 J an 2012 Added suppor t f or Ar dui no
1. 0 I DE

Page 2 of 5
Structures:

Time;
Structure to manipulate time- and date-data.

Variables: hour , mi n, sec: For hol di ng t i me- dat a
dat e, mon, year : For hol di ng dat e- dat a
dow: Day- of - t he- week wi t h monday bei ng t he f i r st day
Usage: Ti me t ; / / Def i ne a st r uct ur e named t of t he Ti me- cl ass

DS1307_RAM;
Buffer for use with readBuffer() and writeBuffer().

Variables: Cel l [ 0- 56] : Byt e- ar r ay t o hol d t he dat a r ead f r omor t o be wr i t t en t o t he on- chi p RAM.
Usage: DS1307_RAM r amBuf f er ; / / Decl ar e a buf f er f or use

Defined Literals:

Weekdays
For use with setDOW() and Time.dow

MONDAY:
TUESDAY:
WEDNESDAY:
THURSDAY:
FRI DAY:
SATURDAY:
SUNDAY:
1
2
3
4
5
6
7

Select length
For use with getTimeStr(), getDateStr(), getDOWStr() and getMonthStr()

FORMAT_SHORT:
FORMAT_LONG:
1
2

Select date format
For use with getDateStr()

FORMAT_LI TTLEENDI AN:
FORMAT_BI GENDI AN:
FORMAT_MI DDLEENDI AN:
1
2
3

Select Square Wave Output rate
For use with setSQWRate()

SQW_RATE_1:
SQW_RATE_4K:
SQW_RATE_8K:
SQW_RATE_32K:
0
1
2
3



Page 3 of 5
Functions:

DS1307(SDA, SCL);
The main class of the interface.

Parameters: SDA: Ar dui no pi n connect ed t o t he SDA- pi n of t he DS1307 ( Pi n 5, Ser i al Dat a)
SCL: Ar dui no pi n connect ed t o t he SCL- pi n of t he DS1307 ( Pi n 6, Ser i al Cl ock)
Usage: DS1307 r t c( 2, 3) ; / / St ar t an i nst ance of t he DS1307 cl ass

getTime();
Get current data from the DS1307.

Parameters: None
Returns: Ti me- st r uct ur e
Usage: t = r t c. get Ti me( ) ; / / Read cur r ent t i me and dat e.

setTime(hour, min, sec);
Set the time.

Parameters: hour : Hour t o st or e i n t he DS1307 ( 0- 23)
mi n: Mi nut e t o st or e i n t he DS1307 ( 0- 59)
sec: Second t o st or e i n t he DS1307 ( 0- 59)
Returns: Not hi ng
Usage: r t c. set Ti me( 23, 59, 59) ; / / Set t he t i me t o 23: 59: 59
Notes: Set t i ng t he t i me wi l l cl ear t he CH ( Cl ock Hal t ) f l ag. See t he dat esheet f or mor e i nf or mat i on on t he CH
f l ag.

setDate(date, mon, year);
Set the date.

Parameters: dat e: Dat e of t he mont h t o st or e i n t he DS1307 ( 1- 31) *1
mon: Mont h t o st or e i n t he DS1307 ( 1- 12)
year : Year t o st or e i n t he DS1307 ( 2000- 2099)
Returns: Not hi ng
Usage: r t c. set Dat e( 4, 10, 2010) ; / / Set t he dat e t o Oct ober 4. , 2010.
Notes: *1: No cheki ng f or i l l egal dat es so Feb 31. i s possi bl e t o i nput . The effect of doing this is unknown.

setDOW(dow);
Set the day-of-the-week.

Parameters: dow: Day of t he week t o st or e i n t he DS1307 ( 1- 7) *1
Returns: Not hi ng
Usage: r t c. set DOW( FRI DAY) ; / / Set t he day- of - t he- week t o be f r i day
Notes: *1: Monday i s 1, and t hr ough t o sunday bei ng 7.

getTimeStr([format]);
Get current time as a string.

Parameters: f or mat : <Optional>
FORMAT_LONG " hh: mm: ss" ( def aul t )
FORMAT_SHORT " hh: mm"
Returns: St r i ng cont ai ni ng t he cur r ent t i me wi t h or wi t hout seconds.
Usage: Ser i al . pr i nt ( r t c. get Ti meSt r ( ) ) ; / / Send t he cur r ent t i me over a ser i al connect i on

getDateStr([slformat[, eformat[, divider]]]);
Get current date as a string.

Parameters: sl f or mat : <Optional> *1
FORMAT_LONG Year wi t h 4 di gi t s ( yyyy) ( def aul t )
FORMAT_SHORT Year wi t h 2 di gi t s ( yy)
ef or mat : <Optional> *2
FORMAT_LI TTLEENDI AN "dd. mm. yyyy" ( def aul t )
FORMAT_BI GENDI AN "yyyy. mm. dd"
FORMAT_MI DDLEENDI AN "mm. dd. yyyy"
di vi der : <Optional>
Si ngl e char act er t o use as di vi der . Def aul t i s ' . '
Returns: St r i ng cont ai ni ng t he cur r ent dat e i n t he speci f i ed f or mat .
Usage: Ser i al . pr i nt ( r t c. get Dat eSt r ( ) ) ; / / Send t he cur r ent dat e over a ser i al connect i on ( i n Li t t l e- Endi an
f or mat )
Notes: *1: Requi r ed i f you need ef or mat or di vi der .
*2: Requi r ed i f you need di vi der . Mor e i nf or mat i on on Wi ki pedi a
( ht t p: / / en. wi ki pedi a. or g/ wi ki / Dat e_f or mat #Dat e_f or mat ) .


Page 4 of 5
getDOWStr([format]);
Get current day-of-the-week as a string.

Parameters: f or mat : <Optional>
FORMAT_LONG Day- of - t he- week i n Engl i sh ( def aul t )
FORMAT_SHORT Abbr evi at ed Day- of - t he- week i n Engl i sh ( 3 l et t er s)
Returns: St r i ng cont ai ni ng t he cur r ent day- of - t he- week i n f ul l or abbr evi at ed f or mat .
Usage: Ser i al . pr i nt ( r t c. get DOWSt r ( FORMAT_SHORT) ) ; / / Send t he cur r ent day i n abbr evi at ed f or mat over a ser i al
connect i on

getMonthStr([format]);
Get current month as a string.

Parameters: f or mat : <Optional>
FORMAT_LONG Mont h i n Engl i sh ( def aul t )
FORMAT_SHORT Abbr evi at ed mont h i n Engl i sh ( 3 l et t er s)
Returns: St r i ng cont ai ni ng t he cur r ent mont h i n f ul l or abbr evi at ed f or mat .
Usage: Ser i al . pr i nt ( r t c. get Mont hSt r ( ) ) ; / / Send t he cur r ent mont h over a ser i al connect i on

halt(value);
Set or clear the CH
*1
flag.

Parameters: val ue: t r ue: Set t he CH f l ag
f al se: Cl ear t he CH f l ag
Returns: Not hi ng
Usage: r t c. hal t ( t r ue) ; / / Set t he CH f l ag
Notes: *1: CH: Cl ock Hal t f l ag. See t he dat asheet f or mor e i nf or mat i on.

writeBuffer(buffer);
Burst-write the buffer to on-chip RAM.

Parameters: buf f er : DS1307_RAM buf f er
Returns: Not hi ng
Usage: r t c. wr i t ebuf f er ( r amBuf f er ) ; / / Wr i t e t he 56 byt es of r amBuf f er t o t he on- chi p RAM

readBuffer();
Burst-read the on-chip RAM to the buffer.

Parameters: None
Returns: DS1307_RAM buf f er
Usage: r amBuf f er =r t c. r eadBuf f er ( ) ; / / Read al l 56 byt es of on- chi p RAM and st or e t he i n r amBuf f er

poke(address, value);
Write one single byte to on-chip RAM.

Parameters: addr ess: addr ess of byt e t o wr i t e ( 0- 55)
val ue : val ue t o wr i t e t o <addr ess> ( 0- 255)
Returns: Not hi ng
Usage: r t c. poke( 15, 160) ; / / Wr i t e 160 t o addr ess 15

peek(address);
Read one single byte from on-chip RAM.

Parameters: addr ess: addr ess of byt e t o r ead ( 0- 55)
Returns: Byt e cont ai ni ng dat a r ead f r omon- chi p RAM
Usage: b=r t c. peek( 18) ; / / Read a si ngl e byt e f r omaddr ess 18 and put t he r esul t i n b

setOutput(enable);
Set the SQW/OUT pin (pin 7) on the DS1307 to HIGH or LOW. This command has no effect if enableSQW() has been set to TRUE.

Parameters: enabl e: TRUE set s t he out put t o HI GH, and FALSE set s i t t o LOW.
Returns: Not hi ng
Usage: r t c. set Out put ( t r ue) ; / / Set SQW/ OUT t o HI GH

enableSQW(enable);
Enable or disable Square Wave output on the SQW/OUT pin (pin 7).

Parameters: enabl e: TRUE enabl es Squar e Wave out put , and FALSE di sabl es i t .
Returns: Not hi ng
Usage: r t c. enabl eSQW( t r ue) ; / / Enabl e Squar e Wave out put on SQW/ OUT


Page 5 of 5
setSQWRate(rate);
Set the Square Wave output rate.

Parameters: r at e: SQW_RATE_1 set s a 1Hz r at e
SQW_RATE_4K set s a 4. 096KHz r at e
SQW_RATE_8K set s a 8. 192KHz r at e
SQW_RATE_32K set s a 32. 768KHz r at e
Returns: Not hi ng
Usage: r t c. set SQWRat e( SQW_RATE_1) ; / / Set s t he r at e f or SQWt o 1 Hz