Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
TimeUtilities.h@6:a517fee06e2e, 2011-11-02 (annotated)
- Committer:
- WiredHome
- Date:
- Wed Nov 02 01:32:07 2011 +0000
- Revision:
- 6:a517fee06e2e
- Parent:
- 5:fbbdf57675c3
v1.04 Minor changes to the adjustment logic for complexity reduction
Who changed what in which revision?
User | Revision | Line number | New 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 | 6:a517fee06e2e | 22 | /// v1.04 20111101 |
WiredHome | 6:a517fee06e2e | 23 | /// \li Minor change to the APIs to reduce some of the complexity |
WiredHome | 5:fbbdf57675c3 | 24 | /// v1.03 20111030 |
WiredHome | 5:fbbdf57675c3 | 25 | /// \li Adding an API to adjust time and calibration based on how far it is |
WiredHome | 5:fbbdf57675c3 | 26 | /// off "now", based on when it was set. |
WiredHome | 3:524ad47afdc7 | 27 | /// v1.02 |
WiredHome | 4:dfb2e93f804a | 28 | /// \li 20110716 Minor documentation update |
WiredHome | 3:524ad47afdc7 | 29 | /// \li 20110616 Minor documentation updates |
WiredHome | 1:6d3d16f4b27c | 30 | /// v1.01 29 May 2011 |
WiredHome | 1:6d3d16f4b27c | 31 | /// \li Slightly improved documentation. |
WiredHome | 1:6d3d16f4b27c | 32 | /// unlabeled 29 May 2011 |
WiredHome | 1:6d3d16f4b27c | 33 | /// \li Initial release as a library |
WiredHome | 0:108436d3cea9 | 34 | /// |
WiredHome | 0:108436d3cea9 | 35 | #ifndef TIMEUTILITIES_H |
WiredHome | 0:108436d3cea9 | 36 | #define TIMEUTILITIES_H |
WiredHome | 0:108436d3cea9 | 37 | |
WiredHome | 0:108436d3cea9 | 38 | #ifndef WIN32 |
WiredHome | 0:108436d3cea9 | 39 | #include "mbed.h" |
WiredHome | 0:108436d3cea9 | 40 | #else |
WiredHome | 0:108436d3cea9 | 41 | typedef int int32_t; |
WiredHome | 0:108436d3cea9 | 42 | #endif |
WiredHome | 0:108436d3cea9 | 43 | |
WiredHome | 0:108436d3cea9 | 44 | #include <time.h> |
WiredHome | 0:108436d3cea9 | 45 | |
WiredHome | 1:6d3d16f4b27c | 46 | /// RealTimeClock is an interface to the mbed RTC module |
WiredHome | 1:6d3d16f4b27c | 47 | /// |
WiredHome | 1:6d3d16f4b27c | 48 | /// It provides interfaces to get and set the time in text representation |
WiredHome | 3:524ad47afdc7 | 49 | /// as well as a means to get and set the timezone offset so that it |
WiredHome | 1:6d3d16f4b27c | 50 | /// maintains time in UTC format. |
WiredHome | 1:6d3d16f4b27c | 51 | /// |
WiredHome | 1:6d3d16f4b27c | 52 | /// Additionally, it provides an interface to adjust the calibration |
WiredHome | 1:6d3d16f4b27c | 53 | /// registers of the RTC, to compensate for 32 kHz clock error, whether |
WiredHome | 1:6d3d16f4b27c | 54 | /// based on the oscillator itself or on some bias to ambient temperature. |
WiredHome | 1:6d3d16f4b27c | 55 | /// |
WiredHome | 3:524ad47afdc7 | 56 | /// @note It is recommended that the system has a battery connected to |
WiredHome | 3:524ad47afdc7 | 57 | /// the mbed battery backup pin. |
WiredHome | 3:524ad47afdc7 | 58 | /// |
WiredHome | 3:524ad47afdc7 | 59 | /// @note The timezone offset is stored in RTC register GPREG0 which |
WiredHome | 3:524ad47afdc7 | 60 | /// is battery backed, permitting recovery on the next startup. |
WiredHome | 1:6d3d16f4b27c | 61 | /// |
WiredHome | 1:6d3d16f4b27c | 62 | /// Example: |
WiredHome | 1:6d3d16f4b27c | 63 | /// @code |
WiredHome | 1:6d3d16f4b27c | 64 | /// RealTimeClock rtc; |
WiredHome | 1:6d3d16f4b27c | 65 | /// |
WiredHome | 1:6d3d16f4b27c | 66 | /// void main() { |
WiredHome | 4:dfb2e93f804a | 67 | /// bool success; |
WiredHome | 4:dfb2e93f804a | 68 | /// char TimeTest[] = "05/29/2011 14:15:18 (-6:00)"; |
WiredHome | 4:dfb2e93f804a | 69 | /// char buf[50]; |
WiredHome | 4:dfb2e93f804a | 70 | /// success = rtc.SetTime(TimeTest); |
WiredHome | 1:6d3d16f4b27c | 71 | /// rtc.GetTimeString(buf); |
WiredHome | 1:6d3d16f4b27c | 72 | /// printf("success: %i, time: %s\n", success, buf); |
WiredHome | 1:6d3d16f4b27c | 73 | /// } |
WiredHome | 4:dfb2e93f804a | 74 | /// prints the following: |
WiredHome | 4:dfb2e93f804a | 75 | /// success: 1, time: Sun May 29 14:15:18 2011 (tzo: -6:00) |
WiredHome | 1:6d3d16f4b27c | 76 | /// @endcode |
WiredHome | 1:6d3d16f4b27c | 77 | /// |
WiredHome | 0:108436d3cea9 | 78 | class RealTimeClock |
WiredHome | 0:108436d3cea9 | 79 | { |
WiredHome | 0:108436d3cea9 | 80 | public: |
WiredHome | 3:524ad47afdc7 | 81 | /// Constructor for the RealTimeClock interface, usually implemented |
WiredHome | 3:524ad47afdc7 | 82 | /// outside of main( ) |
WiredHome | 3:524ad47afdc7 | 83 | /// |
WiredHome | 1:6d3d16f4b27c | 84 | RealTimeClock(); |
WiredHome | 1:6d3d16f4b27c | 85 | |
WiredHome | 3:524ad47afdc7 | 86 | /// Destructor for the RealTimeClock, usually not executed |
WiredHome | 3:524ad47afdc7 | 87 | /// |
WiredHome | 1:6d3d16f4b27c | 88 | ~RealTimeClock(); |
WiredHome | 1:6d3d16f4b27c | 89 | |
WiredHome | 5:fbbdf57675c3 | 90 | /// GetTimeValue gets the current time in time_t format |
WiredHome | 5:fbbdf57675c3 | 91 | /// |
WiredHome | 5:fbbdf57675c3 | 92 | /// Gets the current time from the rtc and returns the time in time_t format. |
WiredHome | 5:fbbdf57675c3 | 93 | /// This is functionally identical to "return time(NULL);", |
WiredHome | 5:fbbdf57675c3 | 94 | /// simply wrapped in this class for convenience. |
WiredHome | 5:fbbdf57675c3 | 95 | /// |
WiredHome | 5:fbbdf57675c3 | 96 | /// @returns current time in time_t format |
WiredHome | 5:fbbdf57675c3 | 97 | /// |
WiredHome | 5:fbbdf57675c3 | 98 | time_t GetTimeValue(); |
WiredHome | 5:fbbdf57675c3 | 99 | |
WiredHome | 1:6d3d16f4b27c | 100 | /// GetTimeString gets the formatted time applying the internal 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 | 3:524ad47afdc7 | 104 | /// |
WiredHome | 1:6d3d16f4b27c | 105 | /// The internal timezone offset can be set with SetTimeOffset |
WiredHome | 1:6d3d16f4b27c | 106 | /// |
WiredHome | 1:6d3d16f4b27c | 107 | /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string |
WiredHome | 1:6d3d16f4b27c | 108 | /// @param tValue is the optional time value to convert to text, if zero, then the current |
WiredHome | 1:6d3d16f4b27c | 109 | /// time is used. |
WiredHome | 1:6d3d16f4b27c | 110 | /// @returns nothing |
WiredHome | 1:6d3d16f4b27c | 111 | /// |
WiredHome | 1:6d3d16f4b27c | 112 | void GetTimeString(char * buffer, time_t tValue = 0); |
WiredHome | 0:108436d3cea9 | 113 | |
WiredHome | 1:6d3d16f4b27c | 114 | /// GetTimeString gets the formatted time applying the time-zone offset of hours and minutes |
WiredHome | 1:6d3d16f4b27c | 115 | /// |
WiredHome | 1:6d3d16f4b27c | 116 | /// It places the formatted string into the buffer in the format of |
WiredHome | 1:6d3d16f4b27c | 117 | /// Sun May 29 07:19:24 2011 (tzo: -6:00) |
WiredHome | 1:6d3d16f4b27c | 118 | /// |
WiredHome | 1:6d3d16f4b27c | 119 | /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string |
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, int hOffset, int mOffset); |
WiredHome | 0:108436d3cea9 | 125 | |
WiredHome | 1:6d3d16f4b27c | 126 | /// GetTimeString gets the formatted time value applying the time-zone offset of hours and minutes |
WiredHome | 1:6d3d16f4b27c | 127 | /// |
WiredHome | 1:6d3d16f4b27c | 128 | /// It places the formatted string into the buffer in the format of |
WiredHome | 1:6d3d16f4b27c | 129 | /// Sun May 29 07:19:24 2011 (tzo: -6:00) |
WiredHome | 1:6d3d16f4b27c | 130 | /// |
WiredHome | 1:6d3d16f4b27c | 131 | /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string |
WiredHome | 1:6d3d16f4b27c | 132 | /// @param tValue is the time value to convert to text, if zero, then the current |
WiredHome | 1:6d3d16f4b27c | 133 | /// time is used. |
WiredHome | 1:6d3d16f4b27c | 134 | /// @param hOffset is the hours offset |
WiredHome | 1:6d3d16f4b27c | 135 | /// @param mOffset is the minutes offset |
WiredHome | 1:6d3d16f4b27c | 136 | /// @returns nothing |
WiredHome | 1:6d3d16f4b27c | 137 | /// |
WiredHome | 1:6d3d16f4b27c | 138 | void GetTimeString(char * buffer, time_t tValue, int hOffset, int mOffset); |
WiredHome | 0:108436d3cea9 | 139 | |
WiredHome | 6:a517fee06e2e | 140 | /// GetTimeLastSet will extract the time_t when last set from RTC ram |
WiredHome | 6:a517fee06e2e | 141 | /// |
WiredHome | 6:a517fee06e2e | 142 | /// When the clock is correctly set, the time value will have been stored |
WiredHome | 6:a517fee06e2e | 143 | /// which permits later adjustments to the calibration based on |
WiredHome | 6:a517fee06e2e | 144 | /// elapsed time and knowing when it was set. This function retrieves it. |
WiredHome | 6:a517fee06e2e | 145 | /// |
WiredHome | 6:a517fee06e2e | 146 | /// @returns time_t value when the time was last set |
WiredHome | 6:a517fee06e2e | 147 | /// |
WiredHome | 6:a517fee06e2e | 148 | time_t GetTimeLastSet(); |
WiredHome | 6:a517fee06e2e | 149 | |
WiredHome | 1:6d3d16f4b27c | 150 | /// SetTimeOffset will set the hour and minute timezone offset |
WiredHome | 1:6d3d16f4b27c | 151 | /// |
WiredHome | 1:6d3d16f4b27c | 152 | /// @param offsetHour is the timezone offset in hours |
WiredHome | 1:6d3d16f4b27c | 153 | /// @param offsetMinute is the timezone offset in minutes |
WiredHome | 1:6d3d16f4b27c | 154 | /// @returns nothing |
WiredHome | 1:6d3d16f4b27c | 155 | /// |
WiredHome | 1:6d3d16f4b27c | 156 | void SetTimeOffset(int offsetHour, int offsetMinute); |
WiredHome | 0:108436d3cea9 | 157 | |
WiredHome | 1:6d3d16f4b27c | 158 | /// GetTimeCalibration will return the calibration register value |
WiredHome | 1:6d3d16f4b27c | 159 | /// |
WiredHome | 1:6d3d16f4b27c | 160 | /// This is the raw register value as a signed 32-bit value (even though |
WiredHome | 1:6d3d16f4b27c | 161 | /// it is actually a 17-bit unsigned value with an additional 'direction' flag). |
WiredHome | 1:6d3d16f4b27c | 162 | /// |
WiredHome | 1:6d3d16f4b27c | 163 | /// @returns calibration settings ranging from -131071 to +131071 |
WiredHome | 1:6d3d16f4b27c | 164 | /// |
WiredHome | 1:6d3d16f4b27c | 165 | int32_t GetTimeCalibration(); |
WiredHome | 0:108436d3cea9 | 166 | |
WiredHome | 1:6d3d16f4b27c | 167 | /// SetTimeCalibration will set the calibration register value |
WiredHome | 1:6d3d16f4b27c | 168 | /// |
WiredHome | 1:6d3d16f4b27c | 169 | /// This accepts a signed value to be used to set the calibration |
WiredHome | 1:6d3d16f4b27c | 170 | /// registers. Setting the calibration value to zero disables the |
WiredHome | 5:fbbdf57675c3 | 171 | /// calibration function. |
WiredHome | 5:fbbdf57675c3 | 172 | /// It is important to know the register function in order to use |
WiredHome | 5:fbbdf57675c3 | 173 | /// this command, and this API is normally not used by external |
WiredHome | 5:fbbdf57675c3 | 174 | /// application code. @See AdjustBySeconds for a user-friendly |
WiredHome | 5:fbbdf57675c3 | 175 | /// API. |
WiredHome | 1:6d3d16f4b27c | 176 | /// |
WiredHome | 1:6d3d16f4b27c | 177 | /// @param calibration value to use ranging from -131071 to +131071 |
WiredHome | 1:6d3d16f4b27c | 178 | /// @returns nothing |
WiredHome | 1:6d3d16f4b27c | 179 | /// |
WiredHome | 1:6d3d16f4b27c | 180 | void SetTimeCalibration(int32_t calibration); |
WiredHome | 0:108436d3cea9 | 181 | |
WiredHome | 0:108436d3cea9 | 182 | |
WiredHome | 1:6d3d16f4b27c | 183 | /// SetTime will set the Real Time Clock from a well formatted string |
WiredHome | 1:6d3d16f4b27c | 184 | /// |
WiredHome | 1:6d3d16f4b27c | 185 | /// This will read a string, and if it is well formed, it will then |
WiredHome | 1:6d3d16f4b27c | 186 | /// set the RTC based on this string. The string should be of the form: |
WiredHome | 1:6d3d16f4b27c | 187 | /// 'MM/DD/YYYY HH:MM:SS' and may have the optional timezone offset |
WiredHome | 1:6d3d16f4b27c | 188 | /// of the form '(+/-HH:MM)' |
WiredHome | 1:6d3d16f4b27c | 189 | /// |
WiredHome | 1:6d3d16f4b27c | 190 | /// example: 05/29/2011 13:15:07 (-6:00) |
WiredHome | 1:6d3d16f4b27c | 191 | /// |
WiredHome | 1:6d3d16f4b27c | 192 | /// @param timestring is the string to parse |
WiredHome | 1:6d3d16f4b27c | 193 | /// @returns true if the time was set |
WiredHome | 1:6d3d16f4b27c | 194 | /// |
WiredHome | 1:6d3d16f4b27c | 195 | bool SetTime(char * timestring); |
WiredHome | 5:fbbdf57675c3 | 196 | |
WiredHome | 5:fbbdf57675c3 | 197 | |
WiredHome | 5:fbbdf57675c3 | 198 | /// AdjustBySeconds adjusts both the time and the calibration by seconds |
WiredHome | 5:fbbdf57675c3 | 199 | /// |
WiredHome | 5:fbbdf57675c3 | 200 | /// This will take a signed value, which is the current adjustment in seconds |
WiredHome | 5:fbbdf57675c3 | 201 | /// to put the clock on the correct time. So, if the clock is behind by |
WiredHome | 5:fbbdf57675c3 | 202 | /// 3 seconds, the value should be +3 to advance the clock accordingly. |
WiredHome | 5:fbbdf57675c3 | 203 | /// It will then adjust the time, and it will attempt to adjust the |
WiredHome | 5:fbbdf57675c3 | 204 | /// calibration factor to make the time more accurate. |
WiredHome | 5:fbbdf57675c3 | 205 | /// |
WiredHome | 5:fbbdf57675c3 | 206 | /// The adjustment can only be made if it has retained when the clock was |
WiredHome | 5:fbbdf57675c3 | 207 | /// last set, in order to know by how much to adjust it. It is also most |
WiredHome | 5:fbbdf57675c3 | 208 | /// accurate if several days have elapsed since the time was set. |
WiredHome | 5:fbbdf57675c3 | 209 | /// |
WiredHome | 5:fbbdf57675c3 | 210 | /// @note The current version only works if the calibration value |
WiredHome | 5:fbbdf57675c3 | 211 | /// is zero when this adjustment is made. |
WiredHome | 5:fbbdf57675c3 | 212 | /// |
WiredHome | 5:fbbdf57675c3 | 213 | /// @param adjustSeconds is the signed value by which to adjust the time to |
WiredHome | 5:fbbdf57675c3 | 214 | /// correct it to the current actual time. |
WiredHome | 5:fbbdf57675c3 | 215 | /// @returns true if the adjustment was made |
WiredHome | 5:fbbdf57675c3 | 216 | /// @returns false if the adjustment could not be made |
WiredHome | 5:fbbdf57675c3 | 217 | /// |
WiredHome | 5:fbbdf57675c3 | 218 | bool AdjustBySeconds(int32_t adjustSeconds); |
WiredHome | 5:fbbdf57675c3 | 219 | |
WiredHome | 5:fbbdf57675c3 | 220 | /// GetVersion will return a pointer to a constant text string |
WiredHome | 5:fbbdf57675c3 | 221 | /// |
WiredHome | 5:fbbdf57675c3 | 222 | /// This returns a pointer to a constant string which represents |
WiredHome | 5:fbbdf57675c3 | 223 | /// the version of this component. |
WiredHome | 5:fbbdf57675c3 | 224 | /// |
WiredHome | 5:fbbdf57675c3 | 225 | /// @returns pointer to a character string holding the version. |
WiredHome | 5:fbbdf57675c3 | 226 | /// |
WiredHome | 5:fbbdf57675c3 | 227 | const char * GetVersion(); |
WiredHome | 5:fbbdf57675c3 | 228 | |
WiredHome | 5:fbbdf57675c3 | 229 | private: |
WiredHome | 5:fbbdf57675c3 | 230 | |
WiredHome | 5:fbbdf57675c3 | 231 | /// SetTimeOffsetStore will store the timezone offset values in RTC ram |
WiredHome | 5:fbbdf57675c3 | 232 | /// |
WiredHome | 5:fbbdf57675c3 | 233 | /// This takes the current timezone offset values and stores them in |
WiredHome | 5:fbbdf57675c3 | 234 | /// the RTC battery backed ram. |
WiredHome | 5:fbbdf57675c3 | 235 | /// |
WiredHome | 5:fbbdf57675c3 | 236 | /// @returns nothing |
WiredHome | 5:fbbdf57675c3 | 237 | /// |
WiredHome | 5:fbbdf57675c3 | 238 | void SetTimeOffsetStore(); |
WiredHome | 5:fbbdf57675c3 | 239 | |
WiredHome | 5:fbbdf57675c3 | 240 | /// GetTimeOffsetStore will extract the timezone offset values from RTC ram |
WiredHome | 5:fbbdf57675c3 | 241 | /// |
WiredHome | 5:fbbdf57675c3 | 242 | /// This extracts the timezone offset values that were stored in RTC |
WiredHome | 5:fbbdf57675c3 | 243 | /// battery backed ram and uses them for time information. |
WiredHome | 5:fbbdf57675c3 | 244 | /// |
WiredHome | 5:fbbdf57675c3 | 245 | /// @returns nothing |
WiredHome | 5:fbbdf57675c3 | 246 | /// |
WiredHome | 5:fbbdf57675c3 | 247 | void GetTimeOffsetStore(); |
WiredHome | 5:fbbdf57675c3 | 248 | |
WiredHome | 6:a517fee06e2e | 249 | /// SetTimeLastSet will store the time_t when last set in RTC ram |
WiredHome | 5:fbbdf57675c3 | 250 | /// |
WiredHome | 5:fbbdf57675c3 | 251 | /// When the clock is correctly set, the time value will be stored |
WiredHome | 5:fbbdf57675c3 | 252 | /// which permits later adjustments to the calibration based on |
WiredHome | 5:fbbdf57675c3 | 253 | /// elapsed time and knowing when it was set. |
WiredHome | 5:fbbdf57675c3 | 254 | /// |
WiredHome | 6:a517fee06e2e | 255 | /// @param t is the time_t value that should be saved |
WiredHome | 5:fbbdf57675c3 | 256 | /// @returns nothing |
WiredHome | 5:fbbdf57675c3 | 257 | /// |
WiredHome | 6:a517fee06e2e | 258 | void SetTimeLastSet(time_t); |
WiredHome | 5:fbbdf57675c3 | 259 | |
WiredHome | 0:108436d3cea9 | 260 | }; |
WiredHome | 0:108436d3cea9 | 261 | |
WiredHome | 0:108436d3cea9 | 262 | #endif |