RTClib
RTClib.h
Go to the documentation of this file.
1 /**************************************************************************/
20 /**************************************************************************/
21 
22 #ifndef _RTCLIB_H_
23 #define _RTCLIB_H_
24 
25 #include <Arduino.h>
26 #include <Wire.h>
27 class TimeSpan;
28 
30 #define PCF8523_ADDRESS 0x68
31 #define PCF8523_CLKOUTCONTROL 0x0F
32 #define PCF8523_CONTROL_1 0x00
33 #define PCF8523_CONTROL_2 0x01
34 #define PCF8523_CONTROL_3 0x02
35 #define PCF8523_TIMER_B_FRCTL 0x12
36 #define PCF8523_TIMER_B_VALUE 0x13
37 #define PCF8523_OFFSET 0x0E
38 #define PCF8523_STATUSREG 0x03
39 
40 #define PCF8563_ADDRESS 0x51
41 #define PCF8563_CLKOUTCONTROL 0x0D
42 #define PCF8563_CONTROL_1 0x00
43 #define PCF8563_CONTROL_2 0x01
44 #define PCF8563_VL_SECONDS 0x02
45 #define PCF8563_CLKOUT_MASK 0x83
46 
47 #define DS1307_ADDRESS 0x68
48 #define DS1307_CONTROL 0x07
49 #define DS1307_NVRAM 0x08
50 
51 #define DS3231_ADDRESS 0x68
52 #define DS3231_TIME 0x00
53 #define DS3231_ALARM1 0x07
54 #define DS3231_ALARM2 0x0B
55 #define DS3231_CONTROL 0x0E
56 #define DS3231_STATUSREG 0x0F
57 #define DS3231_TEMPERATUREREG \
58  0x11
59 
61 
62 #define SECONDS_PER_DAY 86400L
63 #define SECONDS_FROM_1970_TO_2000 \
64  946684800
65 
66 /**************************************************************************/
81 /**************************************************************************/
82 
83 class DateTime {
84 public:
85  DateTime(uint32_t t = SECONDS_FROM_1970_TO_2000);
86  DateTime(uint16_t year, uint8_t month, uint8_t day, uint8_t hour = 0,
87  uint8_t min = 0, uint8_t sec = 0);
88  DateTime(const DateTime &copy);
89  DateTime(const char *date, const char *time);
90  DateTime(const __FlashStringHelper *date, const __FlashStringHelper *time);
91  DateTime(const char *iso8601date);
92  bool isValid() const;
93  char *toString(char *buffer);
94 
99  uint16_t year() const { return 2000U + yOff; }
104  uint8_t month() const { return m; }
109  uint8_t day() const { return d; }
114  uint8_t hour() const { return hh; }
115 
116  uint8_t twelveHour() const;
121  uint8_t isPM() const { return hh >= 12; }
126  uint8_t minute() const { return mm; }
131  uint8_t second() const { return ss; }
132 
133  uint8_t dayOfTheWeek() const;
134 
135  /* 32-bit times as seconds since 2000-01-01. */
136  uint32_t secondstime() const;
137 
138  /* 32-bit times as seconds since 1970-01-01. */
139  uint32_t unixtime(void) const;
140 
149  };
150  String timestamp(timestampOpt opt = TIMESTAMP_FULL);
151 
152  DateTime operator+(const TimeSpan &span);
153  DateTime operator-(const TimeSpan &span);
154  TimeSpan operator-(const DateTime &right);
155  bool operator<(const DateTime &right) const;
156 
166  bool operator>(const DateTime &right) const { return right < *this; }
167 
177  bool operator<=(const DateTime &right) const { return !(*this > right); }
178 
188  bool operator>=(const DateTime &right) const { return !(*this < right); }
189  bool operator==(const DateTime &right) const;
190 
199  bool operator!=(const DateTime &right) const { return !(*this == right); }
200 
201 protected:
202  uint8_t yOff;
203  uint8_t m;
204  uint8_t d;
205  uint8_t hh;
206  uint8_t mm;
207  uint8_t ss;
208 };
209 
210 /**************************************************************************/
214 /**************************************************************************/
215 class TimeSpan {
216 public:
217  TimeSpan(int32_t seconds = 0);
218  TimeSpan(int16_t days, int8_t hours, int8_t minutes, int8_t seconds);
219  TimeSpan(const TimeSpan &copy);
220 
226  int16_t days() const { return _seconds / 86400L; }
233  int8_t hours() const { return _seconds / 3600 % 24; }
240  int8_t minutes() const { return _seconds / 60 % 60; }
247  int8_t seconds() const { return _seconds % 60; }
252  int32_t totalseconds() const { return _seconds; }
253 
254  TimeSpan operator+(const TimeSpan &right);
255  TimeSpan operator-(const TimeSpan &right);
256 
257 protected:
258  int32_t _seconds;
259 };
260 
263  DS1307_OFF = 0x00, // Low
264  DS1307_ON = 0x80, // High
265  DS1307_SquareWave1HZ = 0x10, // 1Hz square wave
266  DS1307_SquareWave4kHz = 0x11, // 4kHz square wave
267  DS1307_SquareWave8kHz = 0x12, // 8kHz square wave
268  DS1307_SquareWave32kHz = 0x13 // 32kHz square wave
269 };
270 
271 /**************************************************************************/
275 /**************************************************************************/
276 class RTC_DS1307 {
277 public:
278  boolean begin(TwoWire *wireInstance = &Wire);
279  void adjust(const DateTime &dt);
280  uint8_t isrunning(void);
281  DateTime now();
282  Ds1307SqwPinMode readSqwPinMode();
283  void writeSqwPinMode(Ds1307SqwPinMode mode);
284  uint8_t readnvram(uint8_t address);
285  void readnvram(uint8_t *buf, uint8_t size, uint8_t address);
286  void writenvram(uint8_t address, uint8_t data);
287  void writenvram(uint8_t address, uint8_t *buf, uint8_t size);
288 
289 protected:
290  TwoWire *RTCWireBus;
291 };
292 
295  DS3231_OFF = 0x1C,
300 };
301 
307  DS3231_A1_Hour = 0x08,
309  DS3231_A1_Date = 0x00,
313 };
324 };
325 
326 /**************************************************************************/
330 /**************************************************************************/
331 class RTC_DS3231 {
332 public:
333  boolean begin(TwoWire *wireInstance = &Wire);
334  void adjust(const DateTime &dt);
335  bool lostPower(void);
336  DateTime now();
337  Ds3231SqwPinMode readSqwPinMode();
338  void writeSqwPinMode(Ds3231SqwPinMode mode);
339  bool setAlarm1(const DateTime &dt, Ds3231Alarm1Mode alarm_mode);
340  bool setAlarm2(const DateTime &dt, Ds3231Alarm2Mode alarm_mode);
341  void disableAlarm(uint8_t alarm_num);
342  void clearAlarm(uint8_t alarm_num);
343  bool alarmFired(uint8_t alarm_num);
344  void enable32K(void);
345  void disable32K(void);
346  bool isEnabled32K(void);
347  float getTemperature(); // in Celsius degree
348 
349 protected:
350  TwoWire *RTCWireBus;
351 };
352 
363 };
364 
374 };
375 
386 };
387 
392 };
393 
394 /**************************************************************************/
398 /**************************************************************************/
399 class RTC_PCF8523 {
400 public:
401  boolean begin(TwoWire *wireInstance = &Wire);
402  void adjust(const DateTime &dt);
403  boolean lostPower(void);
404  boolean initialized(void);
405  DateTime now();
406  void start(void);
407  void stop(void);
408  uint8_t isrunning();
409  Pcf8523SqwPinMode readSqwPinMode();
410  void writeSqwPinMode(Pcf8523SqwPinMode mode);
411  void enableSecondTimer(void);
412  void disableSecondTimer(void);
413  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods,
414  uint8_t lowPulseWidth);
415  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods);
416  void disableCountdownTimer(void);
417  void deconfigureAllTimers(void);
418  void calibrate(Pcf8523OffsetMode mode, int8_t offset);
419 
420 protected:
421  TwoWire *RTCWireBus;
422 };
423 
431 };
432 
433 /**************************************************************************/
437 /**************************************************************************/
438 
439 class RTC_PCF8563 {
440 public:
441  boolean begin(TwoWire *wireInstance = &Wire);
442  boolean lostPower(void);
443  void adjust(const DateTime &dt);
444  DateTime now();
445  void start(void);
446  void stop(void);
447  uint8_t isrunning();
448  Pcf8563SqwPinMode readSqwPinMode();
449  void writeSqwPinMode(Pcf8563SqwPinMode mode);
450 
451 protected:
452  TwoWire *RTCWireBus;
453 };
454 
455 /**************************************************************************/
460 /**************************************************************************/
461 class RTC_Millis {
462 public:
467  void begin(const DateTime &dt) { adjust(dt); }
468  void adjust(const DateTime &dt);
469  DateTime now();
470 
471 protected:
479  uint32_t lastUnix;
487  uint32_t lastMillis;
488 };
489 
490 /**************************************************************************/
498 /**************************************************************************/
499 class RTC_Micros {
500 public:
505  void begin(const DateTime &dt) { adjust(dt); }
506  void adjust(const DateTime &dt);
507  void adjustDrift(int ppm);
508  DateTime now();
509 
510 protected:
515  uint32_t microsPerSecond = 1000000;
521  uint32_t lastUnix;
525  uint32_t lastMicros;
526 };
527 
528 #endif // _RTCLIB_H_
Definition: RTClib.h:295
DateTime(uint32_t t=SECONDS_FROM_1970_TO_2000)
Constructor from Unix time.
Definition: RTClib.cpp:178
bool operator<(const DateTime &right) const
Test if one DateTime is less (earlier) than another.
Definition: RTClib.cpp:664
bool operator<=(const DateTime &right) const
Test if one DateTime is less (earlier) than or equal to another.
Definition: RTClib.h:177
uint8_t ss
Seconds 0-59.
Definition: RTClib.h:207
Pcf8523OffsetMode
Definition: RTClib.h:389
Definition: RTClib.h:361
DateTime operator-(const TimeSpan &span)
Subtract a TimeSpan from the DateTime object.
Definition: RTClib.cpp:632
timestampOpt
Definition: RTClib.h:145
Definition: RTClib.h:369
RTC using the internal micros() clock, has to be initialized before use. Unlike RTC_Millis, this can be tuned in order to compensate for the natural drift of the system clock. Note that now() has to be called more frequently than the micros() rollover period, which is approximately 71.6 minutes.
Definition: RTClib.h:499
Definition: RTClib.h:297
uint8_t d
Day 1-31.
Definition: RTClib.h:204
Simple general-purpose date/time class (no TZ / DST / leap seconds).
Definition: RTClib.h:83
TwoWire * RTCWireBus
I2C bus connected to the RTC.
Definition: RTClib.h:452
uint8_t dayOfTheWeek() const
Return the day of the week.
Definition: RTClib.cpp:570
YYYY-MM-DD
Definition: RTClib.h:148
bool operator>=(const DateTime &right) const
Test if one DateTime is greater (later) than or equal to another.
Definition: RTClib.h:188
PCF8523TimerIntPulse
Definition: RTClib.h:377
Definition: RTClib.h:427
bool isValid() const
Check whether this DateTime is valid.
Definition: RTClib.cpp:403
Definition: RTClib.h:299
Definition: RTClib.h:320
RTC based on the DS1307 chip connected via I2C and the Wire library.
Definition: RTClib.h:276
uint8_t day() const
Return the day of the month.
Definition: RTClib.h:109
Definition: RTClib.h:373
Definition: RTClib.h:306
uint8_t month() const
Return the month.
Definition: RTClib.h:104
Ds1307SqwPinMode
Definition: RTClib.h:262
uint32_t lastMillis
Definition: RTClib.h:487
TwoWire * RTCWireBus
I2C bus connected to the RTC.
Definition: RTClib.h:290
uint8_t isPM() const
Return whether the time is PM.
Definition: RTClib.h:121
uint32_t lastUnix
Definition: RTClib.h:479
Definition: RTClib.h:426
Definition: RTClib.h:357
char * toString(char *buffer)
Writes the DateTime as a string in a user-defined format.
Definition: RTClib.cpp:458
hh:mm:ss
Definition: RTClib.h:147
#define SECONDS_FROM_1970_TO_2000
Unixtime for 2000-01-01 00:00:00, useful for initialization.
Definition: RTClib.h:63
String timestamp(timestampOpt opt=TIMESTAMP_FULL)
Return a ISO 8601 timestamp as a String object.
Definition: RTClib.cpp:709
Definition: RTClib.h:296
bool operator>(const DateTime &right) const
Test if one DateTime is greater (later) than another.
Definition: RTClib.h:166
int32_t _seconds
Actual TimeSpan value is stored as seconds.
Definition: RTClib.h:258
uint8_t second() const
Return the second.
Definition: RTClib.h:131
Definition: RTClib.h:359
void begin(const DateTime &dt)
Start the RTC.
Definition: RTClib.h:505
PCF8523TimerClockFreq
Definition: RTClib.h:366
Definition: RTClib.h:391
Definition: RTClib.h:430
Pcf8563SqwPinMode
Definition: RTClib.h:425
Definition: RTClib.h:385
uint8_t hour() const
Return the hour.
Definition: RTClib.h:114
RTC based on the PCF8523 chip connected via I2C and the Wire library.
Definition: RTClib.h:399
Definition: RTClib.h:381
bool operator!=(const DateTime &right) const
Test if two DateTime objects are not equal.
Definition: RTClib.h:199
Pcf8523SqwPinMode
Definition: RTClib.h:354
Definition: RTClib.h:382
TwoWire * RTCWireBus
I2C bus connected to the RTC.
Definition: RTClib.h:350
Definition: RTClib.h:356
Definition: RTClib.h:358
YYYY-MM-DDThh:mm:ss
Definition: RTClib.h:146
Definition: RTClib.h:428
Definition: RTClib.h:319
int8_t minutes() const
Number of minutes in the TimeSpan This is not the total minutes, it includes days/hours e...
Definition: RTClib.h:240
Definition: RTClib.h:355
Definition: RTClib.h:309
uint32_t unixtime(void) const
Return Unix time: seconds since 1 Jan 1970.
Definition: RTClib.cpp:585
uint32_t lastUnix
Definition: RTClib.h:521
Definition: RTClib.h:378
Definition: RTClib.h:305
void begin(const DateTime &dt)
Start the RTC.
Definition: RTClib.h:467
Definition: RTClib.h:371
Definition: RTClib.h:307
int8_t seconds() const
Number of seconds in the TimeSpan This is not the total seconds, it includes the days/hours/minutes e...
Definition: RTClib.h:247
uint32_t secondstime() const
Convert the DateTime to seconds since 1 Jan 2000.
Definition: RTClib.cpp:607
uint8_t m
Month 1-12.
Definition: RTClib.h:203
DateTime operator+(const TimeSpan &span)
Add a TimeSpan to the DateTime object.
Definition: RTClib.cpp:621
uint8_t twelveHour() const
Return the hour in 12-hour format.
Definition: RTClib.cpp:554
Definition: RTClib.h:379
int8_t hours() const
Number of hours in the TimeSpan This is not the total hours, it includes the days e...
Definition: RTClib.h:233
TwoWire * RTCWireBus
I2C bus connected to the RTC.
Definition: RTClib.h:421
Definition: RTClib.h:322
Definition: RTClib.h:298
Definition: RTClib.h:383
Definition: RTClib.h:362
Ds3231SqwPinMode
Definition: RTClib.h:294
int16_t days() const
Number of days in the TimeSpan e.g. 4.
Definition: RTClib.h:226
uint8_t minute() const
Return the minute.
Definition: RTClib.h:126
Definition: RTClib.h:318
Timespan which can represent changes in time with seconds accuracy.
Definition: RTClib.h:215
uint16_t year() const
Return the year.
Definition: RTClib.h:99
Definition: RTClib.h:304
Definition: RTClib.h:311
Definition: RTClib.h:360
uint32_t lastMicros
Definition: RTClib.h:525
uint8_t hh
Hours 0-23.
Definition: RTClib.h:205
RTC based on the DS3231 chip connected via I2C and the Wire library.
Definition: RTClib.h:331
Ds3231Alarm1Mode
Definition: RTClib.h:303
bool operator==(const DateTime &right) const
Test if two DateTime objects are equal.
Definition: RTClib.cpp:688
Ds3231Alarm2Mode
Definition: RTClib.h:315
uint8_t mm
Minutes 0-59.
Definition: RTClib.h:206
uint8_t yOff
Year offset from 2000.
Definition: RTClib.h:202
Definition: RTClib.h:429
Definition: RTClib.h:390
Definition: RTClib.h:316
RTC using the internal millis() clock, has to be initialized before use. NOTE: this is immune to mill...
Definition: RTClib.h:461
Definition: RTClib.h:367
int32_t totalseconds() const
Total number of seconds in the TimeSpan, e.g. 358027.
Definition: RTClib.h:252
RTC based on the PCF8563 chip connected via I2C and the Wire library.
Definition: RTClib.h:439
Definition: RTClib.h:372
Definition: RTClib.h:380
Definition: RTClib.h:384