DS3231: Add support for the Aging Offset Register

[edgar-bonet]

The DS3231 has an “aging offset” register that can be used to finely trim the frequency of the oscillator, and hence compensate for any frequency inaccuracy that may come as the resonator ages. Advanced users can measure the drift rate of their RTC by comparing with a reliable reference, then use this register to calibrate-out that drift.

This pull request adds support for using the Aging Offset register. It adds the following methods to the class RTC_DS3231:

int8_t getAgingOffset();
void setAgingOffset(int8_t offset);

as well as Doxygen comments explaining what this register is about.

These methods were tested by @terrypin999 (see #299) using the sketch below (#ifdefed-out code removed):

Source code (click to expand/collapse)

#include <RTClib.h>

RTC_DS3231 rtc;

const char help[] = "Available commands:\n\r"
        "  h: print this help\n\r"
        "  t: toggle printing RTC times\n\r"
        "  f: make the RTC fast\n\r"
        "  s: make the RTC slow\n\r"
        "  p: print the aging offset";

void setup() {
    rtc.begin();
    Serial.begin(9600);
    Serial.println("Ready.");
    Serial.println(help);
}

void loop() {
    /* Print RTC updates if asked to do so. */
    static bool do_print_times = false;
    if (do_print_times) {
        static DateTime last_printed_time;
        DateTime now = rtc.now();
        if (now != last_printed_time) {
            char buffer[] = "hh:mm:ss";
            Serial.println(now.toString(buffer));
            last_printed_time = now;
        }
    }

    /* Execute commands from the serial port. */
    switch (Serial.read()) {
        case 'h': Serial.println(help); break;
        case 't': do_print_times = !do_print_times; break;
        case 'f':
            Serial.println("setting aging offset to -128 (fast)");
            rtc.setAgingOffset(-128);
            break;
        case 's':
            Serial.println("setting aging offset to +127 (slow)");
            rtc.setAgingOffset(+127);
            break;
        case 'p':
            Serial.print("aging offset: ");
            Serial.println(rtc.getAgingOffset());
    }
}

Fixes #299.

[terrypin999]

Could this somehow be connected to the 'issue' I've just raised Cannot update to latest version 2.1.4?

[edgar-bonet]

@terrypin999: I don't know. Maybe the library manager sees you have a manually-installed version of RTClib, and this prevents the upgrade?

[terrypin999]

Appreciate the fast reply. That sounds right because meanwhile I then tried IDE 2.3.2 which told me:
Failed to install library: 'RTClib:2.1.4'.
Error: 3 INVALID_ARGUMENT: The library RTClib has multiple installations:

and listing several, all beginning with 'RTClib'. I have always assumed that the
the include line (which this site will not let me insert!)
would be absolutely unambiguous., ignoring any other entries starting with that same text in my \libraries folder. So presumably the compiler looks deeper than the folder name 'RTClib'?

[terrypin999]

Does 2.1.4 includes your work on the Aging Offset Register? If so, and I succeed in updating to it, then it will obviously 'break' my existing sketch, as I edited RTClib.h and replaced that file in my RTClib library. (So I'll then need to explore how to use the new method.)

However I don't understand why, still using 2.1.3 (a library that apparently no longer exists in Manage Libraries!) my sketch no longer compiles. It gives the error
'class RTC_DS3231' has no member named 'readAging'

[edgar-bonet]

@terrypin999: This pull request is still open, which means it has not been merged into the official repository. As for the compile error, I would guess the library manager re-installed the official 2.1.3 version.

[terrypin999]

Thanks, understood. But still don’t follow why unable to update to 2.1.4. Or why 2.1.3 not in the list (or 2.1.2).

[thijstriemstra]

Also see #270