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

Diff: TimeUtilities.h

Revision:
3:524ad47afdc7
Parent:
1:6d3d16f4b27c
Child:
4:dfb2e93f804a
--- a/TimeUtilities.h	Wed Jun 08 11:36:11 2011 +0000
+++ b/TimeUtilities.h	Thu Jun 16 21:11:44 2011 +0000
@@ -6,8 +6,6 @@
 /// Also supports setting the clock, timezone offsets and calibration
 /// of the RTC subsystem.
 ///
-/// @version 1.01
-///
 /// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
 ///     Individuals may use this application for evaluation or non-commercial
 ///     purposes. Within this restriction, changes may be made to this application
@@ -21,6 +19,8 @@
 ///
 /// @note
 /// History
+/// v1.02 
+/// \li 20110616 Minor documentation updates
 /// v1.01 29 May 2011
 /// \li Slightly improved documentation.
 /// unlabeled 29 May 2011
@@ -42,14 +42,18 @@
 /// RealTimeClock is an interface to the mbed RTC module
 ///
 /// It provides interfaces to get and set the time in text representation
-/// as well as a means to get and set the timezone offset, so that it 
+/// as well as a means to get and set the timezone offset so that it 
 /// maintains time in UTC format.
 /// 
 /// Additionally, it provides an interface to adjust the calibration
 /// registers of the RTC, to compensate for 32 kHz clock error, whether
 /// based on the oscillator itself or on some bias to ambient temperature.
 ///
-/// @note The timezone offset is stored in RTC register GPREG0
+/// @note It is recommended that the system has a battery connected to
+/// the mbed battery backup pin.
+///
+/// @note The timezone offset is stored in RTC register GPREG0 which
+/// is battery backed, permitting recovery on the next startup.
 ///
 /// Example:
 /// @code
@@ -58,8 +62,7 @@
 /// void main() {
 ///    bool success;
 ///    char TimeTest[] = "05/29/2011 14:15:18 (-6:00)";
-///       char buf[50];
-///
+///        char buf[50];
 ///        success = rtc.SetTime(Test);
 ///     rtc.GetTimeString(buf);
 ///     printf("success: %i, time: %s\n", success, buf);
@@ -71,16 +74,20 @@
 class RealTimeClock
 {
 public:
-    /// Constructor for the RealTimeClock interface
+    /// Constructor for the RealTimeClock interface, usually implemented
+    /// outside of main( )
+    ///
     RealTimeClock();
 
-    /// Destructor for the RealTimeClock
+    /// Destructor for the RealTimeClock, usually not executed
+    ///
     ~RealTimeClock();
 
     /// GetTimeString gets the formatted time applying the internal time-zone offset of hours and minutes
     ///
     /// It places the formatted string into the buffer in the format of
     /// Sun May 29 07:19:24 2011 (tzo: -6:00)
+    ///
     /// The internal timezone offset can be set with SetTimeOffset
     ///
     /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string