1 /* 2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _HARDWARE_RTC_H 8 #define _HARDWARE_RTC_H 9 10 #include "pico.h" 11 #include "hardware/structs/rtc.h" 12 13 /** \file hardware/rtc.h 14 * \defgroup hardware_rtc hardware_rtc 15 * 16 * \brief Hardware Real Time Clock API 17 * 18 * The RTC keeps track of time in human readable format and generates events when the time is equal 19 * to a preset value. Think of a digital clock, not epoch time used by most computers. There are seven 20 * fields, one each for year (12 bit), month (4 bit), day (5 bit), day of the week (3 bit), hour (5 bit) 21 * minute (6 bit) and second (6 bit), storing the data in binary format. 22 * 23 * \sa datetime_t 24 * 25 * \subsection rtc_example Example 26 * \addtogroup hardware_rtc 27 * 28 * \include hello_rtc.c 29 */ 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /*! Callback function type for RTC alarms 36 * \ingroup hardware_rtc 37 * 38 * \sa rtc_set_alarm() 39 */ 40 typedef void (*rtc_callback_t)(void); 41 42 /*! \brief Initialise the RTC system 43 * \ingroup hardware_rtc 44 */ 45 void rtc_init(void); 46 47 /*! \brief Set the RTC to the specified time 48 * \ingroup hardware_rtc 49 * 50 * \note Note that after setting the RTC date and time, a subsequent read of the values (e.g. via rtc_get_datetime()) may not 51 * reflect the new setting until up to three cycles of the potentially-much-slower RTC clock domain have passed. This represents a period 52 * of 64 microseconds with the default RTC clock configuration. 53 * 54 * \param t Pointer to a \ref datetime_t structure contains time to set 55 * \return true if set, false if the passed in datetime was invalid. 56 */ 57 bool rtc_set_datetime(const datetime_t *t); 58 59 /*! \brief Get the current time from the RTC 60 * \ingroup hardware_rtc 61 * 62 * \param t Pointer to a \ref datetime_t structure to receive the current RTC time 63 * \return true if datetime is valid, false if the RTC is not running. 64 */ 65 bool rtc_get_datetime(datetime_t *t); 66 67 /*! \brief Is the RTC running? 68 * \ingroup hardware_rtc 69 * 70 */ 71 bool rtc_running(void); 72 73 /*! \brief Set a time in the future for the RTC to call a user provided callback 74 * \ingroup hardware_rtc 75 * 76 * \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. 77 * \param user_callback pointer to a \ref rtc_callback_t to call when the alarm fires 78 */ 79 void rtc_set_alarm(const datetime_t *t, rtc_callback_t user_callback); 80 81 /*! \brief Enable the RTC alarm (if inactive) 82 * \ingroup hardware_rtc 83 */ 84 void rtc_enable_alarm(void); 85 86 /*! \brief Disable the RTC alarm (if active) 87 * \ingroup hardware_rtc 88 */ 89 void rtc_disable_alarm(void); 90 91 #ifdef __cplusplus 92 } 93 #endif 94 95 #endif 96
