Unix / Epoch time

Unix time (also known as POSIX time or Epoch time) is a system for describing instants in time, defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, not counting leap seconds. It is used widely in Unix-like and many other operating systems and file formats.

Example: 1419086327 (2014-12-20T14:38:47Z)

Waspmote API defines some functions to use this time format which can be useful in order to translate dates into seconds and perform addition or subtraction of time.

An example of the functions that are shown below: https://development.libelium.com​/​rtc-08-unixepoch-time/

Getting Epoch time

The function getEpochTime() permits to calculate the Unix time associated to a specific year, month, day, hour, minute and second values. It is possible to indicate these values as input or use the current values of the RTC.

Example of use:

{
	 // Define variable to store Epoch time
	 unsigned long epoch;
	 // Example: Get Epoch time from RTC values
	 epoch = RTC.getEpochTime();
	 // Example: Get Epoch time from input values(i.e: 2014-12-20 at 14:38:47)
	 epoch = RTC.getEpochTime( 14, 12, 20, 14, 38, 47 );
}

The function getEpochTime() updates the RTC attributes because it calls getTime() function.

Breaking Epoch time into 'Time and Date'

The function breakTimeAbsolute() permits to convert the input epoch time to time and date values (as UTC components). Thus, it can be useful to add/subtract times. For example: get Epoch time from RTC and add several seconds to calculate a new time instant.

The structure called timestamp_t is defined in WaspRTC class for converting epoch time into UTC timestamps.

Example of use:

{
	 // Define variable for UTC timestamps
   timestamp_t time;
   // Break Epoch time into UTC time
   RTC.breakTimeAbsolute( epoch, &time );

   // Available info: UTC Date
   USB.print( time.year, DEC );
   USB.print( time.month, DEC );
   USB.print( time.date, DEC );
   USB.print( time.hour, DEC );
   USB.print( time.minute, DEC );
   USB.print( time.second, DEC );
}

The function breakTimeOffset() permits to convert the input (great period of seconds) into offset time values (as the number of days, hours, minutes and seconds that the input argument defines). Thus, it can be useful to add/subtract times. For example: get Epoch time from RTC in different instants and then calculate the difference as number of days, hours, minutes and seconds.

The structure called timestamp_t is defined in WaspRTC class for converting great periods of seconds into number of days, hours, minutes and seconds.

Example of use:

{
	 // Define variable for timestamps
	 timestamp_t time;
	 // Get offset time from ‘411361’ seconds
	 RTC.breakTimeOffset( 411361, &time );

	 // Available info: ‘4’ days, ‘18’ hours, ‘16’ minutes and ‘1’seconds
	 USB.print( time.date, DEC );
	 USB.print( time.hour, DEC );
	 USB.print( time.minute, DEC );
	 USB.print( time.second, DEC );
}