Вы находитесь на странице: 1из 5

Page 1 of 5

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

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 Trickle-Charge values
For use with setTCR()

TCR_D1R2K:
TCR_D1R4K:
TCR_D1R8K:
TCR_D2R2K:
TCR_D2R4K:
TCR_D2R8K:
TCR_OFF:
165
166
167
169
170
171
92




Page 3 of 5
Functions:

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

Вам также может понравиться