IS-Matrix-Forge 1.0.0.dev8__tar.gz → 1.0.0.dev9__tar.gz

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: IS-Matrix-Forge
-Version: 1.0.0.dev8
+Version: 1.0.0.dev9
 Summary: 
 License: MIT
 Keywords: led,matrix,framework,hardware
@@ -19,12 +19,16 @@ Requires-Dist: easy-exit-calls (>=1.0.0.dev1,<2.0.0)
 Requires-Dist: imapclient (==3.0.1)
 Requires-Dist: inspy-logger (>=3.2.3,<4.0.0)
 Requires-Dist: inspyre-toolbox (>=1.6.0.dev23)
+Requires-Dist: ipywidgets (==8.1.7)
+Requires-Dist: notebook (>=7.4.4,<8.0.0)
 Requires-Dist: opencv-python (>=4.11.0.86,<5.0.0.0)
 Requires-Dist: pillow (>=11.2.1,<12.0.0)
+Requires-Dist: psutil (==6.1.1)
 Requires-Dist: pyserial (>=3.5,<4.0)
 Requires-Dist: pysimplegui-4-foss (==4.60.4.1)
 Requires-Dist: pysimpleguiweb (==0.39.0)
 Requires-Dist: requests (>=2.32.4,<3.0.0)
+Requires-Dist: wmi (>=1.5.1,<2.0.0)
 Project-URL: Homepage, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Project-URL: Repository, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Description-Content-Type: text/markdown

is_matrix_forge-1.0.0.dev9/is_matrix_forge/Untitled.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "a6d553a0-fca1-411a-a7bd-cf15dce52e97",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "a9c234aa78a641018ba78e54e9a3755b",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(Dropdown(description='Pick a pattern to render...', options=('All LEDs on', 'Gradient (0-13% Br…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from is_matrix_forge.led_matrix import get_controllers\n",
+    "import ipywidgets as widgets\n",
+    "CONTROLLERS = get_controllers(threaded = True)\n",
+    "PATTERNS = CONTROLLERS[0].built_in_pattern_names\n",
+    "\n",
+    "\n",
+    "class DropdownWithButton:\n",
+    "    def __init__(self, options, description='Choose:', button_desc='Run', callback=None):\n",
+    "        self.output = widgets.Output()\n",
+    "        self.dropdown = widgets.Dropdown(\n",
+    "            options=options, description=description, disabled=False\n",
+    "        )\n",
+    "        self.button = widgets.Button(\n",
+    "            description=button_desc, disabled=True, button_style='primary'\n",
+    "        )\n",
+    "        self.callback = callback or self.default_callback\n",
+    "\n",
+    "        # Set up observers\n",
+    "        self.dropdown.observe(self._on_select, names='value')\n",
+    "        self.button.on_click(self._on_click)\n",
+    "\n",
+    "        # Layout\n",
+    "        self.container = widgets.VBox([self.dropdown, self.button, self.output])\n",
+    "        display(self.container)\n",
+    "\n",
+    "    def _on_select(self, change):\n",
+    "        self.button.disabled = False  # Enable button once a selection is made\n",
+    "\n",
+    "    def _on_click(self, b):\n",
+    "        with self.output:\n",
+    "            # Clear prior output\n",
+    "            self.output.clear_output()\n",
+    "            self.callback(self.dropdown.value)\n",
+    "\n",
+    "    @staticmethod\n",
+    "    def default_callback(value):\n",
+    "        print(f\"You selected: {value}\")\n",
+    "\n",
+    "\n",
+    "\n",
+    "def render(selection):\n",
+    "    CONTROLLERS[0].draw_pattern(selection)\n",
+    "\n",
+    "\n",
+    "\n",
+    "drp_bttn = DropdownWithButton(\n",
+    "    options=PATTERNS,\n",
+    "    description='Pick a pattern to render...',\n",
+    "    button_desc='Render',\n",
+    "    callback=render\n",
+    "\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8533a241-ef3b-4a44-99cd-2e88cabb9fbb",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

is_matrix_forge-1.0.0.dev9/is_matrix_forge/assets/digit_map.py

@@ -0,0 +1,82 @@
+"""
+Contains the pixel representation of the ld states within a 3x5 grid.
+"""
+
+
+DIGITS = {
+    "0": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "1": [
+        [0, 1, 0],
+        [1, 1, 0],
+        [0, 1, 0],
+        [0, 1, 0],
+        [1, 1, 1],
+    ],
+    "2": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+    ],
+    "3": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+    "4": [
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+    ],
+    "5": [
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+    "6": [
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "7": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+    ],
+    "8": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "9": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+}
+
+
+__all__ = [
+    'DIGITS'
+]

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev9}/is_matrix_forge/designer_gui/main_window/__init__.py

@@ -86,16 +86,44 @@ class PixelGrid:
 
     @current_frame.setter
     def current_frame(self, value: Any) -> None:
+        """
+        Setter indicating which frame index to display..
+
+        Note:
+            Must be an integer between 0 and len(frames) - 1.
+        """
         if not isinstance(value, int) or not (0 <= value < len(self.frames)):
             raise ValueError("current_frame must be an index into frames list")
         self.__current_frame = value
 
     @property
     def grid(self) -> List[List[int]]:
+        """
+        A column-major 0/1 list representing the pixel grid.
+        """
         return self.__grid
 
     @grid.setter
     def grid(self, value: Any) -> None:
+        """
+        Setter for the grid data.
+
+        Note:
+            A valid grid is structured as follows:
+              - Must be a list
+                - Containing 9 lists
+                  - Each list:
+                    - Must be the same length
+                    - Each item:
+                      - Integer
+                      - 0-1
+
+            Example:
+                Framework Laptop 9x34:
+                    - 9 lists
+                      - each with 34 items
+                        - 0-1
+        """
         if not is_valid_grid(value, self.width, self.height):
             raise ValueError("Grid must match width/height and be 0/1 values")
         self.__grid = value
@@ -105,6 +133,9 @@ class PixelGrid:
 
     @property
     def preferred_device(self):
+        """
+        The device we want to send the grid to.
+        """
         return self.__preferred_device
 
     @preferred_device.setter
@@ -128,6 +159,9 @@ class PixelGrid:
         )
 
     def run(self) -> None:
+        """
+        Run the UI.
+        """
         while True:
             event, _ = self.window.read()
             if event in (sg.WINDOW_CLOSED, 'Exit'):
@@ -152,6 +186,9 @@ class PixelGrid:
 
     # Frame management
     def add_frame(self) -> None:
+        """
+        Add a new frame to the grid.
+        """
         new_grid = copy.deepcopy(self.grid)
         frm = Frame(new_grid)
         self.frames = self.frames + [frm]
@@ -161,6 +198,11 @@ class PixelGrid:
         self._update_frame_indicator()
 
     def prev_frame(self) -> None:
+        """
+        Go back one frame.
+
+        Show the frame that's before the current one.
+        """
         if self.current_frame > 0:
             self.current_frame -= 1
             self._load_frame()
@@ -256,5 +298,9 @@ class PixelGrid:
         return is_valid_grid(grid, self.width, self.height)
 
 
-if __name__ == '__main__':
+def main():
     PixelGrid().run()
+
+
+if __name__ == '__main__':
+    main()

is_matrix_forge-1.0.0.dev9/is_matrix_forge/designer_gui/main_window/layout/menu_bar.py

@@ -0,0 +1,43 @@
+import PySimpleGUI as sg
+
+
+MENU_DEF = [
+    ['File', [
+        'Export',
+        'Export to File',
+        'Load from File',
+        '---',
+        'Exit'
+    ]],
+    ['Matrix', [
+        'Send to Matrix'
+    ]],
+    ['Frame', [
+        'Add Frame'
+    ]]
+]
+
+
+class MenuBar:
+    def __init__(self):
+        self.__layout   = None
+        self.__menu_bar = None
+
+    @property
+    def is_built(self):
+        return self.__layout is not None and self.__menu_bar is not None
+
+    @property
+    def layout(self):
+        return self.__layout
+
+    @property
+    def menu_bar(self):
+        return self.__menu_bar
+
+    def build(self):
+        if self.__layout is not None and self.menu_bar is not None:
+            return [self.menu_bar, [sg.VPush()], *self.__layout]
+        raise RuntimeError("Menu bar or layout is not defined.")
+
+

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev9}/is_matrix_forge/led_matrix/controller/controller.py

@@ -21,17 +21,14 @@ import threading
 from time import sleep
 from typing import Optional, Dict, Any, Union, List
 
-from is_matrix_forge.log_engine import ROOT_LOGGER, Loggable
-
 from inspyre_toolbox.syntactic_sweets.classes import validate_type
-from inspyre_toolbox.syntactic_sweets.classes.decorators.aliases import add_aliases, method_alias
+from inspyre_toolbox.syntactic_sweets.classes.decorators.aliases import method_alias
 from serial.tools.list_ports_common import ListPortInfo
 
 from is_matrix_forge.common.helpers import coerce_to_int
 from aliaser.metaclass import AliasMeta
 from is_matrix_forge.led_matrix.constants import SLOT_MAP
 from is_matrix_forge.led_matrix.display.text import show_string as _show_string_raw
-from is_matrix_forge.led_matrix.controller import MultitonMeta
 from is_matrix_forge.led_matrix.controller.helpers.threading import synchronized
 from is_matrix_forge.led_matrix.commands.map import CommandVals
 from is_matrix_forge.led_matrix.hardware import send_command
@@ -40,10 +37,32 @@ from is_matrix_forge.led_matrix.display.text import show_string
 
 COMMANDS = CommandVals
 
-MOD_LOGGER = ROOT_LOGGER.get_child('led_matrix.controller.controller')
 
+class _BreatherPauseCtx:
+    def __init__(self, controller: LEDMatrixController):
+        self.controller = controller
+        self._was_breathing = False
+
+    def __enter__(self):
+        """
+        Pause the breathing animation. This context manager ensures that the
+        device is not breathing when the context is exited. **A sleep of .05
+        seconds is carried out to ensure the hardware settles before the
+        context is exited. This is to ensure that the device has time to
+        leave the breathing state and restore the previous state.**
+
+        """
+        if getattr(self.controller, "breathing", False):
+            self._was_breathing = True
+            self.controller.breathing = False
+            sleep(0.05)  # Required short delay to ensure hardware settles
 
-class LEDMatrixController(Loggable, metaclass=AliasMeta):
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._was_breathing:
+            self.controller.breathing = True
+
+
+class LEDMatrixController(metaclass=AliasMeta):
     """
     Controller class for LED Matrix devices.
 
@@ -89,7 +108,10 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
             do_not_show_grid_on_init:     Optional[bool] = False,
             thread_safe:                  Optional[bool] = False,
             do_not_warn_on_thread_misuse: Optional[bool] = False,
-            hold_all:                     Optional[bool] = False
+            hold_all:                     Optional[bool] = False,
+            skip_greeting:                Optional[bool] = False,
+            skip_identify:                Optional[bool] = False,
+            skip_all_init_animations:     Optional[bool] = False
     ):
         """
         Initialize a new LED Matrix Controller.
@@ -150,7 +172,16 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
 
         self.__set_up_thread_safety__(thread_safe)
 
-        self.__post_init__()
+        self.__post_init__(
+            skip_identify=skip_identify or skip_all_init_animations,
+            skip_greeting=skip_greeting or skip_all_init_animations
+        )
+
+    def __breather_paused(self):
+        return _BreatherPauseCtx(self)
+
+    def __greet(self):
+        self.scroll_text('Hello')
 
     # ---------------------------------------------------------------------
     # Keep‑alive internal worker
@@ -172,7 +203,7 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
             # Wait with timeout so the thread can exit early when stop_evt is set
             stop_evt.wait(self._KEEP_ALIVE_INTERVAL)
 
-    # ---------------------------------------------------------------------
+    # ----------------------------------f-----------------------------------
     # Property controlling the keep‑alive thread
     # ---------------------------------------------------------------------
 
@@ -214,7 +245,7 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
             self._keep_alive = False
         self.__post_init__()
 
-    def __post_init__(self):
+    def __post_init__(self, skip_greeting= False, skip_identify=False):
         from is_matrix_forge.led_matrix.display.effects.breather import Breather
 
         self.__breather = Breather(self)
@@ -235,19 +266,22 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
         if self.breather is None:
             self.__breather = Breather(self)
 
+        if not skip_greeting:
+            self.__greet()
+
+        if not skip_identify:
+            self.identify()
+
     def __set_up_thread_safety__(self, thread_safe_opt: bool):
         if thread_safe_opt is None or not thread_safe_opt:
             self._thread_safe = False
             return
         else:
             self._thread_safe = True
-            self._cmd_lock = threading.RLock()
 
             return
 
-
     @property
-    @alias('is_animating')
     def animating(self) -> bool:
         """
         Check if the device is currently animating.
@@ -255,12 +289,9 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
         Returns:
             bool: True if the device is animating, False otherwise.
         """
-        log = self.method_logger
-        try:
-            return bool(send_command(self.device, COMMANDS.Animate, with_response=True)[0])
-        except TypeError as e:
-            log.error('Received null response')
-
+        # Guard against `None`, and empty lists
+        res = send_command(dev= self.device, command= COMMANDS.Animate, with_response= True)
+        return bool(res and res[0])
 
     @property
     def breather(self) -> Breather:
@@ -368,8 +399,8 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
         """
         return self.__keep_image
 
-    @keep_image.setter
     @validate_type(bool)
+    @keep_image.setter
     def keep_image(self, new):
         self.__keep_image = new
 
@@ -416,7 +447,7 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
     def scroll_text(self, text: str, skip_end_space: bool = False, loop: bool = False):
         from is_matrix_forge.led_matrix.display.text.scroller import TextScroller
         from is_matrix_forge.led_matrix.display.animations.animation import Animation
-        from is_matrix_forge.led_matrix import fonts as font
+        from is_matrix_forge.led_matrix.display.assets import fonts as font
 
         text_animation = Animation(TextScroller(font).scroll(text, skip_end_space))
         text_animation.set_all_frame_durations(.03)
@@ -424,6 +455,17 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
             text_animation.loop = True
         return self.play_animation(text_animation)
 
+    @property
+    def serial_number(self) -> str:
+        """
+        Get the USB serial number of the device, if available.
+
+        Returns:
+            str:
+                The USB serial number of the device, or an empty string if not available.
+        """
+        return self.device.serial_number
+
     @property
     def set_brightness_on_init(self):
         """
@@ -631,6 +673,9 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
         if not skip_clear:
             self.clear()
 
+    @property
+    def is_animating(self):
+        return self.animating
 
     def jump_to_bootloader(self):
         """
@@ -642,8 +687,21 @@ class LEDMatrixController(Loggable, metaclass=AliasMeta):
         from is_matrix_forge.led_matrix.hardware import bootloader_jump
         bootloader_jump(self.device)
 
-    def list_patterns(self):
-        print(', '.join(self.get_built_in_pattern_names()))
+    def list_patterns(self, skip_print=False):
+        """
+        List the built-in patterns available on the device.
+
+        The primary purpose for this method is to return the pattern names,
+        but also prints them if `skip_print` is set to `False`.
+
+        Parameters:
+            skip_print (bool, optional):
+                If True, don't print the pattern names. (optional, defaults to False).
+        """
+        if not skip_print:
+            print(', '.join(self.built_in_pattern_names))
+
+        return self.built_in_pattern_names
 
     @synchronized
     def set_brightness(self, brightness: Union[int, float], __from_setter=False) -> None:

is_matrix_forge-1.0.0.dev9/is_matrix_forge/led_matrix/controller/helpers/__init__.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import List, Type, Optional
+
+
+def get_controllers(
+    threaded: bool = False,
+    max_workers: Optional[int] = None,
+    controller_cls: Optional[Type] = None,
+    devices: Optional[list] = None,
+    **controller_kwargs
+) -> List['LEDMatrixController']:
+    """
+    Create LEDMatrixController objects, optionally in parallel threads.
+
+    Parameters:
+        threaded (bool): If True, create controllers in threads.
+        max_workers (int, optional): Maximum threads to use (default: len(devices)).
+        controller_cls (Type, optional): Alternate controller class (default: LEDMatrixController).
+        devices (list, optional): Device list (default: imported DEVICES).
+        **controller_kwargs: Additional kwargs for controller class.
+
+    Returns:
+        List[LEDMatrixController]: List of controller instances.
+    """
+    from is_matrix_forge.led_matrix.constants import DEVICES
+    from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+
+    _devices = devices or DEVICES
+    _controller_cls = controller_cls or LEDMatrixController
+    _max_workers = max_workers or len(_devices)
+
+    def create_controller(device):
+        # Here’s where you could add try/except if your hardware is flaky!
+        return _controller_cls(device, 100, thread_safe=True, **controller_kwargs)
+
+    if not threaded:
+        return [create_controller(dev) for dev in _devices]
+
+    with ThreadPoolExecutor(max_workers=_max_workers) as executor:
+        futures = [executor.submit(create_controller, dev) for dev in _devices]
+        controllers = []
+        for fut in as_completed(futures):
+            controllers.append(fut.result())
+        return controllers

is_matrix_forge-1.0.0.dev9/is_matrix_forge/led_matrix/controller/helpers/threading.py

@@ -0,0 +1,67 @@
+import functools
+import threading
+
+from is_matrix_forge.log_engine import ROOT_LOGGER as PARENT_LOGGER
+
+
+def synchronized(method=None, *, pause_breather=True):
+    """
+    Lock & warn if you’re calling off-thread with thread_safe=False.
+    Optionally pause/resume the breather around the method.
+
+    Usage:
+        @synchronized
+        def foo(...): ...
+
+        @synchronized(pause_breather=True)
+        def draw_grid(...): ...
+    """
+    def decorator(method):
+        @functools.wraps(method)
+        def wrapper(self, *args, **kwargs):
+            cur_thread_id = threading.get_ident()
+
+            # ⚠️ misuse detection: warn if another thread calls while thread_safe is False
+            if (
+                not getattr(self, "_thread_safe", False)
+                and getattr(self, "_warn_on_thread_misuse", True)
+                and cur_thread_id != getattr(self, "_owner_thread_id", None)
+            ):
+                PARENT_LOGGER.warning(
+                    "%r called from thread %r but thread_safe=False",
+                    self,
+                    threading.current_thread().name
+                )
+
+            ctx = None
+            if pause_breather:
+                # Try to get the Breather context manager in a robust way
+                breather = getattr(self, "breather", None)
+                if breather is not None and hasattr(breather, "paused"):
+                    ctx = breather.paused
+                else:
+                    # fallback to legacy or alternate pause context
+                    ctx = getattr(self, "breather_paused", None)
+                if ctx is None:
+                    raise RuntimeError(
+                        "Could not find a valid breather pause context. "
+                        "Neither 'breather.paused' nor 'breather_paused' are present on this object."
+                    )
+
+            if ctx is not None:
+                with ctx():
+                    return _run_locked(self, method, *args, **kwargs)
+            else:
+                return _run_locked(self, method, *args, **kwargs)
+
+        return wrapper
+
+    def _run_locked(self, method, *args, **kwargs):
+        # 🔐 actual lock if thread_safe=True
+        if getattr(self, "_thread_safe", False) and getattr(self, "_cmd_lock", None):
+            with self._cmd_lock:
+                return method(self, *args, **kwargs)
+        # fallback: call method directly
+        return method(self, *args, **kwargs)
+
+    return decorator if method is None else decorator(method)

is_matrix_forge-1.0.0.dev9/is_matrix_forge/led_matrix/display/animations/font/font.py

@@ -0,0 +1,2 @@
+class Font:
+    def __init__(self):

is_matrix_forge-1.0.0.dev9/is_matrix_forge/led_matrix/display/assets/__init__.py

@@ -0,0 +1,2 @@
+from is_matrix_forge.led_matrix.display.assets.fonts import FontMap
+from is_matrix_forge.assets.digit_map import DIGITS