Timer

Author: cagcoach

custom_components/ipixel_color/api.py

@@ -19,6 +19,7 @@
 from .device.info import build_device_info_command, parse_device_response
 from .display.text_renderer import render_text_to_png
 from .exceptions import iPIXELConnectionError
+from .giftimer import build_timer_gif
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -336,6 +337,107 @@ async def display_text_pypixelcolor(
             _LOGGER.error("Error displaying pypixelcolor text: %s", err)
             return False
 
+    async def display_timer_gif(
+        self,
+        duration_seconds: int,
+        text_color: tuple[int, int, int] = (0, 255, 0),
+        bg_color: tuple[int, int, int] = (0, 0, 0),
+        font_path: str | None = None,
+    ) -> bool:
+        """Generate and display a countdown timer GIF on the device.
+
+        Args:
+            duration_seconds: Total countdown duration in seconds
+            text_color: RGB tuple for text color (default: green)
+            bg_color: RGB tuple for background color (default: black)
+            font_path: Path to TTF font file, or None for default
+
+        Returns:
+            True if timer GIF was sent successfully
+        """
+        try:
+            import tempfile
+            import os
+            from pathlib import Path
+
+            # Get device dimensions
+            device_info = await self.get_device_info()
+            width = device_info["width"]
+            height = device_info["height"]
+
+            # Determine font size based on display height
+            # Use a font size that fits well in the display
+            font_size = max(8, height - 4)
+
+            # Use default font if none specified
+            if font_path is None:
+                fonts_dir = Path(__file__).parent / "fonts"
+                # Try to find a good monospace font for timer display
+                for font_name in ["7x5.ttf", "5x5.ttf", "OpenSans-Light.ttf"]:
+                    potential_font = fonts_dir / font_name
+                    if potential_font.exists():
+                        font_path = str(potential_font)
+                        break
+
+            # Generate timer GIF to temporary file
+            with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as tmp:
+                tmp_path = tmp.name
+
+            try:
+                frame_count = build_timer_gif(
+                    duration_seconds=duration_seconds,
+                    output_path=tmp_path,
+                    font_size=font_size,
+                    bg=bg_color,
+                    fg=text_color,
+                    font_path=font_path,
+                    width=width,
+                    height=height,
+                )
+
+                _LOGGER.debug(
+                    "Generated timer GIF: %d seconds, %d frames, %dx%d",
+                    duration_seconds, frame_count, width, height
+                )
+
+                # Read the generated GIF
+                with open(tmp_path, "rb") as f:
+                    gif_data = f.read()
+
+            finally:
+                # Clean up temp file
+                if os.path.exists(tmp_path):
+                    os.unlink(tmp_path)
+
+            # Generate image commands using pypixelcolor
+            commands = make_image_command(
+                image_bytes=gif_data,
+                file_extension=".gif",
+                resize_method="crop",
+                device_info_dict=device_info
+            )
+
+            # Send all command frames
+            for i, command in enumerate(commands):
+                _LOGGER.debug(
+                    "Sending timer GIF frame %d/%d: %d bytes",
+                    i + 1, len(commands), len(command)
+                )
+                success = await self._bluetooth.send_command(command)
+                if not success:
+                    _LOGGER.error("Failed to send timer GIF frame %d/%d", i + 1, len(commands))
+                    return False
+
+            _LOGGER.info(
+                "Timer GIF sent: %d seconds countdown (%dx%d, %d bytes, %d frames)",
+                duration_seconds, width, height, len(gif_data), len(commands)
+            )
+            return True
+
+        except Exception as err:
+            _LOGGER.error("Error displaying timer GIF: %s", err)
+            return False
+
     def _notification_handler(self, sender: Any, data: bytearray) -> None:
         """Handle notifications from the device."""
         _LOGGER.debug("Notification from %s: %s", sender, data.hex())

custom_components/ipixel_color/common.py

@@ -5,7 +5,7 @@
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.template import Template
 from homeassistant.helpers import entity_registry as er
-from .const import MODE_TEXT_IMAGE, MODE_TEXT, MODE_CLOCK, DOMAIN
+from .const import MODE_TEXT_IMAGE, MODE_TEXT, MODE_CLOCK, MODE_TIMER, DOMAIN
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -127,6 +127,10 @@ async def update_ipixel_display(hass: HomeAssistant, device_name: str, api, text
             return await _update_text_mode(hass, device_name, api, text)
         elif mode == MODE_CLOCK:
             return await _update_clock_mode(hass, device_name, api)
+        elif mode == MODE_TIMER:
+            # Timer mode is triggered by timer entity state changes, not manual updates
+            _LOGGER.debug("Timer mode active - waiting for timer entity to start")
+            return True
         else:
             _LOGGER.warning("Unknown mode: %s, falling back to textimage", mode)
             return await _update_textimage_mode(hass, device_name, api, text)
@@ -294,7 +298,7 @@ async def _update_text_mode(hass: HomeAssistant, device_name: str, api, text: st
             # We weight the channels since not each color appears as bright as the others.
             # In this way we choose the channel which should be less obvious.
             bg = bg_color or "000000"
-            r, g, b = int(bg[0:2], 16)*333, int(bg[2:4], 16)*169, int(bg[4:6], 16)*909 
+            r, g, b = int(bg[0:2], 16)*333, int(bg[2:4], 16)*169, int(bg[4:6], 16)*909
             if g >= r and g >= b:
                 color = "000100"
             elif b >= r:

custom_components/ipixel_color/const.py

@@ -27,11 +27,13 @@
 MODE_TEXT_IMAGE = "textimage"
 MODE_TEXT = "text"
 MODE_CLOCK = "clock"
+MODE_TIMER = "timer"
 
 AVAILABLE_MODES = [
     MODE_TEXT_IMAGE,
     MODE_TEXT,
     MODE_CLOCK,
+    MODE_TIMER,
 ]
 
 DEFAULT_MODE = MODE_TEXT_IMAGE

custom_components/ipixel_color/giftimer/__init__.py

@@ -0,0 +1,18 @@
+"""Timer GIF generation utilities for iPIXEL Color displays."""
+
+from .formatter import format_time, parse_duration
+from .renderer import get_font, measure_text, create_frame, update_frame, create_palette
+from .gif_builder import build_timer_gif, DEFAULT_BG, DEFAULT_FG
+
+__all__ = [
+    "format_time",
+    "parse_duration",
+    "get_font",
+    "measure_text",
+    "create_frame",
+    "update_frame",
+    "create_palette",
+    "build_timer_gif",
+    "DEFAULT_BG",
+    "DEFAULT_FG",
+]

custom_components/ipixel_color/giftimer/formatter.py

@@ -0,0 +1,37 @@
+"""Time formatting utilities."""
+
+
+def format_time(seconds):
+    """Format seconds into display string.
+
+    - Up to 9:59: shows M:SS (e.g., "5:32")
+    - Above 9:59: shows Xm (e.g., "14m")
+    """
+    if seconds < 0:
+        seconds = 0
+
+    minutes = seconds // 60
+    secs = seconds % 60
+
+    if minutes <= 9:
+        return f"{minutes}:{secs:02d}"
+    else:
+        return f"{minutes}m"
+
+
+def parse_duration(duration_str):
+    """Parse duration string into seconds.
+
+    Accepts: 30s, 5m, 2:30, or plain number (seconds)
+    """
+    duration_str = duration_str.lower().strip()
+
+    if duration_str.endswith("s"):
+        return int(duration_str[:-1])
+    elif duration_str.endswith("m"):
+        return int(duration_str[:-1]) * 60
+    elif ":" in duration_str:
+        parts = duration_str.split(":")
+        return int(parts[0]) * 60 + int(parts[1])
+    else:
+        return int(duration_str)

custom_components/ipixel_color/giftimer/gif_builder.py

@@ -0,0 +1,64 @@
+"""GIF generation from timer frames."""
+
+from .formatter import format_time
+from .renderer import get_font, measure_text, create_frame, update_frame, create_palette
+
+# Default colors: green on black
+DEFAULT_BG = (0, 0, 0)
+DEFAULT_FG = (0, 255, 0)
+
+
+def build_timer_gif(duration_seconds, output_path, font_size=72, bg=DEFAULT_BG, fg=DEFAULT_FG,
+                    font_path=None, width=None, height=None):
+    """Build a countdown timer GIF."""
+    font = get_font(font_size, font_path)
+    palette = create_palette(bg, fg)
+    padding = 20
+
+    # Calculate image size from longest possible text, or use provided size
+    max_text = format_time(duration_seconds)
+    if duration_seconds <= 599:  # Could show 9:59
+        max_text = "9:59"
+    text_w, text_h, _ = measure_text(max_text, font)
+
+    if width is None:
+        width = text_w + 2 * padding
+    if height is None:
+        height = text_h + 2 * padding
+
+    frames = []
+    durations = []
+    prev_frame = None
+    prev_text = None
+    text_x, text_y = 0, 0
+
+    for remaining in range(duration_seconds, -1, -1):
+        current_text = format_time(remaining)
+
+        if remaining == 0:
+            # Inverted colors for final frame
+            inverted_palette = create_palette(fg, bg)
+            frame, text_x, text_y = create_frame(current_text, width, height, font, inverted_palette)
+            durations.append(65535)  # Max GIF duration (65535ms)
+        elif prev_frame is None or len(current_text) != len(prev_text):
+            frame, text_x, text_y = create_frame(current_text, width, height, font, palette)
+            durations.append(1000)
+        else:
+            frame = update_frame(prev_frame, prev_text, current_text, text_x, text_y, font)
+            durations.append(1000)
+
+        frames.append(frame)
+        prev_frame = frame
+        prev_text = current_text
+
+    # Save GIF (loop=1 means play once, no repeat)
+    frames[0].save(
+        output_path,
+        save_all=True,
+        append_images=frames[1:],
+        duration=durations,
+        loop=1,
+        optimize=True
+    )
+
+    return len(frames)

custom_components/ipixel_color/giftimer/renderer.py

@@ -0,0 +1,71 @@
+"""Frame rendering utilities."""
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+DEFAULT_FONT_PATHS = [
+    "/System/Library/Fonts/Menlo.ttc",
+    "/System/Library/Fonts/Monaco.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+]
+
+
+def get_font(size, font_path=None):
+    """Get a font. Uses font_path if provided, otherwise tries defaults."""
+    if font_path:
+        return ImageFont.truetype(font_path, size)
+
+    for path in DEFAULT_FONT_PATHS:
+        try:
+            return ImageFont.truetype(path, size)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def measure_text(text, font):
+    """Measure text dimensions."""
+    img = Image.new("RGB", (1, 1))
+    draw = ImageDraw.Draw(img)
+    bbox = draw.textbbox((0, 0), text, font=font)
+    return bbox[2] - bbox[0], bbox[3] - bbox[1], bbox[1]
+
+
+def create_palette(bg_color, fg_color):
+    """Create a 2-color palette."""
+    palette = list(bg_color) + list(fg_color) + [0] * (256 * 3 - 6)
+    return palette
+
+
+def create_frame(text, width, height, font, palette):
+    """Create a new frame with centered text (2-color palette)."""
+    frame = Image.new("P", (width, height), 0)
+    frame.putpalette(palette)
+    draw = ImageDraw.Draw(frame)
+
+    text_w, text_h, y_offset = measure_text(text, font)
+    x = (width - text_w) // 2
+    y = (height - text_h) // 2 - y_offset
+
+    draw.text((x, y), text, font=font, fill=1)
+    return frame, x, y
+
+
+def update_frame(prev_frame, prev_text, new_text, x, y, font):
+    """Update only changed characters in a frame (2-color palette)."""
+    frame = prev_frame.copy()
+    draw = ImageDraw.Draw(frame)
+
+    x_offset = x
+    for old_char, new_char in zip(prev_text, new_text):
+        bbox = draw.textbbox((x_offset, y), old_char, font=font)
+        char_width = bbox[2] - bbox[0]
+
+        if old_char != new_char:
+            # Clear and redraw only this character
+            draw.rectangle([bbox[0], bbox[1], bbox[2], bbox[3]], fill=0)
+            draw.text((x_offset, y), new_char, font=font, fill=1)
+
+        x_offset += char_width
+
+    return frame

custom_components/ipixel_color/giftimer/timer.gif

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Generate a countdown timer GIF."""
+
+import argparse
+import sys
+
+from formatter import parse_duration
+from gif_builder import build_timer_gif
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate a countdown timer GIF")
+    parser.add_argument("duration", help="Duration: 30s, 5m, 2:30, or seconds")
+    parser.add_argument("-o", "--output", default="timer.gif", help="Output file")
+    parser.add_argument("-s", "--font-size", type=int, default=72, help="Font size")
+    parser.add_argument("-f", "--font", help="Path to font file")
+    parser.add_argument("-W", "--width", type=int, help="Image width")
+    parser.add_argument("-H", "--height", type=int, help="Image height")
+
+    args = parser.parse_args()
+
+    try:
+        seconds = parse_duration(args.duration)
+    except ValueError:
+        print(f"Error: Invalid duration '{args.duration}'", file=sys.stderr)
+        sys.exit(1)
+
+    if seconds <= 0:
+        print("Error: Duration must be positive", file=sys.stderr)
+        sys.exit(1)
+
+    frame_count = build_timer_gif(
+        seconds,
+        args.output,
+        font_size=args.font_size,
+        font_path=args.font,
+        width=args.width,
+        height=args.height
+    )
+
+    print(f"Created {args.output} ({frame_count} frames, {seconds}s)")
+
+
+if __name__ == "__main__":
+    main()