Revision 3:524ad47afdc7, committed 2011-06-16

Comitter:

WiredHome

Date:

Thu Jun 16 21:11:44 2011 +0000

Parent:

2:cbcdd97f3a6d

Child:

4:dfb2e93f804a

Commit message:

v1.02 minor documentation updates

Changed in this revision

--- a/TimeUtilities.cpp	Wed Jun 08 11:36:11 2011 +0000
+++ b/TimeUtilities.cpp	Thu Jun 16 21:11:44 2011 +0000
@@ -16,6 +16,8 @@
 /// @author David Smart, Smartware Computing
 ///
 /// Version History
+/// 20110616
+/// \li minor documentation changes
 /// 20110601
 /// \li discovered the CCALEN flag to enable calibration
 /// 20110529
@@ -33,7 +35,7 @@
 #include <stdlib.h>
 
 #ifdef WIN32
-// Fake it out for Win32
+// Fake it out for Win32 development and testing
 struct LPC {
     unsigned long CCR;          // Clock Control register
     unsigned long GPREG0;       // General Purpose Register - Battery backed
@@ -175,88 +177,3 @@
     return success;
 }
 
-#if 0
-// GetNumber will get from the user a number using the
-/// specified number of digits.
-///
-/// They can enter a number from 0 to 10^(digits-1)
-///
-/// @param digits is the number of digits to enter
-/// @param pValue is a pointer to where to store the result
-/// @returns true if a number was entered
-/// @returns false if they entered a non-digit
-///
-int GetNumber(int digits, int * pValue) {
-    int tempValue = 0;
-    int i;
-
-    while (digits--) {
-        while (!pc.readable())
-            wdt.Service();
-        i = pc.getc();
-        if (i == ' ') i = '0';      // special case for leading blank
-        if (i >= '0' && i <= '9') {
-            pc.putc(i);
-            tempValue = tempValue * 10 + (i - '0');
-        } else
-            return false;
-    }
-    *pValue = tempValue;
-    return true;
-}
-
-/// RTC_Set will interactively set the Real Time Clock
-///
-/// It will allow you to enter the date and time information
-/// and then create a timestamp. After this, it will set
-/// the RTC to that timestamp.
-///
-void RTC_Set(void) {
-    time_t seconds = time(NULL);
-    struct tm *t = localtime(&seconds);
-
-    pc.printf("RTC Set:\r\n");
-    GetTimeString(seconds, tzOffsetHr, tzOffsetMin);
-    pc.printf("    Enter the time MM/DD/YYYY HH:MM:SS\r\n");
-    while (1) {
-        int _m, _d, _y, _H, _M, _S;
-        printf("                 > ");
-        if (GetNumber(2, &_m)) {
-            pc.putc('/');
-            if (!GetNumber(2, &_d))
-                continue;
-            pc.putc('/');
-            if (!GetNumber(4, &_y))
-                continue;
-            t->tm_mon = _m - 1;
-            t->tm_mday = _d;
-            t->tm_year = _y - 1900;
-        } else {
-            pc.printf("%02d/%02d/%04d", t->tm_mon+1, t->tm_mday, t->tm_year+1900);
-        }
-        pc.putc(' ');
-        if (GetNumber(2, &_H)) {
-            pc.putc(':');
-            if (!GetNumber(2, &_M))
-                continue;
-            pc.putc(':');
-            if (!GetNumber(2, &_S))
-                continue;
-            t->tm_hour = _H;
-            t->tm_min = _M;
-            t->tm_sec = _S;
-            pc.printf("\r\n");
-            pc.printf("%02d/%02d/%04d ", t->tm_mon+1, t->tm_mday, t->tm_year+1900);
-            pc.printf("%02d:%02d:%02d\r\n", t->tm_hour, t->tm_min, t->tm_sec);
-            // convert to timestamp and display (1256729737)
-            time_t seconds = mktime(t);
-            seconds = seconds - (time_t)(tzOffsetHr * 3600 + tzOffsetMin * 60);
-            set_time(seconds);
-            break;
-        } else {
-            pc.printf("%02d:%02d:%02d\r\n", t->tm_hour, t->tm_min, t->tm_sec);
-            break;          // they can bail here
-        }
-    }
-}
-#endif

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