David Smart / TimeInterface

A time interface class. This class replicates the normal time functions, but goes a couple of steps further. mbed library 82 and prior has a defective gmtime function. Also, this class enables access to setting the time, and adjusting the accuracy of the RTC.

Dependencies:   CalendarPage

Dependents:   CI-data-logger-server WattEye X10Svr SSDP_Server

TimeInterface.h@1:2ee90f546f54, 2014-06-14 (annotated)

Committer:
WiredHome
Date:
Sat Jun 14 12:34:53 2014 +0000
Revision:
1:2ee90f546f54
Parent:
0:61112ca9193b
Child:
2:65e0a25c7551
Add timelocal() method so local time offset does not have to be added in every use of time().

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:61112ca9193b 1
WiredHome 0:61112ca9193b 2 #ifndef TIMEINTERFACE_H
WiredHome 0:61112ca9193b 3 #define TIMEINTERFACE_H
WiredHome 0:61112ca9193b 4 #include "mbed.h"
WiredHome 0:61112ca9193b 5
WiredHome 0:61112ca9193b 6 // Special Registers and their usage:
WiredHome 0:61112ca9193b 7 // GPREG0: 32 bits
WiredHome 0:61112ca9193b 8 // low word: time zone offset (-720 to +720)
WiredHome 0:61112ca9193b 9 // high word: 2's complement of low word for integrity checking
WiredHome 0:61112ca9193b 10 // GPREG1: 32 bits
WiredHome 0:61112ca9193b 11 // time_t value when the clock was last set
WiredHome 0:61112ca9193b 12
WiredHome 0:61112ca9193b 13
WiredHome 0:61112ca9193b 14 extern "C" {
WiredHome 0:61112ca9193b 15 #include "time.h"
WiredHome 0:61112ca9193b 16 }
WiredHome 0:61112ca9193b 17
WiredHome 0:61112ca9193b 18 struct tm_ex
WiredHome 0:61112ca9193b 19 {
WiredHome 0:61112ca9193b 20 int tm_sec; ///<! seconds, 0 to 59.
WiredHome 0:61112ca9193b 21 int tm_min; ///<! minutes, 0 to 59.
WiredHome 0:61112ca9193b 22 int tm_hour; ///<! hours, 0 to 23.
WiredHome 0:61112ca9193b 23 int tm_mday; ///<! monthday 1 to 31.
WiredHome 0:61112ca9193b 24 int tm_mon; ///<! month 0 to 11.
WiredHome 0:61112ca9193b 25 int tm_year; ///<! years since 1900.
WiredHome 0:61112ca9193b 26 int tm_wday; ///<! days since sunday 0 to 6.
WiredHome 0:61112ca9193b 27 int tm_yday; ///<! days since 1 Jan 0 to 365.
WiredHome 0:61112ca9193b 28 int tm_isdst; ///<! is daylight savings time.
WiredHome 0:61112ca9193b 29 int tm_tzo_min; ///<! localtime zone offset in minutes
WiredHome 0:61112ca9193b 30 };
WiredHome 0:61112ca9193b 31
WiredHome 0:61112ca9193b 32 /// TimeInterface class is much like the normal c-style time.h
WiredHome 0:61112ca9193b 33 /// interface, but is extended with time-zone support, and
WiredHome 0:61112ca9193b 34 /// clock-adjustment support (which permits tuning the clock)
WiredHome 0:61112ca9193b 35 /// for more accuracy.
WiredHome 0:61112ca9193b 36 ///
WiredHome 0:61112ca9193b 37 /// Within this class are the normal time.h methods, simply
WiredHome 0:61112ca9193b 38 /// exposed here for one consistent interface.
WiredHome 0:61112ca9193b 39 ///
WiredHome 0:61112ca9193b 40 /// @note This class uses the special battery backed registers
WiredHome 0:61112ca9193b 41 /// GPREG0 and GPREG1 for TimeInterface data.
WiredHome 0:61112ca9193b 42 ///
WiredHome 0:61112ca9193b 43 /// @note In mbed library ver 84, the gmtime method is defective,
WiredHome 0:61112ca9193b 44 /// and calls to this function return junk data. The
WiredHome 0:61112ca9193b 45 /// gmtime method in this library actually uses localtime,
WiredHome 0:61112ca9193b 46 /// but manages the time-zone offset as it does so.
WiredHome 0:61112ca9193b 47 ///
WiredHome 0:61112ca9193b 48 class TimeInterface
WiredHome 0:61112ca9193b 49 {
WiredHome 0:61112ca9193b 50 public:
WiredHome 0:61112ca9193b 51 TimeInterface();
WiredHome 0:61112ca9193b 52
WiredHome 0:61112ca9193b 53 ~TimeInterface();
WiredHome 0:61112ca9193b 54
WiredHome 0:61112ca9193b 55 /// Gets the system elapsed time in CLOCKS_PER_SEC tics.
WiredHome 0:61112ca9193b 56 ///
WiredHome 0:61112ca9193b 57 /// Divide the returned value by CLOCKS_PER_SEC to get time in seconds.
WiredHome 0:61112ca9193b 58 ///
WiredHome 0:61112ca9193b 59 /// @code
WiredHome 0:61112ca9193b 60 /// clock_t tstart, tend;
WiredHome 0:61112ca9193b 61 /// tstart = clock();
WiredHome 0:61112ca9193b 62 /// // do something long
WiredHome 0:61112ca9193b 63 /// tend = clock();
WiredHome 0:61112ca9193b 64 /// printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC);
WiredHome 0:61112ca9193b 65 /// @endcode
WiredHome 0:61112ca9193b 66 ///
WiredHome 0:61112ca9193b 67 /// @returns elapsed tics.
WiredHome 0:61112ca9193b 68 ///
WiredHome 0:61112ca9193b 69 clock_t clock(void);
WiredHome 0:61112ca9193b 70
WiredHome 0:61112ca9193b 71 /// Gets the current time as a time value, optionally writing it
WiredHome 0:61112ca9193b 72 /// to a provided buffer.
WiredHome 0:61112ca9193b 73 ///
WiredHome 0:61112ca9193b 74 /// This reads the real time clock and returns the current time.
WiredHome 0:61112ca9193b 75 ///
WiredHome 0:61112ca9193b 76 /// @code
WiredHome 0:61112ca9193b 77 /// time_t t_ref1, t_ref2, t_ref3;
WiredHome 0:61112ca9193b 78 /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3);
WiredHome 0:61112ca9193b 79 /// @endcode
WiredHome 0:61112ca9193b 80 ///
WiredHome 1:2ee90f546f54 81 /// @param[inout] timer is an optional pointer to a time_t value that will be written.
WiredHome 0:61112ca9193b 82 /// This pointer is ignored when NULL.
WiredHome 0:61112ca9193b 83 /// @returns time value.
WiredHome 0:61112ca9193b 84 ///
WiredHome 0:61112ca9193b 85 time_t time(time_t * timer = NULL);
WiredHome 0:61112ca9193b 86
WiredHome 1:2ee90f546f54 87 /// Gets the current local time as a time value, optionally writing it
WiredHome 1:2ee90f546f54 88 /// to a provided buffer.
WiredHome 1:2ee90f546f54 89 ///
WiredHome 1:2ee90f546f54 90 /// This reads the real time clock and returns the current time, adjusted
WiredHome 1:2ee90f546f54 91 /// for the local timezone.
WiredHome 1:2ee90f546f54 92 ///
WiredHome 1:2ee90f546f54 93 /// @code
WiredHome 1:2ee90f546f54 94 /// time_t t_ref2, t_ref3;
WiredHome 1:2ee90f546f54 95 /// t_ref2 = t.time(); t.timelocal(&t_ref3);
WiredHome 1:2ee90f546f54 96 /// @endcode
WiredHome 1:2ee90f546f54 97 ///
WiredHome 1:2ee90f546f54 98 /// @param[inout] timer is an optional pointer to a time_t value that will be written.
WiredHome 1:2ee90f546f54 99 /// This pointer is ignored when NULL.
WiredHome 1:2ee90f546f54 100 /// @returns the time value adjusted for the local time zone.
WiredHome 1:2ee90f546f54 101 ///
WiredHome 1:2ee90f546f54 102 time_t timelocal(time_t * timer = NULL);
WiredHome 1:2ee90f546f54 103
WiredHome 0:61112ca9193b 104 /// Convert a time value structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
WiredHome 0:61112ca9193b 105 ///
WiredHome 0:61112ca9193b 106 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 107 /// shared buffer.
WiredHome 0:61112ca9193b 108 /// @note Unlike the standard ctime function, this version DOES NOT append
WiredHome 0:61112ca9193b 109 /// a newline character to the buffer.
WiredHome 0:61112ca9193b 110 ///
WiredHome 1:2ee90f546f54 111 /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
WiredHome 0:61112ca9193b 112 /// @returns a pointer to a private buffer containing the string.
WiredHome 0:61112ca9193b 113 ///
WiredHome 0:61112ca9193b 114 char * ctime(const time_t * timer);
WiredHome 0:61112ca9193b 115
WiredHome 0:61112ca9193b 116 /// Convert a tm structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
WiredHome 0:61112ca9193b 117 ///
WiredHome 0:61112ca9193b 118 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 119 /// shared buffer.
WiredHome 0:61112ca9193b 120 /// @note Unlike the standard ctime function, this version DOES NOT append
WiredHome 0:61112ca9193b 121 /// a newline character to the buffer.
WiredHome 0:61112ca9193b 122 ///
WiredHome 1:2ee90f546f54 123 /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
WiredHome 0:61112ca9193b 124 /// @returns a pointer to a private buffer containing the string.
WiredHome 0:61112ca9193b 125 ///
WiredHome 0:61112ca9193b 126 char * asctime(const struct tm_ex *timeptr);
WiredHome 0:61112ca9193b 127
WiredHome 0:61112ca9193b 128 /// Compute the difference in seconds between two time values.
WiredHome 0:61112ca9193b 129 ///
WiredHome 1:2ee90f546f54 130 /// @param[in] end is the end time to compare to the beginning time.
WiredHome 1:2ee90f546f54 131 /// @param[in] beginning time is compared to the end time.
WiredHome 0:61112ca9193b 132 /// @return the difference in seconds, as a double.
WiredHome 0:61112ca9193b 133 ///
WiredHome 0:61112ca9193b 134 double difftime(time_t end, time_t beginning);
WiredHome 0:61112ca9193b 135
WiredHome 0:61112ca9193b 136 /// Convert the referenced time_t value to a tm structure in UTC/GMT format.
WiredHome 0:61112ca9193b 137 ///
WiredHome 0:61112ca9193b 138 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 139 /// shared buffer.
WiredHome 0:61112ca9193b 140 ///
WiredHome 1:2ee90f546f54 141 /// @param[in] timer is a pointer to a time_t structure to convert.
WiredHome 0:61112ca9193b 142 /// @returns pointer to a tm structure.
WiredHome 0:61112ca9193b 143 ///
WiredHome 0:61112ca9193b 144 struct tm_ex * gmtime(const time_t * timer);
WiredHome 0:61112ca9193b 145
WiredHome 0:61112ca9193b 146
WiredHome 0:61112ca9193b 147 /// Convert the referenced time_t value to a tm structure in local format.
WiredHome 0:61112ca9193b 148 ///
WiredHome 0:61112ca9193b 149 /// This method leverages the time zone offset applied with @see set_tzo().
WiredHome 0:61112ca9193b 150 ///
WiredHome 0:61112ca9193b 151 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 152 /// shared buffer.
WiredHome 0:61112ca9193b 153 ///
WiredHome 1:2ee90f546f54 154 /// @param[in] timer is a pointer to a time_t structure to convert.
WiredHome 0:61112ca9193b 155 /// @returns pointer to a tm structure.
WiredHome 0:61112ca9193b 156 ///
WiredHome 0:61112ca9193b 157 struct tm_ex * localtime(const time_t * timer);
WiredHome 0:61112ca9193b 158
WiredHome 0:61112ca9193b 159 /// Convert a tm_ex structure (an extended time structure) to a time_t
WiredHome 0:61112ca9193b 160 /// value.
WiredHome 0:61112ca9193b 161 ///
WiredHome 1:2ee90f546f54 162 /// @param[in] timeptr is a pointer to a tm_ex structure.
WiredHome 0:61112ca9193b 163 /// @returns the computed time_t value.
WiredHome 0:61112ca9193b 164 ///
WiredHome 0:61112ca9193b 165 time_t mktime(struct tm_ex * timeptr);
WiredHome 0:61112ca9193b 166
WiredHome 0:61112ca9193b 167 /// Presents a time value in a user specified format, into a user specified buffer.
WiredHome 0:61112ca9193b 168 ///
WiredHome 1:2ee90f546f54 169 /// @param[out] ptr is a pointer to the user buffer.
WiredHome 1:2ee90f546f54 170 /// @param[in] maxsize is the size of the user buffer.
WiredHome 1:2ee90f546f54 171 /// @param[in] format is a pointer to the special strftime format specification.
WiredHome 1:2ee90f546f54 172 /// @param[in] timeptr is a pointer to the tm_ex structure.
WiredHome 0:61112ca9193b 173 /// @returns the total number of characters copied into the buffer.
WiredHome 0:61112ca9193b 174 ///
WiredHome 0:61112ca9193b 175 size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr);
WiredHome 0:61112ca9193b 176
WiredHome 0:61112ca9193b 177 // time zone functions
WiredHome 0:61112ca9193b 178
WiredHome 0:61112ca9193b 179 /// Set the internal RTC (clock) to the time value. The time value
WiredHome 0:61112ca9193b 180 /// should be the UTC time, which then permits gmtime and
WiredHome 0:61112ca9193b 181 /// localtime to be used appropriately.
WiredHome 0:61112ca9193b 182 ///
WiredHome 1:2ee90f546f54 183 /// @param[in] t is the UTC time value to set the clock to. If the available
WiredHome 0:61112ca9193b 184 /// time value is local time, the optional time zone offset can
WiredHome 0:61112ca9193b 185 /// be provided.
WiredHome 1:2ee90f546f54 186 /// @param[in] tzo is the optional time zone offset in minutes when it is in
WiredHome 0:61112ca9193b 187 /// the range of -720 to +720 (-12 hours to + 12 hours). Any
WiredHome 0:61112ca9193b 188 /// other value is illegal and no change will be made.
WiredHome 0:61112ca9193b 189 ///
WiredHome 0:61112ca9193b 190 void set_time(time_t t, int16_t tzo_min = 0);
WiredHome 0:61112ca9193b 191
WiredHome 0:61112ca9193b 192 /// Set the time zone offset in minutes.
WiredHome 0:61112ca9193b 193 ///
WiredHome 0:61112ca9193b 194 /// This API should be used before any other methods that fetch
WiredHome 0:61112ca9193b 195 /// the RTC info.
WiredHome 0:61112ca9193b 196 ///
WiredHome 1:2ee90f546f54 197 /// @param[in] tzo is the time zone offset in minutes when it is in
WiredHome 0:61112ca9193b 198 /// the range of -720 to +720 (-12 hours to + 12 hours). Any
WiredHome 0:61112ca9193b 199 /// other value is illegal and no change will be made.
WiredHome 0:61112ca9193b 200 ///
WiredHome 0:61112ca9193b 201 void set_tzo_min(int16_t tzo_min);
WiredHome 0:61112ca9193b 202
WiredHome 0:61112ca9193b 203 /// Get the time zone offset in minutes.
WiredHome 0:61112ca9193b 204 ///
WiredHome 0:61112ca9193b 205 /// @returns the time zone offset value in minutes. If the tzo was
WiredHome 0:61112ca9193b 206 /// never initialized, this returns zero.
WiredHome 0:61112ca9193b 207 ///
WiredHome 0:61112ca9193b 208 int16_t get_tzo_min(void);
WiredHome 0:61112ca9193b 209
WiredHome 0:61112ca9193b 210 /// Get the time value when the clock was last set. This is most
WiredHome 0:61112ca9193b 211 /// often used in calibration of the clock.
WiredHome 0:61112ca9193b 212 ///
WiredHome 0:61112ca9193b 213 /// @returns time last set as a UTC time value.
WiredHome 0:61112ca9193b 214 ///
WiredHome 0:61112ca9193b 215 time_t get_timelastset(void);
WiredHome 0:61112ca9193b 216
WiredHome 0:61112ca9193b 217 /// get_cal will return the calibration register value
WiredHome 0:61112ca9193b 218 ///
WiredHome 0:61112ca9193b 219 /// This is the raw register value as a signed 32-bit value (even though
WiredHome 0:61112ca9193b 220 /// it is actually a 17-bit unsigned value with an additional 'direction' flag).
WiredHome 0:61112ca9193b 221 ///
WiredHome 0:61112ca9193b 222 /// @returns calibration settings ranging from -131071 to +131071
WiredHome 0:61112ca9193b 223 ///
WiredHome 0:61112ca9193b 224 int32_t get_cal();
WiredHome 0:61112ca9193b 225
WiredHome 0:61112ca9193b 226 /// set_cal will set the calibration register value
WiredHome 0:61112ca9193b 227 ///
WiredHome 0:61112ca9193b 228 /// This accepts a signed value to be used to set the calibration
WiredHome 0:61112ca9193b 229 /// registers. Setting the calibration value to zero disables the
WiredHome 0:61112ca9193b 230 /// calibration function.
WiredHome 0:61112ca9193b 231 ///
WiredHome 0:61112ca9193b 232 /// It is important to know the register function in order to use
WiredHome 0:61112ca9193b 233 /// this command, and this API is normally not used by external
WiredHome 0:61112ca9193b 234 /// application code. @See AdjustBySeconds for a user-friendly
WiredHome 0:61112ca9193b 235 /// API.
WiredHome 0:61112ca9193b 236 ///
WiredHome 1:2ee90f546f54 237 /// @param[in] calibration value to use ranging from -131071 to +131071
WiredHome 0:61112ca9193b 238 /// @returns nothing
WiredHome 0:61112ca9193b 239 ///
WiredHome 0:61112ca9193b 240 void set_cal(int32_t calibration);
WiredHome 0:61112ca9193b 241
WiredHome 0:61112ca9193b 242 /// adjust_sec adjusts both the time and the calibration by seconds
WiredHome 0:61112ca9193b 243 ///
WiredHome 0:61112ca9193b 244 /// This will take a signed value, which is the current adjustment in seconds
WiredHome 0:61112ca9193b 245 /// to put the clock on the correct time. So, if the clock is behind by
WiredHome 0:61112ca9193b 246 /// 3 seconds, the value should be +3 to advance the clock accordingly.
WiredHome 0:61112ca9193b 247 /// It will then adjust the time, and it will attempt to adjust the
WiredHome 0:61112ca9193b 248 /// calibration factor to make the time more accurate.
WiredHome 0:61112ca9193b 249 ///
WiredHome 0:61112ca9193b 250 /// The adjustment can only be made if it has retained when the clock was
WiredHome 0:61112ca9193b 251 /// last set, in order to know by how much to adjust it. It is also most
WiredHome 0:61112ca9193b 252 /// accurate if several days have elapsed since the time was set.
WiredHome 0:61112ca9193b 253 ///
WiredHome 0:61112ca9193b 254 /// @note The current version only works if the calibration value
WiredHome 0:61112ca9193b 255 /// is zero when this adjustment is made.
WiredHome 0:61112ca9193b 256 ///
WiredHome 1:2ee90f546f54 257 /// @param[in] adjustSeconds is the signed value by which to adjust the time to
WiredHome 0:61112ca9193b 258 /// correct it to the current actual time.
WiredHome 0:61112ca9193b 259 /// @returns true if the adjustment was made
WiredHome 0:61112ca9193b 260 /// @returns false if the adjustment could not be made
WiredHome 0:61112ca9193b 261 ///
WiredHome 0:61112ca9193b 262 bool adjust_sec(int32_t adjustSeconds);
WiredHome 0:61112ca9193b 263
WiredHome 0:61112ca9193b 264
WiredHome 0:61112ca9193b 265 // ntp interface functions
WiredHome 0:61112ca9193b 266
WiredHome 0:61112ca9193b 267 private:
WiredHome 0:61112ca9193b 268 char result[30]; // holds the converted to text time string
WiredHome 0:61112ca9193b 269 time_t tresult; // holds the converted time structure.
WiredHome 0:61112ca9193b 270 struct tm_ex tm_ext;
WiredHome 0:61112ca9193b 271 };
WiredHome 0:61112ca9193b 272
WiredHome 0:61112ca9193b 273 #endif // TIMEINTERFACE_H