|Shopping Cart Download Website|
|You are here: Teensy Teensyduino Libraries Time|
Time LibraryTime, by Michael Margolis, adds timekeeping ability in hours, minutes, seconds, days, months and years.
Hardware RequirementsTime 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:
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);
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 ProgramTimeSerial 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"
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).
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.
You can open this example from File > Examples > Time > TimeNTP.
To use the Teensy 3.0, 3.1 & 3.2 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. Teensy 3.5 & 3.6 have this 32.768 kHz crystal built in.
The Teensy 3.x RTC will work without a battery, but to retain the time and date while power is off, of course you must also add a 3V battery.
You can open this example from File > Examples > Time > TimeTeensy3.
The time can be set using the Processing program from TimeSerial above.
DetailsDetails may be found at the official Arduino Time page.