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@17:45dae5a72679, 2017-04-12 (annotated)

Committer:
WiredHome
Date:
Wed Apr 12 02:25:22 2017 +0000
Revision:
17:45dae5a72679
Parent:
16:6280e99501f8
Child:
20:5ca2c94d46b8
Enhanced strptime to set the day of week correctly by interpreting the time value parameters.

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 4:9cae2da8215e 5 #include <ctime>
WiredHome 0:61112ca9193b 6
WiredHome 11:1d880a50da8a 7 #include "NTPClient.h" // ver 9
WiredHome 2:65e0a25c7551 8
WiredHome 0:61112ca9193b 9 // Special Registers and their usage:
WiredHome 0:61112ca9193b 10 // GPREG0: 32 bits
WiredHome 0:61112ca9193b 11 // low word: time zone offset (-720 to +720)
WiredHome 0:61112ca9193b 12 // high word: 2's complement of low word for integrity checking
WiredHome 0:61112ca9193b 13 // GPREG1: 32 bits
WiredHome 0:61112ca9193b 14 // time_t value when the clock was last set
WiredHome 0:61112ca9193b 15
WiredHome 0:61112ca9193b 16
WiredHome 0:61112ca9193b 17 extern "C" {
WiredHome 0:61112ca9193b 18 #include "time.h"
WiredHome 0:61112ca9193b 19 }
WiredHome 0:61112ca9193b 20
WiredHome 0:61112ca9193b 21 struct tm_ex
WiredHome 0:61112ca9193b 22 {
WiredHome 0:61112ca9193b 23 int tm_sec; ///<! seconds, 0 to 59.
WiredHome 0:61112ca9193b 24 int tm_min; ///<! minutes, 0 to 59.
WiredHome 0:61112ca9193b 25 int tm_hour; ///<! hours, 0 to 23.
WiredHome 0:61112ca9193b 26 int tm_mday; ///<! monthday 1 to 31.
WiredHome 0:61112ca9193b 27 int tm_mon; ///<! month 0 to 11.
WiredHome 0:61112ca9193b 28 int tm_year; ///<! years since 1900.
WiredHome 0:61112ca9193b 29 int tm_wday; ///<! days since sunday 0 to 6.
WiredHome 0:61112ca9193b 30 int tm_yday; ///<! days since 1 Jan 0 to 365.
WiredHome 0:61112ca9193b 31 int tm_isdst; ///<! is daylight savings time.
WiredHome 0:61112ca9193b 32 int tm_tzo_min; ///<! localtime zone offset in minutes
WiredHome 0:61112ca9193b 33 };
WiredHome 0:61112ca9193b 34
WiredHome 11:1d880a50da8a 35 /// TimeInterface class is much like the normal c-style time.h interface, but
WiredHome 11:1d880a50da8a 36 /// is extended with time-zone support, and clock-adjustment support (which
WiredHome 11:1d880a50da8a 37 /// permits tuning the clock) for more accuracy.
WiredHome 11:1d880a50da8a 38 ///
WiredHome 11:1d880a50da8a 39 /// Additionally, strptime was integrated, which can extract the time from
WiredHome 11:1d880a50da8a 40 /// a text string. A formatter is used, so it cannot parse an arbitrary string.
WiredHome 0:61112ca9193b 41 ///
WiredHome 0:61112ca9193b 42 /// Within this class are the normal time.h methods, simply
WiredHome 0:61112ca9193b 43 /// exposed here for one consistent interface.
WiredHome 0:61112ca9193b 44 ///
WiredHome 0:61112ca9193b 45 /// @note This class uses the special battery backed registers
WiredHome 0:61112ca9193b 46 /// GPREG0 and GPREG1 for TimeInterface data.
WiredHome 0:61112ca9193b 47 ///
WiredHome 0:61112ca9193b 48 /// @note In mbed library ver 84, the gmtime method is defective,
WiredHome 0:61112ca9193b 49 /// and calls to this function return junk data. The
WiredHome 0:61112ca9193b 50 /// gmtime method in this library actually uses localtime,
WiredHome 0:61112ca9193b 51 /// but manages the time-zone offset as it does so.
WiredHome 0:61112ca9193b 52 ///
WiredHome 11:1d880a50da8a 53 /// @code
WiredHome 11:1d880a50da8a 54 /// // TimeInterface Architecture
WiredHome 11:1d880a50da8a 55 /// //
WiredHome 11:1d880a50da8a 56 /// // +--------+
WiredHome 11:1d880a50da8a 57 /// // | clock |----> clock_t clock()
WiredHome 11:1d880a50da8a 58 /// // +--------+
WiredHome 11:1d880a50da8a 59 /// //
WiredHome 11:1d880a50da8a 60 /// // +--------+
WiredHome 11:1d880a50da8a 61 /// // | RTC |<---- setTime(char*, uint16_t, uint32_t)
WiredHome 11:1d880a50da8a 62 /// // | |<---- adjust_sec(int32_t)
WiredHome 11:1d880a50da8a 63 /// // | |<---- set_cal(int32_t)
WiredHome 11:1d880a50da8a 64 /// // | |----> int32_t get_cal()
WiredHome 11:1d880a50da8a 65 /// // | |----> bool get_dst()
WiredHome 17:45dae5a72679 66 /// // | |
WiredHome 11:1d880a50da8a 67 /// // | |<---- set_time(time_t t, int16_t)
WiredHome 11:1d880a50da8a 68 /// // | |----> time_t time(time_t *)
WiredHome 17:45dae5a72679 69 /// // | |------+
WiredHome 17:45dae5a72679 70 /// // +--------+ |
WiredHome 17:45dae5a72679 71 /// // +- | <---- set_dst(char *, char *)
WiredHome 17:45dae5a72679 72 /// // +--------+ | | +----------+
WiredHome 17:45dae5a72679 73 /// // | |<--+ +--|time_local|
WiredHome 17:45dae5a72679 74 /// // |dst_pair|---------| |--------> time_t timelocal(time_t *)
WiredHome 17:45dae5a72679 75 /// // +--------+ +--| |
WiredHome 17:45dae5a72679 76 /// // | +----------+
WiredHome 17:45dae5a72679 77 /// // +--------+ |
WiredHome 17:45dae5a72679 78 /// // | tzo |------+
WiredHome 11:1d880a50da8a 79 /// // | |<---- set_tzo_min(int16_t)
WiredHome 11:1d880a50da8a 80 /// // | |----> int16_t get_tzo_min()
WiredHome 11:1d880a50da8a 81 /// // +--------+
WiredHome 11:1d880a50da8a 82 /// //
WiredHome 11:1d880a50da8a 83 /// // +--------+ +--------------------------+
WiredHome 11:1d880a50da8a 84 /// // | time_t | ---> char * ctime(time_t *) ----> | buffer |
WiredHome 11:1d880a50da8a 85 /// // | value | | Www Mmm dd hh:mm:ss yyyy |
WiredHome 11:1d880a50da8a 86 /// // +--------+ +- char * asctime(tm_ex *) -> +--------------------------+
WiredHome 11:1d880a50da8a 87 /// // ^ | |
WiredHome 11:1d880a50da8a 88 /// // | | | +-----------------+
WiredHome 11:1d880a50da8a 89 /// // | | +-------------------------------> | tm_ex |
WiredHome 11:1d880a50da8a 90 /// // | | | .tm_sec |
WiredHome 11:1d880a50da8a 91 /// // | +- tm_ex * gmtime(const time_t *) -----> | .tm_min |
WiredHome 11:1d880a50da8a 92 /// // | | | .tm_hour |
WiredHome 11:1d880a50da8a 93 /// // | +- tm_ex * localtime(const time_t *) --> | .tm_mday |
WiredHome 11:1d880a50da8a 94 /// // | | .tm_mon |
WiredHome 11:1d880a50da8a 95 /// // +---- time_t mktime(struct tm_ex *) ------- | .tm_year |
WiredHome 11:1d880a50da8a 96 /// // | .tm_wday |
WiredHome 11:1d880a50da8a 97 /// // | .tm_yday |
WiredHome 11:1d880a50da8a 98 /// // | .tm_isdst |
WiredHome 11:1d880a50da8a 99 /// // +-------------------------------------------- | .tm_tzo_min |
WiredHome 11:1d880a50da8a 100 /// // | +-----------------+
WiredHome 11:1d880a50da8a 101 /// // | +--------------------------+
WiredHome 11:1d880a50da8a 102 /// // +- strftime(char * ptr, ..., tm_ex *) --> | buffer |
WiredHome 11:1d880a50da8a 103 /// // +--------------------------+
WiredHome 11:1d880a50da8a 104 /// // double difftime(time_t end, time_t)
WiredHome 11:1d880a50da8a 105 /// @endcode
WiredHome 11:1d880a50da8a 106 ///
WiredHome 0:61112ca9193b 107 class TimeInterface
WiredHome 0:61112ca9193b 108 {
WiredHome 0:61112ca9193b 109 public:
WiredHome 11:1d880a50da8a 110 /// Constructor for the TimeInterface class, which does minimal initialization.
WiredHome 11:1d880a50da8a 111 ///
WiredHome 0:61112ca9193b 112 TimeInterface();
WiredHome 0:61112ca9193b 113
WiredHome 11:1d880a50da8a 114 /// Destructor, normally not used, because it is typically kept for the life
WiredHome 11:1d880a50da8a 115 /// of the program.
WiredHome 11:1d880a50da8a 116 ///
WiredHome 0:61112ca9193b 117 ~TimeInterface();
WiredHome 0:61112ca9193b 118
WiredHome 0:61112ca9193b 119 /// Gets the system elapsed time in CLOCKS_PER_SEC tics.
WiredHome 0:61112ca9193b 120 ///
WiredHome 0:61112ca9193b 121 /// Divide the returned value by CLOCKS_PER_SEC to get time in seconds.
WiredHome 0:61112ca9193b 122 ///
WiredHome 0:61112ca9193b 123 /// @code
WiredHome 0:61112ca9193b 124 /// clock_t tstart, tend;
WiredHome 0:61112ca9193b 125 /// tstart = clock();
WiredHome 0:61112ca9193b 126 /// // do something long
WiredHome 0:61112ca9193b 127 /// tend = clock();
WiredHome 0:61112ca9193b 128 /// printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC);
WiredHome 0:61112ca9193b 129 /// @endcode
WiredHome 0:61112ca9193b 130 ///
WiredHome 0:61112ca9193b 131 /// @returns elapsed tics.
WiredHome 0:61112ca9193b 132 ///
WiredHome 0:61112ca9193b 133 clock_t clock(void);
WiredHome 0:61112ca9193b 134
WiredHome 8:18489e877b0b 135 /// Gets the current time as a UTC time value, optionally writing it
WiredHome 0:61112ca9193b 136 /// to a provided buffer.
WiredHome 0:61112ca9193b 137 ///
WiredHome 8:18489e877b0b 138 /// This reads the real time clock and returns the current UTC time.
WiredHome 0:61112ca9193b 139 ///
WiredHome 0:61112ca9193b 140 /// @code
WiredHome 0:61112ca9193b 141 /// time_t t_ref1, t_ref2, t_ref3;
WiredHome 0:61112ca9193b 142 /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3);
WiredHome 0:61112ca9193b 143 /// @endcode
WiredHome 0:61112ca9193b 144 ///
WiredHome 8:18489e877b0b 145 /// @param[in,out] timer is an optional pointer to a time_t value that will be written.
WiredHome 0:61112ca9193b 146 /// This pointer is ignored when NULL.
WiredHome 8:18489e877b0b 147 /// @returns the UTC time value.
WiredHome 0:61112ca9193b 148 ///
WiredHome 0:61112ca9193b 149 time_t time(time_t * timer = NULL);
WiredHome 0:61112ca9193b 150
WiredHome 8:18489e877b0b 151 /// Gets the current time as a LOCAL time value, optionally writing it
WiredHome 1:2ee90f546f54 152 /// to a provided buffer.
WiredHome 1:2ee90f546f54 153 ///
WiredHome 1:2ee90f546f54 154 /// This reads the real time clock and returns the current time, adjusted
WiredHome 6:c79cfe750416 155 /// for the local timezone and daylight savings time.
WiredHome 1:2ee90f546f54 156 ///
WiredHome 1:2ee90f546f54 157 /// @code
WiredHome 1:2ee90f546f54 158 /// time_t t_ref2, t_ref3;
WiredHome 1:2ee90f546f54 159 /// t_ref2 = t.time(); t.timelocal(&t_ref3);
WiredHome 1:2ee90f546f54 160 /// @endcode
WiredHome 1:2ee90f546f54 161 ///
WiredHome 8:18489e877b0b 162 /// @param[in,out] timer is an optional pointer to a time_t value that will be written.
WiredHome 1:2ee90f546f54 163 /// This pointer is ignored when NULL.
WiredHome 8:18489e877b0b 164 /// @returns the LOCAL time value (UTC adjusted for the LOCAL time zone).
WiredHome 1:2ee90f546f54 165 ///
WiredHome 1:2ee90f546f54 166 time_t timelocal(time_t * timer = NULL);
WiredHome 1:2ee90f546f54 167
WiredHome 0:61112ca9193b 168 /// Convert a time value structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
WiredHome 0:61112ca9193b 169 ///
WiredHome 0:61112ca9193b 170 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 171 /// shared buffer.
WiredHome 0:61112ca9193b 172 /// @note Unlike the standard ctime function, this version DOES NOT append
WiredHome 0:61112ca9193b 173 /// a newline character to the buffer.
WiredHome 0:61112ca9193b 174 ///
WiredHome 1:2ee90f546f54 175 /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
WiredHome 0:61112ca9193b 176 /// @returns a pointer to a private buffer containing the string.
WiredHome 0:61112ca9193b 177 ///
WiredHome 0:61112ca9193b 178 char * ctime(const time_t * timer);
WiredHome 0:61112ca9193b 179
WiredHome 0:61112ca9193b 180 /// Convert a tm structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
WiredHome 0:61112ca9193b 181 ///
WiredHome 0:61112ca9193b 182 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 183 /// shared buffer.
WiredHome 0:61112ca9193b 184 /// @note Unlike the standard ctime function, this version DOES NOT append
WiredHome 0:61112ca9193b 185 /// a newline character to the buffer.
WiredHome 0:61112ca9193b 186 ///
WiredHome 14:b5c01a52bff4 187 /// @code
WiredHome 14:b5c01a52bff4 188 /// time_t tNow = timelocal();
WiredHome 14:b5c01a52bff4 189 /// tm_ex * tEx = localtime(&tNow);
WiredHome 14:b5c01a52bff4 190 /// printf("Time is %s\r\n", asctime(tEx));
WiredHome 14:b5c01a52bff4 191 /// @endcode
WiredHome 14:b5c01a52bff4 192 ///
WiredHome 1:2ee90f546f54 193 /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
WiredHome 0:61112ca9193b 194 /// @returns a pointer to a private buffer containing the string.
WiredHome 0:61112ca9193b 195 ///
WiredHome 0:61112ca9193b 196 char * asctime(const struct tm_ex *timeptr);
WiredHome 0:61112ca9193b 197
WiredHome 0:61112ca9193b 198 /// Compute the difference in seconds between two time values.
WiredHome 0:61112ca9193b 199 ///
WiredHome 1:2ee90f546f54 200 /// @param[in] end is the end time to compare to the beginning time.
WiredHome 1:2ee90f546f54 201 /// @param[in] beginning time is compared to the end time.
WiredHome 0:61112ca9193b 202 /// @return the difference in seconds, as a double.
WiredHome 0:61112ca9193b 203 ///
WiredHome 0:61112ca9193b 204 double difftime(time_t end, time_t beginning);
WiredHome 0:61112ca9193b 205
WiredHome 0:61112ca9193b 206 /// Convert the referenced time_t value to a tm structure in UTC/GMT format.
WiredHome 0:61112ca9193b 207 ///
WiredHome 0:61112ca9193b 208 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 209 /// shared buffer.
WiredHome 0:61112ca9193b 210 ///
WiredHome 1:2ee90f546f54 211 /// @param[in] timer is a pointer to a time_t structure to convert.
WiredHome 0:61112ca9193b 212 /// @returns pointer to a tm structure.
WiredHome 0:61112ca9193b 213 ///
WiredHome 0:61112ca9193b 214 struct tm_ex * gmtime(const time_t * timer);
WiredHome 0:61112ca9193b 215
WiredHome 0:61112ca9193b 216
WiredHome 0:61112ca9193b 217 /// Convert the referenced time_t value to a tm structure in local format.
WiredHome 0:61112ca9193b 218 ///
WiredHome 6:c79cfe750416 219 /// This method leverages the time zone offset applied with @see set_tzo()
WiredHome 6:c79cfe750416 220 /// and the daylight savings time flag applied with @see set_dst().
WiredHome 0:61112ca9193b 221 ///
WiredHome 0:61112ca9193b 222 /// @note Watch out for race conditions as this returns a pointer to a
WiredHome 0:61112ca9193b 223 /// shared buffer.
WiredHome 0:61112ca9193b 224 ///
WiredHome 14:b5c01a52bff4 225 /// @code
WiredHome 14:b5c01a52bff4 226 /// time_t tNow = timelocal();
WiredHome 14:b5c01a52bff4 227 /// tm_ex * tEx = localtime(&tNow);
WiredHome 14:b5c01a52bff4 228 /// @endcode
WiredHome 14:b5c01a52bff4 229 ///
WiredHome 1:2ee90f546f54 230 /// @param[in] timer is a pointer to a time_t structure to convert.
WiredHome 0:61112ca9193b 231 /// @returns pointer to a tm structure.
WiredHome 0:61112ca9193b 232 ///
WiredHome 0:61112ca9193b 233 struct tm_ex * localtime(const time_t * timer);
WiredHome 0:61112ca9193b 234
WiredHome 0:61112ca9193b 235 /// Convert a tm_ex structure (an extended time structure) to a time_t
WiredHome 0:61112ca9193b 236 /// value.
WiredHome 0:61112ca9193b 237 ///
WiredHome 1:2ee90f546f54 238 /// @param[in] timeptr is a pointer to a tm_ex structure.
WiredHome 0:61112ca9193b 239 /// @returns the computed time_t value.
WiredHome 0:61112ca9193b 240 ///
WiredHome 0:61112ca9193b 241 time_t mktime(struct tm_ex * timeptr);
WiredHome 0:61112ca9193b 242
WiredHome 0:61112ca9193b 243 /// Presents a time value in a user specified format, into a user specified buffer.
WiredHome 0:61112ca9193b 244 ///
WiredHome 1:2ee90f546f54 245 /// @param[out] ptr is a pointer to the user buffer.
WiredHome 1:2ee90f546f54 246 /// @param[in] maxsize is the size of the user buffer.
WiredHome 1:2ee90f546f54 247 /// @param[in] format is a pointer to the special strftime format specification.
WiredHome 15:82bd8fc6f317 248 /// see format options.
WiredHome 1:2ee90f546f54 249 /// @param[in] timeptr is a pointer to the tm_ex structure.
WiredHome 0:61112ca9193b 250 /// @returns the total number of characters copied into the buffer.
WiredHome 0:61112ca9193b 251 ///
WiredHome 15:82bd8fc6f317 252 /// format options:
WiredHome 15:82bd8fc6f317 253 /// - %%a Abbreviated weekday name e.g. Thu
WiredHome 15:82bd8fc6f317 254 /// - %%A Full weekday name e.g. Thursday
WiredHome 15:82bd8fc6f317 255 /// - %%b Abbreviated month name e.g. Aug
WiredHome 15:82bd8fc6f317 256 /// - %%B Full month name e.g. August
WiredHome 15:82bd8fc6f317 257 /// - %%c Date and time representation e.g. Thu Aug 23 14:55:02 2001
WiredHome 15:82bd8fc6f317 258 /// - %%C Year divided by 100 and truncated to integer (00-99) e.g. 20
WiredHome 15:82bd8fc6f317 259 /// - %%d Day of the month, zero-padded (01-31) e.g. 23
WiredHome 15:82bd8fc6f317 260 /// - %%D Short MM/DD/YY date, equivalent to %%m/%%d/%%y e.g. 08/23/01
WiredHome 15:82bd8fc6f317 261 /// - %%e Day of the month, space-padded ( 1-31) e.g. 23
WiredHome 15:82bd8fc6f317 262 /// - %%F Short YYYY-MM-DD date, equivalent to %%Y-%%m-%%d e.g. 2001-08-23
WiredHome 15:82bd8fc6f317 263 /// - %%g Week-based year, last two digits (00-99) e.g. 01
WiredHome 15:82bd8fc6f317 264 /// - %%G Week-based year e.g. 2001
WiredHome 15:82bd8fc6f317 265 /// - %%h Abbreviated month name * (same as %%b) e.g. Aug
WiredHome 15:82bd8fc6f317 266 /// - %%H Hour in 24h format (00-23) e.g. 14
WiredHome 15:82bd8fc6f317 267 /// - %%I Hour in 12h format (01-12) e.g. 02
WiredHome 15:82bd8fc6f317 268 /// - %%j Day of the year (001-366) e.g. 235
WiredHome 15:82bd8fc6f317 269 /// - %%m Month as a decimal number (01-12) e.g. 08
WiredHome 15:82bd8fc6f317 270 /// - %%M Minute (00-59) e.g. 55
WiredHome 15:82bd8fc6f317 271 /// - %%n New-line character ('\\n')
WiredHome 15:82bd8fc6f317 272 /// - %%p AM or PM designation e.g. PM
WiredHome 15:82bd8fc6f317 273 /// - %%r 12-hour clock time e.g. 02:55:02 pm
WiredHome 15:82bd8fc6f317 274 /// - %%R 24-hour HH:MM time, equivalent to %%H:%%M e.g. 14:55
WiredHome 15:82bd8fc6f317 275 /// - %%S Second (00-61) e.g. 02
WiredHome 15:82bd8fc6f317 276 /// - %%t Horizontal-tab character ('\t')
WiredHome 15:82bd8fc6f317 277 /// - %%T ISO 8601 time format (HH:MM:SS), equivalent to %%H:%%M:%%S e.g. 14:55:02
WiredHome 15:82bd8fc6f317 278 /// - %%u ISO 8601 weekday as number with Monday as 1 (1-7) e.g. 4
WiredHome 15:82bd8fc6f317 279 /// - %%U Week number with the first Sunday as the first day of week one (00-53) e.g. 33
WiredHome 15:82bd8fc6f317 280 /// - %%V ISO 8601 week number (00-53) e.g. 34
WiredHome 15:82bd8fc6f317 281 /// - %%w Weekday as a decimal number with Sunday as 0 (0-6) e.g. 4
WiredHome 15:82bd8fc6f317 282 /// - %%W Week number with the first Monday as the first day of week one (00-53) e.g. 34
WiredHome 15:82bd8fc6f317 283 /// - %%x Date representation e.g. 08/23/01
WiredHome 15:82bd8fc6f317 284 /// - %%X Time representation e.g. 14:55:02
WiredHome 15:82bd8fc6f317 285 /// - %%y Year, last two digits (00-99) e.g. 01
WiredHome 15:82bd8fc6f317 286 /// - %%Y Year e.g. 2001
WiredHome 15:82bd8fc6f317 287 /// - %%z ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100) (e.g. +100)
WiredHome 15:82bd8fc6f317 288 /// If timezone cannot be determined, no characters
WiredHome 15:82bd8fc6f317 289 /// - %%Z Timezone name or abbreviation (e.g. CDT)
WiredHome 15:82bd8fc6f317 290 /// If timezone cannot be determined, no characters
WiredHome 15:82bd8fc6f317 291 /// - % A % sign
WiredHome 15:82bd8fc6f317 292 ///
WiredHome 0:61112ca9193b 293 size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr);
WiredHome 0:61112ca9193b 294
WiredHome 10:5734dbc2f5cc 295
WiredHome 10:5734dbc2f5cc 296 /// Convert a string, in a defined format, to a time value in a tm_ex structure.
WiredHome 10:5734dbc2f5cc 297 ///
WiredHome 10:5734dbc2f5cc 298 /// Most format details leveraged from The Open Group Base Specifications Issue 6
WiredHome 10:5734dbc2f5cc 299 /// IEEE Std 1003.1, 2004 Edition
WiredHome 10:5734dbc2f5cc 300 /// Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.
WiredHome 10:5734dbc2f5cc 301 ///
WiredHome 10:5734dbc2f5cc 302 /// Modifications for mbed, and addition of the timezone format option by D. Smart
WiredHome 10:5734dbc2f5cc 303 ///
WiredHome 10:5734dbc2f5cc 304 /// @code
WiredHome 10:5734dbc2f5cc 305 /// char timesample[] = "Jan 22 2017 01:32:48 UTC";
WiredHome 10:5734dbc2f5cc 306 /// tm_ex tm;
WiredHome 10:5734dbc2f5cc 307 /// strptime(timesample, "%b %d %Y %H:%M:%S %Z", &tm);
WiredHome 10:5734dbc2f5cc 308 /// @endcode
WiredHome 10:5734dbc2f5cc 309 ///
WiredHome 10:5734dbc2f5cc 310 /// @param[in] buf is a pointer to the string to be parsed.
WiredHome 10:5734dbc2f5cc 311 /// @param[in] format is a pointer to a format string. See the format options.
WiredHome 10:5734dbc2f5cc 312 /// @param[out] tm is a pointer to a tm_ex struct.
WiredHome 10:5734dbc2f5cc 313 /// @returns a pointer to the character following the last one parsed, or null on failure
WiredHome 10:5734dbc2f5cc 314 ///
WiredHome 10:5734dbc2f5cc 315 /// format options:
WiredHome 10:5734dbc2f5cc 316 /// - %%a The day of the week, using the locale's weekday names; either the abbreviated or
WiredHome 10:5734dbc2f5cc 317 /// full name may be specified.
WiredHome 10:5734dbc2f5cc 318 /// - %%A Equivalent to %%a.
WiredHome 10:5734dbc2f5cc 319 /// - %%b The month, using the locale's month names; either the abbreviated or full name
WiredHome 10:5734dbc2f5cc 320 /// may be specified.
WiredHome 10:5734dbc2f5cc 321 /// - %%B Equivalent to %%b.
WiredHome 10:5734dbc2f5cc 322 /// - %%c Replaced by the locale's appropriate date and time representation.
WiredHome 10:5734dbc2f5cc 323 /// - %%C The century number [00,99]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 324 /// - %%d The day of the month [01,31]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 325 /// - %%D The date as %%m / %%d / %%y.
WiredHome 10:5734dbc2f5cc 326 /// - %%e Equivalent to %%d.
WiredHome 10:5734dbc2f5cc 327 /// - %%h Equivalent to %%b.
WiredHome 10:5734dbc2f5cc 328 /// - %%H The hour (24-hour clock) [00,23]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 329 /// - %%I The hour (12-hour clock) [01,12]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 330 /// - %%j The day number of the year [001,366]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 331 /// - %%m The month number [01,12]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 332 /// - %%M The minute [00,59]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 333 /// - %%n Any white space.
WiredHome 10:5734dbc2f5cc 334 /// - %%p The locale's equivalent of a.m or p.m.
WiredHome 10:5734dbc2f5cc 335 /// - %%r 12-hour clock time using the AM/PM notation if t_fmt_ampm is not an empty string
WiredHome 10:5734dbc2f5cc 336 /// in the LC_TIME portion of the current locale; in the POSIX locale, this shall be
WiredHome 10:5734dbc2f5cc 337 /// equivalent to %%I : %%M : %%S %%p.
WiredHome 10:5734dbc2f5cc 338 /// - %%R The time as %%H : %%M.
WiredHome 10:5734dbc2f5cc 339 /// - %%S The seconds [00,60]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 340 /// - %%t Any white space.
WiredHome 10:5734dbc2f5cc 341 /// - %%T The time as %%H : %%M : %%S.
WiredHome 10:5734dbc2f5cc 342 /// - %%U The week number of the year (Sunday as the first day of the week) as a decimal
WiredHome 10:5734dbc2f5cc 343 /// number [00,53]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 344 /// - %%w The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros
WiredHome 10:5734dbc2f5cc 345 /// are permitted but not required.
WiredHome 10:5734dbc2f5cc 346 /// - %%W The week number of the year (Monday as the first day of the week) as a decimal
WiredHome 10:5734dbc2f5cc 347 /// number [00,53]; leading zeros are permitted but not required.
WiredHome 10:5734dbc2f5cc 348 /// - %%x The date, using the locale's date format.
WiredHome 10:5734dbc2f5cc 349 /// - %%X The time, using the locale's time format.
WiredHome 10:5734dbc2f5cc 350 /// - %%y The year within century. When a century is not otherwise specified, values in
WiredHome 10:5734dbc2f5cc 351 /// the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the
WiredHome 10:5734dbc2f5cc 352 /// range [00,68] shall refer to years 2000 to 2068 inclusive; leading zeros shall be
WiredHome 10:5734dbc2f5cc 353 /// permitted but shall not be required.
WiredHome 10:5734dbc2f5cc 354 /// Note: It is expected that in a future version of IEEE Std 1003.1-2001
WiredHome 10:5734dbc2f5cc 355 /// the default century inferred from a 2-digit year will change.
WiredHome 10:5734dbc2f5cc 356 /// (This would apply to all commands accepting a 2-digit year as input.)
WiredHome 10:5734dbc2f5cc 357 /// - %%Y The year, including the century (for example, 1988).
WiredHome 10:5734dbc2f5cc 358 /// - %%Z The timezone offset, as a 3-letter sequence. Only a few whole-hour offsets
WiredHome 10:5734dbc2f5cc 359 /// have been defined.
WiredHome 11:1d880a50da8a 360 /// - %% Replaced by %.
WiredHome 10:5734dbc2f5cc 361 ///
WiredHome 10:5734dbc2f5cc 362 const char * strptime(const char *buf, char *fmt, struct tm_ex *tm);
WiredHome 10:5734dbc2f5cc 363
WiredHome 10:5734dbc2f5cc 364
WiredHome 0:61112ca9193b 365 // time zone functions
WiredHome 0:61112ca9193b 366
WiredHome 8:18489e877b0b 367 /// Set the internal RTC (clock) to the time value.
WiredHome 8:18489e877b0b 368 ///
WiredHome 8:18489e877b0b 369 /// The time valueshould be UTC time along with an offset of zero,
WiredHome 8:18489e877b0b 370 /// which then permits gmtime and localtime to be used appropriately.
WiredHome 8:18489e877b0b 371 /// Alternately, the time can be in localtime, and the offset is then
WiredHome 8:18489e877b0b 372 /// used to compute UTC to set the clock.
WiredHome 0:61112ca9193b 373 ///
WiredHome 2:65e0a25c7551 374 /// @param[in] t should be the UTC time value to set the clock to. If the available
WiredHome 0:61112ca9193b 375 /// time value is local time, the optional time zone offset can
WiredHome 2:65e0a25c7551 376 /// be provided so the system clock is UTC.
WiredHome 1:2ee90f546f54 377 /// @param[in] tzo is the optional time zone offset in minutes when it is in
WiredHome 0:61112ca9193b 378 /// the range of -720 to +720 (-12 hours to + 12 hours). Any
WiredHome 0:61112ca9193b 379 /// other value is illegal and no change will be made.
WiredHome 0:61112ca9193b 380 ///
WiredHome 0:61112ca9193b 381 void set_time(time_t t, int16_t tzo_min = 0);
WiredHome 0:61112ca9193b 382
WiredHome 0:61112ca9193b 383 /// Set the time zone offset in minutes.
WiredHome 0:61112ca9193b 384 ///
WiredHome 0:61112ca9193b 385 /// This API should be used before any other methods that fetch
WiredHome 0:61112ca9193b 386 /// the RTC info.
WiredHome 0:61112ca9193b 387 ///
WiredHome 1:2ee90f546f54 388 /// @param[in] tzo is the time zone offset in minutes when it is in
WiredHome 0:61112ca9193b 389 /// the range of -720 to +720 (-12 hours to + 12 hours). Any
WiredHome 0:61112ca9193b 390 /// other value is illegal and no change will be made.
WiredHome 0:61112ca9193b 391 ///
WiredHome 0:61112ca9193b 392 void set_tzo_min(int16_t tzo_min);
WiredHome 0:61112ca9193b 393
WiredHome 0:61112ca9193b 394 /// Get the time zone offset in minutes.
WiredHome 0:61112ca9193b 395 ///
WiredHome 0:61112ca9193b 396 /// @returns the time zone offset value in minutes. If the tzo was
WiredHome 0:61112ca9193b 397 /// never initialized, this returns zero.
WiredHome 0:61112ca9193b 398 ///
WiredHome 0:61112ca9193b 399 int16_t get_tzo_min(void);
WiredHome 0:61112ca9193b 400
WiredHome 3:49f36b489b64 401 /// Set the clock for local time to report whether the current
WiredHome 3:49f36b489b64 402 /// mode is standard or daylight savings time.
WiredHome 3:49f36b489b64 403 ///
WiredHome 3:49f36b489b64 404 /// return values for localtime will then be adjusted not only
WiredHome 3:49f36b489b64 405 /// for the time zone offset, but for dst.
WiredHome 3:49f36b489b64 406 ///
WiredHome 3:49f36b489b64 407 /// @param[in] dst is a boolean that should be set when dst is
WiredHome 3:49f36b489b64 408 /// the active mode.
WiredHome 6:c79cfe750416 409 /// @returns true, always.
WiredHome 3:49f36b489b64 410 ///
WiredHome 6:c79cfe750416 411 bool set_dst(bool dst);
WiredHome 6:c79cfe750416 412
WiredHome 6:c79cfe750416 413 /// Set the clock for auto-adjust local time based on
WiredHome 6:c79cfe750416 414 /// changing to standard or daylight savings time.
WiredHome 6:c79cfe750416 415 ///
WiredHome 6:c79cfe750416 416 /// return values for localtime will then be adjusted not only
WiredHome 6:c79cfe750416 417 /// for the time zone offset, but for dst.
WiredHome 6:c79cfe750416 418 ///
WiredHome 6:c79cfe750416 419 /// @param[in] dstStart is a string of the form "mm/dd,hh:mm"
WiredHome 6:c79cfe750416 420 /// representing when DST starts.
WiredHome 6:c79cfe750416 421 /// @param[in] dstStop is a string of the form "mm/dd,hh:mm"
WiredHome 6:c79cfe750416 422 /// representing when DST stops.
WiredHome 6:c79cfe750416 423 /// @returns true if the start and stop pair could be successfully
WiredHome 6:c79cfe750416 424 /// parsed.
WiredHome 6:c79cfe750416 425 ///
WiredHome 6:c79cfe750416 426 bool set_dst(const char * dstStart, const char * dstStop);
WiredHome 3:49f36b489b64 427
WiredHome 3:49f36b489b64 428 /// Get the current clock mode for daylight savings time.
WiredHome 3:49f36b489b64 429 ///
WiredHome 3:49f36b489b64 430 /// @returns true if clock is in dst mode.
WiredHome 3:49f36b489b64 431 ///
WiredHome 3:49f36b489b64 432 bool get_dst(void);
WiredHome 3:49f36b489b64 433
WiredHome 0:61112ca9193b 434 /// Get the time value when the clock was last set. This is most
WiredHome 0:61112ca9193b 435 /// often used in calibration of the clock.
WiredHome 0:61112ca9193b 436 ///
WiredHome 0:61112ca9193b 437 /// @returns time last set as a UTC time value.
WiredHome 0:61112ca9193b 438 ///
WiredHome 0:61112ca9193b 439 time_t get_timelastset(void);
WiredHome 0:61112ca9193b 440
WiredHome 0:61112ca9193b 441 /// get_cal will return the calibration register value
WiredHome 0:61112ca9193b 442 ///
WiredHome 0:61112ca9193b 443 /// This is the raw register value as a signed 32-bit value (even though
WiredHome 0:61112ca9193b 444 /// it is actually a 17-bit unsigned value with an additional 'direction' flag).
WiredHome 0:61112ca9193b 445 ///
WiredHome 0:61112ca9193b 446 /// @returns calibration settings ranging from -131071 to +131071
WiredHome 0:61112ca9193b 447 ///
WiredHome 0:61112ca9193b 448 int32_t get_cal();
WiredHome 0:61112ca9193b 449
WiredHome 0:61112ca9193b 450 /// set_cal will set the calibration register value
WiredHome 0:61112ca9193b 451 ///
WiredHome 0:61112ca9193b 452 /// This accepts a signed value to be used to set the calibration
WiredHome 0:61112ca9193b 453 /// registers. Setting the calibration value to zero disables the
WiredHome 0:61112ca9193b 454 /// calibration function.
WiredHome 0:61112ca9193b 455 ///
WiredHome 0:61112ca9193b 456 /// It is important to know the register function in order to use
WiredHome 0:61112ca9193b 457 /// this command, and this API is normally not used by external
WiredHome 0:61112ca9193b 458 /// application code. @See AdjustBySeconds for a user-friendly
WiredHome 0:61112ca9193b 459 /// API.
WiredHome 0:61112ca9193b 460 ///
WiredHome 1:2ee90f546f54 461 /// @param[in] calibration value to use ranging from -131071 to +131071
WiredHome 0:61112ca9193b 462 /// @returns nothing
WiredHome 0:61112ca9193b 463 ///
WiredHome 0:61112ca9193b 464 void set_cal(int32_t calibration);
WiredHome 0:61112ca9193b 465
WiredHome 0:61112ca9193b 466 /// adjust_sec adjusts both the time and the calibration by seconds
WiredHome 0:61112ca9193b 467 ///
WiredHome 0:61112ca9193b 468 /// This will take a signed value, which is the current adjustment in seconds
WiredHome 0:61112ca9193b 469 /// to put the clock on the correct time. So, if the clock is behind by
WiredHome 0:61112ca9193b 470 /// 3 seconds, the value should be +3 to advance the clock accordingly.
WiredHome 0:61112ca9193b 471 /// It will then adjust the time, and it will attempt to adjust the
WiredHome 0:61112ca9193b 472 /// calibration factor to make the time more accurate.
WiredHome 0:61112ca9193b 473 ///
WiredHome 0:61112ca9193b 474 /// The adjustment can only be made if it has retained when the clock was
WiredHome 0:61112ca9193b 475 /// last set, in order to know by how much to adjust it. It is also most
WiredHome 0:61112ca9193b 476 /// accurate if several days have elapsed since the time was set.
WiredHome 0:61112ca9193b 477 ///
WiredHome 0:61112ca9193b 478 /// @note The current version only works if the calibration value
WiredHome 0:61112ca9193b 479 /// is zero when this adjustment is made.
WiredHome 0:61112ca9193b 480 ///
WiredHome 1:2ee90f546f54 481 /// @param[in] adjustSeconds is the signed value by which to adjust the time to
WiredHome 0:61112ca9193b 482 /// correct it to the current actual time.
WiredHome 0:61112ca9193b 483 /// @returns true if the adjustment was made
WiredHome 0:61112ca9193b 484 /// @returns false if the adjustment could not be made
WiredHome 0:61112ca9193b 485 ///
WiredHome 0:61112ca9193b 486 bool adjust_sec(int32_t adjustSeconds);
WiredHome 0:61112ca9193b 487
WiredHome 2:65e0a25c7551 488 /// Set the clock from an internet source (blocking)
WiredHome 2:65e0a25c7551 489 ///
WiredHome 2:65e0a25c7551 490 /// This function is the interface to NTPClient.
WiredHome 2:65e0a25c7551 491 /// Blocks until completion
WiredHome 2:65e0a25c7551 492 ///
WiredHome 2:65e0a25c7551 493 /// @param[in] host NTP server IPv4 address or hostname (will be resolved via DNS)
WiredHome 2:65e0a25c7551 494 /// @param[in] port port to use; defaults to 123
WiredHome 2:65e0a25c7551 495 /// @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 2:65e0a25c7551 496 /// @return 0 on success, NTP error code (<0) on failure
WiredHome 2:65e0a25c7551 497 ///
WiredHome 2:65e0a25c7551 498 NTPResult setTime(const char* host, uint16_t port = NTP_DEFAULT_PORT, uint32_t timeout = NTP_DEFAULT_TIMEOUT);
WiredHome 2:65e0a25c7551 499
WiredHome 2:65e0a25c7551 500 // ntp interface functions
WiredHome 0:61112ca9193b 501 private:
WiredHome 6:c79cfe750416 502 typedef struct {
WiredHome 6:c79cfe750416 503 uint8_t MM;
WiredHome 6:c79cfe750416 504 uint8_t DD;
WiredHome 6:c79cfe750416 505 uint8_t hh;
WiredHome 6:c79cfe750416 506 uint8_t mm;
WiredHome 6:c79cfe750416 507 } dst_event_t;
WiredHome 6:c79cfe750416 508 typedef struct {
WiredHome 6:c79cfe750416 509 dst_event_t dst_start;
WiredHome 6:c79cfe750416 510 dst_event_t dst_stop;
WiredHome 6:c79cfe750416 511 } dst_event_pair_t;
WiredHome 6:c79cfe750416 512
WiredHome 6:c79cfe750416 513 bool parseDSTstring(dst_event_t * result, const char * dstr);
WiredHome 6:c79cfe750416 514
WiredHome 6:c79cfe750416 515 /// Performs a "simple" computation of two dates into minutes.
WiredHome 6:c79cfe750416 516 ///
WiredHome 6:c79cfe750416 517 /// Does not account for leap years or which month it is. Is
WiredHome 6:c79cfe750416 518 /// useful only for comparing which date/time came first, not for
WiredHome 6:c79cfe750416 519 /// computing the difference between them.
WiredHome 6:c79cfe750416 520 ///
WiredHome 6:c79cfe750416 521 /// @return "normalized" minutes since Jan 1 00:00.
WiredHome 6:c79cfe750416 522 ///
WiredHome 6:c79cfe750416 523 uint32_t minutesSinceJan(int mon, int day, int hr, int min);
WiredHome 6:c79cfe750416 524
WiredHome 6:c79cfe750416 525 dst_event_pair_t dst_pair;
WiredHome 6:c79cfe750416 526 bool dst; // true in dst mode
WiredHome 0:61112ca9193b 527 char result[30]; // holds the converted to text time string
WiredHome 0:61112ca9193b 528 time_t tresult; // holds the converted time structure.
WiredHome 0:61112ca9193b 529 struct tm_ex tm_ext;
WiredHome 0:61112ca9193b 530 };
WiredHome 0:61112ca9193b 531
WiredHome 11:1d880a50da8a 532 #endif // TIMEINTERFACE_H