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@4:dfb2e93f804a, 2011-07-16 (annotated)

Committer:
WiredHome
Date:
Sat Jul 16 16:57:22 2011 +0000
Revision:
4:dfb2e93f804a
Parent:
3:524ad47afdc7
Child:
5:fbbdf57675c3
Minor documentation update, no functional change

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