loggerClock class

A class for the clock attached to the logger.

Public static functions

static void setRTCOffset(int8_t offsetHours): Set the static offset in hours from UTC that the RTC is programmed in.
static int8_t getRTCOffset(void) -> int8_t: Get the of the real-time clock (RTC) from UTC in hours.
static time_t getNowAsEpoch(int8_t utcOffset, epochStart epoch) -> time_t: Get the current Universal Coordinated Time (UTC) epoch time from the RTC.
static void getNowAsParts(int8_t& seconds, int8_t& minutes, int8_t& hours, int8_t& day, int8_t& month, int16_t& year, uint8_t tz_offset): Get the current epoch time from the RTC and return it as individual parts.
static String formatDateTime_ISO8601(time_t epochSeconds, int8_t epochSecondsUTCOffset, epochStart epoch) -> String: Convert an epoch time (seconds since a fixed epoch start) into a ISO8601 formatted string.
static String formatDateTime_ISO8601(epochTime in_time, int8_t epochSecondsUTCOffset) -> String: Convert an epochTime object into a ISO8601 formatted string.
static void formatDateTime(char* buffer, const char* fmt, time_t epochSeconds, epochStart epoch): Convert an epoch time into a character string based on the input strftime format string and put it into the given buffer.
static void formatDateTime(char* buffer, const char* fmt, epochTime in_time): Convert an epoch time into a character string based on the input strftime format string and put it into the given buffer.
static bool setRTClock(time_t ts, int8_t utcOffset, epochStart epoch) -> bool: Verify that the input value is sane and if so sets the real time clock to the given time.
static bool setRTClock(epochTime in_time, int8_t utcOffset) -> bool: Verify that the input value is sane and if so sets the real time clock to the given time.
static bool isRTCSane(void) -> bool: Check that the current time on the RTC is within a "sane" range.
static bool isEpochTimeSane(time_t ts, int8_t utcOffset, epochStart epoch) -> bool: Check that a given epoch time (seconds since 1970) is within a "sane" range.
static bool isEpochTimeSane(epochTime in_time, int8_t utcOffset) -> bool: Check that a given epoch time (an epochTime object) is within a "sane" range.
static void setNextRTCInterrupt(time_t ts, int8_t utcOffset, epochStart epoch): Set an alarm to fire a clock interrupt at a specific epoch time.
static void setNextRTCInterrupt(epochTime in_time, int8_t utcOffset): Set an alarm to fire a clock interrupt at a specific epoch time.
static void enablePeriodicRTCInterrupts(): Enable 1 minute interrupts on the RTC.
static void disableRTCInterrupts(): Disable interrupts on the RTC.
static void resetClockInterruptStatus(): Reset the clock interrupt status.
static void rtcISR(void): An ISR to run when the clock interrupt fires.
static void begin(): Start up the real-time clock.
static epochStart getCoreEpochStart() -> epochStart: Get the epoch start for the processor/Arduino core as an epochStart object.
static epochStart getRTCEpochStart() -> epochStart: Get the epoch start for the RTC as an epochStart object.

Protected static functions

static epochStart getProcessorEpochStart() -> epochStart: Figure out where the epoch starts for the processor.
static time_t tsToRawRTC(time_t ts, int8_t utcOffset, epochStart epoch) -> time_t: Convert a timestamp with the given offset and epoch to the RTC internal epoch and UTC offset.
static time_t tsFromRawRTC(time_t ts, int8_t utcOffset, epochStart epoch) -> time_t: Convert a timestamp from the RTC's internal epoch and UTC offset to the requested offset and epoch.
static time_t getRawRTCNow() -> time_t: Get a raw epoch time from the RTC.
static void setRawRTCNow(time_t ts): Sets the RTC to exactly the epoch time provided.
static void rtcBegin(): Begins the underlying RTC.

Protected static variables

static epochStart _core_epoch: The start of the epoch for the processor's internal time.h library.
static int8_t _rtcUTCOffset: The static offset data of the real time clock from UTC in hours.
static epochStart _rtcEpoch: The start of the epoch for the RTC (or the RTC's library).

Function documentation

static void loggerClock::setRTCOffset(int8_t offsetHours)

Set the static offset in hours from UTC that the RTC is programmed in.

Parameters
offsetHours	The offset of the real-time clock (RTC) from UTC in hours

static int8_t loggerClock::getRTCOffset(void)

Get the of the real-time clock (RTC) from UTC in hours.

Returns	int8_t The offset of the real-time clock (RTC) from UTC in hours

static time_t loggerClock::getNowAsEpoch(int8_t utcOffset, epochStart epoch)

Get the current Universal Coordinated Time (UTC) epoch time from the RTC.

Parameters
utcOffset	The offset from UTC to return the epoch time in.
epoch	The type of epoch to use (ie, the standard for the start of the epoch).
Returns	time_t The number of seconds from the start of the given epoch.

static void loggerClock::getNowAsParts(int8_t& seconds, int8_t& minutes, int8_t& hours, int8_t& day, int8_t& month, int16_t& year, uint8_t tz_offset)

Get the current epoch time from the RTC and return it as individual parts.

Parameters
seconds	[out] Reference to a variable where the seconds will be stored
minutes	[out] Reference to a variable where the minutes will be stored
hours	[out] Reference to a variable where the hours will be stored
day	[out] Reference to a variable where the day will be stored
month	[out] Reference to a variable where the month will be stored
year	[out] Reference to a variable where the year will be stored
tz_offset	[in] The time zone offset from UTC in hours

static String loggerClock::formatDateTime_ISO8601(time_t epochSeconds, int8_t epochSecondsUTCOffset, epochStart epoch)

Convert an epoch time (seconds since a fixed epoch start) into a ISO8601 formatted string.

Parameters
epochSeconds	The number of seconds since the start of the given epoch.
epochSecondsUTCOffset	The offset of the input epoch time from UTC in hours.
epoch	The epoch of the input epoch time.
Returns	String An ISO8601 formatted String.

Code modified from parts of the SparkFun RV-8803 library.

static String loggerClock::formatDateTime_ISO8601(epochTime in_time, int8_t epochSecondsUTCOffset)

Convert an epochTime object into a ISO8601 formatted string.

Parameters
in_time	An epochTime object
epochSecondsUTCOffset	The offset of the input epoch time from UTC in hours.
Returns	String An ISO8601 formatted String.

static void loggerClock::formatDateTime(char* buffer, const char* fmt, time_t epochSeconds, epochStart epoch)

Convert an epoch time into a character string based on the input strftime format string and put it into the given buffer.

Parameters
buffer	A buffer to put the finished string into. Make sure that the buffer is big enough to hold all of the characters!
fmt	The strftime format string.
epochSeconds	The number of seconds since the start of the given epoch in the given offset from UTC.
epoch	The epoch of the input epoch time.

static void loggerClock::formatDateTime(char* buffer, const char* fmt, epochTime in_time)

Convert an epoch time into a character string based on the input strftime format string and put it into the given buffer.

Parameters
buffer	A buffer to put the finished string into. Make sure that the buffer is big enough to hold all of the characters!
fmt	The strftime format string.
in_time	An epochTime object

static bool loggerClock::setRTClock(time_t ts, int8_t utcOffset, epochStart epoch)

Verify that the input value is sane and if so sets the real time clock to the given time.

Parameters
ts	The number of seconds since the start of the given epoch.
utcOffset	The offset of the epoch time from UTC.
epoch	The type of epoch to use (ie, the standard for the start of the epoch).
Returns	bool True if the input timestamp passes sanity checks and the clock has been successfully set.

static bool loggerClock::setRTClock(epochTime in_time, int8_t utcOffset)

Verify that the input value is sane and if so sets the real time clock to the given time.

Parameters
in_time	An epochTime object
utcOffset	The offset of the epoch time from UTC.
Returns	bool True if the input timestamp passes sanity checks and the clock has been successfully set.

static bool loggerClock::isRTCSane(void)

Check that the current time on the RTC is within a "sane" range.

Returns	bool True if the current time on the RTC passes sanity range checking

To be sane the clock must be between EARLIEST_SANE_UNIX_TIMESTAMP and LATEST_SANE_UNIX_TIMESTAMP.

static bool loggerClock::isEpochTimeSane(time_t ts, int8_t utcOffset, epochStart epoch)

Check that a given epoch time (seconds since 1970) is within a "sane" range.

Parameters
ts	The timestamp to check (in seconds since the start of the given epoch).
utcOffset	The offset of the epoch time from UTC in hours.
epoch	The type of epoch to use (ie, the standard for the start of the epoch).
Returns	bool True if the given time passes sanity range checking.

To be sane, the clock must be between EARLIEST_SANE_UNIX_TIMESTAMP and LATEST_SANE_UNIX_TIMESTAMP.

static bool loggerClock::isEpochTimeSane(epochTime in_time, int8_t utcOffset)

Check that a given epoch time (an epochTime object) is within a "sane" range.

Parameters
in_time	An epochTime object
utcOffset	The offset of the epoch time from UTC in hours.
Returns	bool True if the given time passes sanity range checking.

To be sane, the clock must be between EARLIEST_SANE_UNIX_TIMESTAMP and LATEST_SANE_UNIX_TIMESTAMP.

static void loggerClock::setNextRTCInterrupt(time_t ts, int8_t utcOffset, epochStart epoch)

Set an alarm to fire a clock interrupt at a specific epoch time.

Parameters
ts	The timestamp for the next interrupt - in seconds from the start of the input epoch.
utcOffset	The offset of the epoch time from UTC in hours.
epoch	The type of epoch to use (ie, the standard for the start of the epoch).

static void loggerClock::setNextRTCInterrupt(epochTime in_time, int8_t utcOffset)

Set an alarm to fire a clock interrupt at a specific epoch time.

Parameters
in_time	An epochTime object
utcOffset	The offset of the epoch time from UTC in hours.

static void loggerClock::enablePeriodicRTCInterrupts()

Enable 1 minute interrupts on the RTC.

Unfortunately, most RTC's do not seem to follow anything like a cron schedule. Recurring/Periodic alarms can generally be only on single seconds/minutes/hours/days not on custom intervals.

static void loggerClock::resetClockInterruptStatus()

Reset the clock interrupt status.

Some RTC's will not fire a new interrupt until the previous interrupt flag has been cleared.

static void loggerClock::rtcISR(void)

An ISR to run when the clock interrupt fires.

For some clocks, we need to reset the clock's interrupt flag so the next interrupt will fire.

static void loggerClock::begin()

Start up the real-time clock.

This is used for operations that cannot happen in the constructor - they must happen at run time, not at compile time.

static epochStart loggerClock::getCoreEpochStart()

Get the epoch start for the processor/Arduino core as an epochStart object.

Returns	epochStart The epoch start for the processor/Arduino core

static epochStart loggerClock::getRTCEpochStart()

Get the epoch start for the RTC as an epochStart object.

Returns	epochStart The epoch start for the RTC

static epochStart loggerClock::getProcessorEpochStart() protected

Figure out where the epoch starts for the processor.

Returns	epochStart The start of the epoch

The real time clock libraries mostly document this, but the cores for the various Arduino processors don't. The time.h file is not much more than a stub.

static time_t loggerClock::tsToRawRTC(time_t ts, int8_t utcOffset, epochStart epoch) protected

Convert a timestamp with the given offset and epoch to the RTC internal epoch and UTC offset.

Parameters
ts	The input epoch time - in seconds since the start of the input epoch.
utcOffset	The offset of the input epoch time from UTC in hours.
epoch	The type of epoch of the input timestamp
Returns	time_t A timestamp converted to the epoch and timezone used internally by the RTC

static time_t loggerClock::tsFromRawRTC(time_t ts, int8_t utcOffset, epochStart epoch) protected

Convert a timestamp from the RTC's internal epoch and UTC offset to the requested offset and epoch.

Parameters
ts	The timestamp in the epoch and timezone used internally by the RTC.
utcOffset	The offset of the desired output epoch time from UTC in hours.
epoch	The type of epoch of the output timestamp
Returns	time_t A timestamp converted from the epoch and timezone used internally by the RTC to the requested epoch and offset

static time_t loggerClock::getRawRTCNow() protected

Get a raw epoch time from the RTC.

Returns	time_t The raw epoch time from the RTC

static void loggerClock::setRawRTCNow(time_t ts) protected

Sets the RTC to exactly the epoch time provided.

Parameters
ts	A timestamp already in the epoch and timezone used internally by the RTC