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@1:6d3d16f4b27c, 2011-05-29 (annotated)

Committer:
WiredHome
Date:
Sun May 29 20:34:27 2011 +0000
Revision:
1:6d3d16f4b27c
Parent:
0:108436d3cea9
Child:
3:524ad47afdc7
v1.01 slightly improved documentation

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