Witty Pi 5 HAT+ — Scheduled Startup Never Works (7 tests, firmware v1.0 and v1.2.1)

# UUGear Support — Witty Pi 5: Scheduled Startup Never Triggers

## Summary
Witty Pi 5 **scheduled shutdown works perfectly**, but the MCU **never wakes the Raspberry Pi** at the scheduled startup time. Tested 6 times across firmware v1.0 and v1.2.1. The Pi must always be turned on manually via the power button.

## Hardware
- **Board**: Witty Pi 5 HAT+
- **Raspberry Pi**: 4 Model B Rev 1.4 (aarch64)
- **OS**: Debian 13 (trixie), Kernel 6.12.75+rpt-rpi-v8
- **Power**: USB 5V standard (V-USB ~5.28V, V-OUT ~5.28V, I-OUT ~0.5A)
- **Temperature**: WittyPi internal ~31°C

## Software
- **wp5 software**: v5.1.1 (updated from v1.00)
- **wp5d daemon**: V5.1.1
- **Firmware MCU**: Updated from v1.0 → v1.2.1 via BOOTSEL+UF2
- **I2C**: Working — `/dev/i2c-1` present, MCU detected at `0x51`

## Problem Description
When scheduling a startup time via `wp5` CLI (option 5), the schedule is confirmed and stored correctly in the MCU registers. After a scheduled shutdown (which works fine), the Pi shuts down cleanly and the WittyPi cuts power. However, **the MCU never restores power at the scheduled startup time**.

When the user presses the power button manually (after waiting 15-60 minutes past the scheduled time), the wp5d log reports `Startup reason: Scheduled Startup` — because the MCU checks if the scheduled time has already passed and reports it as "scheduled" even though it was triggered by the button press.

## Test Results (6 tests on 2026-03-18)

| Test | Firmware | Startup Scheduled | Actual Boot (RTC) | Delay | Who powered on? |
|------|----------|-------------------|-------------------|-------|-----------------|
| 1 | v1.0 | 09:00:00 | I2C error | — | User (button) |
| 2 | v1.0 | 11:43:00 | 11:49:41 | +6m41s | User (button) |
| 3 | v1.0 | 12:03:32 | 12:18:02 | +14m30s | User (button ~12:17) |
| 4 | v1.0 | 12:36:46 | 13:00:48 | +24m02s | User (button ~13:00) |
| 5 | v1.0 | 13:22:12 | 13:42:44 | +20m32s | User (button) |
| 6 | **v1.2.1** | 15:38:10 | 16:23:49 | +45m39s | User (button ~16:23) |
| 7 | **v1.2.1** | 20:40:00 | 20:51:51 | +11m51s | User (button ~20:51) |

**Test 7 details (critical)**: We manually enabled AIE (bit 5 of RTC Control Register, virtual reg 95) and programmed the alarm directly to the RX8025 RTC via virtual registers 88-90, bypassing the wp5 CLI entirely. AIE was confirmed enabled (reg 95 = 0x68) at shutdown. After boot, AIE was STILL enabled (0x68) and AF=False — meaning the RTC alarm DID fire (AF was set then cleared by MCU), but the MCU still did not power on the Pi.

**Key observation**: The "delay" in each test corresponds exactly to when the user pressed the button, not to any MCU-initiated wake-up. The MCU never woke the Pi on its own in any of 7 tests.

## Additional Findings
- MCU settings (pulsing interval, power-cut delay) **change/corrupt** after power cycles
- Set pulsing to 1s → reads back as 34s after reboot
- Power-cut delay changes from 15s to 38s without user action
- Frequent I2C instability: `Reg71 value changed from 0x80 to 0x00 on attempt 2` appears repeatedly in wp5d.log
- Scheduled shutdown always works correctly (wp5d detects it and initiates clean shutdown)
- RTC time sync works correctly (SYS = RTC after sync)

## Steps to Reproduce
1. Install wp5 v5.1.1, flash firmware v1.2.1
2. Ensure I2C works: `i2cdetect -y 1` shows 0x51
3. Sync time: wp5 → option 1 (Write system time to RTC)
4. Schedule startup: wp5 → option 5 → set time 5 minutes in the future
5. Schedule shutdown: wp5 → option 4 → set time 1 minute in the future
6. Wait for shutdown (works correctly)
7. Wait for startup → **Pi never powers on**
8. Press power button → wp5d log shows "Startup reason: Scheduled Startup"

## wp5d.log (relevant excerpt)
```
[15:35:27] Detected shutdown request, clearing and shutdown...
[15:35:27] Shutdown reason: Scheduled Shutdown
[15:35:37] Connected to Witty Pi 5
[15:35:37] RTC has valid time, write RTC time into system...
mié 18 mar 2026 16:23:49 -03
[16:23:49] Done 🙂
[16:23:49] Startup reason: Scheduled Startup
```
(Note: 45-minute gap between shutdown and next boot = user waited then pressed button)

## Firmware Source Code Analysis

We analyzed the open-source MCU firmware at https://github.com/uugear/Witty-Pi-5-Firmware (`src/rtc.c`, `src/power.c`, `src/main.c`, `src/i2c.h`) and identified several issues that likely explain the failure:

### 1. Race condition in `on_alarm_conf_changed()` (rtc.c)
This function only programs the RTC alarm when the Pi state is `STATE_STOPPING` or `STATE_OFF`. If it is called at any other time (e.g., while the Pi is still running), the alarm is **never written** to the RX8025 RTC chip. This means the schedule set by `wp5` may never reach the hardware.

### 2. Silent skip in `load_and_schedule_alarm()` (rtc.c)
If `cur_ts >= scheduled_ts` (i.e., the current time has already passed the scheduled time), the function silently returns without programming any alarm. **No error is logged.** This creates a window where a slightly delayed call results in a completely lost alarm with no indication of failure.

### 3. Alarm callback chain (main.c)
The wake-up path is: `rtc_alarm_occuried_callback()` → reads `ALARM1_SECOND` for delay → schedules `startup_alarm_callback()` → calls `request_startup(ACTION_REASON_ALARM1)`. However, `request_startup()` only works when `current_rpi_state == STATE_OFF`. If the state has not yet transitioned to `STATE_OFF` (e.g., it is still `STATE_STOPPING`), the startup request is silently ignored.

### 4. The "Scheduled Startup" log is misleading
When the user manually presses the power button, the MCU checks whether a scheduled startup time has already passed. If it has, the MCU labels the boot as "Scheduled Startup" even though it never actually triggered the wake-up. This explains why all 6 tests showed `Startup reason: Scheduled Startup` despite every one being manually triggered by button press.

### 5. CR2032 battery is NOT the issue
The RTC backup battery only maintains the RTC clock when USB power is disconnected. The MCU itself runs on USB power and stays active in an infinite loop (`while(true)` in `main.c`) even when the Pi is powered off. The alarm interrupt mechanism does not depend on the battery.

### 6. Settings corruption
MCU configuration registers (pulsing interval `0x12`, power-cut delay `0x13`) showed different values after power cycles (e.g., pulsing set to 1s reads back as 34s). This suggests possible flash/EEPROM write issues in the firmware that may also affect alarm register persistence.

### 7. AIE (Alarm Interrupt Enable) was found DISABLED — but enabling it didn't fix the problem
We read the RX8025T registers via the MCU's virtual register interface:

- **RTC_FLAG (reg 94 / 0x5E)**: 0x20 → AF (bit 3) = 0, UF (bit 5) = 1
- **RTC_CONTROL (reg 95 / 0x5F)**: 0x48 → AIE (bit 5) = 0, UIE (bit 3) = 1, CSEL (bit 6) = 1

AIE was disabled. We successfully enabled it by writing 0x68 to reg 95 (confirmed readback). However, **the MCU actively clears AIE** — if there is any delay between enabling and shutdown, AIE reverts to 0.

**Test 7** was designed to work around this: we enabled AIE as the very last step before `shutdown now`, confirmed AIE=True (reg 95 = 0x68), and shut down immediately. After manually booting ~12 minutes later:
- AIE was still enabled (reg 95 = 0x68) ✅
- AF = 0 (alarm fired and was cleared by MCU) ✅
- But **the MCU did not power on the Pi** ❌

This proves that even with AIE properly enabled:
1. The RTC alarm fires correctly
2. The MCU receives and processes the interrupt (clears AF)
3. But the MCU **fails to execute `request_startup()`** — the power-on step never happens

The bug is in the MCU firmware's alarm-to-power-on chain: `rtc_alarm_occuried_callback()` → `startup_alarm_callback()` → `request_startup(ACTION_REASON_ALARM1)`. One of these steps silently fails.

### 8. I2C bus instability
The wp5d log shows frequent I2C read inconsistencies:
```
[16:27:36] i2c_get: Reg71 value changed from 0x80 to 0x00 on attempt 2.
[16:29:15] i2c_get: Reg71 value changed from 0x80 to 0x00 on attempt 2.
```
These appear throughout the log and may indicate electrical noise or timing issues on the I2C bus between the Pi and the MCU.

## Register Dumps

### Before Test 7 (AIE disabled):
```
RTC_FLAG (94): 0x20 → AF=False, UF=True
RTC_CONTROL (95): 0x48 → AIE=False, UIE=True, CSEL=True
RTC Alarm: min=0x20 hour=0x20 day=0x80
RPI_STATE (13): 0 (MCU thinks Pi OFF while running)
```

### After Test 7 (AIE was manually enabled before shutdown):
```
RTC_FLAG (94): 0x20 → AF=False (alarm fired, MCU cleared it)
RTC_CONTROL (95): 0x68 → AIE=True (persisted through power cycle!)
RTC Alarm: min=0x40 hour=0x20 day=0x80 (20:40 as programmed)
RPI_STATE (13): 2 (STATE_ON — correct after button boot)
ACTION_REASON(14): 59
Startup reason: Button Click (NOT scheduled — MCU didn't wake Pi)
```

## Request
This is a firmware bug: **the MCU is not enabling the AIE (Alarm Interrupt Enable) bit in the RX8025 RTC's Control Register 1**. Without AIE, the RTC cannot generate alarm interrupts, making scheduled startup impossible.

We performed a full source code analysis of the Witty Pi 5 firmware (GitHub: `uugear/Witty-Pi-5-Firmware`) and confirmed the issue through direct I2C register reads. The MCU also blocks writes to the RTC control register from the Pi side, so no workaround is possible without a firmware fix.

**Could you please:**
1. Investigate why `request_startup()` is not called (or silently fails) when the RTC alarm fires while the Pi is powered off — even with AIE correctly enabled and the alarm confirmed to fire
2. Check the `rtc_alarm_occuried_callback()` → `startup_alarm_callback()` → `request_startup()` chain for state-check bugs (e.g., `current_rpi_state` not being `STATE_OFF` when expected)
3. Explain why AIE (bit 5 of RTC Control Register) is not enabled by default after `rtc_init()` and why the MCU actively clears it
4. Provide a firmware fix or updated UF2 that ensures scheduled startup works
5. Address the I2C instability (Reg71 value changes) and settings corruption after power cycles (pulsing interval changes from 1→34, power-cut delay from 15→38)

Thank you.