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.
Dependents: CI-data-logger-server WattEye X10Svr SSDP_Server
TimeInterface.h
- Committer:
- WiredHome
- Date:
- 2017-11-20
- Revision:
- 20:5ca2c94d46b8
- Parent:
- 17:45dae5a72679
- Child:
- 21:f3818e2e0370
File content as of revision 20:5ca2c94d46b8:
#ifndef TIMEINTERFACE_H #define TIMEINTERFACE_H #include "mbed.h" #include <ctime> #include "NTPClient.h" // ver 9 // 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" } /// The tm_ex structure is patterened after the traditional tm struct, however /// it adds an element - the time zone offset in minutes. From this, it is then /// readily able to create a "local time" instead of simply a UTC time. /// 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 (_ex element) }; /// 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. /// /// Additionally, strptime was integrated, which can extract the time from /// a text string. A formatter is used, so it cannot parse an arbitrary string. /// /// 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. /// /// @code /// // TimeInterface Architecture /// // /// // +--------+ /// // | clock |----> clock_t clock() /// // +--------+ /// // /// // +--------+ /// // | RTC |<---- setTime(char*, uint16_t, uint32_t) /// // | |<---- adjust_sec(int32_t) /// // | |<---- set_cal(int32_t) /// // | |----> int32_t get_cal() /// // | |----> bool get_dst() /// // | | /// // | |<---- set_time(time_t t, int16_t) /// // | |----> time_t time(time_t *) /// // | |------+ /// // +--------+ | /// // +- | <---- set_dst(char *, char *) /// // +--------+ | | +----------+ /// // | |<--+ +--|time_local| /// // |dst_pair|---------| |--------> time_t timelocal(time_t *) /// // +--------+ +--| | /// // | +----------+ /// // +--------+ | /// // | tzo |------+ /// // | |<---- set_tzo_min(int16_t) /// // | |----> int16_t get_tzo_min() /// // +--------+ /// // /// // +--------+ +--------------------------+ /// // | time_t | ---> char * ctime(time_t *) ----> | buffer | /// // | value | | Www Mmm dd hh:mm:ss yyyy | /// // +--------+ +- char * asctime(tm_ex *) -> +--------------------------+ /// // ^ | | /// // | | | +-----------------+ /// // | | +-------------------------------- | tm_ex | /// // | | | .tm_sec | /// // | +- tm_ex * gmtime(const time_t *) -----> | .tm_min | /// // | | | .tm_hour | /// // | +- tm_ex * localtime(const time_t *) --> | .tm_mday | /// // | | .tm_mon | /// // +---- time_t mktime(struct tm_ex *) ------- | .tm_year | /// // | .tm_wday | /// // | .tm_yday | /// // +---------------------------------------------> | .tm_isdst | /// // | +-------------------------------------------- | .tm_tzo_min | /// // | | +-----------------+ /// // | | +--------------------------+ /// // | +- strftime(char * ptr, ..., tm_ex *) --> | buffer | /// // +----strptime(char * buf, ..., tm_ex *) --- | Www Mmm dd hh:mm:ss yyyy | /// // +--------------------------+ /// // double difftime(time_t end, time_t) /// @endcode /// class TimeInterface { public: /// Constructor for the TimeInterface class, which does minimal initialization. /// /// @param[in] net is optional and provides the EthernetInterface which is /// used if you want to sync to an NTP server /// TimeInterface(EthernetInterface *m_net = NULL); /// Destructor, normally not used, because it is typically kept for the life /// of the program. /// ~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 UTC time value, optionally writing it /// to a provided buffer. /// /// This reads the real time clock and returns the current UTC time. /// /// @code /// time_t t_ref1, t_ref2, t_ref3; /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3); /// @endcode /// /// @param[in,out] timer is an optional pointer to a time_t value that will be written. /// This pointer is ignored when NULL. /// @returns the UTC time value. /// time_t time(time_t * timer = NULL); /// Gets the current time as a LOCAL time value, optionally writing it /// to a provided buffer. /// /// This reads the real time clock and returns the current time, adjusted /// for the local timezone and daylight savings time. /// /// @code /// time_t t_ref2, t_ref3; /// t_ref2 = t.time(); t.timelocal(&t_ref3); /// @endcode /// /// @param[in,out] timer is an optional pointer to a time_t value that will be written. /// This pointer is ignored when NULL. /// @returns the LOCAL time value (UTC adjusted for the LOCAL time zone). /// time_t timelocal(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. /// /// @code /// time_t tsample = timelocal(); /// printf("time is %s\r\n", ctime(tsample)); /// @endcode /// /// @param[in] 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. /// /// @code /// time_t tNow = timelocal(); /// tm_ex * tEx = localtime(&tNow); /// printf("Time is %s\r\n", asctime(tEx)); /// @endcode /// /// @param[in] 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[in] end is the end time to compare to the beginning time. /// @param[in] 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[in] 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() /// and the daylight savings time flag applied with @see set_dst(). /// /// @note Watch out for race conditions as this returns a pointer to a /// shared buffer. /// /// @code /// time_t tNow = timelocal(); /// tm_ex * tEx = localtime(&tNow); /// @endcode /// /// @param[in] 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[in] 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[out] ptr is a pointer to the user buffer. /// @param[in] maxsize is the size of the user buffer. /// @param[in] format is a pointer to the special strftime format specification. /// see format options. /// @param[in] timeptr is a pointer to the tm_ex structure. /// @returns the total number of characters copied into the buffer. /// /// format options: /// - %%a Abbreviated weekday name e.g. Thu /// - %%A Full weekday name e.g. Thursday /// - %%b Abbreviated month name e.g. Aug /// - %%B Full month name e.g. August /// - %%c Date and time representation e.g. Thu Aug 23 14:55:02 2001 /// - %%C Year divided by 100 and truncated to integer (00-99) e.g. 20 /// - %%d Day of the month, zero-padded (01-31) e.g. 23 /// - %%D Short MM/DD/YY date, equivalent to %%m/%%d/%%y e.g. 08/23/01 /// - %%e Day of the month, space-padded ( 1-31) e.g. 23 /// - %%F Short YYYY-MM-DD date, equivalent to %%Y-%%m-%%d e.g. 2001-08-23 /// - %%g Week-based year, last two digits (00-99) e.g. 01 /// - %%G Week-based year e.g. 2001 /// - %%h Abbreviated month name * (same as %%b) e.g. Aug /// - %%H Hour in 24h format (00-23) e.g. 14 /// - %%I Hour in 12h format (01-12) e.g. 02 /// - %%j Day of the year (001-366) e.g. 235 /// - %%m Month as a decimal number (01-12) e.g. 08 /// - %%M Minute (00-59) e.g. 55 /// - %%n New-line character ('\\n') /// - %%p AM or PM designation e.g. PM /// - %%r 12-hour clock time e.g. 02:55:02 pm /// - %%R 24-hour HH:MM time, equivalent to %%H:%%M e.g. 14:55 /// - %%S Second (00-61) e.g. 02 /// - %%t Horizontal-tab character ('\t') /// - %%T ISO 8601 time format (HH:MM:SS), equivalent to %%H:%%M:%%S e.g. 14:55:02 /// - %%u ISO 8601 weekday as number with Monday as 1 (1-7) e.g. 4 /// - %%U Week number with the first Sunday as the first day of week one (00-53) e.g. 33 /// - %%V ISO 8601 week number (00-53) e.g. 34 /// - %%w Weekday as a decimal number with Sunday as 0 (0-6) e.g. 4 /// - %%W Week number with the first Monday as the first day of week one (00-53) e.g. 34 /// - %%x Date representation e.g. 08/23/01 /// - %%X Time representation e.g. 14:55:02 /// - %%y Year, last two digits (00-99) e.g. 01 /// - %%Y Year e.g. 2001 /// - %%z ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100) (e.g. +100) /// If timezone cannot be determined, no characters /// - %%Z Timezone name or abbreviation (e.g. CDT) /// If timezone cannot be determined, no characters /// - % A % sign /// size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr); /// Convert a string, in a defined format, to a time value in a tm_ex structure. /// /// Most format details leveraged from The Open Group Base Specifications Issue 6 /// IEEE Std 1003.1, 2004 Edition /// Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved. /// /// Modifications for mbed, and addition of the timezone format option by D. Smart /// /// @code /// char timesample[] = "Jan 22 2017 01:32:48 UTC"; /// tm_ex tm; /// strptime(timesample, "%b %d %Y %H:%M:%S %Z", &tm); /// @endcode /// /// @param[in] buf is a pointer to the string to be parsed. /// @param[in] format is a pointer to a format string. See the format options. /// @param[out] tm is a pointer to a tm_ex struct. /// @returns a pointer to the character following the last one parsed, or null on failure /// /// format options: /// - %%a The day of the week, using the locale's weekday names; either the abbreviated or /// full name may be specified. /// - %%A Equivalent to %%a. /// - %%b The month, using the locale's month names; either the abbreviated or full name /// may be specified. /// - %%B Equivalent to %%b. /// - %%c Replaced by the locale's appropriate date and time representation. /// - %%C The century number [00,99]; leading zeros are permitted but not required. /// - %%d The day of the month [01,31]; leading zeros are permitted but not required. /// - %%D The date as %%m / %%d / %%y. /// - %%e Equivalent to %%d. /// - %%h Equivalent to %%b. /// - %%H The hour (24-hour clock) [00,23]; leading zeros are permitted but not required. /// - %%I The hour (12-hour clock) [01,12]; leading zeros are permitted but not required. /// - %%j The day number of the year [001,366]; leading zeros are permitted but not required. /// - %%m The month number [01,12]; leading zeros are permitted but not required. /// - %%M The minute [00,59]; leading zeros are permitted but not required. /// - %%n Any white space. /// - %%p The locale's equivalent of a.m or p.m. /// - %%r 12-hour clock time using the AM/PM notation if t_fmt_ampm is not an empty string /// in the LC_TIME portion of the current locale; in the POSIX locale, this shall be /// equivalent to %%I : %%M : %%S %%p. /// - %%R The time as %%H : %%M. /// - %%S The seconds [00,60]; leading zeros are permitted but not required. /// - %%t Any white space. /// - %%T The time as %%H : %%M : %%S. /// - %%U The week number of the year (Sunday as the first day of the week) as a decimal /// number [00,53]; leading zeros are permitted but not required. /// - %%w The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros /// are permitted but not required. /// - %%W The week number of the year (Monday as the first day of the week) as a decimal /// number [00,53]; leading zeros are permitted but not required. /// - %%x The date, using the locale's date format. /// - %%X The time, using the locale's time format. /// - %%y The year within century. When a century is not otherwise specified, values in /// the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the /// range [00,68] shall refer to years 2000 to 2068 inclusive; leading zeros shall be /// permitted but shall not be required. /// Note: It is expected that in a future version of IEEE Std 1003.1-2001 /// the default century inferred from a 2-digit year will change. /// (This would apply to all commands accepting a 2-digit year as input.) /// - %%Y The year, including the century (for example, 1988). /// - %%Z The timezone offset, as a 3-letter sequence. Only a few whole-hour offsets /// have been defined. /// - %% Replaced by %. /// const char * strptime(const char *buf, char *fmt, struct tm_ex *tm); // time zone functions /// Set the internal RTC (clock) to the time value. /// /// The time valueshould be UTC time along with an offset of zero, /// which then permits gmtime and localtime to be used appropriately. /// Alternately, the time can be in localtime, and the offset is then /// used to compute UTC to set the clock. /// /// @param[in] t should be 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 so the system clock is UTC. /// @param[in] 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[in] 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); /// Set the clock for local time to report whether the current /// mode is standard or daylight savings time. /// /// return values for localtime will then be adjusted not only /// for the time zone offset, but for dst. /// /// @param[in] dst is a boolean that should be set when dst is /// the active mode. /// @returns true, always. /// bool set_dst(bool dst); /// Set the clock for auto-adjust local time based on /// changing to standard or daylight savings time. /// /// return values for localtime will then be adjusted not only /// for the time zone offset, but for dst. /// /// @param[in] dstStart is a string of the form "mm/dd,hh:mm" /// representing when DST starts. /// @param[in] dstStop is a string of the form "mm/dd,hh:mm" /// representing when DST stops. /// @returns true if the start and stop pair could be successfully /// parsed. /// bool set_dst(const char * dstStart, const char * dstStop); /// Get the current clock mode for daylight savings time. /// /// @returns true if clock is in dst mode. /// bool get_dst(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[in] 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[in] 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); /// Set the clock from an internet source (blocking) /// /// This function is the interface to NTPClient. /// Blocks until completion /// /// @param[in] host NTP server IPv4 address or hostname (will be resolved via DNS) /// @param[in] port port to use; defaults to 123 /// @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended) /// @return 0 on success, NTP error code (<0) on failure /// NTPResult setTime(const char* host, uint16_t port = NTP_DEFAULT_PORT, uint32_t timeout = NTP_DEFAULT_TIMEOUT); // ntp interface functions private: EthernetInterface * m_net; typedef struct { uint8_t MM; uint8_t DD; uint8_t hh; uint8_t mm; } dst_event_t; typedef struct { dst_event_t dst_start; dst_event_t dst_stop; } dst_event_pair_t; bool parseDSTstring(dst_event_t * result, const char * dstr); /// Performs a "simple" computation of two dates into minutes. /// /// Does not account for leap years or which month it is. Is /// useful only for comparing which date/time came first, not for /// computing the difference between them. /// /// @return "normalized" minutes since Jan 1 00:00. /// uint32_t minutesSinceJan(int mon, int day, int hr, int min); dst_event_pair_t dst_pair; bool dst; // true in dst mode 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