E3 Designers / TimeManagement

This is a library for managing the mbed real time clock, including functions for setting and getting the rtc in text format, getting and setting the timezone offset, and getting and setting the calibration register, both directly, and by using an adjustment API to automatically set the calibration value.

Dependents:   mbed_escm2000

TimeUtilities.h@3:524ad47afdc7, 2011-06-16 (annotated)

Committer:
WiredHome
Date:
Thu Jun 16 21:11:44 2011 +0000
Revision:
3:524ad47afdc7
Parent:
1:6d3d16f4b27c
Child:
4:dfb2e93f804a
v1.02 minor documentation updates

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:108436d3cea9 1 /// @file TimeUtilities.h contains a real time clock interface for the mbed
WiredHome 0:108436d3cea9 2 ///
WiredHome 1:6d3d16f4b27c 3 /// @mainpage Time Management of the Real Time Clock module
WiredHome 1:6d3d16f4b27c 4 ///
WiredHome 0:108436d3cea9 5 /// APIs for showing the time from the RTC, or from a passed in value.
WiredHome 0:108436d3cea9 6 /// Also supports setting the clock, timezone offsets and calibration
WiredHome 0:108436d3cea9 7 /// of the RTC subsystem.
WiredHome 0:108436d3cea9 8 ///
WiredHome 1:6d3d16f4b27c 9 /// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
WiredHome 1:6d3d16f4b27c 10 /// Individuals may use this application for evaluation or non-commercial
WiredHome 1:6d3d16f4b27c 11 /// purposes. Within this restriction, changes may be made to this application
WiredHome 1:6d3d16f4b27c 12 /// as long as this copyright notice is retained. The user shall make
WiredHome 1:6d3d16f4b27c 13 /// clear that their work is a derived work, and not the original.
WiredHome 1:6d3d16f4b27c 14 /// Users of this application and sources accept this application "as is" and
WiredHome 1:6d3d16f4b27c 15 /// shall hold harmless Smartware Computing, for any undesired results while
WiredHome 1:6d3d16f4b27c 16 /// using this application - whether real or imagined.
WiredHome 1:6d3d16f4b27c 17 ///
WiredHome 1:6d3d16f4b27c 18 /// @author David Smart, Smartware Computing
WiredHome 1:6d3d16f4b27c 19 ///
WiredHome 1:6d3d16f4b27c 20 /// @note
WiredHome 1:6d3d16f4b27c 21 /// History
WiredHome 3:524ad47afdc7 22 /// v1.02
WiredHome 3:524ad47afdc7 23 /// \li 20110616 Minor documentation updates
WiredHome 1:6d3d16f4b27c 24 /// v1.01 29 May 2011
WiredHome 1:6d3d16f4b27c 25 /// \li Slightly improved documentation.
WiredHome 1:6d3d16f4b27c 26 /// unlabeled 29 May 2011
WiredHome 1:6d3d16f4b27c 27 /// \li Initial release as a library
WiredHome 0:108436d3cea9 28 ///
WiredHome 0:108436d3cea9 29 #ifndef TIMEUTILITIES_H
WiredHome 0:108436d3cea9 30 #define TIMEUTILITIES_H
WiredHome 0:108436d3cea9 31
WiredHome 0:108436d3cea9 32 #ifndef WIN32
WiredHome 0:108436d3cea9 33 // embedded build
WiredHome 0:108436d3cea9 34 #include "mbed.h"
WiredHome 0:108436d3cea9 35 #else
WiredHome 0:108436d3cea9 36 // fake it for Windows build
WiredHome 0:108436d3cea9 37 typedef int int32_t;
WiredHome 0:108436d3cea9 38 #endif
WiredHome 0:108436d3cea9 39
WiredHome 0:108436d3cea9 40 #include <time.h>
WiredHome 0:108436d3cea9 41
WiredHome 1:6d3d16f4b27c 42 /// RealTimeClock is an interface to the mbed RTC module
WiredHome 1:6d3d16f4b27c 43 ///
WiredHome 1:6d3d16f4b27c 44 /// It provides interfaces to get and set the time in text representation
WiredHome 3:524ad47afdc7 45 /// as well as a means to get and set the timezone offset so that it
WiredHome 1:6d3d16f4b27c 46 /// maintains time in UTC format.
WiredHome 1:6d3d16f4b27c 47 ///
WiredHome 1:6d3d16f4b27c 48 /// Additionally, it provides an interface to adjust the calibration
WiredHome 1:6d3d16f4b27c 49 /// registers of the RTC, to compensate for 32 kHz clock error, whether
WiredHome 1:6d3d16f4b27c 50 /// based on the oscillator itself or on some bias to ambient temperature.
WiredHome 1:6d3d16f4b27c 51 ///
WiredHome 3:524ad47afdc7 52 /// @note It is recommended that the system has a battery connected to
WiredHome 3:524ad47afdc7 53 /// the mbed battery backup pin.
WiredHome 3:524ad47afdc7 54 ///
WiredHome 3:524ad47afdc7 55 /// @note The timezone offset is stored in RTC register GPREG0 which
WiredHome 3:524ad47afdc7 56 /// is battery backed, permitting recovery on the next startup.
WiredHome 1:6d3d16f4b27c 57 ///
WiredHome 1:6d3d16f4b27c 58 /// Example:
WiredHome 1:6d3d16f4b27c 59 /// @code
WiredHome 1:6d3d16f4b27c 60 /// RealTimeClock rtc;
WiredHome 1:6d3d16f4b27c 61 ///
WiredHome 1:6d3d16f4b27c 62 /// void main() {
WiredHome 1:6d3d16f4b27c 63 /// bool success;
WiredHome 1:6d3d16f4b27c 64 /// char TimeTest[] = "05/29/2011 14:15:18 (-6:00)";
WiredHome 3:524ad47afdc7 65 /// char buf[50];
WiredHome 1:6d3d16f4b27c 66 /// success = rtc.SetTime(Test);
WiredHome 1:6d3d16f4b27c 67 /// rtc.GetTimeString(buf);
WiredHome 1:6d3d16f4b27c 68 /// printf("success: %i, time: %s\n", success, buf);
WiredHome 1:6d3d16f4b27c 69 /// }
WiredHome 1:6d3d16f4b27c 70 /// prints
WiredHome 1:6d3d16f4b27c 71 /// "success: 1, time: Sun May 29 14:15:18 2011 (tzo: -6:00)"
WiredHome 1:6d3d16f4b27c 72 /// @endcode
WiredHome 1:6d3d16f4b27c 73 ///
WiredHome 0:108436d3cea9 74 class RealTimeClock
WiredHome 0:108436d3cea9 75 {
WiredHome 0:108436d3cea9 76 public:
WiredHome 3:524ad47afdc7 77 /// Constructor for the RealTimeClock interface, usually implemented
WiredHome 3:524ad47afdc7 78 /// outside of main( )
WiredHome 3:524ad47afdc7 79 ///
WiredHome 1:6d3d16f4b27c 80 RealTimeClock();
WiredHome 1:6d3d16f4b27c 81
WiredHome 3:524ad47afdc7 82 /// Destructor for the RealTimeClock, usually not executed
WiredHome 3:524ad47afdc7 83 ///
WiredHome 1:6d3d16f4b27c 84 ~RealTimeClock();
WiredHome 1:6d3d16f4b27c 85
WiredHome 1:6d3d16f4b27c 86 /// GetTimeString gets the formatted time applying the internal time-zone offset of hours and minutes
WiredHome 1:6d3d16f4b27c 87 ///
WiredHome 1:6d3d16f4b27c 88 /// It places the formatted string into the buffer in the format of
WiredHome 1:6d3d16f4b27c 89 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 3:524ad47afdc7 90 ///
WiredHome 1:6d3d16f4b27c 91 /// The internal timezone offset can be set with SetTimeOffset
WiredHome 1:6d3d16f4b27c 92 ///
WiredHome 1:6d3d16f4b27c 93 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 1:6d3d16f4b27c 94 /// @param tValue is the optional time value to convert to text, if zero, then the current
WiredHome 1:6d3d16f4b27c 95 /// time is used.
WiredHome 1:6d3d16f4b27c 96 /// @returns nothing
WiredHome 1:6d3d16f4b27c 97 ///
WiredHome 1:6d3d16f4b27c 98 void GetTimeString(char * buffer, time_t tValue = 0);
WiredHome 0:108436d3cea9 99
WiredHome 1:6d3d16f4b27c 100 /// GetTimeString gets the formatted time applying the time-zone offset of hours and minutes
WiredHome 1:6d3d16f4b27c 101 ///
WiredHome 1:6d3d16f4b27c 102 /// It places the formatted string into the buffer in the format of
WiredHome 1:6d3d16f4b27c 103 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 1:6d3d16f4b27c 104 ///
WiredHome 1:6d3d16f4b27c 105 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 1:6d3d16f4b27c 106 /// @param hOffset is the hours offset
WiredHome 1:6d3d16f4b27c 107 /// @param mOffset is the minutes offset
WiredHome 1:6d3d16f4b27c 108 /// @returns nothing
WiredHome 1:6d3d16f4b27c 109 ///
WiredHome 1:6d3d16f4b27c 110 void GetTimeString(char * buffer, int hOffset, int mOffset);
WiredHome 0:108436d3cea9 111
WiredHome 1:6d3d16f4b27c 112 /// GetTimeString gets the formatted time value applying the time-zone offset of hours and minutes
WiredHome 1:6d3d16f4b27c 113 ///
WiredHome 1:6d3d16f4b27c 114 /// It places the formatted string into the buffer in the format of
WiredHome 1:6d3d16f4b27c 115 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 1:6d3d16f4b27c 116 ///
WiredHome 1:6d3d16f4b27c 117 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 1:6d3d16f4b27c 118 /// @param tValue is the time value to convert to text, if zero, then the current
WiredHome 1:6d3d16f4b27c 119 /// time is used.
WiredHome 1:6d3d16f4b27c 120 /// @param hOffset is the hours offset
WiredHome 1:6d3d16f4b27c 121 /// @param mOffset is the minutes offset
WiredHome 1:6d3d16f4b27c 122 /// @returns nothing
WiredHome 1:6d3d16f4b27c 123 ///
WiredHome 1:6d3d16f4b27c 124 void GetTimeString(char * buffer, time_t tValue, int hOffset, int mOffset);
WiredHome 0:108436d3cea9 125
WiredHome 1:6d3d16f4b27c 126 /// SetTimeOffset will set the hour and minute timezone offset
WiredHome 1:6d3d16f4b27c 127 ///
WiredHome 1:6d3d16f4b27c 128 /// @param offsetHour is the timezone offset in hours
WiredHome 1:6d3d16f4b27c 129 /// @param offsetMinute is the timezone offset in minutes
WiredHome 1:6d3d16f4b27c 130 /// @returns nothing
WiredHome 1:6d3d16f4b27c 131 ///
WiredHome 1:6d3d16f4b27c 132 void SetTimeOffset(int offsetHour, int offsetMinute);
WiredHome 0:108436d3cea9 133
WiredHome 1:6d3d16f4b27c 134 /// SetTimeOffsetStore will store the timezone offset values in RTC ram
WiredHome 1:6d3d16f4b27c 135 ///
WiredHome 1:6d3d16f4b27c 136 /// This takes the current timezone offset values and stores them in
WiredHome 1:6d3d16f4b27c 137 /// the RTC battery backed ram.
WiredHome 1:6d3d16f4b27c 138 ///
WiredHome 1:6d3d16f4b27c 139 /// @returns nothing
WiredHome 1:6d3d16f4b27c 140 ///
WiredHome 1:6d3d16f4b27c 141 void SetTimeOffsetStore();
WiredHome 0:108436d3cea9 142
WiredHome 1:6d3d16f4b27c 143 /// GetTimeOffsetStore will extract the timezone offset values from RTC ram
WiredHome 1:6d3d16f4b27c 144 ///
WiredHome 1:6d3d16f4b27c 145 /// This extracts the timezone offset values that were stored in RTC
WiredHome 1:6d3d16f4b27c 146 /// battery backed ram and uses them for time information.
WiredHome 1:6d3d16f4b27c 147 ///
WiredHome 1:6d3d16f4b27c 148 /// @returns nothing
WiredHome 1:6d3d16f4b27c 149 ///
WiredHome 1:6d3d16f4b27c 150 void GetTimeOffsetStore();
WiredHome 0:108436d3cea9 151
WiredHome 1:6d3d16f4b27c 152 /// GetTimeCalibration will return the calibration register value
WiredHome 1:6d3d16f4b27c 153 ///
WiredHome 1:6d3d16f4b27c 154 /// This is the raw register value as a signed 32-bit value (even though
WiredHome 1:6d3d16f4b27c 155 /// it is actually a 17-bit unsigned value with an additional 'direction' flag).
WiredHome 1:6d3d16f4b27c 156 ///
WiredHome 1:6d3d16f4b27c 157 /// @returns calibration settings ranging from -131071 to +131071
WiredHome 1:6d3d16f4b27c 158 ///
WiredHome 1:6d3d16f4b27c 159 int32_t GetTimeCalibration();
WiredHome 0:108436d3cea9 160
WiredHome 1:6d3d16f4b27c 161 /// SetTimeCalibration will set the calibration register value
WiredHome 1:6d3d16f4b27c 162 ///
WiredHome 1:6d3d16f4b27c 163 /// This accepts a signed value to be used to set the calibration
WiredHome 1:6d3d16f4b27c 164 /// registers. Setting the calibration value to zero disables the
WiredHome 1:6d3d16f4b27c 165 /// calibration function.
WiredHome 1:6d3d16f4b27c 166 ///
WiredHome 1:6d3d16f4b27c 167 /// @param calibration value to use ranging from -131071 to +131071
WiredHome 1:6d3d16f4b27c 168 /// @returns nothing
WiredHome 1:6d3d16f4b27c 169 ///
WiredHome 1:6d3d16f4b27c 170 void SetTimeCalibration(int32_t calibration);
WiredHome 0:108436d3cea9 171
WiredHome 0:108436d3cea9 172
WiredHome 1:6d3d16f4b27c 173 /// SetTime will set the Real Time Clock from a well formatted string
WiredHome 1:6d3d16f4b27c 174 ///
WiredHome 1:6d3d16f4b27c 175 /// This will read a string, and if it is well formed, it will then
WiredHome 1:6d3d16f4b27c 176 /// set the RTC based on this string. The string should be of the form:
WiredHome 1:6d3d16f4b27c 177 /// 'MM/DD/YYYY HH:MM:SS' and may have the optional timezone offset
WiredHome 1:6d3d16f4b27c 178 /// of the form '(+/-HH:MM)'
WiredHome 1:6d3d16f4b27c 179 ///
WiredHome 1:6d3d16f4b27c 180 /// example: 05/29/2011 13:15:07 (-6:00)
WiredHome 1:6d3d16f4b27c 181 ///
WiredHome 1:6d3d16f4b27c 182 /// @param timestring is the string to parse
WiredHome 1:6d3d16f4b27c 183 /// @returns true if the time was set
WiredHome 1:6d3d16f4b27c 184 ///
WiredHome 1:6d3d16f4b27c 185 bool SetTime(char * timestring);
WiredHome 0:108436d3cea9 186 };
WiredHome 0:108436d3cea9 187
WiredHome 0:108436d3cea9 188 #endif