v2.0.0
Typedefs | Functions
hardware_rtc
Hardware APIs

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. More...
bool | rtc_get_datetime (datetime_t *t)
| Get the current time from the RTC. More...
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. More...
void | rtc_enable_alarm (void)
| Enable the RTC alarm (if inactive)
void | rtc_disable_alarm (void)
| Disable the RTC alarm (if active)

## 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.
// tbe 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);
}
}
datetime.h
rtc_set_datetime
bool rtc_set_datetime(const datetime_t *t)
Set the RTC to the specified time.
Definition: rtc.c:54
rtc_get_datetime
bool rtc_get_datetime(datetime_t *t)
Get the current time from the RTC.
Definition: rtc.c:87
rtc_init
void rtc_init(void)
Initialise the RTC system.
Definition: rtc.c:22
stdio_init_all
bool stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:200
sleep_ms
void sleep_ms(uint32_t ms)
Wait for the given number of milliseconds before returning.
Definition: time.c:431
sleep_us
void sleep_us(uint64_t us)
Wait for the given number of microseconds before returning.
Definition: time.c:414
rtc.h
stdio.h
stdlib.h
datetime_t
Structure containing date and time information.
Definition: types.h:107
datetime_t::year
int16_t year
0..4095
Definition: types.h:108

## 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_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
  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.

Parameters

  t | Pointer to a datetime_t structure contains time to set

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