Time Library

Time, by Michael Margolis, adds timekeeping ability in hours, minutes, seconds, days, months and years.

Download:

Included with the Teensyduino Installer
Latest Developments on Github

Time Library using Teensy 3.0 RTC

Hardware Requirements

Time does not require any special hardware. Internally, Time depends upon Arduino's millis() function to keep track to elasped time. However, Time can synchronize to several types of hardware which provide time and date information.

See below for details:

Basic Usage

hour();

The current time, in hours (0 to 23)

minute();

The current time, in minutes (0 to 59)

second();

The current time, in seconds (0 to 59)

day();

The current date, in day of the month (1 to 31)

month();

The current date, in month of the year (1 to 12)

year();

The current date, in years (2013, 2014, etc)

setTime(hours, minutes, seconds, days, months, years);

The time and date, using the 6 parameters above.

adjustTime(number);

Adjust the time, adding (positive numbers) or removing (negative numbers) seconds.

Usage with 32-Bit "time_t"

Time uses a special time_t variable type, which is the number of seconds elapsed since 1970. Using time_t lets you store or compare times as a single number, rather that dealing with 6 numbers and details like the number of days in each month and leap years.

now();

Reads the current time, as a time_t number.

setTime(t);

Sets the current time, based on a time_t number.

makeTime(tm);

Convert normal date & time to a time_t number. The time_t number is returned. The tm input is a TimeElements variable type, which has these fields:

tm.Second  Seconds   0 to 59
tm.Minute  Minutes   0 to 59
tm.Hour    Hours     0 to 23
tm.Wday    Week Day  0 to 6  (not needed for mktime)
tm.Day     Day       1 to 31
tm.Month   Month     1 to 12
tm.Year    Year      0 to 99 (offset from 1970)

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.

hour(t);
minute(t);
second(t);
day(t);
month(t);
year(t);

Convert a time_t number to a single time or data field. These can be simpler to use than breakTime() and a 7-field TimeElements variable.

Synchronization With Other Time Services

Time can synchronize its clock with another source of known time. You can use the setTime functions above, or configure Time to automatically call a function which will report the time.

timeStatus();

Returns the status of time sync. Three type of status are defined, with these names:

timeNotSet     Time's clock has not been set.  The time & date are unknown.
timeSet        Time's clock has been set.
timeNeedsSync  Time's clock is set, but the sync has failed, so it may not be accurate.

setSyncProvider(getTimeFunction);

Configure Time to automatically called the getTimeFunction() regularly. This function should obtain the time from another service and return a time_t number, or zero if the time is not known.

setSyncInterval(seconds);

Configure how often the getTimeFunction is called.

TimeSerial Example Program

TimeSerial demonstrates how to set the time & date when no other hardware is capable of providing this information.

You can open this example from File > Examples > Time > TimeSerial.

TimeSerial listens for a message from your computer. This message is sent by a Processing-based program, found in Time's examples/Processing folder. You will need Processing to run this program.

When you click in the window, or when TimeSerial requests an update, this program will send the message using your computer's time. Text printed by TimeSerial appears in the black console windows in Processing.

On Linux, you can send the time message in UTC time zone using "date +T%s > /dev/ttyACM0"

TimeRTCSet Example Program

TimeRTCSet demonstrates synchronizing to a DS1307 real time clock chip. It can also accept Serial messages from the Processing program, to set both Time's clock and the DS1307.

You can open this example from File > Examples > Time > TimeRTCSet.

This example requires the DS1307RTC library.

If you have trouble with the DS1307, the DS1307RTC library provides 2 example for diagnosing problems and setting the time (without Processing).

TimeGPS Example Program

TimeGPS demonstrates synchronizing Time to data from a GPS receiver module, which reports very accurate time when tracking GPS satelites.

You can open this example from File > Examples > Time > TimeGPS.

To use TimeGPS with Teensy, edit this code to use Serial1, and comment out the earlier lines with SoftwareSerial.

// To use a hardware serial port, which is far more efficient than
// SoftwareSerial, uncomment this line and remove SoftwareSerial
#define SerialGPS Serial1

Connect the GPS data to the Serial1 pins (0/1 on Teensy 3.0, 7/8 on Teensy 2.0).

One more edit is necessary. You need to configure your time zone, since GPS reports UTC time.

// Offset hours from gps time (UTC)
//const int offset = 1;   // Central European Time
//const int offset = -5;  // Eastern Standard Time (USA)
//const int offset = -4;  // Eastern Daylight Time (USA)
//const int offset = -8;  // Pacific Standard Time (USA)
const int offset = -7;  // Pacific Daylight Time (USA)

If the GPS module is acquiring satelite tracking, you may see a delay before Time synchronizes and begins printing to the Arduino Serial Monitor.

TimeNTP Example Program

TimeNTP uses the Network Time Protocol with an ethernet adaptor to synchronize to time servers over the internet.

You can open this example from File > Examples > Time > TimeNTP.

TimeTeensy3 Example Program

TimeTeensy3 demonstrates synchronizing Time to the Real Time Clock in Teensy 3.0.

To use the Teensy 3.0 RTC, you must add a 32.768 kHz, 12.5 pF crystal to the bottom side of the board. The crystal shown is Citizen part CFS-206, Digikey part 300-8303-ND, 300-8762-ND, 300-8763-ND, or 300-1002-ND.