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@5:fbbdf57675c3, 2011-10-30 (annotated)

Committer:
WiredHome
Date:
Sun Oct 30 23:42:43 2011 +0000
Revision:
5:fbbdf57675c3
Parent:
4:dfb2e93f804a
Child:
6:a517fee06e2e
v1.03 Added API to adjust the calibration based on an accumulated error over a period of time (typically >= 1 day).

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