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.
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.
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 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 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)constint 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.
TimeTeensy3 demonstrates synchronizing Time to the Real Time Clock in
Teensy 3.0, 3.1, 3.2, 3.5 & 3.6.
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.
