Retries and simplification

CLAUDE.md

@@ -30,18 +30,20 @@ python3 display.py --saturation 1.5 --contrast 1.1 --gamma 0.85
 4. Sends to e-ink display driver
 
 **`src/lib/immich.py`** — Immich API client. Key behaviors:
-- `PhotoHistory` tracks displayed photos in `photo_history.json` to avoid repeats (resets after 7 days)
-- `_pick_weighted_random()` biases selection: 50% chance favorites, 50% chance recent (last 7 days), otherwise random
-- Filters photos by orientation (portrait/landscape) based on EXIF data including rotation tags
+- `PhotoHistory` tracks displayed photos in `photo_history.json` to avoid repeats (resets after 7 days). Asset is only marked displayed after a successful download.
+- `_pick_weighted_random()` biases selection: 20% favorites, 50% recently-added (last 30 days, by Immich `createdAt`), otherwise uniform random
+- Filters photos by orientation (portrait/landscape) based on EXIF data including rotation tags. Raises if nothing matches the requested orientation.
 - Downloads preview-size thumbnails, not originals
+- Asset lists (people-search and album) are cached on disk in `/tmp/frame_cache/` for 1 hour
+- `urlopen` calls retry transient failures twice (3s, 10s backoff)
 
 **`src/lib/homeassistant.py`** — Simple Home Assistant REST client for presence detection.
 
 **`src/lib/waveshare_epd/epd7in3e.py`** — Modified Waveshare driver. The `getbuffer()` method handles the full image pipeline:
 - Center-crops to 800x480 (or 480x800)
-- Enhances saturation/contrast/gamma for e-ink (defaults: saturation=1.4, contrast=1.2, gamma=0.9)
-- Atkinson dithering to 6-color palette using numba JIT
-- Packs into 4-bit-per-pixel buffer (two pixels per byte)
+- Enhances saturation/contrast/gamma for e-ink (caller passes values; CLI defaults live in `display.py`: saturation=1.3, contrast=1.05, gamma=0.90)
+- Atkinson dithering to 6-color palette using numba JIT; produces palette indices directly (no Pillow quantize round-trip)
+- Packs into 4-bit-per-pixel buffer (two pixels per byte) via numpy
 
 **`src/lib/waveshare_epd/epdconfig.py`** — GPIO/SPI hardware config. **Critical: PWR pin is BCM 27** (not default 18).
 
@@ -55,4 +57,5 @@ python3 display.py --saturation 1.5 --contrast 1.1 --gamma 0.85
 - **Dependencies on Pi**: `python3-pil python3-opencv python3-numba python3-smbus spidev gpiozero`
 - **Config via environment variables**: `IMMICH_URL`, `IMMICH_API_KEY`, `HA_URL`, `HA_TOKEN` (with hardcoded defaults in display.py)
 - **Uses only stdlib `urllib`** — no requests library; the Immich client uses `urllib.request` directly
+- **Single-instance lock** at `/tmp/frame.lock` (fcntl) — overlapping cron runs exit cleanly
 - `sys.path.append` is used to add `lib/` to the path from display.py

src/display.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import argparse
+import fcntl
 import os
 import sys
 from datetime import datetime
@@ -12,6 +13,8 @@ from waveshare_epd import epd7in3e
 from immich import ImmichClient, get_random_photo_of_people, get_random_photo_from_album
 from homeassistant import HomeAssistantClient
 
+LOCK_FILE = "/tmp/frame.lock"
+
 IMMICH_URL = os.environ.get("IMMICH_URL", "https://immich.example.com")
 IMMICH_API_KEY = os.environ.get("IMMICH_API_KEY", "REDACTED_IMMICH_API_KEY")
 
@@ -51,6 +54,13 @@ def main() -> None:
     parser.add_argument("--no-enhance", action="store_true")
     args = parser.parse_args()
 
+    lock_fd = open(LOCK_FILE, "w")
+    try:
+        fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        print("Another instance running, skipping")
+        sys.exit(0)
+
     now = datetime.now()
     print(f"Time: {now.strftime('%H:%M')}")
 

src/lib/homeassistant.py

@@ -1,7 +1,11 @@
 #!/usr/bin/env python3
 import json
+import time
+from urllib.error import URLError
 from urllib.request import Request, urlopen
 
+RETRY_DELAYS = (3, 10)
+
 
 class HomeAssistantClient:
     def __init__(self, base_url: str, token: str):
@@ -14,8 +18,16 @@ class HomeAssistantClient:
             "Authorization": f"Bearer {self.token}",
             "Content-Type": "application/json",
         })
+        last_err: Exception | None = None
+        for attempt in range(len(RETRY_DELAYS) + 1):
+            try:
                 with urlopen(req, timeout=30) as resp:
                     return json.loads(resp.read().decode())
+            except (URLError, TimeoutError) as e:
+                last_err = e
+                if attempt < len(RETRY_DELAYS):
+                    time.sleep(RETRY_DELAYS[attempt])
+        raise last_err
 
     def is_person_home(self, entity_id: str) -> bool:
         try:

src/lib/immich.py

@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
+import hashlib
 import json
 import random
 import tempfile
+import time
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
+from urllib.error import URLError
 from urllib.request import Request, urlopen
 
 from progress import ProgressBar
@@ -12,6 +15,41 @@ from progress import ProgressBar
 HISTORY_FILE = Path(__file__).parent.parent / "photo_history.json"
 HISTORY_MAX_AGE_DAYS = 7
 
+CACHE_DIR = Path(tempfile.gettempdir()) / "frame_cache"
+CACHE_TTL_SECONDS = 3600
+
+RETRY_DELAYS = (3, 10)
+
+
+def _urlopen_with_retry(req: Request, timeout: int = 30):
+    """urlopen wrapper that retries transient network failures."""
+    last_err: Exception | None = None
+    for attempt in range(len(RETRY_DELAYS) + 1):
+        try:
+            return urlopen(req, timeout=timeout)
+        except (URLError, TimeoutError) as e:
+            last_err = e
+            if attempt < len(RETRY_DELAYS):
+                time.sleep(RETRY_DELAYS[attempt])
+    raise last_err
+
+
+def _cache_get(key: str) -> list[dict] | None:
+    path = CACHE_DIR / f"{key}.json"
+    if not path.exists():
+        return None
+    if time.time() - path.stat().st_mtime > CACHE_TTL_SECONDS:
+        return None
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _cache_set(key: str, value: list[dict]) -> None:
+    CACHE_DIR.mkdir(exist_ok=True)
+    (CACHE_DIR / f"{key}.json").write_text(json.dumps(value))
+
 
 class PhotoHistory:
     """Track displayed photos to avoid repeats. Clears after 7 days."""
@@ -59,7 +97,6 @@ class PhotoHistory:
 
 
 _history: PhotoHistory | None = None
-_people_cache: dict[str, str] = {}  # name -> id cache
 
 
 def get_history() -> PhotoHistory:
@@ -84,7 +121,7 @@ class ImmichClient:
             body = json.dumps(data).encode()
 
         req = Request(url, data=body, headers=headers, method=method)
-        with urlopen(req, timeout=30) as resp:
+        with _urlopen_with_retry(req, timeout=30) as resp:
             total_size = resp.headers.get('Content-Length')
             if total_size and show_progress:
                 total_size = int(total_size)
@@ -107,6 +144,11 @@ class ImmichClient:
         return None
 
     def search_assets_by_people(self, person_ids: list[str]) -> list[dict]:
+        key = "people_" + hashlib.md5("_".join(sorted(person_ids)).encode()).hexdigest()
+        cached = _cache_get(key)
+        if cached is not None:
+            return cached
+
         items = []
         page = 1
         while True:
@@ -122,12 +164,13 @@ class ImmichClient:
             if not batch or not result.get("assets", {}).get("nextPage"):
                 break
             page += 1
+        _cache_set(key, items)
         return items
 
     def download_asset(self, asset_id: str, dest: Path, show_progress: bool = True) -> Path:
         url = f"{self.base_url.rstrip('/')}/api/assets/{asset_id}/thumbnail?size=preview"
         req = Request(url, headers={"x-api-key": self.api_key})
-        with urlopen(req, timeout=30) as resp:
+        with _urlopen_with_retry(req, timeout=30) as resp:
             total_size = resp.headers.get('Content-Length')
             if total_size and show_progress:
                 total_size = int(total_size)
@@ -149,9 +192,16 @@ class ImmichClient:
         return None
 
     def get_album_assets(self, album_id: str, show_progress: bool = False) -> list[dict]:
+        key = f"album_{album_id}"
+        cached = _cache_get(key)
+        if cached is not None:
+            return cached
+
         album = self._request("GET", f"/albums/{album_id}",
                               show_progress=show_progress, progress_desc="Fetching album")
-        return album.get("assets", [])
+        assets = album.get("assets", [])
+        _cache_set(key, assets)
+        return assets
 
 
 def _is_portrait(asset: dict) -> bool | None:
@@ -218,9 +268,10 @@ def _download_random_asset(client: ImmichClient, assets: list[dict]) -> Path:
         print(f"All {len(assets)} photos shown, picking from full list")
         asset = _pick_weighted_random(assets)
 
-    history.mark_displayed(asset["id"])
     dest = Path(tempfile.gettempdir()) / "immich_photo.jpg"
-    return client.download_asset(asset["id"], dest)
+    path = client.download_asset(asset["id"], dest)
+    history.mark_displayed(asset["id"])
+    return path
 
 
 def get_random_photo_of_people(client: ImmichClient, names: list[str], orientation: int = 0) -> Path:
@@ -235,11 +286,9 @@ def get_random_photo_of_people(client: ImmichClient, names: list[str], orientati
 
     portrait = orientation in (90, 270)
     filtered = _filter_by_orientation(assets, portrait)
-    if filtered:
-        assets = filtered
-    else:
-        print(f"No {'portrait' if portrait else 'landscape'} photos, using any orientation")
-    return _download_random_asset(client, assets)
+    if not filtered:
+        raise ValueError(f"No {'portrait' if portrait else 'landscape'} photos available")
+    return _download_random_asset(client, filtered)
 
 
 def get_random_photo_from_album(client: ImmichClient, album_name: str, orientation: int = 0) -> Path:
@@ -253,8 +302,6 @@ def get_random_photo_from_album(client: ImmichClient, album_name: str, orientati
 
     portrait = orientation in (90, 270)
     filtered = _filter_by_orientation(assets, portrait)
-    if filtered:
-        assets = filtered
-    else:
-        print(f"No {'portrait' if portrait else 'landscape'} photos, using any orientation")
-    return _download_random_asset(client, assets)
+    if not filtered:
+        raise ValueError(f"No {'portrait' if portrait else 'landscape'} photos in album: {album_name}")
+    return _download_random_asset(client, filtered)

src/lib/progress.py

@@ -47,8 +47,3 @@ class ProgressBar:
         """Complete the progress bar."""
         self.current = self.total
         self._render()
-
-
-def print_status(msg: str) -> None:
-    """Print a status message."""
-    print(f"  {msg}")

src/lib/waveshare_epd/epd7in3e.py

@@ -2,38 +2,33 @@
 # Waveshare 7.3" 6-color e-Paper driver (modified)
 # Original: Waveshare team, 2022-10-20
 
-import sys
 import numpy as np
 import cv2
 from PIL import Image, ImageEnhance
 from numba import jit
+from progress import ProgressBar
 from . import epdconfig
 
 EPD_WIDTH = 800
 EPD_HEIGHT = 480
 
-DEFAULT_SATURATION = 1.4
-DEFAULT_CONTRAST = 1.2
-DEFAULT_GAMMA = 0.9
-
+# 6-color e-ink encoding: indices 0,1,2,3,5,6 are wire-format colors;
+# 4 is reserved/unused (filled with BLACK so nearest-color never picks it).
 PALETTE_RGB = np.array([
-    [0, 0, 0],        # BLACK
-    [255, 255, 255],  # WHITE
-    [255, 255, 0],    # YELLOW
-    [255, 0, 0],      # RED
-    [0, 0, 255],      # BLUE
-    [0, 255, 0],      # GREEN
+    [0, 0, 0],        # 0: BLACK
+    [255, 255, 255],  # 1: WHITE
+    [255, 255, 0],    # 2: YELLOW
+    [255, 0, 0],      # 3: RED
+    [0, 0, 0],        # 4: unused
+    [0, 0, 255],      # 5: BLUE
+    [0, 255, 0],      # 6: GREEN
 ], dtype=np.float64)
 
 PERCEPTUAL_WEIGHTS = np.array([0.299, 0.587, 0.114], dtype=np.float64)
 
 
-def _enhance_for_eink(image: Image.Image, saturation: float = None,
-                      contrast: float = None, gamma: float = None) -> Image.Image:
-    saturation = saturation or DEFAULT_SATURATION
-    contrast = contrast or DEFAULT_CONTRAST
-    gamma = gamma or DEFAULT_GAMMA
-
+def _enhance_for_eink(image: Image.Image, saturation: float,
+                      contrast: float, gamma: float) -> Image.Image:
     img = image.convert('RGB')
     if saturation != 1.0:
         img = ImageEnhance.Color(img).enhance(saturation)
@@ -66,18 +61,6 @@ def _crop_center(image: Image.Image, target_w: int, target_h: int,
     return Image.fromarray(cv2.cvtColor(cropped, cv2.COLOR_BGR2RGB))
 
 
-def _render_progress(desc: str, current: int, total: int, width: int = 30) -> None:
-    if total == 0:
-        return
-    percent = int(100 * current / total)
-    filled = int(width * current / total)
-    bar = "█" * filled + "░" * (width - filled)
-    sys.stdout.write(f"\r{desc}: |{bar}| {percent:3d}%")
-    sys.stdout.flush()
-    if current >= total:
-        print()
-
-
 @jit(nopython=True, cache=True)
 def _find_nearest_color(r, g, b, palette, weights):
     best_idx, best_dist = 0, 1e10
@@ -92,14 +75,14 @@ def _find_nearest_color(r, g, b, palette, weights):
 
 
 @jit(nopython=True, cache=True)
-def _atkinson_dither_rows(img, palette, weights, start_row, end_row):
+def _atkinson_dither_rows(img, palette, weights, indices, start_row, end_row):
     height, width = img.shape[:2]
     for y in range(start_row, end_row):
         for x in range(width):
             old_r, old_g, old_b = img[y, x, 0], img[y, x, 1], img[y, x, 2]
             idx = _find_nearest_color(old_r, old_g, old_b, palette, weights)
+            indices[y, x] = idx
             new_r, new_g, new_b = palette[idx, 0], palette[idx, 1], palette[idx, 2]
-            img[y, x, 0], img[y, x, 1], img[y, x, 2] = new_r, new_g, new_b
 
             err_r, err_g, err_b = (old_r - new_r) / 8.0, (old_g - new_g) / 8.0, (old_b - new_b) / 8.0
 
@@ -127,23 +110,25 @@ def _atkinson_dither_rows(img, palette, weights, start_row, end_row):
                 img[y + 2, x, 0] += err_r
                 img[y + 2, x, 1] += err_g
                 img[y + 2, x, 2] += err_b
-    return img
 
 
-def _dither_atkinson(image: Image.Image, show_progress: bool = True) -> Image.Image:
+def _dither_atkinson(image: Image.Image, show_progress: bool = True) -> np.ndarray:
+    """Atkinson-dither to the e-ink palette and return a uint8 array of palette indices."""
     img = np.array(image.convert('RGB'), dtype=np.float64)
-    height = img.shape[0]
+    height, width = img.shape[:2]
+    indices = np.zeros((height, width), dtype=np.uint8)
     if show_progress:
         print("Dithering...")
+        progress = ProgressBar(height, desc="Dithering")
 
     chunk_size = 48
     for i in range((height + chunk_size - 1) // chunk_size):
         start, end = i * chunk_size, min((i + 1) * chunk_size, height)
-        img = _atkinson_dither_rows(img, PALETTE_RGB, PERCEPTUAL_WEIGHTS, start, end)
+        _atkinson_dither_rows(img, PALETTE_RGB, PERCEPTUAL_WEIGHTS, indices, start, end)
         if show_progress:
-            _render_progress("Dithering", end, height)
+            progress.set(end)
 
-    return Image.fromarray(np.clip(img, 0, 255).astype(np.uint8), 'RGB')
+    return indices
 
 
 class EPD:
@@ -253,11 +238,8 @@ class EPD:
         self.wait_busy()
         return 0
 
-    def getbuffer(self, image, saturation=None, contrast=None, gamma=None,
-                  enhance=True, show_progress=True):
-        pal_image = Image.new("P", (1, 1))
-        pal_image.putpalette((0,0,0, 255,255,255, 255,255,0, 255,0,0, 0,0,0, 0,0,255, 0,255,0) + (0,0,0)*249)
-
+    def getbuffer(self, image, saturation: float, contrast: float, gamma: float,
+                  enhance: bool = True, show_progress: bool = True):
         image = image.convert('RGB')
         imwidth, imheight = image.size
 
@@ -271,16 +253,13 @@ class EPD:
                 print("Enhancing...")
             image = _enhance_for_eink(image, saturation, contrast, gamma)
 
-        image = _dither_atkinson(image, show_progress)
+        indices = _dither_atkinson(image, show_progress)
 
         if show_progress:
             print("Packing buffer...")
-        image_6color = image.quantize(palette=pal_image, dither=Image.Dither.NONE)
-        buf_6color = bytearray(image_6color.tobytes('raw'))
-
-        buf = [0x00] * (self.width * self.height // 2)
-        for i in range(0, len(buf_6color), 2):
-            buf[i // 2] = (buf_6color[i] << 4) + buf_6color[i + 1]
+        flat = indices.reshape(-1)
+        packed = (flat[0::2].astype(np.uint8) << 4) | flat[1::2].astype(np.uint8)
+        buf = packed.tolist()
 
         if show_progress:
             print("Ready")