E3 Designers / TimeManagement

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.

Dependents:   mbed_escm2000

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