immich-frame/docs/superpowers/specs/2026-08-04-deep-sleep-single-fetch-design.md

# Deep Sleep Single-Fetch with Probabilistic Weighting

**Date**: 2026-08-04
**Status**: Approved

## Overview

Refactor the deep sleep wake path (`timerWakeCycle`) to fetch a single random photo per wake using probabilistic server-side filtering based on `cycle_mode`. Replaces the current 10-asset batch fetch with a leaner single-call approach that honors weighting settings while minimizing API calls and battery consumption.

## Motivation

In deep sleep slideshow mode, buttons don't respond and there's no photo queue. The device simply wakes, shows one photo, and sleeps again. Fetching 10 assets and picking one wastes HTTP round-trips, bandwidth, and battery. A single `POST /api/search/random` call with `size=1` and appropriate filters is sufficient.

## Immich API Capabilities

The `POST /api/search/random` endpoint (Immich v3) supports these filters relevant to our use case:

- `size` — number of results
- `type` — media type (IMAGE)
- `albumIds` — array of album UUIDs
- `isFavorite` — boolean filter
- `takenAfter` — ISO 8601 datetime string
- `takenBefore` — ISO 8601 datetime string

These server-side filters allow meaningful weighting without fetching large batches.

## Design

### Filter Selection per Cycle Mode

| Mode | Filter applied | Probability | Fallback |
|------|---------------|-------------|----------|
| Random | No extra filter | 100% | — |
| Chronological | `takenAfter=last_shown_date` | 100% | Reset date to epoch |
| ReverseChronological | `takenBefore=last_shown_date` | 100% | Reset date to "now" |
| FavoritesWeighted | `isFavorite=true` | 66% | Drop `isFavorite` |
| FavoritesWeighted | No extra filter | 33% | — |
| WeightedChronological | `takenAfter=(now - 30 days)` | 66% | Drop date filter |
| WeightedChronological | No extra filter | 33% | — |
| WeightedReverseChronological | `takenBefore=(now - 30 days)` | 66% | Drop date filter |
| WeightedReverseChronological | No extra filter | 33% | — |

Album IDs from settings are always included alongside any other filter.

### Retry Logic

```
attempt = 0
while (!displayed && attempt < MAX_RETRIES):
  1. Choose filter based on cycle_mode + probability roll
  2. POST /api/search/random (size=1, filter + albumIds)
  3. If empty response:
     - If using a filter: retry without filter (relax)
     - If already unfiltered: give up (no photos available)
  4. Download + process the asset
  5. If download/process fails: increment attempt, loop
  6. If success: display, update timer_last_date in NVS, break
```

MAX_RETRIES = 5 (matches current `TIMER_WAKE_RETRIES`).

### NVS Persistence

New Settings field: `timer_last_date` (String, ISO datetime).

- Updated after each successful display in deep sleep mode
- Used as the cursor for Chronological and ReverseChronological modes
- Empty string means "no cursor" (start from beginning/end)

### RTC Initialization (Firmware-Wide)

The PaperColor has a hardware RX8130CE Real-Time Clock (I2C 0x32) that persists across deep sleep. It is not currently used in the firmware.

**At boot (both paths), before WiFi:**
- Seed ESP32 system clock from hardware RTC via `M5.Rtc.getDateTime()` + `settimeofday()`

**After WiFi connects (both paths):**
- Sync system clock from NTP via `configTime(0, 0, "pool.ntp.org")`
- Write corrected time back to hardware RTC via `M5.Rtc.setDateTime()`

**Benefits:**
- Deep sleep date filters are reliable
- Normal mode metadata overlays (strftime) display correct time
- Future time-dependent features become trivial

### Date Helpers

New `src/time_utils.h`:
- `String isoNow()` — current time as ISO 8601 (e.g., `"2026-08-04T17:30:00.000Z"`)
- `String isoNowMinus30d()` — 30 days ago as ISO 8601
- `bool hasValidTime()` — returns false if year < 2020 (RTC never synced)

## Files Modified

- `src/immich_client.h` — add `RandomFetchFilter` struct + `fetchOneRandomAssetId()` declaration
- `src/immich_client.cpp` — implement `fetchOneRandomAssetId()`
- `src/settings.h` — add `timer_last_date` field
- `src/settings.cpp` — add NVS read/write for `timer_date`
- `src/main.cpp` — refactor `timerWakeCycle()`, seed system clock from RTC at boot
- `src/wifi_manager.cpp` — add NTP sync after WiFi connect, write back to hardware RTC
- New: `src/time_utils.h` — ISO date helpers

## Normal Mode Impact

- **Slideshow logic**: Untouched. Normal mode still uses `PhotoQueue` with `fetchRandomAssets(50)`.
- **RTC/NTP sync**: Applied to both modes as a general firmware improvement.

## Edge Cases

- No photos match filter: fallback to unfiltered, then give up
- RTC never synced (first boot or battery drained): detect year < 2020, fall back to random for weighted modes
- Chronological cursor exhausted: when `takenAfter=cursor` returns empty, reset cursor to "" (wraps around)
- Album has no favorites: `isFavorite=true` + albumIds returns empty, fallback drops `isFavorite`