root/ds1337/ds1337.h

Revision 12, 11.8 KB (checked in by mlalondesvn, 15 months ago)

DS1624:

ADDED - Support for read/write to the EEPROM
ADDED - DS1624_USE_EEPROM Define in the config to enable eeprom functions
MODIF - Moved the start/stop conversion routine to the start/stopConversion() functions


DS1803 & DS1337:

FIXED - Removed r/w addresses and changed for single address
Line 
1/*
2  DS1337.h - library for DS1337 I2C Real Time Clock
3*/
4
5#ifndef DS1337_h
6#define DS1337_h
7#define DS1337_DEBUG
8
9// include types & constants of Wiring core API
10#include "../global.h"
11
12#include "../global.h"
13#include "../configs/RTC/rtcConfig.h"
14#include "../configs/ds1337/ds1337.h"
15
16/**
17 * Define the position of the RTC buffer values
18**/
19#define DS1337_SEC                      0
20#define DS1337_MIN                      1
21#define DS1337_HR                       2
22#define DS1337_DOW                      3
23#define DS1337_DATE                     4
24#define DS1337_MTH                      5
25#define DS1337_YR                       6
26#define DS1337_CNTY                     7
27
28// For use externally
29#define RTC_SEC                         DS1337_SEC
30#define RTC_MIN                         DS1337_MIN
31#define RTC_HR                          DS1337_HR
32#define RTC_DOW                         DS1337_DOW
33#define RTC_DATE                        DS1337_DATE
34#define RTC_MTH                         DS1337_MTH
35#define RTC_YR                          DS1337_YR
36#define RTC_CNTY                        DS1337_CNTY
37
38/**
39 * Define the DS1337 I2C addresses
40**/
41#ifndef DS1337_ADDR
42#define DS1337_ADDR                 B01101000
43#endif
44
45/**
46 * Define registers and bit masks
47**/
48#define DS1337_LO_BCD                   B00001111
49#define DS1337_HI_BCD                   B01110000
50
51#define DS1337_HI_SEC                   B01110000
52#define DS1337_HI_MIN                   B01110000
53#define DS1337_HI_HR                    B00110000
54#define DS1337_LO_DOW                   B00000111
55#define DS1337_HI_DATE                  B00110000
56#define DS1337_HI_MTH                   B00010000
57#define DS1337_LO_CNTY                  B10000000
58#define DS1337_HI_YR                    B11110000
59
60#define DS1337_ARLM1                    0x07
61#define DS1337_ARLM1_LO_SEC             B00001111
62#define DS1337_ARLM1_HI_SEC             B01110000
63#define DS1337_ARLM1_LO_MIN             B01110000
64#define DS1337_ARLM1_HI_MIN             B00001111
65
66#define DS1337_SP                       0x0E
67#define DS1337_SP_EOSC                  B10000000
68#define DS1337_SP_RS2                   B00010000
69#define DS1337_SP_RS1                   B00001000
70#define DS1337_SP_INTCN                 B00000100
71#define DS1337_SP_A2IE                  B00000010
72#define DS1337_SP_A1IE                  B00000001
73
74#define DS1337_STATUS                   0x0F
75#define DS1337_STATUS_OSF               B10000000
76#define DS1337_STATUS_A2F               B00000010
77#define DS1337_STATUS_A1F               B00000001
78
79// Alarm registers and masks
80#define DS1337_ALARM1                   0x07
81#define DS1337_ALARM2                   0x0B
82
83#define DS1337_ALARM_DT_MASK            B01000000
84#define DS1337_ALARM_MASK               B10000000
85
86#define DS1337_ALARM_MODE               4
87#define DS1337_ALARM_DT                 5
88
89/**
90 * Match Day of the week or match date
91**/
92#define DS1337_ALARM_DT_DOW             true
93#define DS1337_ALARM_DT_DATE            false
94
95/**
96 * Alarm 1: Every second
97 * Alarm 2: Every minute (at 00s)
98**/
99#define DS1337_ALARM_PERA               B00001111
100#define DS1337_ALARM_PER_SEC            DS1337_ALARM_PERA   /* Used for alarm 1 only*/
101#define DS1337_ALARM_PER_MIN            DS1337_ALARM_PERA   /* Used for alarm 2 only*/
102
103/**
104 * Alarm 1: Match second
105 * Alarm 2: Match minute
106**/
107#define DS1337_ALARM_MCH_SEC            B00001110           /* Used for alarm 1 only */
108#define DS1337_ALARM_MCH_MIN            B00001100           /* Used for alarm 2 only */
109
110/**
111 * Alarm 1: Match minutes and seconds
112 * Alarm 2: Match hours and minutes
113**/
114#define DS1337_ALARM_MCH_MINSEC         B00001100           /* Used for alarm 1 only */
115#define DS1337_ALARM_MCH_HRMIN          B00001000           /* Used for alarm 2 only */
116
117/**
118 * Alarm 1: Match hour, minute and second
119**/
120#define DS1337_ALARM_MCH_HRMINSEC       B00001000           /* Used for alarm 1 only */
121
122/**
123 * Alarm 1: Match date, hour, minute, second
124 * Alarm 2: Match da,te hour, minute
125**/
126#define DS1337_ALARM_MCH_DATEHRMINSEC   B00000000           /* Used for alarm 1 only */
127#define DS1337_ALARM_MCH_DATEHRMIN      B00000000           /* Used for alarm 2 only */
128
129/**
130 * Alarm 1: Match day of the week, hour, minute, second
131 * Alarm 2: Match day of the week, hour, minute
132**/
133#define DS1337_ALARM_MCH_DOWHRMINSEC    B10000000           /* Used for alarm 1 only */
134#define DS1337_ALARM_MCH_DOWHRMIN       B10000000           /* Used for alarm 2 only */
135
136// Alarm mode masks
137#define DS1337_ALARM2_MODE_MASK         B00001000
138#define DS1337_ALARM_M1                 B00000001
139#define DS1337_ALARM_M2                 B00000010
140#define DS1337_ALARM_M3                 B00000100
141#define DS1337_ALARM_M4                 B00001000
142
143// Alarm interrupt bitmask
144#define DS1337_ALARM_INT1               B00000001
145#define DS1337_ALARM_INT2               B00000010
146
147// Square Wave output masks
148#define DS1337_SQW_INTCN                B00000100
149#define DS1337_SQW_RS1                  B00001000
150#define DS1337_SQW_RS2                  B00010000
151
152// Square Wave output modes
153#define DS1337_SQW_RS                   B00011000
154#define DS1337_SQW_1HZ                  B00000000
155#define DS1337_SQW_4096KHZ              DS1337_SQW_RS1
156#define DS1337_SQW_8192KHZ              DS1337_SQW_RS2
157#define DS1337_SQW_OSC                  DS1337_SQW_RS1 | DS1337_SQW_RS2
158
159/**
160 * Macros
161**/
162#define clockStop()                     setRegister(DS1337_SP, DS1337_SP_EOSC)
163
164#define getRegisterSP()                 getRegister(DS1337_SP)
165#define getRegisterStatus()             getRegister(DS1337_STATUS)
166
167#define getRegisterBit(reg, bitMask)    (getRegister(reg) & bitMask) && bitMask
168
169#ifndef ISLEAP
170#define ISLEAP(y)                       ((((y) % 4) == 0 && ((y) % 100) != 0) || ((y) % 400) == 0)
171#endif
172
173#ifndef BCDTOBIN
174// This marco is for internal use only!
175#define BCDTOBIN(index, hi)             (10*((rtc_bcd[index] & hi)>>4))+(rtc_bcd[index] & DS1337_LO_BCD)
176#endif
177
178#ifndef BINTOBCD
179#define BINTOBCD(val)                   ((((val)/10)<<4) + (val)%10)
180#endif
181
182/**
183 * getUTS: Macro for calculateUTS
184 * returns the time as a unix time stamp
185 * This function doesn't take into account having DST set or not!
186**/
187#ifdef DS1337_USE_GET_UTS
188#define getUTS(refresh)                 calculateUTS(   RTC.clockGet(DS1337_YR, true), RTC.clockGet(DS1337_MTH, false), \
189                                                        RTC.clockGet(DS1337_DATE, false), RTC.clockGet(DS1337_HR, false), \
190                                                        RTC.clockGet(DS1337_MIN, false), RTC.clockGet(DS1337_SEC, false) \
191                                                    )
192#endif
193
194/**
195 * Use this macro to the time from a unix time stamp
196**/
197#if defined(DS1337_USE_SET_UTS)
198#define clockSet(UTS)                   clockSetWithUTS(UTS, false)
199#endif
200
201/**
202 * Macros for getting time values without refreshing the RTC buffer
203**/
204#define clockGetSec()                   clockGet(DS1337_SEC, false)
205#define clockGetMin()                   clockGet(DS1337_MIN, false)
206#define clockGetHour()                  clockGet(DS1337_HR, false)
207#define clockGetDate()                  clockGet(DS1337_DATE, false)
208#define clockGetMonth()                 clockGet(DS1337_MTH, false)
209#define clockGetDow()                   clockGet(DS1337_DOW, false)
210
211/**
212 * Macros for getting time values refreshing the RTC buffer before each read.
213**/
214#define clockGetRSec()                  clockGet(DS1337_SEC, true)
215#define clockGetRMin()                  clockGet(DS1337_MIN, true)
216#define clockGetRHour()                 clockGet(DS1337_HR, true)
217#define clockGetRDate()                 clockGet(DS1337_DATE, true)
218#define clockGetRMonth()                clockGet(DS1337_MTH, true)
219#define clockGetRDow()                  clockGet(DS1337_DOW, true)
220
221
222#if defined(DS1337_USE_ALARMS_CALLBACK) || defined(DS1337_USE_OSC_INTEGRITY)
223/**
224 * Holds the pointer to callback functions
225**/
226volatile static voidFuncPtr DS1337callbackFunc[3];
227#endif
228
229// library interface description
230class DS1337
231{
232    // user-accessible "public" interface
233    public:
234        /**
235         * clockExists: keeps track of the whether or not the RTC exists
236        **/
237        bool        clockExists;
238       
239        /**
240         * Class constructor
241        **/
242        DS1337();
243       
244        /**
245         * Init: initializes the clock
246         * If the I2C scan mod is available, it'll verify the RTC is reachable
247        **/
248        int8_t      Init(void);
249       
250        /**
251         * clockStart: starts the oscillator and reset the fault flag
252        **/
253        void        clockStart(void);
254    #ifdef DS1337_USE_OSC_INTEGRITY
255        /**
256         * chockSetIntegrityCallback: allow setting the callback function
257         * for the oscillator fault check.
258        **/
259        void        clockIntegrityCallback(void (*)(void));
260    #endif
261    #if defined(DS1337_USE_ALARMS_CALLBACK) || defined(DS1337_USE_OSC_INTEGRITY)
262        /**
263         * clockChecks: performs various clock checks such as integrity and alarms
264         * Will trigger the
265        **/
266        void        clockChecks(void);
267    #endif
268        /**
269         * setRegister: sets a register bit fromt he register number and bitmask
270        **/
271        void        setRegister(uint8_t, uint8_t);
272       
273        /**
274         * unsetRegister: unsets a register bit fromt he register number and bitmask
275        **/
276        void        unsetRegister(uint8_t, uint8_t);
277       
278        /**
279         * getRegister: returns the specified register
280        **/
281        uint8_t     getRegister(uint8_t);
282       
283        /**
284         * clockGet: fills an array with the current time data
285        **/
286        void        clockGet(uint16_t *);
287       
288        /**
289         * clockGet: gets a specific item from the clock buffer
290         * use the second param to specify a buffer refresh
291        **/
292        uint16_t    clockGet(uint8_t, boolean);
293       
294        /**
295         * clockSet: Set the clock time using integer values
296         * Does not do any GMT or DST correction
297        **/
298    #ifdef DS1337_USE_BCD_CLOCKSET
299        void        clockSet(uint8_t, uint16_t);
300    #endif
301       
302        /**
303         * calculateUTS: returns the time as a unix time stamp
304         * This function doesn't take into account having DST set or not!
305         *
306         * Use the macro getUTS macro to access this function!
307        **/
308    #ifdef DS1337_USE_GET_UTS
309        uint32_t calculateUTS(uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t min, uint8_t sec);
310    #endif
311       
312        /**
313         * clockSetWithUTS: sets the date & time from a unix time stamp
314         * pass the second param as true to skip DTS and GMT calculation
315         *
316         * Use the clockSet macro to access this function!
317        **/
318        void        clockSetWithUTS(uint32_t, boolean);
319    #ifdef DS1337_DEBUG
320        /**
321         * Prints all of the DS1337 registers
322        **/
323        void        printRegisters(void);
324    #endif
325    #ifdef DS1337_USE_ALARMS
326        /**
327         * alarmSelect: allows selection of the DS1337 alarm 1 or 2
328         * false for alarm 1 and true for alarm 2
329        **/
330        void        alarmSelect(boolean);
331       
332        /**
333         * Allows setting an alarm's date and time using integers
334        **/
335        void        alarmSet(uint8_t, uint8_t);
336       
337        /**
338         * alarmCheck: checks if an alarm flag was set and reset the flag
339         * set param to true to check for both registers false (or void) to check for the selected alarm
340        **/
341        boolean     alarmCheck(boolean);
342        boolean     alarmCheck(void); // Same as above using false
343   
344    #ifdef DS1337_USE_ALARMS_CALLBACK
345        /**
346         * alarmSetCallback: allows setting of a callback function associated with alarm
347         * The function will be passed a boolean indicating which of alarm1 (false) or alarm2 (true)
348         * triggered the callback
349        **/
350        void        alarmSetCallback(void (*)(void));
351       
352        /**
353         * alarmUnsetCallback: removes the callback function attached to the current alarm
354        **/
355        void        alarmUnsetCallback(void);
356       
357        /**
358         * alarmChecks: will trigger the callback function if an alarm is high
359         * This function need to be placed somewhere in the main loop
360        **/
361        void        alarmChecks(void);
362    #endif
363   
364    #ifdef DS1337_USE_ALARM_INTERRUPTS
365        /**
366         * alarmDisableInterrupts: disables all alarm interrupts
367        **/
368        void        alarmDisableInterrupts(void);
369       
370        /**
371         * alarmSetInterrupt: sets the alarm interrupt for the selected alarm
372        **/
373        void        alarmSetInterrupt(void);
374       
375        /**
376         * alarmUnsetInterrupt: disable interrupt for the select alarm
377        **/
378        void        alarmUnsetInterrupt(void);
379    #endif
380    #endif
381   
382    #ifdef DS1337_USE_SQW_OUTPUT
383        /**
384         * sqwEnable: Enable the square wave output on SQW/INTB
385         * If this is enabled and an interrupt is set for alarm 2
386         * the interrupt will INTA instead of SQW/INTB
387        **/
388        void        sqwEnable(void);
389       
390        /**
391         * sqwDisable: Disables the square wave output on SQW/INTB
392        **/
393        void        sqwDisable(void);
394       
395        /**
396         * sqwSetRate: Sets the square wave rate
397        **/
398        void        sqwSetRate(uint8_t sqwRate);
399    #endif
400    private:
401        /**
402         * Hold a unix time stamp
403        **/
404    #if defined(DS1337_USE_SET_UTS) || defined(DS1337_USE_GET_UTS)
405        uint32_t    tt;
406    #endif
407       
408        /**
409         * Holds the RTC BCD time buffer
410        **/
411        uint8_t     rtc_bcd[8];
412       
413        /**
414         * Writes a value to a clock register
415        **/
416        void        writeRegister(uint8_t, uint8_t);
417       
418        /**
419         * Write the RTC BCD buffer to the clock
420        **/
421        void        clockSave(void);
422       
423        /**
424         * Read the RTC BCD buffer to the clock
425        **/
426        void        clockRead(void);
427       
428        /**
429         * Converts a BCD to a binary integer
430        **/
431        uint8_t     bcdToBin(uint8_t, uint8_t);
432       
433        /**
434         * Converts a binary integer to BCD
435        **/
436        uint8_t     binToBcd(uint8_t);
437       
438    #ifdef DS1337_USE_ALARMS   
439        /**
440         * Hold the buffer for alarm manipulation
441        **/
442        uint8_t     rtc_alarm[4];
443        /**
444         * alarmId: keeps track of which alarm we are working with
445        **/
446        boolean     alarmId;
447       
448        /**
449         * Writes the alarm buffer to the RTC
450        **/
451        void        alarmSave(void);
452    #endif
453};
454
455/**
456 * Define the Object's name
457**/
458extern DS1337 RTC;
459
460#endif
Note: See TracBrowser for help on using the browser.