Document time-setting functions

[IowaDave]

This PR introduces documentation for the time-setting functions.

Also it adds a missing html tag to the time-retrieval functions file.

[IowaDave]

@jneurnberg: please review this submission. I think reviewing is a good idea and would appreciate the benefit of your eyes on this work.

If the file meets your approval please go ahead and merge the PR. Andrew has asked you and me to exercise our initiative and update the repo as we see the need.

Much appreciated,

David

[awickert]

I'll perform the review just now because there are a couple citation requests that I would like to add to the README, and I don't want to cause an edit conflict.

[edit] Ah, this is silly of me. You are editing other files. Got it. So long as a casual user will find all the content!

[IowaDave]

I apologize for causing confusion and concern over terminology. It's your site; I am grateful to have the benefit of your edits. Glad you took the time to catch and correct my errors.

Is there anything left waiting for me to do on this PR?

[awickert]

@IowaDave: I'm not sure what you mean about errors. Could you clarify?

I hunted through the code for setEpoch(time_t, bool) and found the following:

// setEpoch function gives the epoch as parameter and feeds the RTC
// epoch = UnixTime and starts at 01.01.1970 00:00:00
void DS3231::setEpoch(time_t epoch, bool flag_localtime) {
	struct tm tmnow;
	if (flag_localtime) {
		localtime_r(&epoch, &tmnow);
	}
	else {
		gmtime_r(&epoch, &tmnow);
	}
	setSecond(tmnow.tm_sec);
	setMinute(tmnow.tm_min);
	setHour(tmnow.tm_hour);
	setDoW(tmnow.tm_wday + 1);
	setDate(tmnow.tm_mday);
	setMonth(tmnow.tm_mon + 1);
	setYear(tmnow.tm_year - 100);
}

I checked documentation on localtime_r and gmtime_r, and confirmed that both should be with respect to Unix Epoch, and that gmtime is in fact also UTC (whew).

Could you confirm that in your tests you have seen that "epoch" is the start of 2000? I don't have any hardware to perform this test with me at the moment.

(Aside: The setEpoch function was added for v1.1.0 by @hasenradball: c5356092a911c9225b8a643ab054de0446c090b3.)

[hasenradball]

Hi together, let me discuss with you, yes I introduced the function setEpoch. My intention was e.g. if using an ESP8266 sychronize the time via network and if done the time of the CPU is based on UNIX time. And then I am able to query the time from ESP8266 and set the time of the DS3231. I will search the example how I use it.

Here is my example for the ESP8266.

  //  // Get Time from WLAN
  Wifi wlan(SSID, PASSWORD);
  MESZ uhr("192.168.178.1");

  if (wlan.Wifi_Connect()) {
    while (!MESZ::get_time_synchronized()) {
      yield();
    }
    char buffer[9];
    uhr.get_timeformatted(buffer, sizeof(buffer), "%X");
    DBG__PRINT(buffer);

    if (!digitalRead(PIN_CLOCK_SET)) {
      Clock.setEpoch(uhr.getTimeUnix(), true);
      // Set Clock if Pin is at Low Level
      // set to 24h
      Clock.setClockMode(false);
    }
  }
  //DBG__SERIALEND();
  wlan.Wifi_Disconnect();
  wlan.Wifi_Stop();
}

The function getTimeUNIX()return the seconds since Thu 01.01.1970 - 00:00. But if this is so, and the time of the DS3231 starts at 01.01.2000, then my constructor is wrong, I would say from today perspective, right?

If the DS3231 starts at 2000, then it the Sat 01.01.2000 - 00:00.

My Idea behind was to query the time from cpu and set the DS3231.

[hasenradball]

Please letz s discuss and correct the failures if there are.

[hasenradball]

I took a small recherge actually, Maybee I had in mind the NTP time which starts on 1. Januar 1900, 00:00:00. Thus I subtracted 100 Years buts that' s wrong. We had to consider the1970's.

how should we proceed?

[awickert]

Let's make it work as intended in the comments, with the unixtime offset.

See: https://github.com/NorthernWidget/DS3231/pull/65

I'll release a patch after this.

Also commenting here: #53.

[IowaDave]

Hello everyone. It seems best to me that we abandon this PR for documentation of the time-setting functions.

The DS3231::setEpoch() method is undergoing revision. Bring that effort to a successful conclusion should be our priority. After that is done, the draft document in this PR will be out of date.

I propose to withdraw ("close?") this PR, then wait for the fix to setEpoch(). I will make it a priority to re-submit an updated document as soon as possible after the fix gets merged into the Master branch.

Do not worry. I am a retired old man with time on my hands. I need things to do. It will not take long! (he grins)

Meanwhile, I have two more documentation Markdown documents ready to push upstream, and a third almost completed. They cover: managing the hardware, the DateTime object, and the alarm functions. The latter goes into detail about the AlarmBits and could resolve issue #20.

I have been waiting for this PR to be resolved one way or the other before submitting additional PRs. Closing this one at the present time would allow me to move forward with those others.

Will check back here tomorrow. If no one has any objection by then, I would like to withdraw (close) this PR rather than pursue merging it.

Thanks,

David

[IowaDave]

@awickert @hasenradball , This first draft documentation for time-setting functions will be out of date after the PR offered by @hasenradball is merged. There were some other issues mentioned about the draft, too. In my mind it adds up to a conclusion that the work needs a thoughtful re-write. I think it is best to close the first-draft documentation PR at this time. After the setEpoch() function gets updated then I will re-visit the documentation.

[hasenradball]

@IowaDave whats about the changes for the recalculation of unix time? Will you do a PR for this? An maybe the doc should be done after the setEpoch() Bugfix and after the Unitime() rework was merged.

[IowaDave]

Working presently on a PR for calculating UnixTime in DateTime. Also working on revisions to documentation to take account of topics we've been addressing. Actually want to complete my whole set of documentation files this week.

Feeling really grateful that you recruited additional contributors to pitch in on this project. I appreciate that everyone is busy. Yet they show up for the work. Someone once said, "If you want something done, ask a busy person to do it!"

Thanks,

David

On Sun, Aug 21, 2022 at 6:16 AM Hasenradball @.***> wrote:

@IowaDave https://github.com/IowaDave whats about the changes for the recalculation of unix time? Will you do a PR for this? An maybe the doc should be done after the setEpoch() Bugfix and after the Unitime() rework was merged.

— Reply to this email directly, view it on GitHub https://github.com/NorthernWidget/DS3231/pull/60#issuecomment-1221524935, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIOVVUHOMN3N7YV3TGBQISDV2IF2NANCNFSM556MNFZQ . You are receiving this because you were mentioned.Message ID: @.***>

[hasenradball]

@IowaDave Hi David sorry I think I didn t understand your question clearly.

[hasenradball]

maybe I will not clearly unsterstand all process behind the scenes of this library. I just added the setEpoch() functiion in the past.