boards/nucleo-wl55jc, cpu/stm32: enable RTC support, increase RTC accuracy

[crasbe]

Contribution description

This PR takes over #20536 and enables the RTC peripheral for the Nucleo-WL55JC (and WL55 processor in general).

The original author @FlapKap said that he didn't get the alarms to work. The reason for that is a combination of #8746 and the note from the reference manual [1]

Note: Each change of the RTC_CR register is taken into account after around 2 RTCCLK clock
cycles due to clock synchronization.

Essentially we have a race condition in tests/periph/rtc where the sleep period of 2 just causes this issue. Changing that period fixes the issue:

diff --git a/tests/periph/rtc/main.c b/tests/periph/rtc/main.c
index d5433fee1c..38a4da0e40 100644
--- a/tests/periph/rtc/main.c
+++ b/tests/periph/rtc/main.c
@@ -213,7 +213,7 @@ int main(void)

     /* set alarm */
     rtc_get_time(&time);
-    inc_secs(&time, PERIOD); /* note that this increments the seconds above 60! */
+    inc_secs(&time, PERIOD*2); /* note that this increments the seconds above 60! */
     rtc_set_alarm(&time, cb, &rtc_mtx);
     print_time("  Setting alarm to ", &time);
     puts("")

Of course this is just a band-aid fix and the real fix has to be done for #8746, but this is out of scope for this PR.

Testing procedure

Run the tests/periph/rtc test on a Nucleo-WL55JC board.

Behavior with this PR and the aforementioned change:

s
2025-10-31 14:00:33,782 # START
2025-10-31 14:00:33,790 # main(): This is RIOT! (Version: 2025.10-devel-546-g141748-pr/nucleo-wl55jc-rtc-support_new)
2025-10-31 14:00:33,790 #
2025-10-31 14:00:33,792 # RIOT RTC low-level driver test
2025-10-31 14:00:33,798 # This test will display 'Alarm!' every 2 seconds for 4 times
2025-10-31 14:00:33,809 # RTC mem OK
2025-10-31 14:00:33,813 # Clock value is now   2020-02-29 00:06:22
2025-10-31 14:00:33,817 #   Setting clock to   2020-02-28 23:59:57
2025-10-31 14:00:33,820 # Clock value is now   2020-02-28 23:59:57
2025-10-31 14:00:33,824 #   Setting alarm to   2020-02-28 23:59:59
2025-10-31 14:00:33,827 #    Alarm is set to   2020-02-28 23:59:59
2025-10-31 14:00:33,831 #   Alarm cleared at   2020-02-28 23:59:57
2025-10-31 14:00:35,835 #        No alarm at   2020-02-28 23:59:57
2025-10-31 14:00:35,838 #   Setting alarm to   2020-02-29 00:00:01
2025-10-31 14:00:35,838 #
2025-10-31 14:00:37,836 # Alarm!
2025-10-31 14:00:39,837 # Alarm!
2025-10-31 14:00:41,837 # Alarm!
2025-10-31 14:00:43,838 # Alarm!
2025-10-31 14:00:43,840 # RTC mem OK
2025-10-31 14:00:43,847 # { "threads": [{ "name": "main", "stack_size": 1536, "stack_used": 500}]}

Issues/PRs references

Taken over from #20536.
Fixes #18789.
Fixes #8746 thanks to @Meumeu.

Links

[1] https://www.st.com/resource/en/reference_manual/dm00451556-stm32wl5x-advanced-armbased-32bit-mcus-with-subghz-radio-solution-stmicroelectronics.pdf

[crasbe]

I created a new PR because the commit message of the original PR had to be changed and I didn't want to modify the original PR. The actual content is unchanged.

[riot-ci]

Murdock results

✔️ PASSED

6dd5619 boards/lora-e5-dev: enable RTC peripheral

Success	Failures	Total	Runtime
10559	0	10560	11m:38s

Artifacts

• Documentation preview

[crasbe]

The original author @FlapKap said that he didn't get the alarms to work. The reason for that is a combination of #8746 and the note from the reference manual [1]

Okay, that wasn't it. Also the band-aid fix was rather a coincidence to work apparently since the clock didn't actually run.

The reason for that is the use of xtimer_sleep:

After waking up from low-power mode (Stop or Standby), RSF must be cleared by software.
The software must then wait until it is set again before reading the RTC_SSR, RTC_TR and
RTC_DR registers.
The RSF bit must be cleared after wake-up and not before entering low-power mode.

[1] page 989

I added this without using the rtc_lock() function due to the RTC stopping when setting the INIT bit. This will have to be fixed in a subsequent PR. Decided against it and will include it here.

---

Furthermore, RIOT_EPOCH = 2020 wasn't a great choice for the offset of the calender year because the RTC determines whether or not it has been initialized by checking if the year is still at 0. Setting the offset to 2020 and then setting the test-year to 2020 too resulted in the RTC thinking it was uninitialized. This was not a big problem for this PR, but raised some question marks above my head during testing...

[crasbe]

So I took the code from @Meumeu that was visible in the issue #8746 and adapted it to the latest code. The idea was originally from @MichelRottleuthner.

The original pros and cons remain:

+no interface change needed (the current documentation is not violated)
+kind of what one would expect from an RTC peripheral
-doesn't allow you to force-init the RTC anymore (not sure why you would need that with our currently
very limited API though)

[crasbe]

Okay the original solution from @Meumeu did not quite work because the RTC registers have to be enabled first, otherwise the RTC->ICSR register always reads zero, always leading to the full initializiation.

Edit: I also added a check for the EN_REG to avoid pulling power from "under the feet" of the RTC, possibly leading to a glitch.

Now it is very stable though. The only thing I still have to check is if the RSF-flag thing is also required for the other STM32 families (and therefore if the RTC actually works on other STM32 families or if the test just coincidentally worked).

[crasbe]

A test trace is in #8746 (comment), I did not want to post the full sources and logs here.

[crasbe]

The only thing I still have to check is if the RSF-flag thing is also required for the other STM32 families (and therefore if the RTC actually works on other STM32 families or if the test just coincidentally worked).

Okay, all the STM32 reference manuals I checked have the same remark. Therefore I would boldly assume that this is the case for all STM32s.
Next TODO: Check with $Nucleo != WL55 if the RTC was actually running or not.

STM32F0: https://www.st.com/resource/en/reference_manual/rm0091-stm32f0x1stm32f0x2stm32f0x8-advanced-armbased-32bit-mcus-stmicroelectronics.pdf p. 599

STM32G0: https://www.st.com/resource/en/reference_manual/rm0444-stm32g0x1-advanced-armbased-32bit-mcus-stmicroelectronics.pdf p. 875
STM32L0: https://www.st.com/resource/en/reference_manual/rm0377-ultralowpower-stm32l0x1-advanced-armbased-32bit-mcus-stmicroelectronics.pdf p. 552
STM32L1: https://www.st.com/resource/en/reference_manual/cd00240193-stm32l100xx-stm32l151xx-stm32l152xx-and-stm32l162xx-advanced-arm-based-32-bit-mcus-stmicroelectronics.pdf p. 515
STM32L5: https://www.st.com/resource/en/reference_manual/dm00346336-stm32l552xx-and-stm32l562xx-advanced-arm-based-32-bit-mcus-stmicroelectronics.pdf p.1409

STM32U5: https://www.st.com/resource/en/reference_manual/rm0456-stm32u5-series-armbased-32bit-mcus-stmicroelectronics.pdf p. 2601

[crasbe]

Nucleo-WB55 works with master and this PR.
Nucleo-F302R8 works with master and this PR, although the F302R8 does not appear to have RTC memory, even though the test tries to access it...
Nucleo-L452RE works.
Nucleo-F030R8 works.
Nucleo-F207ZG works with master but not with this PR.
Nucleo-F722ZE works with master but not with this PR.

The last two both hang at the "waiting for RSF flag to be set by hardware". The reason for that is that the INIT flag never got cleared in the rtc_init function, as the rtc_unlock function now does not do that anymore. Odd that the other boards did not care, but oh well.

This is now fixed with the latest fixup.

---

This is now officially done and ready for review 🥳

[FlapKap]

@crasbe thanks for picking this up and getting the alarms to work! That's amazing