Improve the examples and documentation

[rin67630]

IMHO since this is this standard Arduino library for NTP, it would avoid a lot of mistakes if its functionality and limitation would be described a bit more elaborated:

It should be important to point out that this library is NOT intended to provide a full date/time functionality and will be limited to provide a time information without provision for daylight saving times, keeping the library sleek, since the overhead to compute an accurate date with respect to leap seconds is not really trivial and requires else quite a lot of resources.

On the other side, the library provides the functionality to return split numbers by seconds, minutes and hours, which is not mentioned in the given examples.

  Second  = timeClient.getSeconds();
  Minute  = timeClient.getMinutes();
  Hour    = timeClient.getHours();
  Weekday = timeClient.getDay();
  Epoch   = timeClient.getEpochTime();

That should be mentioned, since examples are limited to print a string, which means frequently a lot of lost time to find the correct method of getting the required information, which is unfortunately pretty different for each library.

I hope you could take that request into consideration.

[WhymustIhaveaname]

Leap second is a tricky thing. Apparently, this library does not provide the functionality of leap seconds correction. However, surprisingly, the time given by this library is the same as the NTP service on my Ubuntu and the standard time given by the China government. Up to now, there have been about 20 leap seconds. So if there were a leap-second problem, that must be a noticeable error that I never encounter. My opinion to leap second is, "it works, do not touch it".

As for daylight saving times, as far as I know, only Americans use it. And it is such a complicated system. I think we should cancel daylight saving times rather than add this dummy thing into every time library.

There are many other problems(and bugs) in this library and its examples. I also submit some issues and PRs(see issue101 and pull102). But no one contacts me. Some older PRs have not been merged for one or two years.

[rin67630]

Hmm... daylight saving time is heavily used in Europe.
But i did not require the date parts to be processed in NTPClient.
It is fine to get a sleek library to deliver time + week days without date.
I just think, it should be documented. and the examples should provide what the library can deliver.

[rin67630]

Finally i have written a didactic example to use NTP Client in an ESP ecosystem providing many useful variables, full date information and being Posix-compliant string/char array techniques for further use in sketches written for other libraries.
This is NOT another library!
I just used the c++ methods provided by the Espressif libraries, that comes anyway!
This is just an example to start with avoiding crippling one's code with useless/nocive libraries!
Enjoy!
https://github.com/rin67630/NaTLibESP

[WhymustIhaveaname]

daylight saving time

sorry I did not know daylight saving time is so widely used over the world.

I agree with you that this library needs a better document.

[kaynohtee]

what is the increment for time offset? at first it seems to be minutes. 60 minutes offsets the output time by an hour. 120 minutes offsets by two hours. 180 minutes three hours... BUT 240 minutes offsets by 20 hours.
Maybe an example of usage for offset time would be good.

[blaskovicz]

@kaynohtee it's epoch offset in seconds:

// use New_York epoch seconds offset
NTPClient timeClient(ntpUDP, -14400);

eg: https://www.epochconverter.com/timezones

As above mentioned though, this doesn't handle DST so it's tricky...