machine.RTC.init documentation is incorrect
The machine.RTC documentation has some discrepancies.
The ESP8266 machine.RTC modules doesn't appear to have an init function, but rather has a datetime function.
https://github.com/micropython/micropython/blob/8db5d2d1f13aa6413be11bc13c94df72296a0070/ports/esp8266/machine_rtc.c#L127
The order of the arguments to datetime appears to be (year, month, day, wday, hour, minute, seconds, milliseconds)
The ESP32 machine.RTC module
https://github.com/micropython/micropython/blob/8db5d2d1f13aa6413be11bc13c94df72296a0070/ports/esp32/machine_rtc.c#L87
has an init function and a datetime function. The order of the arguments for datetime and init appears to be (year, month, day, hour, minute, seconds, microseconds)
The stm32 machine.RTC module forwards to pyb.RTC
https://github.com/micropython/micropython/blob/8db5d2d1f13aa6413be11bc13c94df72296a0070/ports/stm32/rtc.c#L515
which has an init function and datetime function, but the init function doesn't take any srguments. The datetime function appears to use the order (year, month, day, wday, hour, month, seconds, microseconds)
The documentation documents an init function with arguments in a different order to any of the above and doesnt't mention a datetime function.
And the EPS8266 appears to take milliseconds as the last argument, whereas the others take microseconds.
ports/rtc: Inconsistencies between ports and the documentation.
It looks like the machine.rtc() API is different for all ports and to the documentation.
- to start with the good part: In all ports rtc.datetime() matches the machine.RTC class documentation.
- rtc.init() for the cc3200 works as documented
- rtc.init() differs from the documentation in the item order of the datetime tuple for the ports esp32, samd, mimxrt.
- no rtc.init() at the rp2 port.
- rtc.init() at the stm32 and renesas.ra port just reinit's the RTC device and ignores the function argument.
- rtc.now() is only available in the cc3200 and mimxrt port.
- the documentation for rtc.datetime() is different between the machine.RTC class section and the quickref for the ports stm32, rp2, mimxrt, esp32, esp8266, renesas-ra,
So it seems as if the documentation of rtc.init() and rtc.now() only matches the cc3200 port. I can make that all consistent, but we should agree first on which class methods should be available. So a simple approach would be:
- keep rtc.datetime() as it is now. Maybe add it to the cc3200 port. It is not consistent to CPython datetime.datetime, but that topic has been discussed several times already with the decision to keep the actual rtc.datetime format.
- drop rtc.now() from the mimxrt port. Only keep it at the CC3200 port for legacy.
- drop the set date/time functionality of rtc.init() and/or change at least the documentation.
- fix the inconsistencies in the documentation.
Edit: Created PR #10607