Diff: TimeUtilities.h

Revision:

0:108436d3cea9

Child:

1:6d3d16f4b27c

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/TimeUtilities.h	Sun May 29 20:11:27 2011 +0000
@@ -0,0 +1,158 @@
+/// @file TimeUtilities.h contains a real time clock interface for the mbed
+///
+/// APIs for showing the time from the RTC, or from a passed in value.
+/// Also supports setting the clock, timezone offsets and calibration
+/// of the RTC subsystem.
+///
+/// @note Copyright © 2011 by Smartware Computing, all rights reserved.
+/// @author David Smart
+///
+#ifndef TIMEUTILITIES_H
+#define TIMEUTILITIES_H
+
+#ifndef WIN32
+// embedded build
+#include "mbed.h"
+#else
+// fake it for Windows build
+typedef int int32_t;
+#endif
+
+#include <time.h>
+
+class RealTimeClock
+{
+public:
+	/// 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 
+	/// 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.
+	///
+	/// Example:
+	/// @code
+	/// RealTimeClock rtc;
+	///
+	/// void main() {
+	///    bool success;
+	///    char TimeTest[] = "05/29/2011 14:15:18 (-6:00)";
+	///	   char buf[50];
+	///
+	///    	success = rtc.SetTime(Test);
+	///     rtc.GetTimeString(buf);
+	///     printf("success: %i, time: %s\n", success, buf);
+	/// }
+	/// prints
+	/// "success: 1, time: Sun May 29 14:15:18 2011 (tzo: -6:00)"
+	///
+	RealTimeClock();
+
+	/// Destructor for the RealTimeClock - normally not used
+	~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
+	/// @param tValue is the optional time value to convert to text, if zero, then the current 
+	///         time is used.
+	/// @returns nothing
+	///
+	void GetTimeString(char * buffer, time_t tValue = 0);
+
+	/// GetTimeString gets the formatted time applying the 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)
+	///
+	/// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
+	/// @param hOffset is the hours offset
+	/// @param mOffset is the minutes offset
+	/// @returns nothing
+	///
+	void GetTimeString(char * buffer, int hOffset, int mOffset);
+
+	/// GetTimeString gets the formatted time value applying the 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)
+	///
+	/// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
+	/// @param tValue is the time value to convert to text, if zero, then the current 
+	///         time is used.
+	/// @param hOffset is the hours offset
+	/// @param mOffset is the minutes offset
+	/// @returns nothing
+	///
+	void GetTimeString(char * buffer, time_t tValue, int hOffset, int mOffset);
+
+	/// SetTimeOffset will set the hour and minute timezone offset
+	///
+	/// @param offsetHour is the timezone offset in hours
+	/// @param offsetMinute is the timezone offset in minutes
+	/// @returns nothing
+	///
+	void SetTimeOffset(int offsetHour, int offsetMinute);
+
+	/// SetTimeOffsetStore will store the timezone offset values in RTC ram
+	///
+	/// This takes the current timezone offset values and stores them in 
+	/// the RTC battery backed ram.
+	///
+	/// @returns nothing
+	///
+	void SetTimeOffsetStore();
+
+	/// GetTimeOffsetStore will extract the timezone offset values from RTC ram
+	///
+	/// This extracts the timezone offset values that were stored in RTC
+	/// battery backed ram and uses them for time information.
+	///
+	/// @returns nothing
+	///
+	void GetTimeOffsetStore();
+
+	/// GetTimeCalibration will return the calibration register value
+	///
+	/// This is the raw register value as a signed 32-bit value (even though
+	/// it is actually a 17-bit unsigned value with an additional 'direction' flag).
+	///
+	/// @returns calibration settings ranging from -131071 to +131071
+	///
+	int32_t GetTimeCalibration();
+
+	/// SetTimeCalibration will set the calibration register value
+	///
+	/// This accepts a signed value to be used to set the calibration
+	/// registers. Setting the calibration value to zero disables the
+	/// calibration function.
+	///
+	/// @param calibration value to use ranging from -131071 to +131071
+	/// @returns nothing
+	///
+	void SetTimeCalibration(int32_t calibration);
+
+
+	/// SetTime will set the Real Time Clock from a well formatted string
+	///
+	/// This will read a string, and if it is well formed, it will then
+	/// set the RTC based on this string. The string should be of the form:
+	/// 'MM/DD/YYYY HH:MM:SS' and may have the optional timezone offset 
+	/// of the form '(+/-HH:MM)'
+	///
+	/// example: 05/29/2011 13:15:07 (-6:00)
+	///
+	/// @param timestring is the string to parse
+	/// @returns true if the time was set
+	///
+	bool SetTime(char * timestring);
+};
+
+#endif