From bfa51c1439301d778f57cae09679cb68695454ed Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 23 Nov 2025 14:21:24 +0100
Subject: [PATCH] add logging of screen events

---
 src/dreader_hal/display/it8951.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/dreader_hal/display/it8951.py b/src/dreader_hal/display/it8951.py
index 9a85ba6..504a4fe 100644
--- a/src/dreader_hal/display/it8951.py
+++ b/src/dreader_hal/display/it8951.py
@@ -12,6 +12,7 @@ Hardware: IT8951 controller (used in Waveshare 6" e-Paper HAT and similar)
 """
 
 import asyncio
+import logging
 import sys
 import os
 from typing import Optional
@@ -25,6 +26,8 @@ from IT8951.constants import DisplayModes
 
 from ..types import RefreshMode
 
+logger = logging.getLogger(__name__)
+
 
 class IT8951DisplayDriver:
     """
@@ -93,6 +96,7 @@ class IT8951DisplayDriver:
         """Blocking initialization of display (runs in thread pool)."""
         if self.virtual:
             # Virtual display for testing
+            logger.info(f"Initializing IT8951 virtual display: {self.width}x{self.height}")
             self.display = VirtualEPDDisplay(
                 dims=(self.width, self.height),
                 rotate=self.rotate,
@@ -100,6 +104,7 @@ class IT8951DisplayDriver:
             )
         else:
             # Real e-ink display
+            logger.info(f"Initializing IT8951 e-ink display: {self.width}x{self.height}, VCOM={self.vcom}V")
             self.display = AutoEPDDisplay(
                 vcom=self.vcom,
                 bus=self.bus,
@@ -110,7 +115,9 @@ class IT8951DisplayDriver:
             )
 
         # Clear screen
+        logger.info("Clearing IT8951 display to white")
         self.display.clear()
+        logger.info("IT8951 display initialized successfully")
 
     async def cleanup(self) -> None:
         """
@@ -162,6 +169,9 @@ class IT8951DisplayDriver:
 
         # Determine refresh mode
         display_mode = self._determine_refresh_mode(mode)
+        mode_name = self._get_mode_name(display_mode)
+
+        logger.info(f"[IT8951] Displaying image {image.size} {image.mode} | Refresh #{self._refresh_count + 1} | Mode: {mode_name}")
 
         # Prepare image for e-ink
         prepared_image = self._prepare_image(image)
@@ -180,6 +190,8 @@ class IT8951DisplayDriver:
             display_mode
         )
 
+        logger.info(f"[IT8951] Display update completed (refresh #{self._refresh_count})")
+
         # Automatically put display to sleep after update to save power
         # E-ink displays only need power during refresh, not for static display
         if self.auto_sleep:
@@ -279,6 +291,17 @@ class IT8951DisplayDriver:
             # Default to DU (fast)
             return DisplayModes.DU
 
+    def _get_mode_name(self, display_mode: int) -> str:
+        """Get human-readable name for display mode."""
+        if display_mode == DisplayModes.INIT:
+            return "INIT (full refresh)"
+        elif display_mode == DisplayModes.DU:
+            return "DU (fast)"
+        elif display_mode == DisplayModes.GC16:
+            return "GC16 (quality)"
+        else:
+            return f"Mode {display_mode}"
+
     def _update_display(self, display_mode: int) -> None:
         """
         Update the physical display (blocking).