David Smart / TimeManagement

This is a library for managing the mbed real time clock, including functions for setting and getting the rtc in text format, getting and setting the timezone offset, and getting and setting the calibration register, both directly, and by using an adjustment API to automatically set the calibration value.

Dependents:   LAB4WEEK1 Motor

TimeUtilities.h@0:108436d3cea9, 2011-05-29 (annotated)

Committer:
WiredHome
Date:
Sun May 29 20:11:27 2011 +0000
Revision:
0:108436d3cea9
Child:
1:6d3d16f4b27c
Initial release of a real time clock management library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:108436d3cea9 1 /// @file TimeUtilities.h contains a real time clock interface for the mbed
WiredHome 0:108436d3cea9 2 ///
WiredHome 0:108436d3cea9 3 /// APIs for showing the time from the RTC, or from a passed in value.
WiredHome 0:108436d3cea9 4 /// Also supports setting the clock, timezone offsets and calibration
WiredHome 0:108436d3cea9 5 /// of the RTC subsystem.
WiredHome 0:108436d3cea9 6 ///
WiredHome 0:108436d3cea9 7 /// @note Copyright © 2011 by Smartware Computing, all rights reserved.
WiredHome 0:108436d3cea9 8 /// @author David Smart
WiredHome 0:108436d3cea9 9 ///
WiredHome 0:108436d3cea9 10 #ifndef TIMEUTILITIES_H
WiredHome 0:108436d3cea9 11 #define TIMEUTILITIES_H
WiredHome 0:108436d3cea9 12
WiredHome 0:108436d3cea9 13 #ifndef WIN32
WiredHome 0:108436d3cea9 14 // embedded build
WiredHome 0:108436d3cea9 15 #include "mbed.h"
WiredHome 0:108436d3cea9 16 #else
WiredHome 0:108436d3cea9 17 // fake it for Windows build
WiredHome 0:108436d3cea9 18 typedef int int32_t;
WiredHome 0:108436d3cea9 19 #endif
WiredHome 0:108436d3cea9 20
WiredHome 0:108436d3cea9 21 #include <time.h>
WiredHome 0:108436d3cea9 22
WiredHome 0:108436d3cea9 23 class RealTimeClock
WiredHome 0:108436d3cea9 24 {
WiredHome 0:108436d3cea9 25 public:
WiredHome 0:108436d3cea9 26 /// RealTimeClock is an interface to the mbed RTC module
WiredHome 0:108436d3cea9 27 ///
WiredHome 0:108436d3cea9 28 /// It provides interfaces to get and set the time in text representation
WiredHome 0:108436d3cea9 29 /// as well as a means to get and set the timezone offset, so that it
WiredHome 0:108436d3cea9 30 /// maintains time in UTC format.
WiredHome 0:108436d3cea9 31 ///
WiredHome 0:108436d3cea9 32 /// Additionally, it provides an interface to adjust the calibration
WiredHome 0:108436d3cea9 33 /// registers of the RTC, to compensate for 32 kHz clock error, whether
WiredHome 0:108436d3cea9 34 /// based on the oscillator itself or on some bias to ambient temperature.
WiredHome 0:108436d3cea9 35 ///
WiredHome 0:108436d3cea9 36 /// Example:
WiredHome 0:108436d3cea9 37 /// @code
WiredHome 0:108436d3cea9 38 /// RealTimeClock rtc;
WiredHome 0:108436d3cea9 39 ///
WiredHome 0:108436d3cea9 40 /// void main() {
WiredHome 0:108436d3cea9 41 /// bool success;
WiredHome 0:108436d3cea9 42 /// char TimeTest[] = "05/29/2011 14:15:18 (-6:00)";
WiredHome 0:108436d3cea9 43 /// char buf[50];
WiredHome 0:108436d3cea9 44 ///
WiredHome 0:108436d3cea9 45 /// success = rtc.SetTime(Test);
WiredHome 0:108436d3cea9 46 /// rtc.GetTimeString(buf);
WiredHome 0:108436d3cea9 47 /// printf("success: %i, time: %s\n", success, buf);
WiredHome 0:108436d3cea9 48 /// }
WiredHome 0:108436d3cea9 49 /// prints
WiredHome 0:108436d3cea9 50 /// "success: 1, time: Sun May 29 14:15:18 2011 (tzo: -6:00)"
WiredHome 0:108436d3cea9 51 ///
WiredHome 0:108436d3cea9 52 RealTimeClock();
WiredHome 0:108436d3cea9 53
WiredHome 0:108436d3cea9 54 /// Destructor for the RealTimeClock - normally not used
WiredHome 0:108436d3cea9 55 ~RealTimeClock();
WiredHome 0:108436d3cea9 56
WiredHome 0:108436d3cea9 57 /// GetTimeString gets the formatted time applying the internal time-zone offset of hours and minutes
WiredHome 0:108436d3cea9 58 ///
WiredHome 0:108436d3cea9 59 /// It places the formatted string into the buffer in the format of
WiredHome 0:108436d3cea9 60 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 0:108436d3cea9 61 /// The internal timezone offset can be set with SetTimeOffset
WiredHome 0:108436d3cea9 62 ///
WiredHome 0:108436d3cea9 63 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 0:108436d3cea9 64 /// @param tValue is the optional time value to convert to text, if zero, then the current
WiredHome 0:108436d3cea9 65 /// time is used.
WiredHome 0:108436d3cea9 66 /// @returns nothing
WiredHome 0:108436d3cea9 67 ///
WiredHome 0:108436d3cea9 68 void GetTimeString(char * buffer, time_t tValue = 0);
WiredHome 0:108436d3cea9 69
WiredHome 0:108436d3cea9 70 /// GetTimeString gets the formatted time applying the time-zone offset of hours and minutes
WiredHome 0:108436d3cea9 71 ///
WiredHome 0:108436d3cea9 72 /// It places the formatted string into the buffer in the format of
WiredHome 0:108436d3cea9 73 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 0:108436d3cea9 74 ///
WiredHome 0:108436d3cea9 75 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 0:108436d3cea9 76 /// @param hOffset is the hours offset
WiredHome 0:108436d3cea9 77 /// @param mOffset is the minutes offset
WiredHome 0:108436d3cea9 78 /// @returns nothing
WiredHome 0:108436d3cea9 79 ///
WiredHome 0:108436d3cea9 80 void GetTimeString(char * buffer, int hOffset, int mOffset);
WiredHome 0:108436d3cea9 81
WiredHome 0:108436d3cea9 82 /// GetTimeString gets the formatted time value applying the time-zone offset of hours and minutes
WiredHome 0:108436d3cea9 83 ///
WiredHome 0:108436d3cea9 84 /// It places the formatted string into the buffer in the format of
WiredHome 0:108436d3cea9 85 /// Sun May 29 07:19:24 2011 (tzo: -6:00)
WiredHome 0:108436d3cea9 86 ///
WiredHome 0:108436d3cea9 87 /// @param buffer is a pointer to a buffer large enough (>= 40 chars) for the formatted time string
WiredHome 0:108436d3cea9 88 /// @param tValue is the time value to convert to text, if zero, then the current
WiredHome 0:108436d3cea9 89 /// time is used.
WiredHome 0:108436d3cea9 90 /// @param hOffset is the hours offset
WiredHome 0:108436d3cea9 91 /// @param mOffset is the minutes offset
WiredHome 0:108436d3cea9 92 /// @returns nothing
WiredHome 0:108436d3cea9 93 ///
WiredHome 0:108436d3cea9 94 void GetTimeString(char * buffer, time_t tValue, int hOffset, int mOffset);
WiredHome 0:108436d3cea9 95
WiredHome 0:108436d3cea9 96 /// SetTimeOffset will set the hour and minute timezone offset
WiredHome 0:108436d3cea9 97 ///
WiredHome 0:108436d3cea9 98 /// @param offsetHour is the timezone offset in hours
WiredHome 0:108436d3cea9 99 /// @param offsetMinute is the timezone offset in minutes
WiredHome 0:108436d3cea9 100 /// @returns nothing
WiredHome 0:108436d3cea9 101 ///
WiredHome 0:108436d3cea9 102 void SetTimeOffset(int offsetHour, int offsetMinute);
WiredHome 0:108436d3cea9 103
WiredHome 0:108436d3cea9 104 /// SetTimeOffsetStore will store the timezone offset values in RTC ram
WiredHome 0:108436d3cea9 105 ///
WiredHome 0:108436d3cea9 106 /// This takes the current timezone offset values and stores them in
WiredHome 0:108436d3cea9 107 /// the RTC battery backed ram.
WiredHome 0:108436d3cea9 108 ///
WiredHome 0:108436d3cea9 109 /// @returns nothing
WiredHome 0:108436d3cea9 110 ///
WiredHome 0:108436d3cea9 111 void SetTimeOffsetStore();
WiredHome 0:108436d3cea9 112
WiredHome 0:108436d3cea9 113 /// GetTimeOffsetStore will extract the timezone offset values from RTC ram
WiredHome 0:108436d3cea9 114 ///
WiredHome 0:108436d3cea9 115 /// This extracts the timezone offset values that were stored in RTC
WiredHome 0:108436d3cea9 116 /// battery backed ram and uses them for time information.
WiredHome 0:108436d3cea9 117 ///
WiredHome 0:108436d3cea9 118 /// @returns nothing
WiredHome 0:108436d3cea9 119 ///
WiredHome 0:108436d3cea9 120 void GetTimeOffsetStore();
WiredHome 0:108436d3cea9 121
WiredHome 0:108436d3cea9 122 /// GetTimeCalibration will return the calibration register value
WiredHome 0:108436d3cea9 123 ///
WiredHome 0:108436d3cea9 124 /// This is the raw register value as a signed 32-bit value (even though
WiredHome 0:108436d3cea9 125 /// it is actually a 17-bit unsigned value with an additional 'direction' flag).
WiredHome 0:108436d3cea9 126 ///
WiredHome 0:108436d3cea9 127 /// @returns calibration settings ranging from -131071 to +131071
WiredHome 0:108436d3cea9 128 ///
WiredHome 0:108436d3cea9 129 int32_t GetTimeCalibration();
WiredHome 0:108436d3cea9 130
WiredHome 0:108436d3cea9 131 /// SetTimeCalibration will set the calibration register value
WiredHome 0:108436d3cea9 132 ///
WiredHome 0:108436d3cea9 133 /// This accepts a signed value to be used to set the calibration
WiredHome 0:108436d3cea9 134 /// registers. Setting the calibration value to zero disables the
WiredHome 0:108436d3cea9 135 /// calibration function.
WiredHome 0:108436d3cea9 136 ///
WiredHome 0:108436d3cea9 137 /// @param calibration value to use ranging from -131071 to +131071
WiredHome 0:108436d3cea9 138 /// @returns nothing
WiredHome 0:108436d3cea9 139 ///
WiredHome 0:108436d3cea9 140 void SetTimeCalibration(int32_t calibration);
WiredHome 0:108436d3cea9 141
WiredHome 0:108436d3cea9 142
WiredHome 0:108436d3cea9 143 /// SetTime will set the Real Time Clock from a well formatted string
WiredHome 0:108436d3cea9 144 ///
WiredHome 0:108436d3cea9 145 /// This will read a string, and if it is well formed, it will then
WiredHome 0:108436d3cea9 146 /// set the RTC based on this string. The string should be of the form:
WiredHome 0:108436d3cea9 147 /// 'MM/DD/YYYY HH:MM:SS' and may have the optional timezone offset
WiredHome 0:108436d3cea9 148 /// of the form '(+/-HH:MM)'
WiredHome 0:108436d3cea9 149 ///
WiredHome 0:108436d3cea9 150 /// example: 05/29/2011 13:15:07 (-6:00)
WiredHome 0:108436d3cea9 151 ///
WiredHome 0:108436d3cea9 152 /// @param timestring is the string to parse
WiredHome 0:108436d3cea9 153 /// @returns true if the time was set
WiredHome 0:108436d3cea9 154 ///
WiredHome 0:108436d3cea9 155 bool SetTime(char * timestring);
WiredHome 0:108436d3cea9 156 };
WiredHome 0:108436d3cea9 157
WiredHome 0:108436d3cea9 158 #endif