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

is_matrix_forge/led_matrix/Scripts/install_presets/arguments.py

@@ -0,0 +1,84 @@
+"""
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/Scripts/install_presets/arguments.py
+
+Description:
+    Holds the Arguments class for the command-line arguments for the preset
+    installer.
+"""
+from argparse import ArgumentParser
+from is_matrix_forge.log_engine import LOG_LEVELS
+from is_matrix_forge.led_matrix.constants import APP_DIRS
+from is_matrix_forge.common.helpers.github_api import REPO_PRESETS_URL
+
+
+class Arguments(ArgumentParser):
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(
+            'LEDMatrixLib:install_presets',
+            description='Download and install premade LED matrix grid design patterns from GitHub.',
+        )
+        self.__parsed = None
+
+        self.__build()
+
+    @property
+    def parsed(self):
+        """
+        Returns the parsed command-line arguments.
+        """
+        if self.__parsed is None:
+            self.parse()
+
+        return self.__parsed
+
+    def __build(self):
+        """
+        Build the command-line arguments.
+        """
+        # Add the `URL` argument
+        self.add_argument(
+            '--url',
+            help='GitHub API URL to download presets from.',
+            default=REPO_PRESETS_URL,
+            action='store'
+        )
+
+        # Add the `app-dir` argument
+        self.add_argument(
+            '--app-dir',
+            help='The directory in which this app can save its files.',
+            default=APP_DIRS.user_data_path,
+            action='store'
+        )
+
+        # Add the `overwrite` argument.
+        self.add_argument(
+            '--overwrite',
+            help='Overwrite existing preset files to be replaced.',
+            action='store_true',
+
+        )
+
+        # Add the `no-progress` argument.
+        self.add_argument(
+            '--no-progress',
+            help='Disable progress bars.',
+            action='store_true'
+        )
+
+    def parse(self):
+        """
+        Parse the command-line arguments.
+
+        Note:
+            Once this method is run, it will define `Arguments.parsed`.
+        """
+        self.__parsed = self.parse_args()

is_matrix_forge/led_matrix/Scripts/install_presets/main.py

@@ -0,0 +1,192 @@
+"""
+Author:
+    Taylor B.
+
+Project:
+    led-matrix-battery
+
+File:
+    is_matrix_forge/led_matrix/Scripts/install_presets/main.py
+
+Description:
+    Provides a CLI to download JSON preset files from the GitHub repository and save them locally,
+    ensuring local files are fresh by verifying and re-downloading if checksums differ.
+
+Classes:
+    - PresetInstaller
+
+Functions:
+    - main
+
+Constants:
+    - API_URL
+    - REQ_HEADERS
+    - REPO_PRESETS_URL
+
+Dependencies:
+    - typing
+    - pathlib
+    - requests
+    - tqdm
+    - inspy_logger
+    - inspyre_toolbox.path_man.provision_path
+    - is_matrix_forge.common.helpers.verify_checksum
+    - is_matrix_forge.led_matrix.constants.PROJECT_URLS, APP_DIRS
+    - is_matrix_forge.common.helpers.github_api.assemble_github_content_path_url
+    - is_matrix_forge.led_matrix.display.grid.presets.manifest.GridPresetManifest
+
+Example Usage:
+    python -m is_matrix_forge.preset_installer \
+        --app-dir /path/to/data \
+        --overwrite \
+        --no-progress
+"""
+import argparse
+from typing import List, Dict, Optional, Union
+from pathlib import Path
+import requests
+import hashlib
+from is_matrix_forge.progress import tqdm
+
+from is_matrix_forge.led_matrix.constants import PROJECT_URLS, APP_DIRS, GITHUB_REQ_HEADERS as REQ_HEADERS
+from is_matrix_forge.led_matrix.display.grid.presets.manifest import GridPresetManifest
+from inspy_logger import InspyLogger, Loggable
+from inspyre_toolbox.path_man import provision_path
+from is_matrix_forge.common.helpers.github_api import assemble_github_content_path_url as assemble_url, REPO_PRESETS_URL
+
+LOGGER = InspyLogger('LEDMatrixLib:PresetInstaller', console_level='info', no_file_logging=True)
+
+API_URL = PROJECT_URLS['github_api']
+REQ_HEADERS = {"Accept": "application/vnd.github.v3+json"}
+
+
+def github_blob_sha(content: bytes) -> str:
+    header = f"blob {len(content)}\0".encode()
+    return hashlib.sha1(header + content).hexdigest()
+
+
+class PresetInstaller(Loggable):
+    def __init__(
+            self,
+            url: str = REPO_PRESETS_URL,
+            headers: Optional[Dict[str, str]] = None,
+            app_dir: Union[str, Path] = APP_DIRS.user_data_path,
+            overwrite_existing: bool = False,
+            with_progress: bool = True
+    ):
+        super().__init__(LOGGER)
+        self.url = url
+        self.headers = headers or REQ_HEADERS
+        self.app_dir = provision_path(app_dir)
+        self.overwrite = overwrite_existing
+        self.with_progress = with_progress
+
+        self.presets_dir = self.app_dir / 'presets'
+        self.presets_dir.mkdir(parents=True, exist_ok=True)
+        self.log = self.class_logger
+
+    def run(self):
+        log = self.method_logger
+        log.debug(f"Fetching file list from {self.url}")
+        files = self.get_file_list()
+        iterator = tqdm(files, desc="Processing files", unit="file") if self.with_progress else files
+
+        for f in iterator:
+            if self._is_json(f):
+                self._process_file(f)
+            else:
+                log.debug(f"Skipping non-JSON file: {f.get('name')}")
+
+        manifest_path = self.presets_dir / "manifest.json"
+        manifest = GridPresetManifest(manifest_path)
+        manifest.scan(self.presets_dir)
+
+    def get_file_list(self) -> List[Dict]:
+        res = requests.get(self.url, headers=self.headers)
+        res.raise_for_status()
+        return res.json()
+
+    @staticmethod
+    def _is_json(file_info: Dict) -> bool:
+        """
+        Upon receipt of file info, verify that it's for a JSON file (has the .json extension).
+        """
+        return file_info.get('type') == 'file' and file_info.get('name', '').endswith('.json')
+
+    def _process_file(self, file_info: Dict):
+        name = file_info['name']
+        local_path = self.presets_dir / name
+
+        res = requests.get(file_info['download_url'])
+        res.raise_for_status()
+        content = res.content
+
+        actual_sha = github_blob_sha(content)
+        expected_sha = file_info['sha']
+
+        if actual_sha != expected_sha:
+            self.log.error(f"GitHub SHA mismatch for {name}")
+            raise ValueError(f"GitHub blob SHA mismatch for {name}")
+
+        self.save_file(local_path, content.decode('utf-8'), overwrite=True)
+
+    def _download_file(self, file_info: Dict, local_path: Path):
+        if self.with_progress:
+            self._download_with_progress(file_info, local_path)
+        else:
+            self._download_simple(file_info, local_path)
+
+    def _download_simple(self, file_info: Dict, local_path: Path):
+        res = requests.get(file_info['download_url'])
+        res.raise_for_status()
+        self.save_file(local_path, res.content.decode('utf-8'), overwrite=True)
+
+    def _download_with_progress(self, file_info: Dict, local_path: Path):
+        url = file_info['download_url']
+        res = requests.get(url, stream=True)
+        res.raise_for_status()
+        total = int(res.headers.get('content-length', 0))
+        bar = tqdm(total=total, unit='B', unit_scale=True, desc=f"Downloading {file_info['name']}", leave=False)
+
+        chunks = []
+        for chunk in res.iter_content(chunk_size=1024):
+            if chunk:
+                chunks.append(chunk)
+                bar.update(len(chunk))
+        bar.close()
+
+        content = b''.join(chunks).decode('utf-8')
+        self.save_file(local_path, content, overwrite=True)
+
+    def save_file(self, path: Path, data: str, overwrite: bool = False):
+        log = self.method_logger
+        path = provision_path(path)
+        if path.exists() and not overwrite:
+            log.warning(f"Skipping existing file {path}")
+            return
+        with open(path, 'w') as f:
+            f.write(data)
+        log.debug(f"Wrote file {path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Install JSON presets from GitHub")
+    parser.add_argument('--url', help="GitHub API URL for presets", default=REPO_PRESETS_URL)
+    parser.add_argument('--app-dir', help="Local directory to save presets", default=str(APP_DIRS.user_data_path))
+    parser.add_argument('--overwrite', help="Overwrite existing files", action='store_true')
+    parser.add_argument('--no-progress', help="Disable progress bars", action='store_false', dest='with_progress')
+
+    args = parser.parse_args()
+
+    installer = PresetInstaller(
+        url=args.url,
+        headers=REQ_HEADERS,
+        app_dir=args.app_dir,
+        overwrite_existing=args.overwrite,
+        with_progress=args.with_progress
+    )
+    installer.run()
+
+
+if __name__ == '__main__':
+    main()

is_matrix_forge/led_matrix/__init__.py

@@ -0,0 +1,7 @@
+
+
+def get_controllers():
+    from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+    from is_matrix_forge.led_matrix.constants import DEVICES
+
+    return [LEDMatrixController(device, 100) for device in DEVICES]

is_matrix_forge/led_matrix/commands/__init__.py

@@ -0,0 +1,84 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/commands/__init__.py
+ 
+
+Description:
+    
+
+"""
+from typing import List, Optional, ByteString
+
+import serial
+from serial.tools.list_ports_common import ListPortInfo
+
+from is_matrix_forge.led_matrix.constants import RESPONSE_SIZE, FWK_MAGIC
+from is_matrix_forge.led_matrix.helpers import disconnect_dev
+
+
+def send_command_raw(dev: ListPortInfo, command: List[int], with_response: bool = False, response_size: Optional[int] = None) -> Optional[ByteString]:
+    """
+    Send a command to the device using a new serial connection.
+
+    Args:
+        dev (ListPortInfo): The device to send the command to.
+        command (List[int]): The command to send.
+        with_response (bool, optional): Whether to wait for a response from the device. Defaults to False.
+        response_size (Optional[int], optional): The size of the response to expect. Defaults to None.
+
+    Returns:
+        Optional[ByteString]: The response from the device, if any, or None if no response or an error occurred.
+
+    Raises:
+        IOError, OSError: If there is an error communicating with the device.
+    """
+    # print(f"Sending command: {command}")
+    res_size = response_size or RESPONSE_SIZE
+    try:
+        with serial.Serial(dev.device, 115200) as s:
+            s.write(command)
+
+            return s.read(res_size) if with_response else None
+    except (IOError, OSError) as _ex:
+        disconnect_dev(dev.device)
+        return None
+        # print("Error: ", ex)
+
+
+def send_command(
+        dev:           ListPortInfo,
+        command:       int,
+        parameters:    Optional[List[int]] = None,
+        with_response: bool                = False
+) -> Optional[ByteString]:
+    """
+    Send a command to the device using a new serial connection.
+
+    Parameters:
+        dev (ListPortInfo):
+            The device to send the command to.
+
+        command (int):
+            The command to send.
+
+        parameters (Optional[List[int]], optional):
+            The parameters to send with the command. Defaults to None.
+
+        with_response (bool, optional):
+            Whether to wait for a response from the device. Defaults to False.
+
+    Returns:
+        Optional[ByteString]:
+            The response from the device, if any, or None if no response or an error occurred.
+    """
+    if parameters is None:
+        parameters = []
+    return send_command_raw(dev, FWK_MAGIC + [command] + parameters, with_response)

is_matrix_forge/led_matrix/commands/map.py

@@ -0,0 +1,46 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    ${DIR_PATH}/${FILE_NAME}
+ 
+
+Description:
+    $DESCRIPTION
+
+"""
+from enum import IntEnum
+
+
+class CommandVals(IntEnum):
+    Brightness = 0x00
+    Pattern = 0x01
+    BootloaderReset = 0x02
+    Sleep = 0x03
+    Animate = 0x04
+    Panic = 0x05
+    Draw = 0x06
+    StageGreyCol = 0x07
+    DrawGreyColBuffer = 0x08
+    SetText = 0x09
+    StartGame = 0x10
+    GameControl = 0x11
+    GameStatus = 0x12
+    SetColor = 0x13
+    DisplayOn = 0x14
+    InvertScreen = 0x15
+    SetPixelColumn = 0x16
+    FlushFramebuffer = 0x17
+    ClearRam = 0x18
+    ScreenSaver = 0x19
+    SetFps = 0x1A
+    SetPowerMode = 0x1B
+    PwmFreq = 0x1E
+    DebugMode = 0x1F
+    Version = 0x20

is_matrix_forge/led_matrix/constants.py

@@ -0,0 +1,82 @@
+"""
+Constants for the LED Matrix Battery Monitor.
+
+This module defines various constants used throughout the application, including:
+- Serial communication settings (baudrate, response size)
+- Hardware identifiers (magic numbers, product ID, vendor ID)
+- Matrix dimensions (height, width)
+- Grayscale conversion constants for different input sources
+- Physical slot mapping for device locations
+- Project URLs for external resources
+"""
+from is_matrix_forge.common.dirs import PRESETS_DIR
+
+# Hardware identifiers
+FWK_MAGIC = [0x32, 0xAC]
+PID       = 0x20
+SN_PREFIX = 'FRAK'
+VID       = 0x32AC
+
+# Serial configuration
+DEFAULT_BAUDRATE = 115_200
+RESPONSE_SIZE    = 32
+
+# Disconnected device placeholder
+DISCONNECTED_DEVS = []
+
+
+# Matrix dimensions
+HEIGHT = 34
+WIDTH  = 9
+
+# Project URLs
+PROJECT_URLS = {
+    'github_api': 'https://api.github.com/repos/Inspyre-Softworks/led-matrix-battery/contents'
+}
+
+GITHUB_REQ_HEADERS = {"Accept": "application/vnd.github.v3+json"}
+
+
+# Physical slot mapping
+SLOT_MAP = {
+    '1-3.2': {'abbrev': 'R1', 'side': 'right', 'slot': 1},
+    '1-3.3': {'abbrev': 'R2', 'side': 'right', 'slot': 2},
+    '1-4.2': {'abbrev': 'L1', 'side': 'left',  'slot': 1},
+    '1-4.3': {'abbrev': 'L2', 'side': 'left',  'slot': 2},
+}
+
+
+from cv2 import COLOR_BGR2GRAY, COLOR_RGB2GRAY
+from is_matrix_forge.led_matrix.helpers.device import DEVICES
+from is_matrix_forge.common.dirs import APP_DIRS
+from is_matrix_forge.dev_tools.presets import MANIFEST_FILE_NAME
+
+MANIFEST_FILE_PATH = PRESETS_DIR.joinpath(MANIFEST_FILE_NAME)
+
+# Grayscale conversion constants
+GRAYSCALE_CVT = {
+    'camera': COLOR_BGR2GRAY,
+    'video': COLOR_RGB2GRAY,
+}
+
+
+# Cleanup
+del COLOR_BGR2GRAY, COLOR_RGB2GRAY
+
+__all__ = [
+    'APP_DIRS',
+    'DEFAULT_BAUDRATE',
+    'DEVICES',
+    'DISCONNECTED_DEVS',
+    'FWK_MAGIC',
+    'GITHUB_REQ_HEADERS',
+    'GRAYSCALE_CVT',
+    'HEIGHT',
+    'PID',
+    'PROJECT_URLS',
+    'RESPONSE_SIZE',
+    'SN_PREFIX',
+    'SLOT_MAP',
+    'VID',
+    'WIDTH',
+]

is_matrix_forge/led_matrix/controller/__init__.py

@@ -0,0 +1,26 @@
+"""
+LED Matrix Controller Module.
+
+This module provides the main controller class for interacting with LED matrix devices.
+It handles device communication, animation control, pattern display, and other
+operations related to the LED matrix hardware.
+"""
+
+from __future__ import annotations
+
+# Standard library
+from typing import Optional
+
+# Third‑party
+
+# Inspyre‑Softworks
+
+from .multiton import MultitonMeta
+from is_matrix_forge.led_matrix.constants import HEIGHT, WIDTH
+
+from is_matrix_forge.led_matrix.display.grid.grid import Grid
+from .helpers.threading import synchronized
+
+
+def generate_blank_grid(width: Optional[int] = None, height: Optional[int] = None) -> Grid:
+    return Grid.load_blank_grid(width=width or WIDTH, height=height or HEIGHT)