feat(power): improve X4 Pro battery life - drop RC_FAST frontlight retention + add shutdown-reason RTC marker

[Belphemur]

Prepare the FreeInk SDK for the crosspoint firmware changes that improve X4 Pro battery life.

This PR includes the SDK-side changes needed for the crosspoint battery-drain improvement:

• Drop RC_FAST frontlight retention in light sleep (removes LEDC_SLEEP_MODE_KEEP_ALIVE / FREEINK_FRONTLIGHT_LS)
• Restore 25 kHz frontlight PWM timer (was downgraded to 10 kHz by the RC_FAST workaround)
• Add shutdown-reason RTC marker so crosspoint can detect power-off shutdowns via RTC
• Add park() support for frontlight power-gating during sleep

The light-sleep RC_FAST keep-alive is intentionally removed per discussion with the @itsthisjustin - upstream PR #39 compatibility is not preserved.

Crosspoint consumer-side changes (auto-shutdown timer, HalPowerManager, HalFrontlight) will follow in a separate draft PR after this merges.

[Copilot]

Pull request overview

Prepares the FreeInk SDK for upcoming crosspoint firmware power-management changes by removing the RC_FAST/KEEP_ALIVE light-sleep frontlight retention approach (and its 10 kHz PWM limitation), restoring the OEM frontlight PWM frequency for X4 Pro, and introducing an RTC slow-memory shutdown-reason marker to support stock-parity power-off detection.

Changes:

• Added a shutdown-reason marker API in PowerManager backed by RTC slow RAM (write + consume-once read).
• Updated the FREEINK_FRONTLIGHT_LS LEDC setup to drop RC_FAST/KEEP_ALIVE and return to auto-clock selection so 25 kHz / 10-bit works again.
• Restored X4 Pro’s board-profile frontlight PWM setting to 25 kHz and updated documentation/comments around deep-sleep leakage mitigation (park()).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
libs/hardware/PowerManager/src/PowerManager.cpp	Implements RTC slow-RAM shutdown marker read/write logic.
libs/hardware/PowerManager/include/PowerManager.h	Exposes new shutdown-reason API and enum.
libs/hardware/FrontlightManager/src/FrontlightManager.cpp	Removes RC_FAST/KEEP_ALIVE configuration; uses auto clocking and keeps deep-sleep park() behavior.
libs/hardware/FrontlightManager/include/FrontlightManager.h	Updates park() contract/comments and removes LS keep-alive bookkeeping fields.
libs/hardware/BoardConfig/include/BoardConfig.h	Restores X4 Pro frontlight PWM frequency to OEM 25 kHz / 10-bit.

Suppressed comments (3)

libs/hardware/PowerManager/src/PowerManager.cpp:123

• The shutdown reason is documented as a single byte, but this writes a full 32-bit word to RTC slow RAM. That will zero/overwrite the other 3 bytes at 0x50000000..03, which could conflict with other RTC-slow users now or later. Use a volatile uint8_t* for the reason cell and store only the byte.

  auto* magicCell = reinterpret_cast<volatile uint32_t*>(kShutdownMagicAddr);
  auto* reasonCell = reinterpret_cast<volatile uint32_t*>(kShutdownReasonAddr);
  // Reason first, magic last: a torn write (power cut mid-sequence) leaves NO

libs/hardware/PowerManager/src/PowerManager.cpp:134

• Same issue on read/clear: using a volatile uint32_t* for the reason cell reads and clears 4 bytes even though only the low byte is meaningful. Read/clear the reason as a uint8_t to avoid clobbering neighboring bytes in RTC slow RAM.

  auto* magicCell = reinterpret_cast<volatile uint32_t*>(kShutdownMagicAddr);
  auto* reasonCell = reinterpret_cast<volatile uint32_t*>(kShutdownReasonAddr);
  if (*magicCell != kShutdownMagic) return 0;
  const uint16_t result = static_cast<uint16_t>(((*reasonCell & 0xffu) << 8) | 1u);
  // Clear both cells: the marker is consumed exactly once (stock behavior).

libs/hardware/FrontlightManager/src/FrontlightManager.cpp:106

• Similarly, the channel config currently relies on the zero-initialized sleep_mode being "not KEEP_ALIVE". Make this explicit with LEDC_SLEEP_MODE_NO_ALIVE so future enum/value changes can’t accidentally re-enable KEEP_ALIVE behavior.

  ledc_channel_config_t chan = {};
  chan.gpio_num = gpio;
  chan.speed_mode = LEDC_LOW_SPEED_MODE;
  chan.channel = static_cast<ledc_channel_t>(ch);
  chan.intr_type = LEDC_INTR_DISABLE;

---

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

[Belphemur]

@itsthisjustin relates to what we talked about about disabling RC_FAST to keep the same refresh rate on the frontlight + other findings relating to how the stock firmware works.

I plan to add to upstream an auto shutdown feature, different from sleep, akin to what the stock firmware has, and store in the slow mem the reason (as stock does it) for the sleep.