IS-Matrix-Forge 1.0.0.dev1__py3-none-any.whl

is_matrix_forge/led_matrix/display/grid/helpers.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import threading
+from typing import Any, List
+
+from inspyre_toolbox.chrono import sleep as ist_sleep
+from serial.tools.list_ports_common import ListPortInfo
+
+from is_matrix_forge.common.helpers import coerce_to_int
+from is_matrix_forge.led_matrix.helpers.device import get_devices
+from is_matrix_forge.led_matrix.constants import HEIGHT, WIDTH
+from is_matrix_forge.led_matrix.display.helpers import render_matrix
+from is_matrix_forge.led_matrix.errors import MalformedGridError
+
+
+def get_grid_spec_from_animation_file(path: str, frame_number: int) -> List[List[int]]:
+    pass
+
+
+def generate_blank_grid(
+        width: int = WIDTH,
+        height: int = HEIGHT,
+        fill_value: int = 0
+) -> List[List[int]]:
+    """
+    Generate a blank grid of the specified width and height.
+
+    A blank grid is a list of lists of 0s, where each inner list represents a row of the grid.
+
+    Parameters:
+        width (int):
+            The width (in pixels) of the grid. Default is 9.
+
+        height (int):
+            The height (in pixels) of the grid. Default is 34.
+
+        fill_value (int):
+            The value to fill the grid with:
+
+              - Default is 0.
+              - Accepts 0 or 1:
+                  - 0 for no LEDs on.
+                  - 1 for all LEDs on.
+
+    Returns:
+        List[List[int]]:
+            A blank grid of the specified width and height.
+
+    Raises:
+        TypeError:
+            If width or height is not an int.
+    """
+    if not isinstance(width, int):
+        width = coerce_to_int(width)
+        if width is None:
+            raise TypeError(f"width must be an int, not {type(width)}")
+
+    if not isinstance(height, int):
+        height = coerce_to_int(height)
+        if height is None:
+            raise TypeError(f"height must be an int, not {type(height)}")
+
+    if not isinstance(fill_value, int):
+        fill_value = coerce_to_int(fill_value)
+        if fill_value is None:
+            raise TypeError(f"fill_value must be an int, not {type(fill_value)}")
+
+    if fill_value not in (0, 1):
+        raise ValueError(f"fill_value must be 0 or 1, not {fill_value}")
+
+    return [
+        [fill_value for _ in range(height)]
+        for _ in range(width)
+    ]
+
+
+def is_valid_grid(grid, width, height):
+
+    # column-major: width columns of height rows each
+    return (
+        isinstance(grid, list)
+        and len(grid) == width
+        and all(
+            isinstance(col, list)
+            and len(col) == height
+            and all(cell in (0,1) for cell in col)
+            for col in grid
+        )
+    )
+
+
+
+
+def hold_pattern(dev, grid: List[List[int]], reapply_interval: float = 55.00) -> None:
+    """
+    Hold the state of the LED matrix indefinitely, only updating the display every `reapply_interval` seconds.
+
+    This is useful for maintaining a static display on the LED matrix without having a constant refresh/computation
+    load.
+
+    Parameters:
+        dev (ListPortInfo):
+            The serial com device/port to use.
+
+        grid (List[List[int]])::
+            The grid to display on the LED matrix.
+
+        reapply_interval (Union[float, int]):
+            The interval in seconds at which to reapply the grid state to the LED matrix. Default is 55 seconds,
+            maximum is 60 (the number of seconds before the matrix turns all the LEDs off unless a new state is
+            applied)
+
+    Returns:
+        None
+    """
+    if not isinstance(dev, ListPortInfo):
+        raise TypeError(f"dev must be a ListPortInfo object, not {type(dev)}")
+
+    if not isinstance(grid, list) or not is_valid_grid(grid, 9, 34):
+        raise MalformedGridError(f"grid must be a 9x34 list of 0/1, not {type(grid)}")
+
+    def worker(interval):
+        global running
+        running.state = True
+        while running:
+            ist_sleep(interval)
+            render_matrix(dev, grid)
+
+    thread = threading.Thread(target=worker, args=(reapply_interval,), daemon=True)
+    thread.start()

is_matrix_forge/led_matrix/display/grid/presets/__init__.py

@@ -0,0 +1,64 @@
+"""
+Grid presets module for LED Matrix display.
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/display/grid/presets/__init__.py
+
+Description:
+    This module provides functionality for managing grid presets for the LED matrix display.
+    It includes a manifest of available presets and validation functions.
+"""
+from pathlib import Path
+from typing import Optional
+
+from is_matrix_forge.common.helpers import verify_checksum
+from is_matrix_forge.led_matrix.constants import PRESETS_DIR
+from is_matrix_forge.led_matrix.display.grid.presets.manifest import GridPresetManifest
+
+
+PRESETS_MANIFEST = GridPresetManifest(PRESETS_DIR / 'manifest.json')
+
+
+def validate_preset_files(preset_dir_path: Optional[Path] = None, manifest: Optional[GridPresetManifest] = None) -> bool:
+    """
+    Validate that all preset files in the manifest exist and are valid.
+
+    Args:
+        preset_dir_path (Optional[Path], optional): 
+            The directory containing preset files. Defaults to PRESETS_DIR if None.
+        manifest (Optional[GridPresetManifest], optional): 
+            The manifest to validate against. Defaults to PRESETS_MANIFEST if None.
+
+    Returns:
+        bool: True if all preset files are valid, False otherwise.
+
+    Note:
+        Validation checks that each file listed in the manifest exists in the
+        preset directory and that its checksum matches the value stored in the
+        manifest.
+    """
+
+    preset_dir_path = preset_dir_path or PRESETS_DIR
+    manifest = manifest or PRESETS_MANIFEST
+
+    if not isinstance(preset_dir_path, Path):
+        preset_dir_path = Path(preset_dir_path)
+
+    all_valid = True
+
+    for filename, checksum in manifest.as_dict().items():
+        file_path = preset_dir_path / filename
+        if not file_path.exists():
+            all_valid = False
+            break
+        if not verify_checksum(checksum, file_path):
+            all_valid = False
+            break
+
+    return all_valid

is_matrix_forge/led_matrix/display/grid/presets/manifest.py

@@ -0,0 +1,172 @@
+"""
+Author:
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File:
+    is_matrix_forge/led_matrix/display/grid/presets/manifest.py
+
+Description:
+    Manages a JSON-based manifest mapping filenames to checksums,
+    wrapped with metadata such as build version and save date.
+"""
+
+import json
+import hashlib
+from pathlib import Path
+from typing import Optional, Dict, Union
+from datetime import datetime
+
+from easy_exit_calls import ExitCallHandler
+from is_matrix_forge.dev_tools.debug import is_debug_mode
+
+ECH = ExitCallHandler()
+
+
+def calculate_checksum(file_path: Union[str, Path]) -> str:
+    """
+    Calculates a SHA256 checksum for a file.
+
+    Parameters:
+        file_path (Union[str, Path]): Path to the file.
+
+    Returns:
+        str: Hex digest of the file's SHA256 checksum.
+    """
+    hash_sha256 = hashlib.sha256()
+    with open(file_path, 'rb') as f:
+        for chunk in iter(lambda: f.read(4096), b''):
+            hash_sha256.update(chunk)
+    return hash_sha256.hexdigest()
+
+
+class GridPresetManifest:
+    """
+    Represents a manifest that maps preset filenames to their known checksums,
+    along with versioning and date metadata.
+
+    Automatically saves the manifest to disk when the program exits (in debug mode).
+    """
+
+    DEFAULT_VERSION = "dev"
+
+    def __init__(self, manifest_path: Union[str, Path]):
+        self.manifest_path = Path(manifest_path)
+        self._manifest_dict: Dict[str, str] = {}
+        self._meta: Dict[str, str] = {
+            'version': self.DEFAULT_VERSION,
+            'date': datetime.now().isoformat()
+        }
+
+        self._load()
+
+        if is_debug_mode():
+            ECH.register_handler(self._save)
+
+    def _load(self):
+        """
+        Loads the manifest and metadata from disk if it exists.
+        """
+        if self.manifest_path.exists():
+            try:
+                with open(self.manifest_path, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+
+                    self._meta = data.get('meta', self._meta)
+                    manifest = data.get('manifest', [])
+
+                    self._manifest_dict = {
+                        list(item.keys())[0]: list(item.values())[0]
+                        for item in manifest
+                    }
+
+            except Exception as e:
+                print(f"[GridPresetManifest] Failed to load manifest: {e}")
+        else:
+            self._manifest_dict = {}
+
+    def _save(self):
+        """
+        Saves the manifest and metadata to disk in JSON format.
+        """
+        try:
+            self._meta['date'] = datetime.now().isoformat()
+            data = {
+                'meta': self._meta,
+                'manifest': [{k: v} for k, v in self._manifest_dict.items()]
+            }
+
+            with open(self.manifest_path, 'w', encoding='utf-8') as f:
+                json.dump(data, f, indent=2)
+        except Exception as e:
+            print(f"[GridPresetManifest] Failed to save manifest: {e}")
+
+    def get_checksum(self, filename: str) -> Optional[str]:
+        """
+        Returns the stored checksum for a given file.
+
+        Parameters:
+            filename (str): Name of the file to query.
+
+        Returns:
+            Optional[str]: Checksum string or None.
+        """
+        return self._manifest_dict.get(filename)
+
+    def add(self, filename: str, checksum: str):
+        """
+        Adds or updates a checksum entry in the manifest.
+
+        Parameters:
+            filename (str): File name.
+            checksum (str): Checksum string.
+        """
+        self._manifest_dict[filename] = checksum
+
+    def scan(self, dir_path: Union[str, Path]):
+        """
+        Scans a directory for files and adds their checksums to the manifest.
+
+        Parameters:
+            dir_path (Union[str, Path]): Directory path.
+        """
+        dir_path = Path(dir_path)
+        if not dir_path.is_dir():
+            raise ValueError(f"{dir_path} is not a valid directory")
+
+        for file in dir_path.iterdir():
+            if file.is_file():
+                checksum = calculate_checksum(file)
+                self.add(file.name, checksum)
+
+    def __getitem__(self, filename: str) -> Optional[str]:
+        return self.get_checksum(filename)
+
+    def __setitem__(self, filename: str, checksum: str):
+        self.add(filename, checksum)
+
+    def __contains__(self, filename: str) -> bool:
+        return filename in self._manifest_dict
+
+    def as_dict(self) -> Dict[str, str]:
+        """
+        Returns a copy of the manifest dictionary.
+        """
+        return self._manifest_dict.copy()
+
+    def get_meta(self) -> Dict[str, str]:
+        """
+        Returns a copy of the metadata dictionary.
+        """
+        return self._meta.copy()
+
+    def set_version(self, version: str):
+        """
+        Sets the version in metadata.
+
+        Parameters:
+            version (str): Version string.
+        """
+        self._meta['version'] = version

is_matrix_forge/led_matrix/display/helpers/__init__.py

@@ -0,0 +1,110 @@
+import time
+import math
+from is_matrix_forge.led_matrix.commands.map import CommandVals
+from is_matrix_forge.led_matrix.commands import send_command
+
+
+def keep_image(
+    controller,
+    breathe: bool = False,
+    breathe_fps: float = 30,
+    interval: float = 0.1,
+    time_between_refreshes: float = 50
+):
+    """
+    Continuously hold the current image on-screen, optionally breathing the brightness.
+
+    Args:
+        controller: an LEDMatrixController-like object with:
+            - .brightness (0-100)
+            - .keep_image (bool flag you can set to False to exit)
+            - .draw_grid(grid) or .render_current() to re-send the image
+            - .set_brightness(value)
+        breathe: if True, oscillate brightness in a sinusoidal “breathing” pattern
+        breathe_fps: how many brightness steps per second when breathing
+        interval: seconds between each brightness step (if breathing)
+        time_between_refreshes: seconds to sleep after one full breath cycle
+                                 (or between redraws if not breathing)
+    """
+    base_brightness = controller.brightness
+    t = 0.0
+    period = 1.0  # one full sine cycle = 1 second
+    step = 1.0 / breathe_fps
+
+    while controller.keep_image:
+        if breathe:
+            # Compute a smooth sine-based oscillation from 0→1→0
+            phase = (t % period) / period            # 0.0→1.0
+            fade = 0.5 * (1 - math.cos(2 * math.pi * phase))
+            bri = int(round(base_brightness * fade))
+            controller.set_brightness(bri)
+            time.sleep(interval)
+            t += interval
+        else:
+            # just hold at base brightness
+            controller.set_brightness(base_brightness)
+            time.sleep(time_between_refreshes)
+
+        # re-draw the current image (whatever the controller is holding)
+        # assume controller.draw_current() or similar:
+        try:
+            controller.render_current()
+        except AttributeError:
+            # fallback to a generic draw call
+            controller.draw()
+
+
+def light_leds(dev, leds):
+    """Light a specific number of LEDs"""
+    # Initialize a byte array with all LEDs off
+    vals = [0x00 for _ in range(39)]
+
+    # Calculate how many complete bytes we need to fill (each byte = 8 LEDs)
+    complete_bytes = int(leds / 8)
+
+    # Set all complete bytes to 0xFF (all 8 bits on)
+    for byte in range(complete_bytes):
+        vals[byte] = 0xFF
+
+    # Handle the remaining LEDs (less than 8) in the last partial byte
+    remaining_leds = leds % 8
+
+    # For each remaining LED, set the corresponding bit in the last byte
+    # This creates a binary pattern like 00011111 for 5 remaining LEDs
+    for i in range(remaining_leds):
+        vals[complete_bytes] += 1 << i
+
+    # Send the command to the device to display the pattern
+    send_command(dev, CommandVals.Draw, vals)
+
+
+def render_matrix(dev, matrix):
+    """Show a black/white matrix
+    Send everything in a single command"""
+    # Initialize a byte array to hold the binary representation of the matrix
+    # 39 bytes = 312 bits, which is enough for 9x34 = 306 pixels
+    vals = [0x00 for _ in range(39)]
+
+    # Iterate through each position in the 9x34 matrix
+    for x in range(9):
+        for y in range(34):
+            # Convert 2D coordinates to a linear index
+            # The matrix is stored in column-major order (y changes faster than x)
+            i = x + 9 * y
+
+            # If the pixel at this position is "on" (non-zero)
+            if matrix[x][y]:
+                # Calculate which byte in the vals array this pixel belongs to
+                byte_index = int(i / 8)
+
+                # Calculate which bit within that byte represents this pixel
+                bit_position = i % 8
+
+                # Set the corresponding bit in the appropriate byte
+                # This efficiently packs 8 pixels into each byte
+                vals[byte_index] = vals[byte_index] | (1 << bit_position)
+
+    # Send the packed binary data to the device
+    send_command(dev, CommandVals.Draw, vals)
+
+

is_matrix_forge/led_matrix/display/helpers/columns.py

@@ -0,0 +1,33 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    ${DIR_PATH}/${FILE_NAME}
+ 
+
+Description:
+    $DESCRIPTION
+
+"""
+from is_matrix_forge.led_matrix.commands.map import CommandVals
+from is_matrix_forge.led_matrix.constants import FWK_MAGIC
+
+
+def send_col(dev, s, x, vals):
+    """Stage greyscale values for a single column. Must be committed with commit_cols()"""
+    command = FWK_MAGIC + [CommandVals.StageGreyCol, x] + vals
+    send_serial(dev, s, command)
+
+
+def commit_cols(dev, s):
+    """Commit the changes from sending individual cols with send_col(), displaying the matrix.
+    This makes sure that the matrix isn't partially updated."""
+    from ..hardware import FWK_MAGIC
+    command = FWK_MAGIC + [CommandVals.DrawGreyColBuffer, 0x00]
+    send_serial(dev, s, command)