New library for Arduino Time and Date

i have new library date , time derived  from playground datetime code has different api intended more flexible , easier use.

the new api more consistent arduino function style. facilitates date , time code can used variety of distinctly different external time sources minimum change sketch logic.

example sketches illustrate how similar sketch logic can used each of following time sources: real time clock, internet ntp time service, gps time data, , serial time messages computer time synchronization.

this prototype code intended proof of concept , has had limited testing.
feedback on api , implementation welcome.

the download here

some of functions available in library include:

hour();            // hour  (0-23)
minute();          // minute (0-59)          
second();          // second (0-59)
day();             // day (1-31)
weekday();         // day of week, sunday day 0
month();           // month (1-12)
year();            // full 4 digit year: (2009, 2010 etc)

there functions return hour in 12 hour format
hour_12();         // hour in 12 hour format
am_pm();           // returns false if am, true if pm

now();              // returns current time seconds since jan 1 1970

the time , date functions can take optional parameter time:
for example:
 time_t t = now(); // store current time in time variable t
 hour(t);          // returns hour given time t

storing snapshot of time in variable , using time elements avoids errors if time rolls new second between accessing elements.

functions managing timer services are:  
settime(t);             // set system time give time t
adjusttime(adjustment); // adjust system time adding adjustment value

timestatus();       // indicates if time has been set , synchronized
                   // returns 1 of following enumerations:
   timenotset      // time has never been set, clock started @ jan 1 1970
   timeneedssync   // time had been set sync attempt did not succeed
   timeset         // time set , synced
time not valid if status timenotset. otherwise, time can used may
have drifted if status timeneedssync.       

there functions set external time source , interval between automatic time synchronization:
setsyncprovider(gettimefunction);  // set external time provider
setsyncinterval(interval);                  // set number of seconds between re-sync


see readme.txt file in download more details.

here example sketch gets time ds1307 rtc (the rtc library used included in download linked above)

code: [select]

#include <time.h>  
#include <wire.h>  
#include <ds1307tiny.h>  // basic ds1307 library returns time time_t

void setup()  {
 serial.begin(9600);
 setsyncprovider(rtc.get);   // function time rtc
 if(timestatus()!= timeset)
    serial.println("unable sync rtc");
 else
    serial.println("rtc has set system time");      
}

void loop()
{
  digitalclockdisplay();  
  delay(1000);
}

void digitalclockdisplay()
{
 // digital clock display of time
 serial.print(hour(),dec);
 printdigits(minute());
 printdigits(second());
 serial.print(" ");
 serial.print(day(),dec);
 serial.print(" ");
 serial.print(month(),dec);
 serial.print(" ");
 serial.print(year(),dec);
 serial.println();
}

void printdigits(byte digits){
 // utility function digital clock display: prints preceding colon , leading 0
 serial.print(":");
 if(digits < 10)
   serial.print('0');
 serial.print(digits,dec);
}

here similar clock code time synced ntp time server using arduino ethernet shield

code: [select]

#include <time.h>
#include <ethernet.h>
#include <udpbytewise.h>  // udp library from: bjoern@cs.stanford.edu 12/30/2008


byte mac[] = { 0xde, 0xad, 0xbe, 0xef, 0xfe, 0xed };
byte ip[] = { 192, 168, 1, 44 };
byte gateway[] = { 192, 168, 1, 254 };
byte time_dot_nist_dot_gov[] = { 192, 43, 244, 18}; // time.nist.gov

time_t prevdisplay = 0; // when digital clock displayed

void setup()
{
 serial.begin(9600);
 ethernet.begin(mac,ip,gateway);  
 serial.println("waiting sync");
 setsyncprovider(getntptime);  
}

void loop()
{  
 if(timestatus()!= timenotset)
    // here if time has been set
    if( now() != prevdisplay) //update display if time has changed
    {
      prevdisplay = now();
      digitalclockdisplay();  
    }
}

void digitalclockdisplay(){
 // digital clock display of time
 serial.print(hour(),dec);
 printdigits(minute());
 printdigits(second());
 serial.print(" ");
 serial.print(day(),dec);
 serial.print(" ");
 serial.print(month(),dec);
 serial.print(" ");
 serial.print(year(),dec);
 serial.println();
}

void printdigits(byte digits){
 // utility function digital clock display: prints preceding colon , leading 0
 serial.print(":");
 if(digits < 10)
   serial.print('0');
 serial.print(digits,dec);
}

/*-------- ntp code ----------*/

unsigned long getntptime()
{
 sendntppacket(time_dot_nist_dot_gov);
 delay(1000);
 if ( udpbytewise.available() ) {
   for(int i=0; < 40; i++)
      udpbytewise.read(); // ignore every field except time
   const unsigned long seventy_years = 2208988800ul;        
   return getulong() -  seventy_years;      
 }
 return 0; // return 0 if unable time
}

unsigned long sendntppacket(byte *address)
{
 udpbytewise.begin(123);
 udpbytewise.beginpacket(address, 123);
 udpbytewise.write(b11100011);   // li, version, mode
 udpbytewise.write(0);    // stratum
 udpbytewise.write(6);  // polling interval
 udpbytewise.write(0xec); // peer clock precision
 write_n(0, 8);    // root delay & root dispersion
 udpbytewise.write(49);
 udpbytewise.write(0x4e);
 udpbytewise.write(49);
 udpbytewise.write(52);
 write_n(0, 32); //reference , time stamps  
 udpbytewise.endpacket();  
}

unsigned long getulong()
{
   unsigned long ulong = (unsigned long)udpbytewise.read() << 24;
   ulong |= (unsigned long)udpbytewise.read() << 16;
   ulong |= (unsigned long)udpbytewise.read() << 8;
   ulong |= (unsigned long)udpbytewise.read();
   return ulong;
}

void write_n(int what, int how_many)
{
 for( int = 0; < how_many; i++ )
   udpbytewise.write(what);
}

and sketch syncs time serial messages (a processing sketch provides these messages in download)

code: [select]

#include <time.h>  

#define time_msg_len  11   // time sync pc header followed unix time_t ten ascii digits
#define time_header  't'   // header tag serial time sync message
#define time_request  7    // ascii bell character requests time sync message

// t1262347200  //noon jan 1 2010

void setup()  {

 serial.begin(9600);
 pinmode(13, output);            // led lit when synced
 setsyncprovider( requestsync);  //set function call when sync required
}

void loop(){    
 if(serial.available() )
 {
   processsyncmessage();
 }
 if(timestatus()== timenotset)
   digitalwrite(13, !digitalread(13)); //    serial.println("waiting sync message");
 else    
 {
   digitalwrite(13,timestatus() == timeset); // on if synced, off if needs refresh  
   digitalclockdisplay();  
 }
 delay(1000);
}

void digitalclockdisplay(){
 // digital clock display of time
 serial.print(hour(),dec);
 printdigits(minute());
 printdigits(second());
 serial.print(" ");
 serial.print(day(),dec);
 serial.print(" ");
 serial.print(month(),dec);
 serial.print(" ");
 serial.print(year(),dec);
 serial.println();
}

void printdigits(byte digits){
 // utility function digital clock display: prints preceding colon , leading 0
 serial.print(":");
 if(digits < 10)
   serial.print('0');
 serial.print(digits,dec);
}

void processsyncmessage() {
 // if time sync available serial port, update time , return true
 while(serial.available() >=  time_msg_len ){  // time message consists of header , ten ascii digits
   char c = serial.read() ;
   serial.print(c);  
   if( c == time_header ) {      
     time_t pctime = 0;
     for(int i=0; < time_msg_len -1; i++){  
       c = serial.read();          
       if( c >= '0' && c <= '9'){  
         pctime = (10 * pctime) + (c - '0') ; // convert digits number    
       }
     }  
     settime(pctime);   // sync arduino clock time received on serial port
   }  
 }
}

time_t requestsync()
{
 serial.print(time_request,byte);  
 return 0; // time sent later in response serial mesg
}


Arduino Forum > Forum 2005-2010 (read only) > Software > Development > New library for Arduino Time and Date

arduino