hardware_rtc

Hardware Real Time Clock API. More...

Typedefs
typedef void(*)	rtc_callback_t(void)

Functions
void	rtc_init (void)
	Initialise the RTC system.
bool	rtc_set_datetime (const datetime_t *t)
	Set the RTC to the specified time.
bool	rtc_get_datetime (datetime_t *t)
	Get the current time from the RTC.
bool	rtc_running (void)
	Is the RTC running?
void	rtc_set_alarm (const datetime_t *t, rtc_callback_t user_callback)
	Set a time in the future for the RTC to call a user provided callback.
void	rtc_enable_alarm (void)
	Enable the RTC alarm (if inactive).
void	rtc_disable_alarm (void)
	Disable the RTC alarm (if active).
bool	rtc_run_from_external_source (uint32_t src_hz, uint gpio_pin)
	Run the RTC from an external clock source through GPIO.

Detailed Description

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.

See also

datetime_t

Example

 
#include <stdio.h>
#include "hardware/rtc.h"
#include "pico/stdlib.h"
#include "pico/util/datetime.h"

int main() {
    stdio_init_all();
    printf("Hello RTC!\n");
 
    char datetime_buf[256];
    char *datetime_str = &datetime_buf[0];
 
    // Start on Friday 5th of June 2020 15:45:00
    datetime_t t = {
            .year  = 2020,
            .month = 06,
            .day   = 05,
            .dotw  = 5, // 0 is Sunday, so 5 is Friday
            .hour  = 15,
            .min   = 45,
            .sec   = 00
    };
 
    // Start the RTC
    rtc_init();
    rtc_set_datetime(&t);
 
    // clk_sys is >2000x faster than clk_rtc, so datetime is not updated immediately when rtc_get_datetime() is called.
    // The delay is up to 3 RTC clock cycles (which is 64us with the default clock settings)
    sleep_us(64);
 
    // Print the time
    while (true) {
        rtc_get_datetime(&t);
        datetime_to_str(datetime_str, sizeof(datetime_buf), &t);
        printf("\r%s      ", datetime_str);
        sleep_ms(100);
    }
}

Typedef Documentation

rtc_callback_t

typedef void(*) rtc_callback_t(void)

Callback function type for RTC alarms

See also

rtc_set_alarm()

Function Documentation

rtc_get_datetime()

bool rtc_get_datetime

(

datetime_t *

t

)

Get the current time from the RTC.

Parameters

t	Pointer to a datetime_t structure to receive the current RTC time

Returns

true if datetime is valid, false if the RTC is not running.

rtc_run_from_external_source()

bool rtc_run_from_external_source	(	uint32_t	src_hz,
		uint	gpio_pin )

Run the RTC from an external clock source through GPIO.

Note

This function will return false if the external clock source is not running.

Parameters

src_hz	The frequency of the external clock source
gpio_pin	The input pin providing the external clock (GP20 or GP22)

Returns

true if it is possible to run the RTC from the external clock frequency, false otherwise.

rtc_set_alarm()

void rtc_set_alarm	(	const datetime_t *	t,
		rtc_callback_t	user_callback )

Set a time in the future for the RTC to call a user provided callback.

Parameters

t	Pointer to a datetime_t structure containing a time in the future to fire the alarm. Any values set to -1 will not be matched on.
user_callback	pointer to a rtc_callback_t to call when the alarm fires

rtc_set_datetime()

bool rtc_set_datetime

(

const datetime_t *

t

)

Set the RTC to the specified time.

Note

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.

Parameters

t	Pointer to a datetime_t structure contains time to set

Returns

true if set, false if the passed in datetime was invalid.