RTC Interface

RTC Interface. More...

Data Structures
struct	rtc_time
	Structure for storing date and time values with sub-second precision. More...

Typedefs
typedef void(*	rtc_update_callback) (const struct device *dev, void *user_data)
	RTC update event callback.
typedef void(*	rtc_alarm_callback) (const struct device *dev, uint16_t id, void *user_data)
	RTC alarm triggered callback.

Functions
int	rtc_set_time (const struct device *dev, const struct rtc_time *timeptr)
	API for setting RTC time.
int	rtc_get_time (const struct device *dev, struct rtc_time *timeptr)
	API for getting RTC time.

RTC Interface Alarm
int	rtc_alarm_get_supported_fields (const struct device *dev, uint16_t id, uint16_t *mask)
	API for getting the supported fields of the RTC alarm time.
int	rtc_alarm_set_time (const struct device *dev, uint16_t id, uint16_t mask, const struct rtc_time *timeptr)
	API for setting RTC alarm time.
int	rtc_alarm_get_time (const struct device *dev, uint16_t id, uint16_t *mask, struct rtc_time *timeptr)
	API for getting RTC alarm time.
int	rtc_alarm_is_pending (const struct device *dev, uint16_t id)
	API for testing if RTC alarm is pending.
int	rtc_alarm_set_callback (const struct device *dev, uint16_t id, rtc_alarm_callback callback, void *user_data)
	API for setting alarm callback.

RTC Interface Update
int	rtc_update_set_callback (const struct device *dev, rtc_update_callback callback, void *user_data)
	API for setting update callback.

RTC Interface Calibration
int	rtc_set_calibration (const struct device *dev, int32_t calibration)
	API for setting RTC calibration.
int	rtc_get_calibration (const struct device *dev, int32_t *calibration)
	API for getting RTC calibration.

RTC Interface Helpers
static struct tm *	rtc_time_to_tm (struct rtc_time *timeptr)
	Convenience function for safely casting a rtc_time pointer to a tm pointer.

RTC Alarm Time Mask
Mask for alarm time fields to enable when setting alarm time
#define	RTC_ALARM_TIME_MASK_SECOND   BIT(0)
#define	RTC_ALARM_TIME_MASK_MINUTE   BIT(1)
#define	RTC_ALARM_TIME_MASK_HOUR   BIT(2)
#define	RTC_ALARM_TIME_MASK_MONTHDAY   BIT(3)
#define	RTC_ALARM_TIME_MASK_MONTH   BIT(4)
#define	RTC_ALARM_TIME_MASK_YEAR   BIT(5)
#define	RTC_ALARM_TIME_MASK_WEEKDAY   BIT(6)
#define	RTC_ALARM_TIME_MASK_YEARDAY   BIT(7)
#define	RTC_ALARM_TIME_MASK_NSEC   BIT(8)

Detailed Description

RTC Interface.

Since

3.4

Version

0.1.0

Macro Definition Documentation

RTC_ALARM_TIME_MASK_HOUR

#define RTC_ALARM_TIME_MASK_HOUR   BIT(2)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_MINUTE

#define RTC_ALARM_TIME_MASK_MINUTE   BIT(1)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_MONTH

#define RTC_ALARM_TIME_MASK_MONTH   BIT(4)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_MONTHDAY

#define RTC_ALARM_TIME_MASK_MONTHDAY   BIT(3)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_NSEC

#define RTC_ALARM_TIME_MASK_NSEC   BIT(8)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_SECOND

#define RTC_ALARM_TIME_MASK_SECOND   BIT(0)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_WEEKDAY

#define RTC_ALARM_TIME_MASK_WEEKDAY   BIT(6)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_YEAR

#define RTC_ALARM_TIME_MASK_YEAR   BIT(5)

#include <zephyr/drivers/rtc.h>

RTC_ALARM_TIME_MASK_YEARDAY

#define RTC_ALARM_TIME_MASK_YEARDAY   BIT(7)

#include <zephyr/drivers/rtc.h>

Typedef Documentation

rtc_alarm_callback

rtc_alarm_callback

#include <zephyr/drivers/rtc.h>

RTC alarm triggered callback.

Parameters

dev	Device instance invoking the handler
id	Alarm id
user_data	Optional user data passed with the alarm configuration

rtc_update_callback

rtc_update_callback

#include <zephyr/drivers/rtc.h>

RTC update event callback.

Parameters

dev	Device instance invoking the handler
user_data	Optional user data provided when update irq callback is set

Function Documentation

rtc_alarm_get_supported_fields()

int rtc_alarm_get_supported_fields	(	const struct device *	dev,
		uint16_t	id,
		uint16_t *	mask
	)

#include <zephyr/drivers/rtc.h>

API for getting the supported fields of the RTC alarm time.

Parameters

dev	Device instance
id	Id of the alarm
mask	Mask of fields in the alarm time which are supported

Note

Bits in the mask param are defined here RTC_ALARM_TIME_MASK.

Returns

0 if successful

-EINVAL if id is out of range or time is invalid

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_alarm_get_time()

int rtc_alarm_get_time	(	const struct device *	dev,
		uint16_t	id,
		uint16_t *	mask,
		struct rtc_time *	timeptr
	)

#include <zephyr/drivers/rtc.h>

API for getting RTC alarm time.

Parameters

dev	Device instance
id	Id of the alarm
mask	Destination for mask of fields which are enabled in the alarm time
timeptr	Destination for the alarm time

Note

Bits in the mask param are defined here RTC_ALARM_TIME_MASK

Returns

0 if successful

-EINVAL if id is out of range

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_alarm_is_pending()

int rtc_alarm_is_pending	(	const struct device *	dev,
		uint16_t	id
	)

#include <zephyr/drivers/rtc.h>

API for testing if RTC alarm is pending.

Test whether or not the alarm with id is pending. If the alarm is pending, the pending status is cleared.

Parameters

dev	Device instance
id	Id of the alarm to test

Returns

1 if alarm was pending

0 if alarm was not pending

-EINVAL if id is out of range

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_alarm_set_callback()

int rtc_alarm_set_callback	(	const struct device *	dev,
		uint16_t	id,
		rtc_alarm_callback	callback,
		void *	user_data
	)

#include <zephyr/drivers/rtc.h>

API for setting alarm callback.

Setting the alarm callback for an alarm, will enable the alarm callback. When the callback for an alarm is enabled, the alarm triggered event will invoke the callback, after which the alarm pending status will be cleared automatically. The alarm will remain enabled until manually disabled using rtc_alarm_set_time().

To disable the alarm callback for an alarm, the callback and user_data parameters must be set to NULL. When the alarm callback for an alarm is disabled, the alarm triggered event will set the alarm status to "pending". To check if the alarm status is "pending", use rtc_alarm_is_pending().

Parameters

dev	Device instance
id	Id of the alarm for which the callback shall be set
callback	Callback called when alarm occurs
user_data	Optional user data passed to callback

Returns

0 if successful

-EINVAL if id is out of range

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_alarm_set_time()

int rtc_alarm_set_time	(	const struct device *	dev,
		uint16_t	id,
		uint16_t	mask,
		const struct rtc_time *	timeptr
	)

#include <zephyr/drivers/rtc.h>

API for setting RTC alarm time.

To enable an RTC alarm, one or more fields of the RTC alarm time must be enabled. The mask designates which fields of the RTC alarm time to enable. If the mask parameter is 0, the alarm will be disabled. The RTC alarm will trigger when all enabled fields of the alarm time match the RTC time.

Parameters

dev	Device instance
id	Id of the alarm
mask	Mask of fields in the alarm time to enable
timeptr	The alarm time to set

Note

The timeptr param may be NULL if the mask param is 0

Only the enabled fields in the timeptr param need to be configured

Bits in the mask param are defined here RTC_ALARM_TIME_MASK

Returns

0 if successful

-EINVAL if id is out of range or time is invalid

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_get_calibration()

int rtc_get_calibration	(	const struct device *	dev,
		int32_t *	calibration
	)

#include <zephyr/drivers/rtc.h>

API for getting RTC calibration.

Parameters

dev	Device instance
calibration	Destination for calibration in parts per billion

Returns

0 if successful

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_get_time()

int rtc_get_time	(	const struct device *	dev,
		struct rtc_time *	timeptr
	)

#include <zephyr/drivers/rtc.h>

API for getting RTC time.

Parameters

dev	Device instance
timeptr	Destination for the time

Returns

0 if successful

-ENODATA if RTC time has not been set

-errno code if failure

rtc_set_calibration()

int rtc_set_calibration	(	const struct device *	dev,
		int32_t	calibration
	)

#include <zephyr/drivers/rtc.h>

API for setting RTC calibration.

Calibration is applied to the RTC clock input. A positive calibration value will increase the frequency of the RTC clock, a negative value will decrease the frequency of the RTC clock.

Parameters

dev	Device instance
calibration	Calibration to set in parts per billion

Returns

0 if successful

-EINVAL if calibration is out of range

-ENOTSUP if API is not supported by hardware

-errno code if failure

rtc_set_time()

int rtc_set_time	(	const struct device *	dev,
		const struct rtc_time *	timeptr
	)

#include <zephyr/drivers/rtc.h>

API for setting RTC time.

Parameters

dev	Device instance
timeptr	The time to set

Returns

0 if successful

-EINVAL if RTC time is invalid or exceeds hardware capabilities

-errno code if failure

rtc_time_to_tm()

static struct tm * rtc_time_to_tm ( struct rtc_time *  timeptr )

inlinestatic

#include <zephyr/drivers/rtc.h>

Convenience function for safely casting a rtc_time pointer to a tm pointer.

rtc_update_set_callback()

int rtc_update_set_callback	(	const struct device *	dev,
		rtc_update_callback	callback,
		void *	user_data
	)

#include <zephyr/drivers/rtc.h>

API for setting update callback.

Setting the update callback will enable the update callback. The update callback will be invoked every time the RTC clock is updated by 1 second. It can be used to synchronize the RTC clock with other clock sources.

To disable the update callback for the RTC clock, the callback and user_data parameters must be set to NULL.

Parameters

dev	Device instance
callback	Callback called when update occurs
user_data	Optional user data passed to callback

Returns

0 if successful

-ENOTSUP if API is not supported by hardware

-errno code if failure