RTClib
RTClib.h
Go to the documentation of this file.
1 /**************************************************************************/
20 /**************************************************************************/
21 
22 #ifndef _RTCLIB_H_
23 #define _RTCLIB_H_
24 
25 #include <Adafruit_I2CDevice.h>
26 #include <Arduino.h>
27 
28 class TimeSpan;
29 
31 #define SECONDS_PER_DAY 86400L
32 #define SECONDS_FROM_1970_TO_2000 \
33  946684800
34 
35 
37  DS1307_OFF = 0x00, // Low
38  DS1307_ON = 0x80, // High
39  DS1307_SquareWave1HZ = 0x10, // 1Hz square wave
40  DS1307_SquareWave4kHz = 0x11, // 4kHz square wave
41  DS1307_SquareWave8kHz = 0x12, // 8kHz square wave
42  DS1307_SquareWave32kHz = 0x13 // 32kHz square wave
43 };
44 
47  DS3231_OFF = 0x1C,
52 };
53 
59  DS3231_A1_Hour = 0x08,
61  DS3231_A1_Date = 0x00,
63  DS3231_A1_Day = 0x10
65 };
76 };
87 };
88 
98 };
99 
110 };
111 
116 };
117 
125 };
126 
127 /**************************************************************************/
142 /**************************************************************************/
143 class DateTime {
144 public:
145  DateTime(uint32_t t = SECONDS_FROM_1970_TO_2000);
146  DateTime(uint16_t year, uint8_t month, uint8_t day, uint8_t hour = 0,
147  uint8_t min = 0, uint8_t sec = 0);
148  DateTime(const DateTime &copy);
149  DateTime(const char *date, const char *time);
150  DateTime(const __FlashStringHelper *date, const __FlashStringHelper *time);
151  DateTime(const char *iso8601date);
152  bool isValid() const;
153  char *toString(char *buffer) const;
154 
159  uint16_t year() const { return 2000U + yOff; }
164  uint8_t month() const { return m; }
169  uint8_t day() const { return d; }
174  uint8_t hour() const { return hh; }
175 
176  uint8_t twelveHour() const;
181  uint8_t isPM() const { return hh >= 12; }
186  uint8_t minute() const { return mm; }
191  uint8_t second() const { return ss; }
192 
193  uint8_t dayOfTheWeek() const;
194 
195  /* 32-bit times as seconds since 2000-01-01. */
196  uint32_t secondstime() const;
197 
198  /* 32-bit times as seconds since 1970-01-01. */
199  uint32_t unixtime(void) const;
200 
209  };
210  String timestamp(timestampOpt opt = TIMESTAMP_FULL) const;
211 
212  DateTime operator+(const TimeSpan &span) const;
213  DateTime operator-(const TimeSpan &span) const;
214  TimeSpan operator-(const DateTime &right) const;
215  bool operator<(const DateTime &right) const;
216 
226  bool operator>(const DateTime &right) const { return right < *this; }
227 
237  bool operator<=(const DateTime &right) const { return !(*this > right); }
238 
248  bool operator>=(const DateTime &right) const { return !(*this < right); }
249  bool operator==(const DateTime &right) const;
250 
259  bool operator!=(const DateTime &right) const { return !(*this == right); }
260 
261 protected:
262  uint8_t yOff;
263  uint8_t m;
264  uint8_t d;
265  uint8_t hh;
266  uint8_t mm;
267  uint8_t ss;
268 };
269 
270 /**************************************************************************/
274 /**************************************************************************/
275 class TimeSpan {
276 public:
277  TimeSpan(int32_t seconds = 0);
278  TimeSpan(int16_t days, int8_t hours, int8_t minutes, int8_t seconds);
279  TimeSpan(const TimeSpan &copy);
280 
286  int16_t days() const { return _seconds / 86400L; }
293  int8_t hours() const { return _seconds / 3600 % 24; }
300  int8_t minutes() const { return _seconds / 60 % 60; }
307  int8_t seconds() const { return _seconds % 60; }
312  int32_t totalseconds() const { return _seconds; }
313 
314  TimeSpan operator+(const TimeSpan &right) const;
315  TimeSpan operator-(const TimeSpan &right) const;
316 
317 protected:
318  int32_t _seconds;
319 };
320 
321 /**************************************************************************/
325 /**************************************************************************/
326 class RTC_I2C {
327 protected:
334  static uint8_t bcd2bin(uint8_t val) { return val - 6 * (val >> 4); }
340  static uint8_t bin2bcd(uint8_t val) { return val + 6 * (val / 10); }
341  Adafruit_I2CDevice *i2c_dev = NULL;
342  uint8_t read_register(uint8_t reg);
343  void write_register(uint8_t reg, uint8_t val);
344 };
345 
346 /**************************************************************************/
350 /**************************************************************************/
352 public:
353  bool begin(TwoWire *wireInstance = &Wire);
354  void adjust(const DateTime &dt);
355  uint8_t isrunning(void);
356  DateTime now();
357  Ds1307SqwPinMode readSqwPinMode();
358  void writeSqwPinMode(Ds1307SqwPinMode mode);
359  uint8_t readnvram(uint8_t address);
360  void readnvram(uint8_t *buf, uint8_t size, uint8_t address);
361  void writenvram(uint8_t address, uint8_t data);
362  void writenvram(uint8_t address, const uint8_t *buf, uint8_t size);
363 };
364 
365 /**************************************************************************/
369 /**************************************************************************/
371 public:
372  bool begin(TwoWire *wireInstance = &Wire);
373  void adjust(const DateTime &dt);
374  bool lostPower(void);
375  DateTime now();
376  Ds3231SqwPinMode readSqwPinMode();
377  void writeSqwPinMode(Ds3231SqwPinMode mode);
378  bool setAlarm1(const DateTime &dt, Ds3231Alarm1Mode alarm_mode);
379  bool setAlarm2(const DateTime &dt, Ds3231Alarm2Mode alarm_mode);
380  void disableAlarm(uint8_t alarm_num);
381  void clearAlarm(uint8_t alarm_num);
382  bool alarmFired(uint8_t alarm_num);
383  void enable32K(void);
384  void disable32K(void);
385  bool isEnabled32K(void);
386  float getTemperature(); // in Celsius degree
394  static uint8_t dowToDS3231(uint8_t d) { return d == 0 ? 7 : d; }
395 };
396 
397 /**************************************************************************/
401 /**************************************************************************/
403 public:
404  bool begin(TwoWire *wireInstance = &Wire);
405  void adjust(const DateTime &dt);
406  bool lostPower(void);
407  bool initialized(void);
408  DateTime now();
409  void start(void);
410  void stop(void);
411  uint8_t isrunning();
412  Pcf8523SqwPinMode readSqwPinMode();
413  void writeSqwPinMode(Pcf8523SqwPinMode mode);
414  void enableSecondTimer(void);
415  void disableSecondTimer(void);
416  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods,
417  uint8_t lowPulseWidth);
418  void enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods);
419  void disableCountdownTimer(void);
420  void deconfigureAllTimers(void);
421  void calibrate(Pcf8523OffsetMode mode, int8_t offset);
422 };
423 
424 /**************************************************************************/
428 /**************************************************************************/
430 public:
431  bool begin(TwoWire *wireInstance = &Wire);
432  bool lostPower(void);
433  void adjust(const DateTime &dt);
434  DateTime now();
435  void start(void);
436  void stop(void);
437  uint8_t isrunning();
438  Pcf8563SqwPinMode readSqwPinMode();
439  void writeSqwPinMode(Pcf8563SqwPinMode mode);
440 };
441 
442 /**************************************************************************/
447 /**************************************************************************/
448 class RTC_Millis {
449 public:
454  void begin(const DateTime &dt) { adjust(dt); }
455  void adjust(const DateTime &dt);
456  DateTime now();
457 
458 protected:
466  uint32_t lastUnix;
474  uint32_t lastMillis;
475 };
476 
477 /**************************************************************************/
485 /**************************************************************************/
486 class RTC_Micros {
487 public:
492  void begin(const DateTime &dt) { adjust(dt); }
493  void adjust(const DateTime &dt);
494  void adjustDrift(int ppm);
495  DateTime now();
496 
497 protected:
502  uint32_t microsPerSecond = 1000000;
508  uint32_t lastUnix;
512  uint32_t lastMicros;
513 };
514 
515 #endif // _RTCLIB_H_
char * toString(char *buffer) const
Writes the DateTime as a string in a user-defined format.
Definition: RTClib.cpp:441
Definition: RTClib.h:47
DateTime(uint32_t t=SECONDS_FROM_1970_TO_2000)
Constructor from Unix time.
Definition: RTClib.cpp:161
bool operator<(const DateTime &right) const
Test if one DateTime is less (earlier) than another.
Definition: RTClib.cpp:647
bool operator<=(const DateTime &right) const
Test if one DateTime is less (earlier) than or equal to another.
Definition: RTClib.h:237
uint8_t ss
Seconds 0-59.
Definition: RTClib.h:267
Pcf8523OffsetMode
Definition: RTClib.h:113
Definition: RTClib.h:85
timestampOpt
Definition: RTClib.h:205
Definition: RTClib.h:93
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:486
Definition: RTClib.h:49
uint8_t d
Day 1-31.
Definition: RTClib.h:264
Simple general-purpose date/time class (no TZ / DST / leap seconds).
Definition: RTClib.h:143
uint8_t dayOfTheWeek() const
Return the day of the week.
Definition: RTClib.cpp:553
YYYY-MM-DD
Definition: RTClib.h:208
bool operator>=(const DateTime &right) const
Test if one DateTime is greater (later) than or equal to another.
Definition: RTClib.h:248
PCF8523TimerIntPulse
Definition: RTClib.h:101
Definition: RTClib.h:121
bool isValid() const
Check whether this DateTime is valid.
Definition: RTClib.cpp:386
Definition: RTClib.h:51
Definition: RTClib.h:72
RTC based on the DS1307 chip connected via I2C and the Wire library.
Definition: RTClib.h:351
uint8_t day() const
Return the day of the month.
Definition: RTClib.h:169
Definition: RTClib.h:97
Definition: RTClib.h:58
uint8_t month() const
Return the month.
Definition: RTClib.h:164
Ds1307SqwPinMode
Definition: RTClib.h:36
uint32_t lastMillis
Definition: RTClib.h:474
uint8_t isPM() const
Return whether the time is PM.
Definition: RTClib.h:181
uint32_t lastUnix
Definition: RTClib.h:466
Definition: RTClib.h:120
Definition: RTClib.h:81
hh:mm:ss
Definition: RTClib.h:207
A generic I2C RTC base class. DO NOT USE DIRECTLY.
Definition: RTClib.h:326
#define SECONDS_FROM_1970_TO_2000
Unixtime for 2000-01-01 00:00:00, useful for initialization.
Definition: RTClib.h:32
String timestamp(timestampOpt opt=TIMESTAMP_FULL) const
Return a ISO 8601 timestamp as a String object.
Definition: RTClib.cpp:692
Definition: RTClib.h:48
bool operator>(const DateTime &right) const
Test if one DateTime is greater (later) than another.
Definition: RTClib.h:226
int32_t _seconds
Actual TimeSpan value is stored as seconds.
Definition: RTClib.h:318
uint8_t second() const
Return the second.
Definition: RTClib.h:191
Definition: RTClib.h:83
void begin(const DateTime &dt)
Start the RTC.
Definition: RTClib.h:492
PCF8523TimerClockFreq
Definition: RTClib.h:90
Definition: RTClib.h:115
Definition: RTClib.h:124
Pcf8563SqwPinMode
Definition: RTClib.h:119
Definition: RTClib.h:109
uint8_t hour() const
Return the hour.
Definition: RTClib.h:174
RTC based on the PCF8523 chip connected via I2C and the Wire library.
Definition: RTClib.h:402
Definition: RTClib.h:105
bool operator!=(const DateTime &right) const
Test if two DateTime objects are not equal.
Definition: RTClib.h:259
Pcf8523SqwPinMode
Definition: RTClib.h:78
Definition: RTClib.h:106
Definition: RTClib.h:80
Definition: RTClib.h:82
YYYY-MM-DDThh:mm:ss
Definition: RTClib.h:206
Definition: RTClib.h:122
Definition: RTClib.h:71
static uint8_t dowToDS3231(uint8_t d)
Convert the day of the week to a representation suitable for storing in the DS3231: from 1 (Monday) t...
Definition: RTClib.h:394
int8_t minutes() const
Number of minutes in the TimeSpan This is not the total minutes, it includes days/hours e...
Definition: RTClib.h:300
static uint8_t bcd2bin(uint8_t val)
Convert a binary coded decimal value to binary. RTC stores time/date values as BCD.
Definition: RTClib.h:334
Definition: RTClib.h:79
Definition: RTClib.h:61
uint32_t unixtime(void) const
Return Unix time: seconds since 1 Jan 1970.
Definition: RTClib.cpp:568
uint32_t lastUnix
Definition: RTClib.h:508
Definition: RTClib.h:102
Definition: RTClib.h:57
void begin(const DateTime &dt)
Start the RTC.
Definition: RTClib.h:454
Definition: RTClib.h:95
Definition: RTClib.h:59
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:307
uint32_t secondstime() const
Convert the DateTime to seconds since 1 Jan 2000.
Definition: RTClib.cpp:590
uint8_t m
Month 1-12.
Definition: RTClib.h:263
uint8_t twelveHour() const
Return the hour in 12-hour format.
Definition: RTClib.cpp:537
Definition: RTClib.h:103
int8_t hours() const
Number of hours in the TimeSpan This is not the total hours, it includes the days e...
Definition: RTClib.h:293
Definition: RTClib.h:74
Definition: RTClib.h:50
Definition: RTClib.h:107
Definition: RTClib.h:86
Ds3231SqwPinMode
Definition: RTClib.h:46
int16_t days() const
Number of days in the TimeSpan e.g. 4.
Definition: RTClib.h:286
uint8_t minute() const
Return the minute.
Definition: RTClib.h:186
Definition: RTClib.h:70
Timespan which can represent changes in time with seconds accuracy.
Definition: RTClib.h:275
uint16_t year() const
Return the year.
Definition: RTClib.h:159
DateTime operator+(const TimeSpan &span) const
Add a TimeSpan to the DateTime object.
Definition: RTClib.cpp:604
Definition: RTClib.h:56
Definition: RTClib.h:63
Definition: RTClib.h:84
DateTime operator-(const TimeSpan &span) const
Subtract a TimeSpan from the DateTime object.
Definition: RTClib.cpp:615
uint32_t lastMicros
Definition: RTClib.h:512
uint8_t hh
Hours 0-23.
Definition: RTClib.h:265
RTC based on the DS3231 chip connected via I2C and the Wire library.
Definition: RTClib.h:370
static uint8_t bin2bcd(uint8_t val)
Convert a binary value to BCD format for the RTC registers.
Definition: RTClib.h:340
Ds3231Alarm1Mode
Definition: RTClib.h:55
bool operator==(const DateTime &right) const
Test if two DateTime objects are equal.
Definition: RTClib.cpp:671
Ds3231Alarm2Mode
Definition: RTClib.h:67
uint8_t mm
Minutes 0-59.
Definition: RTClib.h:266
uint8_t yOff
Year offset from 2000.
Definition: RTClib.h:262
Definition: RTClib.h:123
Definition: RTClib.h:114
Definition: RTClib.h:68
RTC using the internal millis() clock, has to be initialized before use. NOTE: this is immune to mill...
Definition: RTClib.h:448
Definition: RTClib.h:91
int32_t totalseconds() const
Total number of seconds in the TimeSpan, e.g. 358027.
Definition: RTClib.h:312
RTC based on the PCF8563 chip connected via I2C and the Wire library.
Definition: RTClib.h:429
Definition: RTClib.h:96
Definition: RTClib.h:104
Definition: RTClib.h:108