Arc Time Lib2
https://playground.arduino.cc/Code/Time/
Arduino Time library
The Time library adds timekeeping functionality to Arduino with or without
external timekeeping hardware. It allows a sketch to get the time and date as:
second, minute, hour, day, month and year. It also provides time as a standard
C time_t so elapsed times can be easily calculated and time values shared across
different platforms.
Update: newer versions of Time, TimeAlarms, and DS1307RTC are available,
featuring more updates for newer version of the Arduino IDE and compatibility
with Arduino Due.
The code is derived from the earlier Playground DateTime library but is updated
to provide an API that is more flexible and easier to use.
This old download does not work on Arduino 1.6.1. Use the links above. Time
includes example sketches illustrating how similar sketch code can be used with:
a Real Time Clock,Internet NTP time service, GPS time data, DCF77 radio signal,
and Serial time messages from a computer. To use all of the features in the
library, you'll need the UdpBytewise library, found here.
Additional documentation is included in a readme.txt file
Functional Overview
hour(); // The hour now ( 0-23 )
minute(); // The minute now ( 0-59 )
second(); // The second now ( 0-59 )
day(); // The day now ( 1-31 )
weekday(); // Day of the week ( 1-7 ), Sunday is day 1
month(); // The month now ( 1-12 )
year(); // The full four digit year: ( 2009,
// 2010 etc )
there are also functions to return the hour in 12 hour format
hourFormat12(); // The hour now in 12 hour format
isAM(); // Returns true if time now is AM
isPM(); // Returns true if time now is PM
now(); // Returns the current time as seconds
// since Jan 1 1970
The time and date functions can take an optional parameter for the time. This
prevents errors if the time rolls over between elements. For example, if a new
minute begins between getting the minute and second, the values will be
inconsistent. Using the following functions eliminates this problem
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
Functions for printing out string descriptions for day and month
monthStr()
monthShortStr()
dayStr()
dayShortStr()
Be aware that a parameter is required for this string functions. The argument is
NOT the timestamp, e.g. time_t, but must be something like month(). So
monthStr( month() ) or dayStr( weekday() ) will work.
See also the TimeSerialDateStrings.ino example sketch in the Time library
Functions for managing the timer services are:
setTime( t ); // Set the system time to the
// given time t
setTime( hr,min,sec,day,month,yr ); // Another way to set
// the time
adjustTime( adjustment ); // Adjust system time by adding
// the adjustment value
// WARNING: this is not compatible with using a sync provider as it
// only adjusts the library system time and not time in the sync provider.
// This offset adjustment will be lost on the next time sync.
// If the time is moved forward, an immediate call to now() can get the time
// from the sync provider rather than the adjusted library system time.
// i.e. do not depend on now() to return an adjusted time when using
// a sync provider even when called immediately after adjustTime()
timeStatus(); // Indicates if time has been set and
// recently synchronized
// returns one of the following
// enumerations:
* timeNotSet // The time has never been set,
// the clock started at Jan 1 1970
* timeNeedsSync // The time had been set but a sync
// attempt did not succeed
* timeSet // The time is set and is synced
// Time and Date values are not valid if
// the status is timeNotSet. Otherwise
// values can be used but the returned
// time may have drifted if the status is
// timeNeedsSync.
setSyncProvider( getTimeFunction );// Set the external time
// provider
setSyncInterval( interval ); // Set the number of
// seconds between re-syncs
There are many convenience macros in TimeLib.h for time constants and conversion
of time units.
Using the Library Copy the download to the Library directory. The Time directory
contains the Time library and some example sketches illustrating how the library
can be used with various time sources:
- TimeSerial.ino shows Arduino as a clock without external hardware.
It is synchronized by time messages sent over the serial port.
A companion Processing sketch will automatically provide these messages
if it is running and connected to the Arduino serial port.
- TimeRTC uses a DS1307 Real Time Clock ( or DS3231 ChronoDot RTC* ) to
provide time synchronization.
To run this sketch the DS1307RTC library must be installed.
* The I2C 'DS3231' interface is very straightforward and
virtually identical to the register addresses of the popular DS1337
and DS1307 RTCs, which means that existing code for the Arduino,
Basic Stamp, Cubloc, and other controllers should work with no modification.
For reference purposes see >> https://www.adafruit.com/products/255
- TimeNTP uses the Arduino Ethernet shield to access time using the
internet NTP time service.
The NTP protocol uses UDP and the UdpBytewise library is required, see:
https://bitbucket.org/bjoern/arduino_osc/src/tip/libraries/Ethernet/
Note: This is out of date. For Arduino 0022, see the built in Udp NTP example,
and also see http://arduino.cc/en/Tutorial/UdpNtpClient.
-TimeGPS gets time from a GPS
This requires the TinyGPS library from Mikal Hart:
http://arduiniana.org/libraries/TinyGPS
Example sketch:
The test sketch uses a message on the serial port to set the time. A Processing
sketch that sends these messages is included in the download but you can test
this sketch by sending T1262347200 using the serial monitor ( this sets the time
to noon on Jan 1 2010 ). On a Unix system, you can set the time with the shell
command:
TZ_adjust=-8; echo T$( ( $(date + %s) +60*60* $TZ_adjust) ) > /dev/tty.usbserial-A8008pym
-- edit: The above code did not work for me in my Linux terminal, I wrote the
below script which worked. (I was using zsh and UnoR3)
/*H********************************************************************
*
**********************************************************************/
TZ_adjust = 5.5; d = $( date + % s ); t = $( echo "60*60*$TZ_adjust/1" | bc ); \
echo T$( echo $d + $t | bc ) > / dev / ttyACM0
( : sourceend: )
Adjust TZ_adjust value to your timezone and serial port to your Arduino.
( : source lang = c getcode: )
/*F********************************************************************
*
**********************************************************************/
#include <Time.h>
//************************* DEFINES ************************************
#define TIME_MSG_LEN 11 // TIME SYNC TO PC IS HEADER FOLLOWED BY Unix time_t
// AS TEN ASCII DIGITS
#define TIME_HEADER 'T' // HEADER TAG FOR SERIAL TIME SYNC MESSAGE
#define TIME_REQUEST 7 // ASCII BELL CHARACTER REQUESTS A TIME SYNC MESSAGE
//************************* PROTOTYPES ************************************
void digitalClockDisplay();
//************************* VARIABLES ************************************
// T1262347200 //noon Jan 1 2010
/*F********************************************************************
*
**********************************************************************/
void
setup()
{
Serial.begin( BAUD );
}
/*F********************************************************************
*
**********************************************************************/
void
loop()
{
if( Serial.available() )
{
processSyncMessage();
}
if( timeStatus() == timeNotSet )
Serial.println( "waiting for sync message" );
else
digitalClockDisplay();
delay( 1000 );
}
/*F********************************************************************
*
**********************************************************************/
void
digitalClockDisplay()
{
// DIGITAL CLOCK DISPLAY OF TIME
Serial.print( hour() );
printDigits( minute() );
printDigits( second() );
Serial.print( " " );
Serial.print( day() );
Serial.print( " " );
Serial.print( month() );
Serial.print( " " );
Serial.print( year() );
Serial.println();
}
/*F********************************************************************
*
**********************************************************************/
void
printDigits( int digits )
{
// UTILITY FUNCTION FOR DIGITAL CLOCK DISPLAY:
// PRINTS PRECEDING COLON AND LEADING 0
Serial.print( ":" );
if( digits < 10 )
Serial.print( '0' );
Serial.print( digits );
}
/*F********************************************************************
*
**********************************************************************/
void
processSyncMessage()
{
// IF TIME SYNC AVAILABLE FROM SERIAL PORT, UPDATE TIME AND RETURN TRUE
while( Serial.available() >= TIME_MSG_LEN )
{ // TIME MESSAGE CONSISTS OF HEADER & 10 ASCII DIGITS
char c = Serial.read() ;
Serial.print( c );
if( c == TIME_HEADER )
{
time_t pctime = 0;
for( int i = 0; i < TIME_MSG_LEN - 1; i++ )
{
c = Serial.read();
if( c >= '0' && c <= '9' )
{ // CONVERT DIGITS TO NUMBER
pctime = (10 * pctime) + (c - '0') ;
}
}
setTime( pctime ); // SYNC ARD CLOCK TO TIME RECEIVED ON SERIAL PORT
}
}
}
Here is a fragment from the TimeNTP.ino example sketch showing how the
syncProvider functionality simplifies the sketch code. This sketch gets time
from an Internet time provider ( NTP ) using the Arduino Ethernet shield. Note
that the loop code does not require any logic to maintain time sync. The Time
library will automatically monitor NTP and sync the time as necessary.
/*F********************************************************************
*
**********************************************************************/
void
setup()
{
Serial.begin( 9600 );
Ethernet.begin( mac, ip, gateway );
Serial.println( "waiting for sync" );
setSyncProvider( getNtpTime );
while( timeStatus() == timeNotSet )
; // wait until the time is set by the sync provider
}
/*F********************************************************************
*
**********************************************************************/
void
loop()
{
if( now() != prevDisplay ) // UPDATE DISPLAY ONLY IF TIME HAS CHANGED
{
prevDisplay = now();
digitalClockDisplay();
}
}
/*F********************************************************************
* DIGITAL CLOCK DISPLAY OF TIME
**********************************************************************/
void
digitalClockDisplay()
{
Serial.print( hour() );
printDigits( minute() );
printDigits( second() );
Serial.print( " " );
Serial.print( day() );
Serial.print( " " );
Serial.print( month() );
Serial.print( " " );
Serial.print( year() );
Serial.println();
}
/*F********************************************************************
* UTILITY FUNCTION FOR DIGITAL CLOCK DISPLAY: PRINTS PRECEDING COLON AND
LEADING 0
**********************************************************************/
void
printDigits( int digits )
{
Serial.print( ":" );
if( digits < 10 )
Serial.print( '0' );
Serial.print( digits );
}
/*-------- NTP code ----------*/
// ntp code not shown - see TimeNTP.ino example sketch
Errata
The macro to convert days to time_t was corrected as of July 22 2011
On using and modifying libraries
http://www.arduino.cc/en/Main/Libraries
http://www.arduino.cc/en/Reference/Libraries
Questions, comments and suggestions on the library and documentation
Forum discussion
Old forum discussion
Trademark
Contact Us
Distributors
Careers
Help Center
Newsletter
FOLLOW US
© 2023 Arduino
Terms Of Service
Privacy Policy
Security
Cookie Settings