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