Diff: TimeInterface.h

Revision:

0:61112ca9193b

Child:

1:2ee90f546f54

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/TimeInterface.h	Sun Jun 08 00:18:43 2014 +0000
@@ -0,0 +1,256 @@
+
+#ifndef TIMEINTERFACE_H
+#define TIMEINTERFACE_H
+#include "mbed.h"
+
+// Special Registers and their usage:
+// GPREG0: 32 bits
+//      low word: time zone offset (-720 to +720)
+//      high word: 2's complement of low word for integrity checking
+// GPREG1: 32 bits
+//      time_t value when the clock was last set
+
+
+extern "C" {
+#include "time.h"
+}
+
+struct tm_ex
+{
+    int   tm_sec;       ///<! seconds, 0 to 59.
+    int   tm_min;       ///<! minutes, 0 to 59.
+    int   tm_hour;      ///<! hours,   0 to 23.
+    int   tm_mday;      ///<! monthday 1 to 31.
+    int   tm_mon;       ///<! month    0 to 11.
+    int   tm_year;      ///<! years since 1900.
+    int   tm_wday;      ///<! days since sunday 0 to 6.
+    int   tm_yday;      ///<! days since 1 Jan 0 to 365.
+    int   tm_isdst;     ///<! is daylight savings time.
+    int   tm_tzo_min;   ///<! localtime zone offset in minutes
+};
+
+/// TimeInterface class is much like the normal c-style time.h
+/// interface, but is extended with time-zone support, and
+/// clock-adjustment support (which permits tuning the clock)
+/// for more accuracy.
+///
+/// Within this class are the normal time.h methods, simply
+/// exposed here for one consistent interface.
+///
+/// @note This class uses the special battery backed registers
+///     GPREG0 and GPREG1 for TimeInterface data.
+///
+/// @note In mbed library ver 84, the gmtime method is defective,
+///     and calls to this function return junk data. The 
+///     gmtime method in this library actually uses localtime,
+///     but manages the time-zone offset as it does so.
+///
+class TimeInterface
+    {
+public:
+    TimeInterface();
+    
+    ~TimeInterface();
+    
+    /// Gets the system elapsed time in CLOCKS_PER_SEC tics.
+    ///
+    /// Divide the returned value by CLOCKS_PER_SEC to get time in seconds.
+    ///
+    /// @code
+    /// clock_t tstart, tend;
+    /// tstart = clock();
+    /// // do something long
+    /// tend = clock();
+    /// printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC);
+    /// @endcode
+    ///
+    /// @returns elapsed tics.
+    ///
+    clock_t clock(void);
+    
+    /// Gets the current time as a time value, optionally writing it
+    /// to a provided buffer.
+    ///
+    /// This reads the real time clock and returns the current time.
+    ///
+    /// @code
+    /// time_t t_ref1, t_ref2, t_ref3;
+    /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3);
+    /// @endcode
+    ///
+    /// @param timer is an optional pointer to a time_t value that will be written. 
+    ///     This pointer is ignored when NULL.
+    /// @returns time value.
+    ///
+    time_t time(time_t * timer = NULL);
+
+    /// Convert a time value structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
+    ///
+    /// @note Watch out for race conditions as this returns a pointer to a
+    ///     shared buffer.
+    /// @note Unlike the standard ctime function, this version DOES NOT append 
+    ///     a newline character to the buffer.
+    ///
+    /// @param timeptr is a pointer to a tm structure containing the time to convert.
+    /// @returns a pointer to a private buffer containing the string.
+    ///
+    char * ctime(const time_t * timer);
+
+    /// Convert a tm structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
+    ///
+    /// @note Watch out for race conditions as this returns a pointer to a
+    ///     shared buffer.
+    /// @note Unlike the standard ctime function, this version DOES NOT append 
+    ///     a newline character to the buffer.
+    ///
+    /// @param timeptr is a pointer to a tm structure containing the time to convert.
+    /// @returns a pointer to a private buffer containing the string.
+    ///
+    char * asctime(const struct tm_ex *timeptr);
+
+    /// Compute the difference in seconds between two time values.
+    ///
+    /// @param end is the end time to compare to the beginning time.
+    /// @param beginning time is compared to the end time.
+    /// @return the difference in seconds, as a double.
+    ///
+    double difftime(time_t end, time_t beginning);
+    
+    /// Convert the referenced time_t value to a tm structure in UTC/GMT format.
+    ///
+    /// @note Watch out for race conditions as this returns a pointer to a
+    ///     shared buffer.
+    ///
+    /// @param timer is a pointer to a time_t structure to convert.
+    /// @returns pointer to a tm structure.
+    ///
+    struct tm_ex * gmtime(const time_t * timer);
+    
+    
+    /// Convert the referenced time_t value to a tm structure in local format.
+    ///
+    /// This method leverages the time zone offset applied with @see set_tzo().
+    ///
+    /// @note Watch out for race conditions as this returns a pointer to a
+    ///     shared buffer.
+    ///
+    /// @param timer is a pointer to a time_t structure to convert.
+    /// @returns pointer to a tm structure.
+    ///
+    struct tm_ex * localtime(const time_t * timer);
+    
+    /// Convert a tm_ex structure (an extended time structure) to a time_t
+    /// value.
+    ///
+    /// @param timeptr is a pointer to a tm_ex structure.
+    /// @returns the computed time_t value.
+    ///
+    time_t mktime(struct tm_ex * timeptr);
+    
+    /// Presents a time value in a user specified format, into a user specified buffer.
+    ///
+    /// @param ptr is a pointer to the user buffer.
+    /// @param maxsize is the size of the user buffer.
+    /// @param format is a pointer to the special strftime format specification.
+    /// @param timeptr is a pointer to the tm_ex structure.
+    /// @returns the total number of characters copied into the buffer.
+    ///
+    size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr);
+    
+    // time zone functions
+    
+    /// Set the internal RTC (clock) to the time value. The time value
+    /// should be the UTC time, which then permits gmtime and 
+    /// localtime to be used appropriately.
+    ///
+    /// @param t is the UTC time value to set the clock to. If the available 
+    ///     time value is local time, the optional time zone offset can
+    ///     be provided.
+    /// @param tzo is the optional time zone offset in minutes when it is in
+    ///     the range of -720 to +720 (-12 hours to + 12 hours). Any
+    ///     other value is illegal and no change will be made.
+    ///
+    void set_time(time_t t, int16_t tzo_min = 0);
+    
+    /// Set the time zone offset in minutes.
+    ///
+    /// This API should be used before any other methods that fetch
+    /// the RTC info.
+    ///
+    /// @param tzo is the time zone offset in minutes when it is in
+    ///     the range of -720 to +720 (-12 hours to + 12 hours). Any
+    ///     other value is illegal and no change will be made.
+    ///
+    void set_tzo_min(int16_t tzo_min);
+    
+    /// Get the time zone offset in minutes.
+    ///
+    /// @returns the time zone offset value in minutes. If the tzo was
+    /// never initialized, this returns zero.
+    ///
+    int16_t get_tzo_min(void);
+    
+    /// Get the time value when the clock was last set. This is most
+    /// often used in calibration of the clock.
+    ///
+    /// @returns time last set as a UTC time value.
+    ///
+    time_t get_timelastset(void);
+    
+    /// get_cal 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 get_cal();
+
+    /// set_cal 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. 
+    ///
+    /// It is important to know the register function in order to use 
+    /// this command, and this API is normally not used by external
+    /// application code. @See AdjustBySeconds for a user-friendly
+    /// API.
+    ///
+    /// @param calibration value to use ranging from -131071 to +131071
+    /// @returns nothing
+    ///
+    void set_cal(int32_t calibration);
+
+    /// adjust_sec adjusts both the time and the calibration by seconds
+    ///
+    /// This will take a signed value, which is the current adjustment in seconds
+    /// to put the clock on the correct time. So, if the clock is behind by
+    /// 3 seconds, the value should be +3 to advance the clock accordingly.
+    /// It will then adjust the time, and it will attempt to adjust the
+    /// calibration factor to make the time more accurate.
+    ///
+    /// The adjustment can only be made if it has retained when the clock was
+    /// last set, in order to know by how much to adjust it. It is also most
+    /// accurate if several days have elapsed since the time was set.
+    ///
+    /// @note The current version only works if the calibration value
+    ///       is zero when this adjustment is made.
+    /// 
+    /// @param adjustSeconds is the signed value by which to adjust the time to
+    ///        correct it to the current actual time.
+    /// @returns true if the adjustment was made
+    /// @returns false if the adjustment could not be made
+    ///
+    bool adjust_sec(int32_t adjustSeconds);
+
+    
+    // ntp interface functions
+    
+private:
+    char result[30];    // holds the converted to text time string
+    time_t tresult;     // holds the converted time structure.
+    struct tm_ex tm_ext;
+    };
+
+#endif // TIMEINTERFACE_H
\ No newline at end of file