px_rtc_util.h : Software RTC and utility functions

Description

This module provides basic time, calender and alarm functionality.

File(s):

• utils/inc/px_rtc_util.h
• utils/inc/px_rtc_util_cfg_template.h
• utils/src/px_rtc_util.c

Data Structures
struct	px_rtc_date_time_t
	Structure to store date and time. More...

Macros
#define	PX_RTC_UTIL_CFG_SEC_SINCE_Y2K   1
	Option to also keep track of seconds elapsed since Y2K (2000-01-01 00:00:00) More...
#define	PX_RTC_UTIL_CFG_PERIODIC_FLAGS   1
	Option to enable periodic flags (minute, hour and day) More...
#define	PX_RTC_UTIL_CFG_TICKS_PER_SEC   0
	Option to specify number of ticks per second. Use 0 to disable (one tick per sec). More...
#define	PX_RTC_UTIL_CFG_DAY_OF_WEEK   0
	Option to enable day of week support. 0 = disable; 1=enable. More...

Typedefs
typedef uint32_t	px_rtc_sec_since_y2k_t
	Size definition to track seconds since Y2K (2000-01-01 00:00:00 Saturday) More...
typedef uint8_t	px_rtc_alarm_mask_t
	Alarm mask. More...

Enumerations
enum	px_rtc_util_day_t {   PX_RTC_UTIL_DAY_MON = 0 , PX_RTC_UTIL_DAY_TUE = 1 , PX_RTC_UTIL_DAY_WED = 2 , PX_RTC_UTIL_DAY_THU = 3 ,   PX_RTC_UTIL_DAY_FRI = 4 , PX_RTC_UTIL_DAY_SAT = 5 , PX_RTC_UTIL_DAY_SUN = 6 }
	Day of week. More...
enum	px_rtc_time_compare_t { PX_RTC_UTIL_TIME_OLDER , PX_RTC_UTIL_TIME_EQUAL , PX_RTC_UTIL_TIME_NEWER }
	Result of RTC time comparision. More...

Functions
void	px_rtc_util_init (void)
	Initialise module. More...
void	px_rtc_util_on_tick (void)
	Call this function once a second to update date, time and alarm flag. More...
void	px_rtc_util_date_time_wr (px_rtc_date_time_t *date_time)
	Set the time and date. More...
void	px_rtc_util_date_time_rd (px_rtc_date_time_t *date_time)
	Get a copy of the time and date. More...
void	px_rtc_util_alarm_wr (const px_rtc_date_time_t *alarm, px_rtc_alarm_mask_t alarm_mask)
	Set the alarm time and date. More...
void	px_rtc_util_alarm_rd (px_rtc_date_time_t *alarm, px_rtc_alarm_mask_t *alarm_mask)
	Get a copy of the alarm time and date. More...
bool	px_rtc_util_alarm_flag_is_set (void)
	See if alarm flag is set. More...
void	px_rtc_util_alarm_flag_clear (void)
	Clear alarm flag. More...
void	px_rtc_util_date_time_reset (px_rtc_date_time_t *date_time)
	Reset date-time structure to 2000-01-01 00:00. More...
bool	px_rtc_util_date_time_fields_are_valid (const px_rtc_date_time_t *date_time)
	Test if all of the fields in the date-time structure are correct. More...
px_rtc_time_compare_t	px_rtc_util_cmp_date_time (const px_rtc_date_time_t *date_time1, const px_rtc_date_time_t *date_time2)
	Compare two date-time structures to see if the first is older, equal or newer than the second. More...
px_rtc_time_compare_t	px_rtc_util_cmp_date (const px_rtc_date_time_t *date_time1, const px_rtc_date_time_t *date_time2)
	Compare two dates to see if the first is older, equal or newer than the second. More...
bool	px_rtc_util_date_is_equal (const px_rtc_date_time_t *date_time1, const px_rtc_date_time_t *date_time2)
	Compare the dates to see if they fall on the same day. More...
px_rtc_sec_since_y2k_t	px_rtc_util_date_time_to_sec_since_y2k (const px_rtc_date_time_t *date_time)
	Convert a date and time to seconds elapsed since 2000-01-01 00:00 (Y2K) More...
void	px_rtc_util_sec_since_y2k_to_date_time (px_rtc_sec_since_y2k_t sec_since_y2k, px_rtc_date_time_t *date_time)
	Convert seconds elapsed since 2000-01-01 00:00 (Y2K) to a date and time. More...
void	px_rtc_util_date_time_inc (px_rtc_date_time_t *date_time, const px_rtc_date_time_t *date_time_inc)
	Increment a date-time structure with a specified number of years, months, days, hours, minutes and seconds. More...
void	px_rtc_util_date_time_dec (px_rtc_date_time_t *date_time, const px_rtc_date_time_t *date_time_dec)
	Decrement a date-time structure with a specified number of years, months, days, hours, minutes and seconds. More...
px_rtc_util_day_t	px_rtc_util_date_to_day_of_week (const px_rtc_date_time_t *date_time)
	Calculate day of week. More...
void	px_rtc_util_printf_date_time (const px_rtc_date_time_t *date_time)
	Report date and time using printf. More...
void	px_rtc_util_log_report_date_time (const px_rtc_date_time_t *date_time)
	Report date and time using PX_LOG_TRACE(). More...
void	px_rtc_util_log_report_date (const px_rtc_date_time_t *date_time)
	Report date using PX_LOG_TRACE(). More...
void	px_rtc_util_log_report_time (const px_rtc_date_time_t *date_time)
	Report time using PX_LOG_TRACE(). More...

Alarm bit mask
#define	PX_RTC_UTIL_ALARM_MASK_DIS   0
	Disable alarm. More...
#define	PX_RTC_UTIL_ALARM_MASK_SEC   (1 << 0)
	Alarm match on second. More...
#define	PX_RTC_UTIL_ALARM_MASK_MIN   (1 << 1)
	Alarm match on minute. More...
#define	PX_RTC_UTIL_ALARM_MASK_HOUR   (1 << 2)
	Alarm match on hour. More...
#define	PX_RTC_UTIL_ALARM_MASK_DAY   (1 << 3)
	Alarm match on day. More...
#define	PX_RTC_UTIL_ALARM_MASK_MONTH   (1 << 4)
	Alarm match on month. More...
#define	PX_RTC_UTIL_ALARM_MASK_YEAR   (1 << 5)
	Alarm match on year. More...

---

Data Structure Documentation

px_rtc_date_time_t

struct px_rtc_date_time_t

Structure to store date and time.

Definition at line 95 of file px_rtc_util.h.

Data Fields
uint8_t	year	Years: 0 to 99 (2000 - 2099)
uint8_t	month	Months: 1 to 12.
uint8_t	day	Days: 1 to 31 (depending on month)
uint8_t	hour	Hours: 0 to 23.
uint8_t	min	Minutes: 0 to 59.
uint8_t	sec	Seconds: 0 to 59.

Macro Definition Documentation

PX_RTC_UTIL_ALARM_MASK_DIS

#define PX_RTC_UTIL_ALARM_MASK_DIS   0

Disable alarm.

Definition at line 59 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_SEC

#define PX_RTC_UTIL_ALARM_MASK_SEC   (1 << 0)

Alarm match on second.

Definition at line 60 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_MIN

#define PX_RTC_UTIL_ALARM_MASK_MIN   (1 << 1)

Alarm match on minute.

Definition at line 61 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_HOUR

#define PX_RTC_UTIL_ALARM_MASK_HOUR   (1 << 2)

Alarm match on hour.

Definition at line 62 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_DAY

#define PX_RTC_UTIL_ALARM_MASK_DAY   (1 << 3)

Alarm match on day.

Definition at line 63 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_MONTH

#define PX_RTC_UTIL_ALARM_MASK_MONTH   (1 << 4)

Alarm match on month.

Definition at line 64 of file px_rtc_util.h.

PX_RTC_UTIL_ALARM_MASK_YEAR

#define PX_RTC_UTIL_ALARM_MASK_YEAR   (1 << 5)

Alarm match on year.

Definition at line 65 of file px_rtc_util.h.

PX_RTC_UTIL_CFG_SEC_SINCE_Y2K

#define PX_RTC_UTIL_CFG_SEC_SINCE_Y2K   1

Option to also keep track of seconds elapsed since Y2K (2000-01-01 00:00:00)

Definition at line 34 of file px_rtc_util_cfg_template.h.

PX_RTC_UTIL_CFG_PERIODIC_FLAGS

#define PX_RTC_UTIL_CFG_PERIODIC_FLAGS   1

Option to enable periodic flags (minute, hour and day)

Definition at line 37 of file px_rtc_util_cfg_template.h.

PX_RTC_UTIL_CFG_TICKS_PER_SEC

#define PX_RTC_UTIL_CFG_TICKS_PER_SEC   0

Option to specify number of ticks per second. Use 0 to disable (one tick per sec).

Definition at line 40 of file px_rtc_util_cfg_template.h.

PX_RTC_UTIL_CFG_DAY_OF_WEEK

#define PX_RTC_UTIL_CFG_DAY_OF_WEEK   0

Option to enable day of week support. 0 = disable; 1=enable.

Definition at line 43 of file px_rtc_util_cfg_template.h.

Typedef Documentation

px_rtc_sec_since_y2k_t

typedef uint32_t px_rtc_sec_since_y2k_t

Size definition to track seconds since Y2K (2000-01-01 00:00:00 Saturday)

Definition at line 82 of file px_rtc_util.h.

px_rtc_alarm_mask_t

typedef uint8_t px_rtc_alarm_mask_t

Alarm mask.

Definition at line 120 of file px_rtc_util.h.

Enumeration Type Documentation

px_rtc_util_day_t

enum px_rtc_util_day_t

Day of week.

Enumerator
PX_RTC_UTIL_DAY_MON	Monday.
PX_RTC_UTIL_DAY_TUE	Tuesday.
PX_RTC_UTIL_DAY_WED	Wednesday.
PX_RTC_UTIL_DAY_THU	Thursday.
PX_RTC_UTIL_DAY_FRI	Friday.
PX_RTC_UTIL_DAY_SAT	Saturday.
PX_RTC_UTIL_DAY_SUN	Sunday.

Definition at line 69 of file px_rtc_util.h.

px_rtc_time_compare_t

enum px_rtc_time_compare_t

Result of RTC time comparision.

Enumerator
PX_RTC_UTIL_TIME_OLDER	Time is older.
PX_RTC_UTIL_TIME_EQUAL	Time is equal.
PX_RTC_UTIL_TIME_NEWER	Time is newer.

Definition at line 112 of file px_rtc_util.h.

Function Documentation

px_rtc_util_init()

void px_rtc_util_init

(

void

)

Initialise module.

Definition at line 245 of file px_rtc_util.c.

px_rtc_util_on_tick()

void px_rtc_util_on_tick

(

void

)

Call this function once a second to update date, time and alarm flag.

Set flag to indicate that an alarm has occurred

Definition at line 270 of file px_rtc_util.c.

px_rtc_util_date_time_wr()

void px_rtc_util_date_time_wr

(

px_rtc_date_time_t *

date_time

)

Set the time and date.

Parameters

[in]

date_time

Pointer to a structure that contains the new date and time.

Definition at line 355 of file px_rtc_util.c.

px_rtc_util_date_time_rd()

void px_rtc_util_date_time_rd

(

px_rtc_date_time_t *

date_time

)

Get a copy of the time and date.

Parameters

[out]

date_time

Pointer to a structure that will hold the new date and time.

Definition at line 408 of file px_rtc_util.c.

px_rtc_util_alarm_wr()

void px_rtc_util_alarm_wr	(	const px_rtc_date_time_t *	alarm,
		px_rtc_alarm_mask_t	alarm_mask
	)

Set the alarm time and date.

The alarm flag will be cleared.

Parameters

alarm	Pointer to a structure that contains the new alarm time.
alarm_mask	Alarm mask (disabled, sec, min, hour, day, month, year)

Definition at line 430 of file px_rtc_util.c.

px_rtc_util_alarm_rd()

void px_rtc_util_alarm_rd	(	px_rtc_date_time_t *	alarm,
		px_rtc_alarm_mask_t *	alarm_mask
	)

Get a copy of the alarm time and date.

Parameters

alarm	Pointer to a structure that will hold the current alarm time.
alarm_mask	Pointer to hold the current alarm mask to match on (disabled, sec, min, hour, day, month, year)

Definition at line 451 of file px_rtc_util.c.

px_rtc_util_alarm_flag_is_set()

bool px_rtc_util_alarm_flag_is_set

(

void

)

See if alarm flag is set.

Return values

true	Alarm flag set (alarm has occurred)
false	Alarm flag not set (alarm has not occurred)

Definition at line 460 of file px_rtc_util.c.

px_rtc_util_alarm_flag_clear()

void px_rtc_util_alarm_flag_clear

(

void

)

Clear alarm flag.

Definition at line 465 of file px_rtc_util.c.

px_rtc_util_date_time_reset()

void px_rtc_util_date_time_reset

(

px_rtc_date_time_t *

date_time

)

Reset date-time structure to 2000-01-01 00:00.

Parameters

date_time

Pointer to a structure that will hold the new date and time.

Definition at line 504 of file px_rtc_util.c.

px_rtc_util_date_time_fields_are_valid()

bool px_rtc_util_date_time_fields_are_valid

(

const px_rtc_date_time_t *

date_time

)

Test if all of the fields in the date-time structure are correct.

Parameters

date_time

Pointer to a structure containing the date and time.

Return values

true	All of the fields are valid.
false	One or more of the fields are invalid.

Definition at line 520 of file px_rtc_util.c.

px_rtc_util_cmp_date_time()

px_rtc_time_compare_t px_rtc_util_cmp_date_time	(	const px_rtc_date_time_t *	date_time1,
		const px_rtc_date_time_t *	date_time2
	)

Compare two date-time structures to see if the first is older, equal or newer than the second.

Parameters

date_time1	First date-time structure
date_time2	Second date-time structure

Return values

PX_RTC_UTIL_TIME_OLDER	First date-time is older than second.
PX_RTC_UTIL_TIME_EQUAL	First date-time is equal to second.
PX_RTC_UTIL_TIME_NEWER	First date-time is newer than second.

Definition at line 562 of file px_rtc_util.c.

px_rtc_util_cmp_date()

px_rtc_time_compare_t px_rtc_util_cmp_date	(	const px_rtc_date_time_t *	date_time1,
		const px_rtc_date_time_t *	date_time2
	)

Compare two dates to see if the first is older, equal or newer than the second.

Parameters

date_time1	First date-time structure
date_time2	Second date-time structure

Return values

PX_RTC_UTIL_TIME_OLDER	First date-time is older than second.
PX_RTC_UTIL_TIME_EQUAL	First date-time is equal to second.
PX_RTC_UTIL_TIME_NEWER	First date-time is newer than second.

Definition at line 627 of file px_rtc_util.c.

px_rtc_util_date_is_equal()

bool px_rtc_util_date_is_equal	(	const px_rtc_date_time_t *	date_time1,
		const px_rtc_date_time_t *	date_time2
	)

Compare the dates to see if they fall on the same day.

Parameters

date_time1	First date-time structure
date_time2	Second data-time structure

Return values

true	Dates fall on the same day
false	Dates do not fall on the same day

Definition at line 665 of file px_rtc_util.c.

px_rtc_util_date_time_to_sec_since_y2k()

px_rtc_sec_since_y2k_t px_rtc_util_date_time_to_sec_since_y2k

(

const px_rtc_date_time_t *

date_time

)

Convert a date and time to seconds elapsed since 2000-01-01 00:00 (Y2K)

Parameters

date_time

date-time structure

Returns

px_rtc_util_sec_since_y2k_t Seconds since Y2K (2000-01-01 00:00:00)

Definition at line 691 of file px_rtc_util.c.

px_rtc_util_sec_since_y2k_to_date_time()

void px_rtc_util_sec_since_y2k_to_date_time	(	px_rtc_sec_since_y2k_t	sec_since_y2k,
		px_rtc_date_time_t *	date_time
	)

Convert seconds elapsed since 2000-01-01 00:00 (Y2K) to a date and time.

Parameters

sec_since_y2k	Seconds since Y2K (2000-01-01 00:00:00)
date_time	date-time structure to receive calculated date and time

Definition at line 733 of file px_rtc_util.c.

px_rtc_util_date_time_inc()

void px_rtc_util_date_time_inc	(	px_rtc_date_time_t *	date_time,
		const px_rtc_date_time_t *	date_time_inc
	)

Increment a date-time structure with a specified number of years, months, days, hours, minutes and seconds.

Parameters

date_time	date-time structure to increment
date_time_inc	date-time structure containing amount to increment by

Definition at line 777 of file px_rtc_util.c.

px_rtc_util_date_time_dec()

void px_rtc_util_date_time_dec	(	px_rtc_date_time_t *	date_time,
		const px_rtc_date_time_t *	date_time_dec
	)

Decrement a date-time structure with a specified number of years, months, days, hours, minutes and seconds.

Parameters

date_time	date-time structure to decrement
date_time_dec	date-time structure containing amount to decrement by

Definition at line 849 of file px_rtc_util.c.

px_rtc_util_date_to_day_of_week()

px_rtc_util_day_t px_rtc_util_date_to_day_of_week

(

const px_rtc_date_time_t *

date_time

)

Calculate day of week.

Parameters

date_time

date

Returns

px_rtc_util_day_t day of week

Definition at line 921 of file px_rtc_util.c.

px_rtc_util_printf_date_time()

void px_rtc_util_printf_date_time

(

const px_rtc_date_time_t *

date_time

)

Report date and time using printf.

Parameters

date_time

date-time structure to report

Definition at line 955 of file px_rtc_util.c.

px_rtc_util_log_report_date_time()

void px_rtc_util_log_report_date_time

(

const px_rtc_date_time_t *

date_time

)

Report date and time using PX_LOG_TRACE().

Parameters

date_time

date-time structure to report

Definition at line 966 of file px_rtc_util.c.

px_rtc_util_log_report_date()

void px_rtc_util_log_report_date

(

const px_rtc_date_time_t *

date_time

)

Report date using PX_LOG_TRACE().

Parameters

date_time

date-time structure to report

Definition at line 977 of file px_rtc_util.c.

px_rtc_util_log_report_time()

void px_rtc_util_log_report_time

(

const px_rtc_date_time_t *

date_time

)

Report time using PX_LOG_TRACE().

Parameters

date_time

date-time structure to report

Definition at line 985 of file px_rtc_util.c.