RTClib

RTClib is designed to work with several Adafruit RTC breakout boards, including:

• DS3231 Precision RTC (standard breakout and Stemma QT versions)
• PCF8523 RTC
• DS1307 RTC

RTClib is compatible with a wide range of MCUs. Note the following specific pin requirements for I2C (SDA/SCL) communication:

• ATmega32u4 (e.g., Leonardo, Micro, Yun, Teensy 2.0, Flora, Bluefruit Micro): Use SDA/SCL on pins D3 & D2.
• ESP8266 (e.g., Adafruit Huzzah): SDA/SCL default to pins 4 & 5, but you can assign any two pins using Wire.begin(SDA, SCL).
• ATmega2560 (e.g., Arduino Mega): Use SDA/SCL on pins 20 & 21.
• ATSAM3X8E (e.g., Arduino Due): Use SDA1 and SCL1.

RTClib requires the following library to function:

• Adafruit BusIO

To install the RTClib library, open the Arduino IDE, use the Library Manager, search for "RTClib", and select install.

# No CLI command provided, use Arduino Library Manager

The TimeSpan class represents a duration of time with seconds accuracy. It is used to perform arithmetic with DateTime objects (e.g., adding or subtracting time).

Key capabilities:

• Initialization: Create from total seconds or from components (days, hours, minutes, seconds).
• Extraction: Retrieve components via .days(), .hours(), .minutes(), and .seconds(). Note that .hours(), .minutes(), and .seconds() return the component within the larger unit (e.g., .hours() returns 0-23, not total hours).
• Arithmetic: Add or subtract two TimeSpan objects.

// Create a span of 1 day, 2 hours, 30 minutes, and 5 seconds
TimeSpan span(1, 2, 30, 5);

// Add span to a DateTime
DateTime futureTime = dt + span;

// Get total seconds
int32_t total = span.totalseconds();

The RTC_Millis class provides a way to track time using the Arduino millis() function. This is useful when no hardware RTC is available.

Key Characteristics:

• Immunity: It is designed to be immune to millis() rollover events.
• Initialization: You must call .begin(DateTime) to set the starting time before using it.
• Usage: Use .now() to get the current DateTime based on the elapsed millis().

RTC_Millis rtc;

void setup() {
  // Initialize with current time
  rtc.begin(DateTime(__DATE__, __TIME__));
}

void loop() {
  DateTime now = rtc.now();
}

The RTC_PCF8523 class provides an interface for the PCF8523 I2C RTC chip.

Common Tasks:

• Setup: Call .begin() to initialize.
• Time Management: Use .adjust(DateTime) to set the time and .now() to retrieve the current time.
• Timers: Enable/disable the second timer or a countdown timer using .enableCountdownTimer(PCF8523TimerClockFreq clkFreq, uint8_t numPeriods, uint8_t lowPulseWidth).
• Calibration: Adjust accuracy using .calibrate(Pcf8523OffsetMode mode, int8_t offset).
• SQW Pin: Configure the SQW pin using .writeSqwPinMode(Pcf8523SqwPinMode).

The RTC_DS1307 class provides an interface for the DS1307 I2C RTC chip.

Common Tasks:

• Setup: Call .begin() to initialize.
• Time Management: Use .adjust(DateTime) to set the time and .now() to retrieve the current time.
• SQW Pin: Configure the Square Wave output pin using .writeSqwPinMode(Ds1307SqwPinMode).
• NVRAM: Read or write to the chip's non-volatile RAM using .readnvram(address) or .writenvram(address, data).

The RTC_Micros class tracks time using the Arduino micros() function. It is more precise than RTC_Millis but requires more frequent updates.

Key Characteristics:

• Drift Compensation: Unlike RTC_Millis, you can tune this class to compensate for system clock drift using .adjustDrift(int ppm).
• Constraint: You must call .now() more frequently than the micros() rollover period (approximately every 71.6 minutes) to prevent errors.
• Initialization: Call .begin(DateTime) to set the starting time.