rak4631: use a fitted RAK12002 RTC, and keep its backup switchover enabled

[ptr727]

Manual references are to the RV-3028-C7 Application Manual, Rev. 1.4, November 2021 (Micro Crystal, RV-3028-C7), cited as §section and page. Code links are permalinks:

• dev at 52644a8, which includes rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99.
• This PR's commit ad2df09.

The defect

Two separate failures, both on a RAK4631 with a RAK12002 fitted (an RV3028 at 0x52).

1. The RTC is never used. The RAK4631 overlay declares no zephcore,rtc-i2c candidate, so rtc_probe() never sees the chip. The time survives a warm reboot only in noinit RAM, so every power cut starts the node at 1970 until the next GPS, app or CLI sync.
2. Declaring it is not enough. The RV3028 ships with backup switchover disabled: EEPROM 37h has BSM = 00 on delivery (§3.15.6, p. 39; §3.18, p. 41). With the chip declared but left as delivered, a power cut drops VDD with nothing switching to the supercap, so the chip resets and the time is lost (Testing, row B).

The RAK12002's backup is a supercapacitor. §7.3 (p. 105) specifies direct switching (DSM) with the trickle charger for a capacitor backup, and adds that "Power Management settings have to be stored in EEPROM for permanent configuration". A RAM-only setting does not last. With EERD = 0, the chip reloads its configuration RAM from EEPROM at power-on and every day at midnight (§4.6.2, p. 54). §4.6.9 (p. 57) warns that "the new, changed configurations are lost as soon as a refresh occurs".

The fix

Declare the RV3028 in the RAK4631 overlay (board.overlay), with the descriptor and zero-mask that rtc-i2c.dtsi uses for it. The overlay declares only that candidate, because the file's DS3231 at 0x68 shares the address of WisBlock IMUs.

A new optional rv3028-eeprom-config property (binding) holds (register, mask, value) triplets for the configuration registers 35h-37h. The RAK4631 sets:

• 35h: CLKOE = 0, so CLKOUT is off, since it is unused (§3.15.4, p. 37; §7.3 note 5, p. 105). Only that bit is masked; the chip's other 35h bits are kept.
• 37h: TCE = 1, FEDE = 1, BSM = 01 (DSM), TCR = 00 (3 kΩ, the delivery value). FEDE "should always be set to 1" (§3.15.6, p. 39).
• EEOffset[0] (37h bit 7) and BSIE keep the chip's own values, and 36h, the rest of the factory trim, is never written.

The overlay comment notes that any other RV3028 module at 0x52 gets the same settings, trickle charging included.

When the store runs. rtc_probe() calls the store only when two things hold:

• rtc_identify() returned RTC_FOUND, meaning a read identified the chip by rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99's rules. An adoption on a failed second read (RTC_FOUND_GARBLED) stays the time write-back target but gets no EEPROM writes.
• The boot time read showed no switchover (next section).

A store skipped for either reason is retried from the 10-minute retry. Each retry (rv3028_cfg_retry_fn()) runs rtc_identify() again before any write, and stops if two reads rule the chip out.

How it stores the config. rv3028_store_config() follows §3.15.6 (p. 39), which says BSM must be 00 or 10 to read or write the EEPROM:

1. Set EERD = 1, then wait for EEbusy = 0 (§4.6.7, p. 56). This also covers the ~66 ms power-on refresh. rv3028_eeprom_idle() ends the wait on the first failed status read, rather than polling a dead bus through each transfer's timeout.
2. Save RAM 37h, then write it back with BSM = 00, so switchover is off while the EEPROM is accessed.
3. For each configured byte, read the EEPROM copy with a single-byte read (EECMD 22h, §4.6.6, p. 55). Write it with a single-byte write (21h, §4.6.5, p. 55) only if its masked bits differ. The waits follow §4.6.7: 1 ms after a read or Refresh and 10 ms after a write, before polling EEbusy.
4. Run a Refresh (12h, §4.6.4, p. 54). It reloads RAM from EEPROM and brings back the stored switchover mode. The config is then read back on every run.
5. If the Refresh did not complete, write 37h as configured, in RAM only, once EEbusy reads 0. If EEbusy never clears, leave switchover off rather than enable it during an EEPROM operation. A retry or the daily refresh restores it.
6. Clear EERD with a fresh read-modify-write of Control 1. Clearing it while EEbusy may still be set is a judgement call: §4.6.7 only describes it after EEbusy reads 0.

Failure handling (rv3028_configure()):

• If the config is not stored, it is set in the RAM mirror once EEbusy reads 0. It then lasts until the chip's next refresh from EEPROM.
• If the config is stored but EERD could not be cleared, that is logged separately, since EERD = 1 also stops the daily refresh.
• Either way the store is retried every 10 minutes, at most 3 times per boot.

The time read and write (rv3028_steady(), rv3028_write_time()). A switchover to backup disables the chip's I2C interface mid-transfer (§4.2, p. 45). The rest of a read then comes back 0xFF, and a tail that starts inside the year byte can still be valid BCD: a year too high. So at a node with rv3028-eeprom-config, the time is read at boot and written on each sync with BSF cleared before (§3.7, p. 22) and checked after:

• Read. A read that failed or saw BSF gives no time ("time unreadable") and skips that boot's store.
• Write order. A write sets year 00h first, then 00h-05h, then the real year. The burst's seconds restart the prescaler (§4.5.1, p. 53).
• A cut write. A power loss cutting the write after its first byte and before its last, which takes the MCU down so no retry can repeat it, leaves year 2000, so the next boot takes no time from it. With every other field valid it reads as "time not yet set" and still adopts the chip, because identity ignores the year.
• Retry. A write that is not confirmed is repeated every 5 s, up to 12 times, with the time run on (rv3028_save_retry_fn()).

Gated. All of the RV3028 code is under #if DT_ANY_COMPAT_HAS_PROP_STATUS_OKAY(zephcore_rtc_i2c, rv3028_eeprom_config). A board without the property builds the same RTC object as dev.

An already-configured chip costs two EEPROM byte reads and a Refresh per boot, and no EEPROM write.

Notes for review

• The rebase onto rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99. This PR drops everything rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99 provides: the all-0xFF skip and re-probe, the RV3028 always-zero check (now the node's zero-mask), and the "time unreadable" adoption.
• Why §3.15.6 instead of the vendor drivers' Update. Micro Crystal's Linux driver and Zephyr's mfd_rv3028.c run a Refresh, and a whole-block Update of 30h-37h, with switchover live. The §3.15.6 sequence was chosen on the manual. It is the only sequence that stays valid when the backup sits above VDD: in DSM the chip then runs from backup permanently, and an EEPROM write needs VDD (§4.6.8, p. 57). It also never rewrites the 36h trim. Its cost is that switchover is off for a measured 14.3 ms per boot on a configured chip (52.2 ms when two bytes are written), plus up to 2 ms for DSM to react once re-enabled (§4.2.2, p. 46). A full power cut inside that window loses the time.
• The same rules in MeshCore and Zephyr. These RV3028 rules are shared with the MeshCore and Zephyr work: §3.15.6 for EEPROM access, the EEbusy gate, the BSF bracket, and the year-last write order. See drivers: rv3028: disable backup switchover during EEPROM access zephyrproject-rtos/zephyr#121252 (issue drivers: rv3028: EEPROM is read and written with the backup switchover enabled zephyrproject-rtos/zephyr#121253), Store RV3028 backup switchover and trickle charger config in EEPROM 🤖🤖 meshcore-dev/MeshCore#3545 and Read and write the RV3028 clock atomically, and reject switchover-garbled transfers 🤖🤖 meshcore-dev/MeshCore#3421.
• Behaviour change: the settings outlive this firmware. A module configured once keeps DSM and trickle charging after a reflash to other firmware, or a move to another carrier. That is the point of the fix. It matters only for a carrier whose backup element is not rechargeable. The shared rtc-i2c.dtsi sets none of this, because other boards' backup supplies are not known, and trickle charging a primary cell is wrong.
• DSM caution. §4.2.2 (p. 46) warns DSM can switch needlessly when VDD and VBACKUP are close (3.3 V against about 3.05 V once the cap is trickle-charged, §4.3, p. 48). §7.3 prescribes DSM for a capacitor anyway, and level switching would leave the charge below 2.0 V unused. The BSF bracket on the time read and write is what makes a needless switchover harmless.
• Out of scope, pre-existing:
  • A password-locked chip ignores writes to its write-protected registers while acknowledging them (§4.18.1, p. 87). The store, the RAM fallback and a time write can then all report success with nothing written.
  • A 12-hour-mode RTC is misread by the probe: RTC probe assumes 24-hour mode: an RV3028 left in 12-hour mode is misread or never adopted ptr727/liquidraver-ZephCore#34.
  • The weekday is written in binary, while the RX8130CE's WEEK register is one-hot: RTC save writes the weekday in binary; the RX8130CE's WEEK register is one-hot ptr727/liquidraver-ZephCore#39.

Testing

Builds at ad2df09: rak4631 repeater and companion, release (CONFIG_LOG=n) and debug, and thinknode_m1 companion. There are no compiler warnings.

• On thinknode_m1, ZephyrRTCDiscover.c.obj is 1628 B of text, identical to dev, with no RV3028 symbols.
• On the RAK4631 repeater the feature costs about 3 KB of text against dev.

Hardware: a RAK4631 with a RAK12002, USB only (no battery fitted), debug repeater builds. The time CLI command set the clock from the host before each check.

Power cut (USB unplugged and replugged by the maintainer; rows A-D are from the earlier revision, raw logs in this comment):

Row	Build	Cut	Boot after the cut	clock
A	dev f9d01cf	69 s	no RTC lines (no candidate declared)	1/1/1970: time lost
B	declaration only, delivery EEPROM (BSM = 00)	88 s	RTC at 2000-01-01; power-loss flag set	1/1/1970: time lost
D	earlier revision of this PR, 334d9f7	65 s	restored the time set before the cut	time kept
E	this rebase, b489046 (BSF-bracketed read and write)	66 s	restored the time set before the cut, to the second	time kept

This rebase, on the same board. The boot restore through the bracketed read and the bracketed save were checked after each revision. A warm reboot after the year-last write (3f51c58) restored exactly the written time. The board's EEPROM had already been configured by the earlier revision (35h/37h = 40/34), so these boots wrote nothing to it. The commits after 3f51c58 change no RTC code in debug builds:

• b574fdf moves the RAM fallback, which runs only after a failed store, out of a log call. Release builds now run it.
• The last commit is comments only. The RTC object is byte-identical.

EEPROM store (earlier revision, from delivery EEPROM; the store code is unchanged apart from the EEbusy gate on its failure paths):

Step	EEPROM 35h / 37h read by the store	RAM 35h / 37h after	Log
First boot	C0 / 10	40 / 34	config committed to EEPROM; switchover off 52.2 ms
Reboot	40 / 34	40 / 34	nothing written; switchover off 14.3 ms
RTC stepped past its midnight refresh	—	40 / 34 before and after 00:00:00	config held, so it is in EEPROM, not RAM only

Not tested on hardware: paths that need fault injection, namely the RAM fallback, the EERD-only failure, the config and save retries, a switchover during the read or write, and a cut write leaving year 2000. Also untested: a battery-fitted board, and temperature.

Known limitations (none is reached on a healthy chip and bus):

1. A time write is confirmed by acknowledgements and a clear BSF, not by reading it back. A password-locked chip acknowledges the writes but ignores them, so with BSF clear the write reads as confirmed without taking effect, and with BSF set it never confirms.
2. A power loss cutting a write mid-byte leaves that byte undefined (§5.10, p. 95). In the final one-byte year write that byte can read as a valid year; in the burst it can make the next boot rule the chip out. The year-last order covers a cut between bytes. A cut plain write on dev has the same exposure.
3. A tick at Dec 31 23:59:59 that lands after the burst but before the final year write, which needs the work queue to stall for over a second, would store the old year.
4. The EEbusy and Refresh waits are in kernel ticks. A build with a coarse tick (not the nRF52840's 32768 Hz) stretches them about tenfold.

Fork issues: ptr727#4, ptr727#33. Iteration history and review rounds: ptr727#35.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

The retry path still rejects an all-0xFF RV3028, preventing initial synchronization and configuration.

Review effort: Lite
Findings: None

What changed in this PR

Adds RAK12002 RV3028 RTC discovery and persistent backup-switchover configuration for RAK4631.

Changes:

• Declares and configures the RV3028 in the board overlay.
• Adds EEPROM configuration, validation, retries, and fallback handling.
• Updates RTC bindings, documentation, and Kconfig help.

File	Summary
zephcore/​Kconfig	Documents RTC configuration behavior.
zephcore/​dts/​bindings/​rtc/​zephcore,rtc-i2c.yaml	Defines RV3028 EEPROM configuration.
zephcore/​boards/​nrf52840/​rak4631/​board.overlay	Declares and configures the fitted RV3028.
zephcore/​adapters/​clock/​ZephyrRTCDiscover.h	Documents discovery and persistence behavior.
zephcore/​adapters/​clock/​ZephyrRTCDiscover.c	Implements RV3028 probing, EEPROM handling, fallback, and retries.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ptr727]

Answering Copilot's review overview on 3d399d5 (round), which reported "Findings: None" with this headline:

The retry path still rejects an all-0xFF RV3028, preventing initial synchronization and configuration.

Disproven: a real RV3028 never presents an all-0xFF time block, so the all-0xFF skip cannot reject one.

• Reset state: the RV-3028-C7 Application Manual (Rev. 1.4, November 2021) says "After reset, all registers are set according to Table in section REGISTER RESET VALUES SUMMARY" (p. 12). That table (§3.18, p. 41) gives the time block 00h-06h as Seconds 00, Minutes 00, Hours 00, Weekday 00, Date 01, Month 01, Year 00. So a chip fresh from power-on reads 2000-01-01 00:00:00, which is valid BCD with no always-zero bit set (§3.2, p. 12). It is adopted on its first read, logged as "time not yet set", and configured. The first sync then writes the time.
• Operation: once running, every register holds counter values in range, never seven 0xFF bytes.
• What the skip does catch: an all-0xFF block is an erased EEPROM answering at 0x52, which is the case the skip exists for. Even so, the first save probes once more before giving up.
• On hardware: on a RAK4631 with a RAK12002, the store configured a chip from its delivery EEPROM and restored the time across reboots and USB-unplug power cuts; see the Testing section and the raw logs. No read on that chip was ever all 0xFF.

[liquidraver]

Thanks for this. #99 is merged, so this now conflicts in ZephyrRTCDiscover.c, ZephyrRTCDiscover.h and the binding YAML. Please rebase onto dev and drop what #99 already provides (the all-0xFF skip and re-probe, the hardcoded RV3028 always-zero check, the "time unreadable" path); the RAK4631 node should carry zero-mask instead.

A few things I'd like addressed in the rebase:

1. Run the EEPROM store only on a clean identification. With rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99's rules a device whose first read rules it out and whose second read fails is still adopted, and here adoption means immediate register writes to it.
2. Known limitation 1 (a year read too high after a switchover during the boot read): please include the BSF clear-before / check-after fix you describe. A forward clock jump is expensive on the mesh, since peers keep the timestamp and only GPS can step us back.
3. Gate the RV3028 code so boards without rv3028-eeprom-config don't carry it (e.g. DT_ANY_COMPAT_HAS_PROP_STATUS_OKAY). On thinknode_m1 it cost about 1.1 KB before the rebase.
4. Small: the new RV3028_* defines split the BCD2BIN / BIN2BCD pair.

I'm fine with the persistent EEPROM config for the RAK12002's supercap. Please mention in the overlay comment that any other RV3028 at 0x52 gets the same trickle-charge setting.

[ptr727]

Thanks. Rebased onto dev at 52644a8 as ad2df09. Everything #99 provides is dropped from this PR: the all-0xFF skip and re-probe, the hardcoded RV3028 always-zero check, and the "time unreadable" path. The RAK4631 node now carries zero-mask = [80 80 c0 f8 c0 e0 00], the same as rtc-i2c.dtsi.

1. EEPROM store only on a clean identification. rv3028_configure() runs only when rtc_identify() returns RTC_FOUND. A device adopted on a failed second read (RTC_FOUND_GARBLED) is the write-back target, as rtc: identify RTCs by documented always-zero bits; stop skipping real ones #99 has it, but nothing is written to its EEPROM. The store is also skipped when a switchover shows during the boot time read (2 below), since the EEPROM needs VDD (§4.6.8, p. 57). A skipped store is retried from the existing 10-minute retry, at most 3 per boot. Each retry runs rtc_identify() again before any write, and stops if two reads rule the chip out.
2. BSF clear-before / check-after (known limitation 1). At a node with rv3028-eeprom-config, once identified, the time is read again with BSF cleared before (§3.7, p. 22: written as 0, in VDD state) and checked after. If BSF is set or any transfer failed, no time is taken ("time unreadable"). A switchover disables the I2C interface mid-transfer (§4.2, p. 45), so this covers the tail that can start inside the year byte. The same bracket now covers the save:
   • The write order is year 00h, then 00h-05h, then the real year. A power loss cutting the write between its first and last byte leaves year 2000, so the next boot takes no time from it. A cut inside one byte leaves that byte undefined (§5.10); that window is listed under Known limitations in the description.
   • A write that isn't confirmed is repeated every 5 s, up to 12 times, with the time run on.
3. Gated. All RV3028 code is under #if DT_ANY_COMPAT_HAS_PROP_STATUS_OKAY(zephcore_rtc_i2c, rv3028_eeprom_config). On thinknode_m1 companion, ZephyrRTCDiscover.c.obj is 1628 B of text, the same as dev, with no RV3028 symbols. On the RAK4631 repeater the feature costs about 3 KB of text against dev.
4. BCD2BIN / BIN2BCD are together again. The RV3028 defines sit inside the gated block.
5. Overlay comment now ends: "Any other RV3028 module at 0x52 gets the same settings, trickle charging included, kept in its EEPROM."

Two more changes from the rebase's own review:

• A pre-existing bug, fixed. The RAM fallback after a failed store ran inside LOG_WRN's arguments, so release builds (CONFIG_LOG=n) never ran it. It now runs before the log line.
• EEbusy. After a Refresh that didn't complete, and for that RAM fallback, switchover is turned back on only once EEbusy reads 0. Otherwise it stays off until a retry or the daily refresh (§3.15.6), rather than coming on during an EEPROM operation.

Testing, on a RAK4631 with a RAK12002, debug repeater builds:

• The boot restore through the bracketed read and the bracketed save were run at each revision of the rebase.
• A 66 s USB power cut kept the time (restored exactly the time set before the cut).
• A warm reboot after the year-last write restored the written time.
• Release and debug builds of rak4631 (repeater and companion) and thinknode_m1 compile with no warnings.

Keeping ZephCore, MeshCore and Zephyr in step. The same RV3028 rules are in flight in the other two projects:

• Zephyr: drivers: rv3028: disable backup switchover during EEPROM access zephyrproject-rtos/zephyr#121252 (issue drivers: rv3028: EEPROM is read and written with the backup switchover enabled zephyrproject-rtos/zephyr#121253) applies §3.15.6 to Zephyr's RV3028 MFD, RTC and EEPROM drivers: switchover off for any EEPROM access, single-byte writes and a Refresh instead of an Update, so the 36h trim is never rewritten.
• Zephyr: drivers: ethernet: dm9051: fix RX stall and oversized frame restart zephyrproject-rtos/zephyr#121191 and drivers: ethernet: dm9051: fix locking, TX completion and RX path robustness zephyrproject-rtos/zephyr#121192 fix DM9051 Ethernet driver bugs: an RX stall (drivers: ethernet: dm9051: RX thread stalls when an ISR event arrives while ISR is serviced zephyrproject-rtos/zephyr#121193), oversized-frame restart, locking, and TX completion. They aren't related to this PR, but ZephCore picks them up on a Zephyr bump.
• MeshCore: Store RV3028 backup switchover and trickle charger config in EEPROM 🤖🤖 meshcore-dev/MeshCore#3545 is the same EEPROM store for MeshCore's RV3028, and Read and write the RV3028 clock atomically, and reject switchover-garbled transfers 🤖🤖 meshcore-dev/MeshCore#3421 is its atomic time read; the BSF and write-order rules above are agreed across the three for those changes.