DS1302 - Arduino library support for the DS1302 Trickle Charge
Timekeeping Chip 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 DS1302 RTC wi t h t he Ar dui no.
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 6 Aug 2010 i ni t i al r el ease 2. 0 23 Aug 2010 Added f unct i ons t o use on- chi p RAM 2. 1 17 Nov 2010 Added set TCR( ) ; 2. 2 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
DS1302_RAM; Buffer for use with readBuffer() and writeBuffer().
Variables: Cel l [ 0- 30] : Ar r ay of 31 byt es 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: DS1302_RAM r amBuf f er ; / / Decl ar e a buf f er f or use
DS1302(CE, IO, SCLK); The main class of the interface.
Parameters: CE: CE- pi n of t he DS1302 ( Pi n 5) I O: I / O- pi n of t he DS1302 ( Pi n 6) SCLK: SCLK- pi n of t he DS1302 ( Pi n 7) Usage: DS1302 r t c( 2, 3, 4) ; / / St ar t an i nst ance of t he DS1302 cl ass
getTime(); Get current data from the DS1302.
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 DS1302 ( 0- 23) mi n: Mi nut e t o st or e i n t he DS1302 ( 0- 59) sec: Second t o st or e i n t he DS1302 ( 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 DS1302 ( 1- 31) *1 mon: Mont h t o st or e i n t he DS1302 ( 1- 12) year : Year t o st or e i n t he DS1302 ( 2000- 2099) Returns: Not hi ng Usage: r t c. set Dat e( 6, 8, 2010) ; / / Set t he dat e t o August 6. , 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 DS1302 ( 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.
writeProtect(enable); Set or clear the WP *1 bit.
Parameters: enabl e: t r ue: Set t he WP bi t f al se: Cl ear t he WP bi t Returns: Not hi ng Usage: r t c. wr i t ePr ot ect ( f al se) ; / / Cl ear t he WP bi t Notes: *1: WP: Wr i t e- Pr ot ect bi t . See t he dat asheet f or mor e i nf or mat i on.
setTCR(value); Set the Trickle-Charge Register. Use the defined literals to set the correct value. Added in v2.1 Parameters: val ue: Use t he def i ned l i t er al s t o set t he number of di odes and r esi st ance used. Returns: Not hi ng Usage: r t c. set TCR( TCR_D1R4K) ; / / Set t he Tr i ckl e- char ge r egi st er t o suppor t 1 di ode and a 4K ohmr esi st or . Notes: The l i t er al s ar e def i nes as TCR_DxRyK wher e x i s t he number of di odes used ( 1 or 2) , and y i s t he r esi st ance used ( 2, 4 or 8 Kohm) . TCR_OFF t ur ns of t he Tr i ckl e- Char ge f unct i on.
writeBuffer(buffer); Burst-write the buffer to on-chip RAM. Added in v2.0 Parameters: buf f er : DS1302_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 31 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. Added in v2.0 Parameters: None Returns: DS1302_RAM buf f er Usage: r amBuf f er =r t c. r eadBuf f er ( ) ; / / Read al l 31 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. Added in v2.0 Parameters: addr ess: addr ess of byt e t o wr i t e ( 0- 30) 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
Page 5 of 5
peek(address); Read one single byte from on-chip RAM. Added in v2.0 Parameters: addr ess: addr ess of byt e t o r ead ( 0- 30) 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