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

is_matrix_forge/led_matrix/errors/grid.py

@@ -0,0 +1,37 @@
+from .base import LEDMatrixControllerError
+
+
+class GridDefinitionError(LEDMatrixControllerError, ValueError):
+    """
+    Base class for all grid definition errors.
+
+    A "grid definition error" is an error that occurs while defining a grid for the LED matrix, either in translation
+    from data to the LED matrix or in the grid itself. This includes errors such as malformed grids, invalid grid
+    sizes, etc.
+
+    Provided Subclasses:
+        - MalformedGridError:
+            Raised when the grid structure does not match expectations. This can include issues such as incorrect
+            dimensions, missing elements, or other structural problems.
+    """
+    default_message = 'An error has occurred within the grid definition!'
+
+
+class MalformedGridError(GridDefinitionError):
+    """
+    Raised when the grid is malformed.
+
+    Class Attributes:
+        default_message (str):
+            **Read-Only**. The default message for the error.
+    """
+    default_message = 'The grid is malformed!'
+
+    def __init__(self, more_info: str = None, **kwargs) -> None:
+        if more_info is not None:
+            self.default_message = f"{self.default_message}\n\n  Additional information from caller:\n    {more_info}"
+
+        super().__init__(message=self.default_message, **kwargs)
+
+
+__all__ = ['GridDefinitionError', 'MalformedGridError']

is_matrix_forge/led_matrix/errors/matrix.py

@@ -0,0 +1,68 @@
+from inspyre_toolbox.exceptional import CustomRootException
+from .base import LEDMatrixControllerError
+
+
+class MatrixError(LEDMatrixControllerError):
+    """
+    Base class for all LED matrix errors.
+
+    Subclasses of this exception are used to indicate specific errors that can occur while interacting with the LED
+    matrix hardware.
+
+    Provided Subclasses:
+        - MatrixConnectionError:
+            Raised when the LED matrix cannot be connected to.
+
+        - MatrixInUseError:
+            Raised when the LED matrix is already in use by another process.
+    """
+    default_message = 'An error occurred while interacting with the LED matrix!'
+
+    def __init__(self, message: str = None, device_name: str = None) -> None:
+        full_msg = self.default_message
+
+        if device_name is not None:
+            full_msg += f' (Device: {device_name})'
+
+        if message is not None:
+            full_msg = f'{full_msg}\n\n  Additional Info:\n{" " * 4}{message}'
+
+        super().__init__(full_msg)
+
+
+class MatrixConnectionError(MatrixError):
+    """
+    Raised when the LED matrix cannot be connected to.
+    """
+    default_message = 'Unable to connect to the LED matrix!'
+
+    def __init__(self, message: str = None) -> None:
+        if message is None:
+            message = self.default_message
+        else:
+            message = f'{self.default_message}\n\n  Additional Info:\n{" " * 4}{message}'
+
+        super().__init__(message)
+
+
+class MatrixInUseError(MatrixConnectionError):
+    """
+    Raised when the LED matrix is already in use by another process.
+    """
+    message = 'The LED matrix is already in use, and cannot be used by this program! Please close the other ' \
+                      'instance/process and try again!'
+
+    def __init__(self):
+        super().__init__(self.message)
+
+
+class InvalidBrightnessError(MatrixError):
+    """
+    Raised when the brightness value provided is invalid.
+    """
+    default_message = 'The brightness value provided is invalid! Value must be an integer between 0 and 255!'
+
+    def __init__(self, brightness: int):
+        message = f'{self.default_message}\n\n  Brightness: {brightness}'
+
+        super().__init__(message)

is_matrix_forge/led_matrix/errors/misc.py

@@ -0,0 +1,36 @@
+from .base import CustomRootException
+
+
+class MiscError(CustomRootException):
+    pass
+
+
+class ImplicitNameDerivationError(MiscError, ValueError):
+    """
+    Raised by `freeze_setter` when it's used to decorate a property setter
+    whose name begins with a single underscore (e.g., `_my_prop`) without an
+    explicit `attr_name` being provided.
+
+    This error occurs because the default behavior of `freeze_setter` is to
+    derive the underlying private attribute name by prepending an underscore
+    to the setter's name. If the setter is `_my_prop`, this would implicitly
+    attempt to create `__my_prop`. Attributes starting with double underscores
+    trigger Python's name mangling, which can lead to unexpected behavior and
+    make the underlying attribute name less predictable if not explicitly intended.
+
+    To prevent this implicit and potentially confusing name derivation,
+    `freeze_setter` requires that you explicitly specify the `attr_name`
+    when decorating setters that start with a single underscore.
+
+    TL;DR: When using `freeze_setter` on a property setter named `_my_prop`,
+    you must explicitly specify the `attr_name` as "__my_prop" to avoid confusion
+    about how the underlying attribute will be named, and to confirm your intent.
+    """
+    default_message = (
+        "Implicitly derived attribute names are not allowed for properties "
+        "whose names begin with a single underscore. Please provide an "
+        "`attr_name` argument."
+    )
+
+    def __init__(self, **kwargs):
+        super().__init__(message=self.default_message, **kwargs)

is_matrix_forge/led_matrix/fonts.py

@@ -0,0 +1,20 @@
+from typing import List
+import json
+import importlib.resources
+
+from is_matrix_forge.assets.font_map import FontMap
+
+# Load the default font map shipped with the package using importlib.resources
+with importlib.resources.open_text("is_matrix_forge.assets", "char_map.json", encoding="utf-8") as f:
+    _FONT_DATA = json.load(f)
+FONT_MAP = FontMap(font_map=_FONT_DATA)
+
+
+def convert_font(ch: str) -> List[int]:
+    """Return the 5x6 glyph list for a single character."""
+    return FONT_MAP.lookup(ch, kind="character")
+
+
+def convert_symbol(symbol: str) -> List[int]:
+    """Return the glyph list for a named symbol."""
+    return FONT_MAP.lookup(symbol, kind="symbol")

is_matrix_forge/led_matrix/hardware.py

@@ -0,0 +1,172 @@
+"""
+Hardware communication module for LED Matrix.
+
+This module provides low-level functions for communicating with LED matrix hardware.
+It includes functions for sending commands, controlling brightness, and other basic operations.
+"""
+
+from is_matrix_forge.led_matrix.commands import send_command
+from is_matrix_forge.led_matrix.commands.map import CommandVals
+from is_matrix_forge.led_matrix.helpers.core.lazy_mod_load import LazyModuleLoader
+from enum import IntEnum
+
+
+# Import the necessary functions from the controller module
+
+
+class PatternVals(IntEnum):
+    Percentage = 0x00
+    Gradient = 0x01
+    DoubleGradient = 0x02
+    DisplayLotus = 0x03
+    ZigZag = 0x04
+    FullBrightness = 0x05
+    DisplayPanic = 0x06
+    DisplayLotus2 = 0x07
+
+
+class Game(IntEnum):
+    Snake = 0x00
+    Pong = 0x01
+    Tetris = 0x02
+    GameOfLife = 0x03
+
+
+class GameOfLifeStartParam(IntEnum):
+    Currentmatrix = 0x00
+    Pattern1 = 0x01
+    Blinker = 0x02
+    Toad = 0x03
+    Beacon = 0x04
+    Glider = 0x05
+
+    def __str__(self):
+        return self.name.lower()
+
+    def __repr__(self):
+        return str(self)
+
+    @staticmethod
+    def argparse(s):
+        try:
+            return GameOfLifeStartParam[s.lower().capitalize()]
+        except KeyError:
+            return s
+
+
+class GameControlVal(IntEnum):
+    Up = 0
+    Down = 1
+    Left = 2
+    Right = 3
+    Quit = 4
+
+
+def disconnect_dev(dev):
+    """
+    Disconnect the device from the system.
+
+    Parameters:
+        dev (str):
+            The device to disconnect.
+    """
+    global DISCONNECTED_DEVS
+    if dev in DISCONNECTED_DEVS:
+        return
+    DISCONNECTED_DEVS.append(dev)
+
+
+def bootloader_jump(dev):
+    """Reboot into the bootloader to flash new firmware"""
+    send_command(dev, CommandVals.BootloaderReset, [0x00])
+
+
+def brightness(dev, b: int):
+    """Adjust the brightness scaling of the entire screen."""
+    send_command(dev, CommandVals.Brightness, [b])
+
+
+def get_brightness(dev):
+    """Adjust the brightness scaling of the entire screen."""
+    res = send_command(dev, CommandVals.Brightness, with_response=True)
+    return int(res[0])
+
+
+def get_version(dev):
+    """Get the device's firmware version"""
+    res = send_command(dev, CommandVals.Version, with_response=True)
+    if not res:
+        return 'Unknown'
+    major = res[0]
+    minor = (res[1] & 0xF0) >> 4
+    patch = res[1] & 0xF
+    pre_release = res[2]
+
+    version = f"{major}.{minor}.{patch}"
+    if pre_release:
+        version += " (Pre-release)"
+    return version
+
+
+def send_serial(dev, s, command):
+    """Send serial command by using existing serial connection"""
+    try:
+        s.write(command)
+    except (IOError, OSError) as _ex:
+        disconnect_dev(dev.device)
+        # print("Error: ", ex)
+
+
+def animate(dev, b: bool):
+    """Enable/disable animation"""
+    send_command(dev, CommandVals.Animate, [0x01 if b else 0x00])
+
+
+def get_animate(dev):
+    """Check if animation is enabled"""
+    res = send_command(dev, CommandVals.Animate, with_response=True)
+    return bool(res[0])
+
+
+def get_pwm_freq(dev):
+    """Adjust the brightness scaling of the entire screen."""
+    res = send_command(dev, CommandVals.PwmFreq, with_response=True)
+    freq = int(res[0])
+    if freq == 0:
+        return 29000
+    elif freq == 1:
+        return 3600
+    elif freq == 2:
+        return 1800
+    elif freq == 3:
+        return 900
+    else:
+        return None
+
+
+def pwm_freq(dev, freq):
+    """Set the PWM frequency"""
+    if freq == "29kHz":
+        send_command(dev, CommandVals.PwmFreq, [0])
+    elif freq == "3.6kHz":
+        send_command(dev, CommandVals.PwmFreq, [1])
+    elif freq == "1.8kHz":
+        send_command(dev, CommandVals.PwmFreq, [2])
+    elif freq == "900Hz":
+        send_command(dev, CommandVals.PwmFreq, [3])
+
+
+def percentage(dev, p):
+    """Fill a percentage of the screen. Bottom to top"""
+    send_command(dev, CommandVals.Pattern, [PatternVals.Percentage, p])
+
+
+def define_controllers(threaded=False):
+    from is_matrix_forge.led_matrix.controller.helpers import get_controllers
+    return get_controllers(threaded)
+
+
+# CONTROLLERS = define_controllers()
+
+
+

is_matrix_forge/led_matrix/helpers/__init__.py

@@ -0,0 +1,165 @@
+import serial
+from inspyre_toolbox.chrono.sleep import NegateSwitch
+from inspyre_toolbox.path_man import provision_path
+
+from serial.tools.list_ports_common import ListPortInfo
+from threading import Thread
+
+import json
+from pathlib import Path
+from typing import Union, Optional, List, Any, ByteString
+
+
+def get_json_from_file(path: Union[str, Path]) -> Any:
+    """
+    Load and parse a JSON file.
+
+    Args:
+        path (Union[str, Path]): The path to the JSON file to load.
+
+    Returns:
+        Any: The parsed JSON data.
+
+    Raises:
+        FileNotFoundError:
+            If the file does not exist.
+
+        IsADirectoryError:
+            If the path points to a directory.
+
+        json.JSONDecodeError:
+            If the file contains invalid JSON.
+    """
+    path = provision_path(path)
+    if not path.exists():
+        raise FileNotFoundError(f'Preset file not found: {path}')
+
+    if not path.is_file():
+        raise IsADirectoryError(f'Preset file is a directory: {path}')
+
+    with open(path, 'r') as f:
+        return json.load(f)
+
+
+def load_from_file(
+        path:              Union[str, Path],
+        expected_width:    Optional[int]               = None,
+        expected_height:   Optional[int]               = None,
+        fallback_duration: Optional[Union[int, float]] = None
+) -> List['Frame']:
+    """
+    Load a list of frames from a file.
+
+    Args:
+        path (Union[str, Path]): The path to the file to load.
+        expected_width (Optional[int]): The expected width of the frames in the file. Defaults to 9.
+        expected_height (Optional[int]): The expected height of the frames in the file. Defaults to 34.
+        fallback_duration (Optional[Union[int, float]]): The duration of the frames in the file. 
+            Defaults to 0.33 (1/3 of a second).
+
+    Returns:
+        List[Frame]: A list of frames loaded from the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        IsADirectoryError: If the path points to a directory.
+        ValueError: If the file does not contain a valid JSON array.
+    """
+    from is_matrix_forge.led_matrix.display.animations.frame.helpers import migrate_frame
+    from is_matrix_forge.led_matrix.display.grid.helpers import is_valid_grid
+
+    width  = expected_width  or 9
+    height = expected_height or 34
+
+    data = get_json_from_file(path)
+
+    if not isinstance(data, list):
+        raise ValueError(f"File {path} does not contain a valid JSON array")
+
+    frames = []
+    for entry in data:
+
+        if not isinstance(entry, dict) and isinstance(entry, list) and is_valid_grid(entry, width, height):
+            entry = migrate_frame(entry, fallback_duration)
+            entry['duration'] = fallback_duration or .33
+
+        frames.append(entry)
+
+    return data
+
+
+def disconnect_dev(dev: str) -> None:
+    """
+    Disconnect the device from the system.
+
+    Args:
+        dev (str): The device to disconnect.
+
+    Note:
+        This function adds the device to a global list of disconnected devices
+        to prevent further attempts to communicate with it.
+    """
+    global DISCONNECTED_DEVS
+    if dev in DISCONNECTED_DEVS:
+        return
+
+    DISCONNECTED_DEVS.append(dev)
+
+
+def send_serial(dev: ListPortInfo, s: 'serial.Serial', command: ByteString) -> None:
+    """
+    Send serial command by using an existing serial connection.
+
+    Args:
+        dev (ListPortInfo): The device to send the command to.
+        s (serial.Serial): The serial connection to use.
+        command (ByteString): The command to send.
+
+    Raises:
+        IOError, OSError: If there is an error communicating with the device.
+    """
+    try:
+        s.write(command)
+    except (IOError, OSError) as _ex:
+        disconnect_dev(dev.device)
+        # print("Error: ", ex)
+
+
+def identify_devices(devices: Optional[List[ListPortInfo]] = None) -> None:
+    """
+    Identify LED matrix devices by flashing an identification message on each
+    connected matrix. If no specific devices are provided, all detected devices
+    are used.
+
+    Parameters:
+        devices (Optional[List[ListPortInfo]], optional):
+            List of devices to identify. Defaults to ``None`` which will use all
+            detected devices.
+    """
+    from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+
+    if devices is None:
+        from is_matrix_forge.led_matrix.helpers.device import DEVICES
+        devices = DEVICES
+
+    import logging
+
+    controllers = [LEDMatrixController(dev, 100) for dev in devices]
+
+    def safe_identify(controller):
+        try:
+            controller.identify()
+        except Exception as e:
+            logging.exception(f"Exception in identify thread for controller {controller}: {e}")
+
+    threads = []
+    for controller in controllers:
+        t = Thread(target=safe_identify, args=(controller,))
+        threads.append(t)
+        t.start()
+
+    for t in threads:
+        t.join()
+
+
+running = NegateSwitch(False)

is_matrix_forge/led_matrix/helpers/core/__init__.py

@@ -0,0 +1,17 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/helpers/core/__init__.py
+ 
+
+Description:
+    
+
+"""

is_matrix_forge/led_matrix/helpers/core/lazy_mod_load.py

@@ -0,0 +1,84 @@
+import sys
+import types
+import logging
+import pkgutil
+from importlib import import_module
+from typing import Set, Optional, Union
+
+
+class LazyModuleLoader:
+    """
+    A utility to lazily load submodules and avoid circular imports.
+
+    Parameters
+    ----------
+    parent_module : str
+        The fully qualified name of the module (e.g., 'is_matrix_forge.led_matrix').
+
+    submodules : Optional[Set[str]]
+        A set of submodules to lazily load. If not provided, it will be auto-discovered.
+
+    fallback_module : Optional[str]
+        Optional fallback module to delegate attribute lookups to.
+
+    enable_logging : bool
+        Enable logging for import errors.
+    """
+
+    def __init__(
+        self,
+        parent_module: str,
+        submodules: Optional[Set[str]] = None,
+        fallback_module: Optional[str] = None,
+        enable_logging: bool = True
+    ):
+        self.module_name = parent_module
+        self.submodules = submodules or self._discover_submodules()
+        self.fallback_module = fallback_module
+        self.enable_logging = enable_logging
+        self.logger = logging.getLogger(__name__)
+        self._install()
+
+    def _discover_submodules(self) -> Set[str]:
+        try:
+            module = import_module(self.module_name)
+            path = module.__path__
+            return {name for _, name, is_pkg in pkgutil.iter_modules(path)}
+        except Exception as e:
+            if self.enable_logging:
+                self.logger.error(f"Error discovering submodules for '{self.module_name}': {e}")
+            return set()
+
+    def _install(self):
+        mod = sys.modules[self.module_name]
+        mod.__getattr__ = self.__getattr__
+        mod.__dir__ = self.__dir__
+        mod.__all__ = sorted(self.submodules)
+
+    def __getattr__(self, name):
+        if name in self.submodules:
+            try:
+                full_name = f"{self.module_name}.{name}"
+                module = import_module(full_name)
+                sys.modules[full_name] = module
+                return module
+            except ImportError as e:
+                if self.enable_logging:
+                    self.logger.error(f"Failed to import submodule '{name}': {e}")
+                raise
+        elif self.fallback_module:
+            base = import_module(self.fallback_module)
+            try:
+                return getattr(base, name)
+            except AttributeError as e:
+                if self.enable_logging:
+                    self.logger.error(
+                        f"Fallback '{self.fallback_module}' has no attribute '{name}': {e}"
+                    )
+                raise
+        else:
+            raise AttributeError(f"Module '{self.module_name}' has no attribute '{name}'")
+
+    def __dir__(self):
+        return sorted(set(sys.modules[self.module_name].__dict__) | self.submodules)
+