Time variable -- format?(SOLVED)

I'd like to manipulate the time variable "t" directly, but can't seem to find anything on it's structure. For example, is it an unsigned long? Just a count of ticks since 1 Jan 1970, or maybe a byte-oriented BCD string, or what?


Where does one find this variable t?

I could tell you what the variable t does in the code I last wrote, but I'm smart enough to never use one letter variables. If I had named a variable just "t" it would definitely be the counter in a for loop and have nothing to do with time.

In your code... Well, I can't see that code can I? So how am I supposed to know anything about this variable that is called t in your code. It could be holding unix time or it could be holding a pin number for all I know.

Why don't you post the code you're asking about? Or shall we all take random wild guesses at what variable might be called t and what it might be intended to do.

Just a count of ticks since 1 Jan 1970

Seconds, not ticks.

Who's Clive?

One finds this variable in the Arduino Reference for the Time Library.

Forgive me for assuming that the "Time Library" from the Arduino Reference was using a reserved variable "t".

From the Reference:

time_t t = now(); // Store the current time in time
                    //  variable t
  hour(t);          // Returns the hour for the given
                    //  time t
  minute(t);        // Returns the minute for the given
                    //  time t
  second(t);        // Returns the second for the given
                    //  time t
  day(t);           // The day for the given time t

  weekday(t);       // Day of the week for the given
                    //  time t  
  month(t);         // The month for the given time t

  year(t);          // The year for the given time t

What I am asking, is what is the form of the variable "t" when used in the code statement below:

setTime(t); // Set the system time to the given time t

If I know what the hour, minute, and second is, how do I build "t" so that it works in setTime()? I am not interested in the date, so if "t" is just the number of seconds' ticks since 00:00:00 on 1 Jan 1970, then "t" is easy to build mathematically, except how long/big/wide is the variable? Do I have to create it with time_t? Mathematically how do I assign a value to it? Please don't tell me to use:

setTime(hr,min,sec,day,month,yr); // Another way to set the time

because this sets the system time, not the variable [in this case] "t". And if I did set system time using setTime() in this way, I'd still have to read time using now(), which means I still need to know what the format of the return is for now().

An unsigned long can hold 4,294,967,296 ticks, enough for 100 years plus a little.

If you're still reading, please read "byte" as "4-bits". "Word" as "16-bits." Yeah, I know, it doesn't conform. But what is it that many sketches do when they do "BCDtodecimal" and vice versa? I think they are working on 4-bit somethings that I think is a byte.

I can now see that "t" could be "x" or "whogivesacrapabouttime" or whatever. Which raises another question. Is there a reserved system variable for time, a reserved word/byte/long/reallylong? Can it be accessed directly?

Actually, I guess I don't need direct access to the system time variable if I know what form now() returns. I'm getting the idea that time_t creates a variable with properties not shared by an unsigned long. Right?

So, once again, if I execute code "t=now()", what does "t" look like?

  1. Unsigned long and can be manipulated as such?
  2. 64-bit BCD by byte? (year_hi, year_low, month, day_hi, day_low, hour_hi, hour_low, minute_hi, minute_low, seconds_hi, seconds_low, day_of_week)
  3. 64-bit decimal by byte [needs one more byte] (year_hi, year_low, month_hi, month_low, day_hi, day_low, hour_hi, hour_low, minute_hi, minute_low, seconds_hi, seconds_low, day_of_week) If I got this right, this format could do 100 years less one second, and still have three 4-bit bytes left over.
  4. Some other oddity with unique properties?

Thanks. I anticipate some readers will want more detail. Just ask.

ps--thanks, PaulS. You replied while I was venting. If it's just ticks (that would be seconds' ticks), can it be manipulated like an unsigned long?

pps--Clive? Did I misspell something earlier?

time_t t = now();

That's just the example code. They created a variable called t in that code. It could have been named Tom, Dick, or Harry it doesn't matter. What matters is that it is of type time_t.

If you look in the header source for the Time library you find this line.

typedef unsigned long time_t;

Which means that it is really just a regular unsigned long.

Now for what it means that is another story. It gets populated with the value returned from now(). If you read the documentation for the library, it says that now() will return the number of seconds since midnight Jan 1 1970.

So in this example, t is a plain vanilla unsigned long holding the number of seconds UNIX time.

Thanks, Delta_G. Very simple. I need to start reading the "included" code. I have attempted that for other libraries and found them obscure, but this is simple enough.

My only question [rhetorical at this point] is why would someone create an obscure typedef when they could just use a readable "unsigned long"? I consider that the worst maneuver in code writing--making code undecipherable. You can use plain language or you can be a lawyer.

One question remains. Is there named/reserved system time [unsigned long] variable? Or does setTime() work some machine-level code magic? The code in the Time Library has to work on something.

One question remains. Is there named/reserved system time [unsigned long] variable? Or does setTime() work some machine-level code magic? The code in the Time Library has to work on something.

The millis() function will return the number of milliseconds since the last time the board was reset as an unsigned long. After you set the real world time, the time library just uses millis() to see how long it has been since then and keep up with the unix time that way. The caveat is that you have to set the time each time the board is reset because it can't hold onto that time while the power isn't there.

Thanks, everyone. I should have examined Time.cpp and Time.h before I asked the question. Live and learn.

I’ve dived into the Time.cpp and Time.h and conclude that either (1) the system time variable is not directly accessible because it is not global or (2) maybe “sysTime” can be accessed, but it won’t be current unless “setTime()” has been executed. I’ll have to compile a little program to find out. In the code below it shows that “now()” returns sysTime, which is updated in a call to “setTime()” (note: internally Time.cpp uses “t” as the unsigned long to store time in seconds’ ticks–so much for not using a single letter as a major variable, or am I not reading this correctly? Yes, I understand that as a local variable it’s “invisible.”):

time_t now(){
  while( millis() - prevMillis >= 1000){      
    prevMillis += 1000;	
    sysUnsyncedTime++; // this can be compared to the synced time to measure long term drift     
  if(nextSyncTime <= sysTime){
	if(getTimePtr != 0){
	  time_t t = getTimePtr();
      if( t != 0)
        Status = (Status == timeNotSet) ?  timeNotSet : timeNeedsSync;        
  return sysTime;

void setTime(time_t t){ 
 if(sysUnsyncedTime == 0) 
   sysUnsyncedTime = t;   // store the time of the first call to set a valid Time   

  sysTime = t;  
  nextSyncTime = t + syncInterval;
  Status = timeSet; 
  prevMillis = millis();  // restart counting from now (thanks to Korman for this fix)

In Time.h, I see the following enumerated time-variables and the one structure (repeated three times), but everything else seems to be simple unsigned longs–no unique properties.

typedef enum {timeNotSet, timeNeedsSync, timeSet
}  timeStatus_t ;

typedef enum {
    dowInvalid, dowSunday, dowMonday, dowTuesday, dowWednesday, dowThursday, dowFriday, dowSaturday
} timeDayOfWeek_t;

typedef enum {
    tmSecond, tmMinute, tmHour, tmWday, tmDay,tmMonth, tmYear, tmNbrFields
} tmByteFields;	   

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;

Bottom line is, I can build a conforming variable “t” to update sysTime and can read and parse the time returned by now(), without needing direct access to the local variable(s) in the time functions.

My application is a distributed radiant heat control system where the central unit has an RTC and sends out updated time messages a couple times a day via serial link to the remote units, which apply the update and then use their local CPU clock and Time.cpp functions to display time-of-day.