TimeLib library functions

Projects Programming
1

Hello
I've been exploring some of the many TimeLib.h functions etc, but there's one that is stumping me still after a lot of trawling through the search engines - it's void breakTime(time_t time tmElements_t &tm); // break time_t into elements.

From the libray notes

breakTime(t, tm);

Convert a time_t number to normal date & time. The tm input is a TimeElements variable which breakTime fills with the 7 numbers, computed from the "t" input.

I'd be grateful if someone could give a pointer as to what the"tm input" is.

I appreciate that hours(t) etc. do much the same, but this is a bit of unfinished business.
Eventually, I want to do a sketch that demonstrates all the functions for future reference.

Thanks

2

What is the question?

Convert a time_t number to normal date & time. The tm input is a TimeElements variable which breakTime fills with the 7 numbers, computed from the "t" input.

fairly accurately describes what it does.
I woudn't use the term "normal date & time" as what does "normal" mean?
I would use words like what is in the description in the comment from the Time.h header file:

void breakTime(time_t time, tmElements_t &tm);  // break time_t into elements

tm is a pointer to a TimeElements or tmElements_t structure.
The call converts the epoch time_t variable into its date and time components to allow printing for humans.

Note that the Time library is not timezone aware so it can't track real/true epoch time and provide true local time.
I think if Michael had not lived in the London area (which uses GMT) then it would be likely that the library would have included timezone support.

--- bill

3

Thanks Bill
I'm afraid I'm none the wiser.
Am I right in thinking that it takes a long number like the Unix number 123456789 and breaks it up into hour , minutes etc?
But is the output an array or something?
You'll have blame the libray writer Paul Stoffregen or MM for the normal date and time bit as it was a straight lift out of Github.
I have got a copy of Jack Christensen's TimeZone library
Have to admit that I'm a bit out of my depth on this, like most coding issues, amateur only

4

bperrybap:
tm is a pointer to a TimeElements or tmElements_t structure.

reference

tigger:
But is the output an array or something?

it is a struct

5

The Time library is based on standard unix time API functions.
The API is nearly the same with a few annoying differences beyond the camelback name changes.
The unix time API functions have existed for 40+ years. (almost 50)

BulldogLowell:
reference

The code obviously.

tigger:
Thanks Bill
I'm afraid I'm none the wiser.
Am I right in thinking that it takes a long number like the Unix number 123456789 and breaks it up into hour , minutes etc?
But is the output an array or something?

Again, breakTime() takes a unix epoch time_t value specified by time and breaks into the various date and time components and stores them a tmElements_t or TimeElements structure (same thing) as pointed to by the second argument tm.

update:
Note the API function breakTime() is using a C++ call by reference for the TimeElments structure parameter.
Please ignore the comments below about using a pointer to the TimeElements structure.

The only potentially confusing part is that the prototype for breakTime() is using C++ syntax for the pointer. (see the & in the prototoype? that is what I'm talking about)
This allows the application to call the function either of two ways and the compiler will handle it.
The user can specify:
note: this call using a reference to a TimeElements structure is correct

breakTime(epochvalue, tmElementsVarName);

or
note: this call using a pointer a TimeElements structure incorrect

breakTime(epochvalue, &tmElementsVarName);

You'll have blame the libray writer Paul Stoffregen or MM for the normal date and time bit as it was a straight lift out of Github.

I do not see the words about "normal date and time" you mention in the actual source code.
The actual code uses these words:
from Time.cpp

void breakTime(time_t timeInput, tmElements_t &tm){
// break the given time_t into time components
// this is a more compact version of the C library localtime function
// note that year is offset from 1970 !!!

from TimeLib.h

void breakTime(time_t time, tmElements_t &tm);  // break time_t into elements

Since this is open source, you can always look at the code to see how it works and what it is doing.

--- bill

6

bperrybap:
The code obviously.

no... read the quote, the code uses a reference not a pointer

7

BulldogLowell:
no... read the quote, the code uses a reference not a pointer

Insert foot in mouth...
Yeah I knew it was a reference.
My mistake was stupidly/foolishly assuming that the compiler would accept a pointer argument to a function that was using a reference argument as long as the types were the same.

Under the hood from a code generation point of view, and access to the output data,
code that uses C++ by reference should be the same as code that use a pointer.

By reference is quite a bit more convenient.

(i'll go back an put a note in that previous post to reflect my stupidity)
--- bill

8

Oh wow lads.
Please excuse my ignorance. All I'm asking is how to to use the b****y thing.
How do I turn a long time number into hours, mins etc.?
Structures, pointers etc. mean not a lot to me. It's not Trump vs Kim il whatsit.
I have no formal coding experience/training, but I do like to get things to work whether it's cut and paste or whatrever. I spend half my day battling the sodding tax-dodgers, government and do this for a little mental exercise. A working example or a hint of what to look for would help a lot. I don't have the hours in the day to be an expert. For me, just to get a real time clock working is a milestone achievement.
As for

I do not see the words about "normal date and time" you mention in the actual source code.

, this was cut from one of the libraries under the section

Usage with 32-Bit "time_t"

-I don't dream it up.
I'm always grateful for replies, but do accept that users range in experience and ambition and it's a long time since I did homework

9

you can think of breakTime() as a method of decoding a Unix timestamp into its constituents of time of day, day of the year and so on.

It is delivered to you in a struct (google C++ struct) from which you can easily glean all of the respective components.

that is all there is to it.

likewise, from the respective elements of time, you can use makeTime() to create a timestamp.

10

Cheers Bulldog
Interestingly, I got makeTime to work, no trouble, but then, it's simpler to use.
I will indeed check out C++ struct.
Do I take it you're from North of the Border? A southerner here, but rapidly falling out of love with it. I feel the Lochs calling. Takes me back to MacFisheries.

11

tigger:
Oh wow lads.
Please excuse my ignorance. All I'm asking is how to to use the b****y thing.
How do I turn a long time number into hours, mins etc.?

but hours, mins, etc... is not a time or a date

The unix epoch is midnight jan 1, 1970. The time_t value represents seconds since the epoch.
Knowing how many hours and mins since then is typically not very useful and it is actually not a simple calculation since there are leap years involved.
I'm guessing that hours and minutes, etc, is probably not what you are actually looking for.

Usually what is wanted is the human readable date and time components/elements such as month number, day of month number, hour of time, minute of time,etc...

And for that you use breakTime() it converts the time_t into its time elements (with no adjustment for timezone) and stores them the TimeElements structure you pass to it.
You can then you grab what you want from that structure as it has all those date and time element values in it.

Structures, pointers etc. mean not a lot to me. It's not Trump vs Kim il whatsit.

You will need to understand these to get very far as they are very basic concepts for the C/C++ language.

While you have not said specifically what you want, it sounds like you are wanting the date and time components represented by the epoch value.
Those values will be in the TimeElements data structure that you passed to breakTime() when it returns.

The definition of the TimeElements structure in the TimeLib.h header file.
You can see all the members.
You reference them through the data structure.
i.e.
tmName.Hour
tmName.Minute
tmName.Month

etc...
Just keep in mind that Year is relative to 1970 and not an actual year.

In terms of time zone support, while Jack's TimeZone library does work quite well, it is not the way timezones are normally handled on unix machines since normally there is a localtime() function that is timezone aware that handles it.
Since the Time library is not timeZone aware you must play games to offset the epoch value (which is actually changing the time) to trick the breakTime() code to providing the date & time elements for the local timezone.

Whenever tracking epoch time and using the Time library you must decide if you really need to track the REAL datetime of things or not.
The value of using the REAL time epoch is that no mater what timezone you are in the REAL time is always the same.
This can be valuable if you need a true time stamp.
But with this comes the issue of correcting for local time if the human ever wants to see the time based on the local timezone.

If on the other hand you don't need timezone independent timestamps, you can cheat and just pretend you are in london and not mess with timezones at all.
Yes the actual time represented by the epoch time_t value will be incorrect, but it doesn't matter since the local time displayed will still be correct.
So if localtime is all you need, it is simpler to ignore timezones.

--- bill

12

Taken from TimeLib.h:

typedef unsigned long time_t;

typedef struct  { 
  uint8_t Second; 
  uint8_t Minute; 
  uint8_t Hour; 
  uint8_t Wday;   // day of week, sunday is day 1
  uint8_t Day;
  uint8_t Month; 
  uint8_t Year;   // offset from 1970; 
} 	tmElements_t, TimeElements, *tmElementsPtr_t;

Here is a little sketch that puts it all together:

#include <TimeLib.h>

time_t anUnsignedLongContainingAUnixTimeStamp = 1510508760; //Number of seconds since 1970-01-01-00:00:00 (Unix EPOCH)
tmElements_t sevenIntegersInAStructure;

void setup() {
  // put your setup code here, to run once:
  Serial.begin(9600);

  breakTime(anUnsignedLongContainingAUnixTimeStamp, sevenIntegersInAStructure);

  Serial.println(sevenIntegersInAStructure.Year + 1970);
  Serial.println(sevenIntegersInAStructure.Month);
  Serial.println(sevenIntegersInAStructure.Day);
  Serial.println(sevenIntegersInAStructure.Wday);
  Serial.println(sevenIntegersInAStructure.Hour);
  Serial.println(sevenIntegersInAStructure.Minute);
  Serial.println(sevenIntegersInAStructure.Second);
}

void loop() {
  // put your main code here, to run repeatedly:

}

Jacques

13

tigger:
Oh wow lads.
Please excuse my ignorance. All I'm asking is how to to use the b****y thing.
How do I turn a long time number into hours, mins etc.?
Structures, pointers etc. mean not a lot to me. It's not Trump vs Kim il whatsit.
I have no formal coding experience/training, but I do like to get things to work whether it's cut and paste or whatrever. I spend half my day battling the sodding tax-dodgers, government and do this for a little mental exercise. A working example or a hint of what to look for would help a lot. I don't have the hours in the day to be an expert. For me, just to get a real time clock working is a milestone achievement.
As for , this was cut from one of the libraries under the section -I don't dream it up.
I'm always grateful for replies, but do accept that users range in experience and ambition and it's a long time since I did homework

Chill. The example sketches that ship with the library demonstrate the usage quite well. You can almost cut and paste from those. But there is far more value in it in the usages that you can dream up yourself.

14

aarg:
The example sketches that ship with the library demonstrate the usage quite well.

Actually, tigger does have a point.
While the examples do show how to get date/time elements from a time_t value using the functions for extracting each element like hour() or minute(), they don't show how to use breakTime() and get the elements from the tmElements_t structure.

Even though it is straight forward and quite simple, the library doesn't come with any "hand holding" examples that show how to do it.

--- bill

15

Thank you all for your contributions which I will go through and will make every effort to understand and get this to work. Despite what aarg says, I wouldn’t be here if I had found even one example that showed breakTime in action
It is hard for anyone without formal training to get their heads around the precise workings of one language, let alone two.
I like to make things work and try never to give up - my whole working career has been about solving problems in an industry that is fundamental to public health and I would get involved when the day-to-day operators had hit the buffers with a problem. I quite often threw solutions at it until one stuck which gave you breathing space, then remove them one by one at leisure until you find out the root cause.
There are contributors on the forum who eat and sleep code and have scant regard for those who aren't so fluent and belittle their efforts - with the right reasons at heart. Everyone starts somewhere and the Arduino user community covers the whole range of abilities. Others with huge knowledge on the subject freely make their knowledge available to all. Not a lot of point in taking a lifetime's knowledge to the MCU in the sky. I know what's behind quotes like "get your wallet out", but it's all about open source.
I use cut and paste a lot and rely heavily on tutorials and examples - I don't need or want to spend hours in what is already a busy day learning every full stop to get an LED to flash. I can't remember where I first heard about Arduino, but it opened up a whole new interest.
Right now I'm working on an MSF clock project, but rather than just buy the ferrites and a decoder, I'm winding my own coils and putting RF amplifiers together - I'm going through a completely new subject, namely radio reception and already it has been satisfying just to get a resonant circuit plumb on 60-kHz. Never heard of Litz wire before. Even dug the old crystal set out. My eureka moment was as a child discovering that connecting a torch lamp to an EveryReady battery with a couple of bits of fuse wire made light.
Arduino Cookbook is my bedtime reading, with others, but write the book, not in an epoch.
I'll let you know how I get on, and thanks again.

16

Thank you Jacques
That demonstrates it nicely
I would have struggled to get that to work
Now all the other replies will start to make sense as will "structure"
Most grateful

tigger

17

Glad I could Help.

Jacques

18

Has someone experiencing same issue?

When I use time_t structer and functions like day(), month(), year(), I am getting different date.
I put "Feb 18 2019" date to time_t structer, but I get 19.1.2019.

Example:

DS3231 rtc;

rtc.begin();
rtc.setDateTime("Feb 18 2019", __TIME__); 


time_t dateTime;
dateTime = rtc.getDateTime().unixtime;

String dateString = String(day(dateTime)) +  '.' + String(month(dateTime)) + '.' + String(year(dateTime));

//dateString contains 19.1.2019 ?!

It seems, that function breakTime is not working properly.

19

Has someone experiencing same issue?

Your issue have NOTHING to do with the TimeLib library. Why did you post it here?

Why did you not post a link to the library you are using?

20

I think that month(time_t t) and others functions are from Time.h.