blob: 2a72a8eb96366fd05a077fa85eecdc85da909d13 [file] [log] [blame]
/*
* Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
#ifndef _HARDWARE_RTC_H
#define _HARDWARE_RTC_H
#include "pico.h"
#include "hardware/structs/rtc.h"
/** \file hardware/rtc.h
* \defgroup hardware_rtc hardware_rtc
*
* Hardware Real Time Clock API
*
* The RTC keeps track of time in human readable format and generates events when the time is equal
* to a preset value. Think of a digital clock, not epoch time used by most computers. There are seven
* fields, one each for year (12 bit), month (4 bit), day (5 bit), day of the week (3 bit), hour (5 bit)
* minute (6 bit) and second (6 bit), storing the data in binary format.
*
* \sa datetime_t
*
* \subsection rtc_example Example
* \addtogroup hardware_rtc
*
* \include hello_rtc.c
*/
#ifdef __cplusplus
extern "C" {
#endif
/*! Callback function type for RTC alarms
* \ingroup hardware_rtc
*
* \sa rtc_set_alarm()
*/
typedef void (*rtc_callback_t)(void);
/*! \brief Initialise the RTC system
* \ingroup hardware_rtc
*/
void rtc_init(void);
/*! \brief Set the RTC to the specified time
* \ingroup hardware_rtc
*
* \note Note that after setting the RTC date and time, a subsequent read of the values (e.g. via rtc_get_datetime()) may not
* reflect the new setting until up to three cycles of the potentially-much-slower RTC clock domain have passed. This represents a period
* of 64 microseconds with the default RTC clock configuration.
*
* \param t Pointer to a \ref datetime_t structure contains time to set
* \return true if set, false if the passed in datetime was invalid.
*/
bool rtc_set_datetime(datetime_t *t);
/*! \brief Get the current time from the RTC
* \ingroup hardware_rtc
*
* \param t Pointer to a \ref datetime_t structure to receive the current RTC time
* \return true if datetime is valid, false if the RTC is not running.
*/
bool rtc_get_datetime(datetime_t *t);
/*! \brief Is the RTC running?
* \ingroup hardware_rtc
*
*/
bool rtc_running(void);
/*! \brief Set a time in the future for the RTC to call a user provided callback
* \ingroup hardware_rtc
*
* \param t Pointer to a \ref datetime_t structure containing a time in the future to fire the alarm. Any values set to -1 will not be matched on.
* \param user_callback pointer to a \ref rtc_callback_t to call when the alarm fires
*/
void rtc_set_alarm(datetime_t *t, rtc_callback_t user_callback);
/*! \brief Enable the RTC alarm (if inactive)
* \ingroup hardware_rtc
*/
void rtc_enable_alarm(void);
/*! \brief Disable the RTC alarm (if active)
* \ingroup hardware_rtc
*/
void rtc_disable_alarm(void);
#ifdef __cplusplus
}
#endif
#endif