Real-Time Clock (RTC)
Overview
RTL8721F provides an RTC in the AON domain, keeping calendar time and alarm/wakeup state across chip sleep and reset. The Rust driver ameba_hal::rtc wraps the PAC register block directly — no raw bit-masking or C FFI is involved.
Features
Calendar time in binary or BCD format via
TimeFormat::Bin/TimeFormat::Bcd, covering year, day-of-year, hours, minutes, seconds, and 12/24-hour format viaHourFormatClock source selection between the SDM 32 kHz oscillator and OSC131K/4 via
ClockSource::Sdm32k/ClockSource::Osc131kDiv4, and asynchronous/synchronous prescaler configuration viaRtcConfigAlarm comparison on seconds, minutes, hours, and day, with per-field masking via
AlarmMask/AlarmDayMaskWakeup timer with a configurable auto-reload value, independent of the alarm comparator
Day-counter rollover threshold and its own interrupt, configured via
set_day_threshold/set_day_intDaylight-saving hour adjustment via
DaylightSaving::Add1h/DaylightSaving::Sub1h, with the adjustment direction recorded in a backup bitRTC_OUT pin signal routing via
OutputSel::Alarm/ClkSpre/ClkApreSmooth calibration of the time-update frequency via
set_calib, with configurable sign, magnitude, and periodAON detection-interrupt helpers via
get_det_intr/clear_det_intr, independent of the RTC peripheral’s own interrupt flags
Note
The driver exposes no embedded_hal trait implementation — embedded-hal has no standard calendar/RTC trait, so all access goes through the methods on Rtc directly.
Operating Modes
RTC exposes three usage patterns built on the same peripheral instance: calendar time keeping, alarm comparison, and the wakeup timer.
Calendar Time
The base mode, always active once init succeeds: the peripheral free-runs a calendar clock that set_time writes and get_time reads back. The clock source must be selected after enable(true), since it defaults to the uncalibrated OSC131K/4 tap on AON power-on.
use ameba_hal::{
println,
rcc,
rtc::{AmPm, ClockSource, Rtc, RtcConfig, TimeConfig, TimeFormat},
};
...
rcc::enable(rcc::Peripheral::RTC);
let rtc = unsafe { Rtc::steal() };
rtc.enable(true);
rcc::enable(rcc::Peripheral::RTC_FEN);
let ok = rtc.init(&RtcConfig::default());
if !ok {
println!("[RTC] init failed");
return;
}
// Set time to 2025-01-01 12:00:00
let start_time = TimeConfig {
am_pm: AmPm::Am,
year: 2025,
days: 1,
hours: 12,
minutes: 0,
seconds: 0,
};
let ok = rtc.set_time(TimeFormat::Bin, &start_time);
if !ok {
println!("[RTC] set_time failed");
return;
}
...
rtc.set_clock_source(ClockSource::Sdm32k);
...
let t = rtc.get_time(TimeFormat::Bin);
Full example: examples/rtc/src/main.rs.
Alarm
A comparator against the running calendar clock, configured with set_alarm and armed with alarm_cmd. Fields set in AlarmMask / AlarmDayMask always match (they are excluded from the comparison). Fields left clear must equal the configured value. So a mask of just HOURS | MINUTES leaves seconds as the only compared field, firing once a minute when the seconds counter reaches the alarm’s configured seconds value.
use ameba_hal::rtc::{AlarmConfig, AlarmMask, Rtc, TimeFormat};
let rtc = unsafe { Rtc::steal() };
let alarm = AlarmConfig {
mask: AlarmMask::HOURS | AlarmMask::MINUTES,
..AlarmConfig::default()
};
rtc.set_alarm(TimeFormat::Bin, &alarm);
rtc.alarm_cmd(true);
// Once RTC_IRQ fires, call rtc.clear_alarm() from the handler.
There is no standalone alarm example under examples/rtc/. The calls above are illustrative, built directly from the set_alarm / alarm_cmd / AlarmConfig signatures and doc comments in ameba-hal/src/rtc/mod.rs, not excerpted from a runnable program.
Wakeup Timer
An independent auto-reload countdown, unrelated to the calendar clock or alarm comparator, configured with set_wakeup and armed with wakeup_cmd. Enabling blocks for several seconds while the write-protected auto-reload register synchronizes.
use ameba_hal::rtc::Rtc;
let rtc = unsafe { Rtc::steal() };
rtc.set_wakeup(0x1FFF);
rtc.wakeup_cmd(true);
// Once RTC_IRQ fires, call rtc.clear_wakeup() from the handler.
There is no standalone wakeup-timer example under examples/rtc/. The calls above are illustrative, built directly from the set_wakeup / wakeup_cmd signatures and doc comments in ameba-hal/src/rtc/mod.rs, not excerpted from a runnable program.
Application Examples
The Rust SDK provides one example project at rtc:
Sets the calendar time to 2025-01-01 12:00:00, waits 3 seconds, reads the time back, and checks that the elapsed seconds fall within a 2-4 second window to confirm the RTC is actually ticking.
Wiring: none — no external wiring required.
[RTC] start
[RTC] time set to 2025-01-01 12:00:00, waiting 3s...
[RTC] read-back: 2025-001 12:00:02
[RTC] diff: 2s (embassy elapsed: 3000ms)
[PASS] RTC: tick OK
The read-back can be 1 second lower than the 3 s wait (12:00:02 with diff: 2s); the check passes for any difference of 2 to 4 seconds.
Note
Build the example with cargo xtask build example --name rtc.
API Reference
Quick Usage
use ameba_hal::rcc;
use ameba_hal::rtc::{AmPm, ClockSource, Rtc, RtcConfig, TimeConfig, TimeFormat};
rcc::enable(rcc::Peripheral::RTC);
let rtc = unsafe { Rtc::steal() };
rtc.enable(true);
rtc.init(&RtcConfig::default());
rtc.set_clock_source(ClockSource::Sdm32k);
let now = TimeConfig { am_pm: AmPm::Am, year: 2025, days: 1, hours: 12, minutes: 0, seconds: 0 };
rtc.set_time(TimeFormat::Bin, &now);
let t = rtc.get_time(TimeFormat::Bin);
For alarm comparison and the wakeup timer, please see the Operating Modes section above.