RTC: report failures from every setter, add isValid(), make timerSleep fail-closed

[ainyan03]

Summary

The RTC setters and IRQ controls could not tell a communication failure from success: setDateTime, clearIRQ and disableIRQ returned void, setAlarmIRQ returned an int that was really the "alarm enabled" flag, and setTimerIRQ returned 0 both for a requested stop and for a failed write. Power_Class::timerSleep then powered the device off even when the wake-up alarm had not been armed.

This PR makes every RTC setter report whether the RTC is in the requested state, adds isValid() to the RTC value types, and makes timerSleep refuse to sleep unless a wake-up is actually armed.

API

API	Before	After
setDateTime / setDate / setTime	void	bool (every register write acknowledged; out-of-range field or unsupported year → false)
setTimerIRQ(msec, uint32_t* applied_msec = nullptr)	uint32_t (0 = stopped or failed)	bool, the programmed period through the optional out-pointer (same shape as setChargeCurrent)
setAlarmIRQ(date, time)	int (alarm enabled?)	bool (alarm in the requested state; a request with no alarm field clears the alarm and returns true)
clearIRQ / disableIRQ	void	bool
getTime() / getDate() / getDateTime() (value-returning)	undefined content on failure	every field −1; isValid() to check
rtc_time_t / rtc_date_t / rtc_datetime_t	–	isValid() (all fields set and in range)
RTC_Class::hasTimerIRQ() / canSetAlarm()	–	capability queries, nothing is written
Power::timerSleep(...) ×3	void	bool: returns only when sleep was not entered (false)

Behaviour

• timerSleep is fail-closed: the old IRQ sources must be disabled and cleared, the new one armed, and a wake route registered; otherwise the device stays awake and everything armed by the call is released again. Invalid arguments, an RTC without the needed feature (PowerHub has no timer) and the PC build return false before any RTC state is touched.
• The alarm interrupt is enabled only after the complete alarm value was accepted; a stale alarm flag is cleared before re-arming; a failed request never leaves a partial or old alarm armed.
• Timer operations preserve a pending alarm flag and vice versa (PCF8563 Control_status_2 W0C handling, RX8130 flag masks).
• On boards whose RTC IRQ is relayed by the M5PM1 (PaperMono, ToughC5) the relay's stale wake source / IRQ status is cleared between stopping the old source and arming the new one, and a relay failure is part of the result.
• setDateTime rejects a year the chip cannot store instead of wrapping it (PCF8563 1900-2099, RX8130 / PowerHub 2000-2099).
• RTC_PowerHub: rewritten against the STM32 firmware register map (plain binary registers, alarm = minute/hour/day + enable, no timer, no readable alarm flag). begin() probes the firmware, getVoltLow() no longer reads an unrelated register, weekday values are validated on read.

Breaking changes

• Return types changed: setDateTime/setDate/setTime, setAlarmIRQ(date, time), clearIRQ, disableIRQ (void/int → bool), timerSleep (void → bool). Calls that ignore the result still compile. A return type is not part of the mangled name: rebuild everything that links against the library.
• setAlarmIRQ(date, time): a request with no alarm field (a clear) used to return 0 and now returns true; code that used the int as "alarm enabled" must be revisited. Without an RTC it returns false instead of −1.
• setTimerIRQ(msec) returns bool instead of the programmed period. uint32_t n = setTimerIRQ(ms); still compiles but stores 0/1; read the period through setTimerIRQ(ms, &n).
• setAlarmIRQ(int seconds) (deprecated by comment since 0.2.x; it programmed the timer, not the alarm) is removed. Use setTimerIRQ(seconds * 1000). The overload is declared = delete so that setAlarmIRQ(0) is a compile error instead of silently binding to the tm* overload.
• RTC_Base subclasses: the virtuals changed (setTimerIRQ(msec, applied*), bool returns, virtual destructor) and must be updated.
• Power::timerSleep(int) on PowerHub returns false (no RTC timer); use the date/time overloads.
• setTimerIRQ(1..499 ms) on PCF8563 now arms the 1 s minimum step instead of stopping the timer.
• getTime()/getDate()/getDateTime() (value-returning) now return all −1 on failure (year was 2000 before).

Known limitations (unchanged behaviour, now documented)

• The RTC alarm wakes only boards where its IRQ is wired to a wake route; an alarm from an external RTC unit does not wake the board.
• RX8130 requests below about 250 ms use the 4096 Hz source, whose /INT pulse the M5PM1 relay does not catch.
• PowerHub: the STM32 applies alarm changes asynchronously and exposes no confirmation; true means the request was accepted.

Verification

Board	RTC	Checked
Tough	PCF8563 + AXP192	set/get round trip, weekday auto-compute, isValid boundaries, timer (applied = 1000 ms), alarm, disable; timerSleep(15) power-off → RTC wake, repeated cycles
ToughC5	RX8130 via M5PM1	same set; timerSleep(15) with EXT1 wake, repeated cycles
PaperS3	RX8130 via M5PM1	same set; timerSleep(15) power-off → RTC wake, repeated cycles
PowerHub	STM32 front-end	set/get, alarm/disable acceptance, timer unsupported → false (before the last review rounds)

Builds: ESP32 / S3 / C5 / P4 (Arduino) and native, no new warnings. Independent adversarial reviews (two lenses, thirteen rounds) until no implementation finding remained. CI run on the ainyan03 fork before this PR.