David Smart / 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:   LAB4WEEK1 Motor

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?

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 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