Aging Register adjustment: suggested addition

[terrypin999]

Hobbyist here, not a programmer/developer/techie, so hope you’ll excuse this submission as an ‘Issue’.

I believe that, like me, other RTClib users get clock inaccuracy with the DS3231. Arduino Forum contributor @gfvalvo helped me to implement its adjustment after a simple addition to RTClib.h. So directly below the section

//
/*!
@brief RTC based on the DS3231 chip connected via I2C and the Wire library
*/
//
(which in the current release 2.1.3 ends with empty line 400), I’ve inserted the following five lines:

// Add Aging Register Access
static constexpr uint8_t agingRegister = 0x10;
int8_t readAging(){
return read_register(agingRegister);
}
void setAging(int8_t newAgingValue) {
write_register(agingRegister, newAgingValue);
}
};
My own sketch already includes the RTClib library and its minimal initialisation

// Initialize the rtc object
rtc.begin();
to which I added the following five lines in setup(), to compensate for my clock’s current slowness.

// Using edited RTClib.h from gfvalvo to adjust AgingRegister
int8_t aging = rtc.readAging();
Serial.println(aging);
int8_t newAging = -50;
rtc.setAging(newAging);
Trial and error will be needed (before hopefully reducing drift to a couple of seconds a week at most), but I already believe it to be working satisfactorily. The method seems significantly simpler than some I’ve seen, so I’d suggest its serious consideration for a future release please.

[edgar-bonet]

@terrypin999: I added the methods you are requesting to my fork of RTClib, but I don't have the hardware to test them. Would you mind testing that yourself? It is in the branch “aging-offset” of my fork. The new methods are called getAgingOffset() and setAgingOffset():

constexpr int8_t calibratedAgingOffset = -50;

void setup() {
    rtc.begin();
    Serial.begin(9600);
    Serial.print("Initial aging offset: ");
    Serial.println(rtc.getAgingOffset());
    rtc.setAgingOffset(calibratedAgingOffset);
    Serial.print("New aging offset:     ");
    Serial.println(rtc.getAgingOffset());
}

If this works for you, I will submit a pull request here with the change.

[terrypin999]

Ok, I’ll do that Sunday or Monday .--TerryOn 23 Mar 2024, at 21:35, Edgar Bonet ***@***.***> wrote: @terrypin999: I added the methods you are requesting to my fork of RTClib, but I don't have the hardware to test them. Would you mind testing that yourself? It is in the branch “aging-offset” of my fork. The new methods are called getAgingOffset() and setAgingOffset(): constexpr int8_t calibratedAgingOffset = -50; void setup() { rtc.begin(); Serial.begin(9600); Serial.print("Initial aging offset: "); Serial.println(rtc.getAgingOffset()); rtc.setAgingOffset(calibratedAgingOffset); Serial.print("New aging offset: "); Serial.println(rtc.getAgingOffset()); } If this works for you, I will submit a pull request here with the change. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[terrypin999]

Hi Edgar, I'd like to help but I'm way out of my depth. As I said in my Issue #299: "Hobbyist here, not a programmer/developer/techie...". So github is largely alien territory for me. After prefixing your link with 'github.com/' I reached the page you presumably intended. https://www.dropbox.com/scl/fi/da3gq3segzsfurbkfzb35/EdgarFork.jpg?rlkey=ddwki3dhwuub9894irnbugtv6&raw=1 But without a foolproof step-by step guide I've no idea how to proceed to do what you require, sorry! Best wishes, Terry ==================== "Hobbyist here, not a programmer/developer/techie..."

…

On Sat, 23 Mar 2024 14:35:13 -0700, you wrote: @terrypin999: I added the methods you are requesting to my fork of RTClib, but I don't have the hardware to test them. Would you mind testing that yourself? It is in [the branch �aging-offset� of my fork][fork]. The new methods are called `getAgingOffset()` and `setAgingOffset()`: ```c++ constexpr int8_t calibratedAgingOffset = -50; void setup() { rtc.begin(); Serial.begin(9600); Serial.print("Initial aging offset: "); Serial.println(rtc.getAgingOffset()); rtc.setAgingOffset(calibratedAgingOffset); Serial.print("New aging offset: "); Serial.println(rtc.getAgingOffset()); } ``` If this works for you, I will submit a pull request here with the change. [fork]: /edgar-bonet/RTClib/tree/aging-offset

[edgar-bonet]

@terrypin999: I found a tutorial with good step-by-step instructions: Install an Arduino library from GitHub. It is provided both as a Web page and as a video. Note that this tutorial offers two options:

• Download a specific version of the library (from a “tag”)
• download the latest source code

Please, use the second option (latest source code), as there is no tag on this specific branch.

[terrypin999]

I know how to install a library from github and have now duly installed yours. But as you see from my screenshot I am unable to use it. Can you therefore tell me the full file and path of its .json file so that I can try the preferences.txt method. https://www.dropbox.com/scl/fi/atofyz9y7ckmv8qood88g/EdgarBonet-aging.jpg?rlkey=09utumhhdlmb2tmy2ly2im9zn&raw=1 I'm working with several sketches at present, or I'd also try restarting the IDE to see if that lets me include your library. I will do so later. Terry ====================

…

On Sun, 24 Mar 2024 06:41:26 -0700, you wrote: @terrypin999: I found a tutorial with good step-by-step instructions: [Install an Arduino library from GitHub][1]. It is provided both as a Web page and as a video. Note that this tutorial offers two options: * Download a specific version of the library (from a �tag�) * download the latest source code Please, use the second option (latest source code), as there is no tag on this specific branch. [1]: https://roboticsbackend.com/install-arduino-library-from-github/

[edgar-bonet]

@terrypin999: I guess this may be due to both libraries having the same name, as it appears in the name field of library.properties. I suggest you move your current RTClib directory out of …\libraries, and rename RTClib-aging-offset as RTClib.

[terrypin999]

Following on from my earlier reply, restarting the IDE did not help. And when I tried the Add.ZIP Library method I got the error message "A subfolder of your sketchbook is not a valid library" I assume you can successfully download and compile it?

…

On Sun, 24 Mar 2024 06:41:26 -0700, you wrote: @terrypin999: I found a tutorial with good step-by-step instructions: [Install an Arduino library from GitHub][1]. It is provided both as a Web page and as a video. Note that this tutorial offers two options: * Download a specific version of the library (from a �tag�) * download the latest source code Please, use the second option (latest source code), as there is no tag on this specific branch. [1]: https://roboticsbackend.com/install-arduino-library-from-github/

[terrypin999]

But that longer name is the one you gave your ZIP, i didn’t name it.Why don’t you give your library a unique name, as there are already several confusingly called RTClib.What about the ‘json/preferences’ route, is that feasible?On 24 Mar 2024, at 16:15, Edgar Bonet ***@***.***> wrote: @terrypin999: I guess this may be due to both libraries having the same name, as it appears in the name field of library.properties. I suggest you move your current RTClib directory out of …\libraries, and rename RTClib-aging-offset as RTClib. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[terrypin999]

I meant to also ask what needs testing? The simple edit to RTClib.h edit described is working successfully for me….On 24 Mar 2024, at 17:02, terrypin ***@***.***> wrote:But that longer name is the one you gave your ZIP, i didn’t name it.Why don’t you give your library a unique name, as there are already several confusingly called RTClib.What about the ‘json/preferences’ route, is that feasible?On 24 Mar 2024, at 16:15, Edgar Bonet ***@***.***> wrote: @terrypin999: I guess this may be due to both libraries having the same name, as it appears in the name field of library.properties. I suggest you move your current RTClib directory out of …\libraries, and rename RTClib-aging-offset as RTClib. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[edgar-bonet]

@terrypin999: I did not name the ZIP file: the name was automatically generated by GitHub. You may have to change it to RTClib.zip to make it work.

Why don’t you give your library a unique name

It's not my library. 😝

My fork is not a competing project: it is a tool meant for submitting pull requests in order to help make this version of the library (which is the official one) better. This is the “GitHub way” of collaborating on open source projects. See the introduction to the guide Contributing to a project.

what needs testing?

My implementation of the idea you suggested. I did not copy the “simple edit to RTClib.h” you posted. Instead, I re-implemented the same functionality in a way that is consistent with the style and coding conventions of this library.

[terrypin999]

OK, understood. I think we're now close to singing from the same hymn sheet. I've renamed your 'fork' ('version' in my terminology) to RTClib as you suggested. (And as a check I've attached a comparison of the .h and .cpp files). But when I then substitute that in my fairly complex working project, (the only one I have using the DS3231), I get the error: 'class RTC_DS3231' has no member named 'readAging' I won't paste the entire 300 or so line error report, but here's a link: https://www.dropbox.com/scl/fi/1qoy9j66y887uuwp31t5v/ErrorReport-Edgar.txt?rlkey=4hgejw9rcq7dyqlppaqtwd8r8&raw=1 If you can write a minimalised demo sketch that you think should compile with your version of RTClib then I'll try that. Comparison of .cpp and .h: https://www.dropbox.com/scl/fi/xbju9vph423uqkcz2pfym/CompareKeyFiles.jpg?rlkey=vjl7kmelhg8mlecsifh3esukf&raw=1 ====================

…

On Sun, 24 Mar 2024 12:41:41 -0700, you wrote: @terrypin999: I did not name the ZIP file: the name was automatically generated by GitHub. You may have to change it to RTClib.zip to make it work. > Why don�t you give your library a unique name It's not my library. 😝 My fork is not a competing project: it is a tool meant for submitting pull requests in order to help make _this_ version of the library (which is the official one) better. This is the �GitHub way� of collaborating on open source projects. See the introduction to the guide [Contributing to a project][gh]. > what needs testing? My implementation of the idea you suggested. I did not copy the �simple edit to RTClib.h� you posted. Instead, I re-implemented the same functionality in a way that is consistent with the style and coding conventions of this library. [gh]: https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project

[edgar-bonet]

@terrypin999 wrote:

here's a link [to the error report]

Thanks for that report! One noteworthy thing I see there is:

Multiple libraries were found for "RTClib.h"
 Used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib
 Not used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib-MyEdit
 Not used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib-aging-offset

So it found three alternatives, and chose the one in the folder named like the library: “RTClib”. If this is a copy of RTClib-aging-offset, it should work.

error: 'class RTC_DS3231' has no member named 'readAging'
error: 'class RTC_DS3231' has no member named 'setAging'

I named the methods getAgingOffset() and setAgingOffset(), for consistency with the current naming conventions and the datasheet.

If you can write a minimalised demo sketch that you think should compile with your version of RTClib then I'll try that.

This compiles:

#include <RTClib.h>

constexpr int8_t calibratedAgingOffset = -50;

RTC_DS3231 rtc;

void setup() {
    rtc.begin();
    Serial.begin(9600);
    Serial.print("Initial aging offset: ");
    Serial.println(rtc.getAgingOffset());
    rtc.setAgingOffset(calibratedAgingOffset);
    Serial.print("New aging offset:     ");
    Serial.println(rtc.getAgingOffset());
}

void loop(){}

Comparison of .cpp and .h: [...]

OK, as expected.

For the record, here is the diff between adafruit:master and edgar-bonet:aging-offset, as computed by GitHub itself.

[terrypin999]

Yes, that was a copy of RTClib-aging-offset. Your sketch compiles here too. Sudden family emergency an hour or so ago. Will be out for most of afternoon at least, so unsure when I can resume contact. What's next step? You don't have a DS3231, right? I do, but it's my only one and it's in that 'finished', cased project. Can you, perhaps with help from another expert, suggest a sketch and schematic I can test that would give you confidence? Mon 25 Mar 2024 1148, UK.

…

On Mon, 25 Mar 2024 04:16:37 -0700, you wrote: @terrypin999 wrote: > here's a link [to the error report] Thanks for that report! One noteworthy thing I see there is: > ```text > Multiple libraries were found for "RTClib.h" > Used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib > Not used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib-MyEdit > Not used: C:\Users\terry\Dropbox\Electronics\Arduino\SKETCHES\libraries\RTClib-aging-offset > ``` So it found three alternatives, and chose the one in the folder named like the library: �RTClib�. If this is a copy of RTClib-aging-offset, it should work. > ```text > error: 'class RTC_DS3231' has no member named 'readAging' > error: 'class RTC_DS3231' has no member named 'setAging' > ``` I named the methods `getAgingOffset()` and `setAgingOffset()`, for consistency with the current naming conventions and the datasheet. > If you can write a minimalised demo sketch that you think should compile with your version of RTClib then I'll try that. This compiles: ```c++ #include <RTClib.h> constexpr int8_t calibratedAgingOffset = -50; RTC_DS3231 rtc; void setup() { rtc.begin(); Serial.begin(9600); Serial.print("Initial aging offset: "); Serial.println(rtc.getAgingOffset()); rtc.setAgingOffset(calibratedAgingOffset); Serial.print("New aging offset: "); Serial.println(rtc.getAgingOffset()); } void loop(){} ``` > Comparison of .cpp and .h: [...] OK, as expected. For the record, here is the [diff between adafruit:master and edgar-bonet:aging-offset][diff], as computed by GitHub itself. [diff]: master...edgar-bonet:aging-offset

[edgar-bonet]

I indeed do not have a DS3231.

Can you, perhaps with help from another expert, suggest a sketch and schematic I can test that would give you confidence?

I just wrote the test sketch below. The required connections are:

• Arduino's I2C pins to a DS3231
• Arduino's USB port to a computer running either the Arduino's serial monitor or a terminal emulator

Source code (click to expand/collapse)

#include <RTClib.h>

#ifdef MOCK_RTC

/* Mock DS3231 for testing this sketch without the actual hardware. */
class Mock_RTC_DS3231 : public RTC_Micros {
public:
    void begin() { RTC_Micros::begin(DateTime(F(__DATE__), F(__TIME__))); }
    int8_t getAgingOffset() { return aging_offset; }
    void setAgingOffset(int8_t offset) {
        aging_offset = offset;
        adjustDrift(-aging_offset * 200);  // exaggerate drift
    }
private:
    int8_t aging_offset;
};

#define RTC_DS3231 Mock_RTC_DS3231

#endif  // defined(MOCK_RTC)

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());
    }
}

The sketch is controlled by single-character commands sent through the serial port. Send h to get a summary of the available commands. You may check that:

• printing the aging offset gets what you would expect
• setting the RTC to run fast makes it run fast
• setting it to run slow makes it run slow

I tested the sketch using a mock RTC which I left there for the record. It will not be used unless you #define MOCK_RTC.

[terrypin999]

OK, hope to be able to look at that tonight. But yesterday I found I DID have another DS3231, as my AZ delivery last year was a pack of two. So I assume I just run your sketch with this single line commented out? #define RTC_DS3231 Mock_RTC_DS3231 ====================

…

On Tue, 26 Mar 2024 02:37:33 -0700, you wrote: I indeed do not have a DS3231. > Can you, perhaps with help from another expert, suggest a sketch and schematic I can test that would give you confidence? I just wrote the test sketch below. The required connections are: * Arduino's I2C pins to a DS3231 * Arduino's USB port to a computer running either the Arduino's serial monitor or a terminal emulator <details><summary>Source code (click to expand/collapse)</summary> ```c++ #include <RTClib.h> #ifdef MOCK_RTC /* Mock DS3231 for testing this sketch without the actual hardware. */ class Mock_RTC_DS3231 : public RTC_Micros { public: void begin() { RTC_Micros::begin(DateTime(F(__DATE__), F(__TIME__))); } int8_t getAgingOffset() { return aging_offset; } void setAgingOffset(int8_t offset) { aging_offset = offset; adjustDrift(-aging_offset * 200); // exaggerate drift } private: int8_t aging_offset; }; #define RTC_DS3231 Mock_RTC_DS3231 #endif // defined(MOCK_RTC) 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()); } } ``` </details> The sketch is controlled by single-character commands sent through the serial port. Send `h` to get a summary of the available commands. You may check that: * printing the aging offset gets what you would expect * setting the RTC to run fast makes it run fast * setting it to run slow makes it run slow I tested the sketch using a mock RTC which I left there for the record. It will not be used unless you \#define MOCK\_RTC.