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

is_matrix_forge/led_matrix/helpers/device.py

@@ -0,0 +1,118 @@
+"""
+Device helper functions for LED matrix hardware.
+
+This module provides utility functions for working with LED matrix devices,
+including functions to convert between different device location formats.
+"""
+from serial import Serial, SerialException
+from serial.tools import list_ports
+from is_matrix_forge.log_engine import ROOT_LOGGER
+
+
+MOD_LOGGER = ROOT_LOGGER.get_child('led_matrix.helpers.device')
+
+
+def serial_loc_to_physical(dev):
+    """
+    Convert the serial location of a device to its physical location.
+
+    Parameters:
+        dev (ListPortInfo):
+            The device to convert.
+
+    Returns:
+        str:
+            The physical location of the device.
+    """
+    return dev.device
+
+
+def device_available(device):
+    """
+    Check if a device is available.
+
+    Parameters:
+        device:
+            The device to check.
+
+    Returns:
+        bool:
+            True if the device is available, False otherwise.
+
+    """
+    log = MOD_LOGGER.get_child('device_available')
+    log.debug(f'Checking if device is available: {device}...')
+
+    if not check_device(device):
+        log.warning(f'Device {device} failed check, thus not available.')
+        return False
+    else:
+        log.debug(f'Device {device} is available.')
+        return True
+
+
+def check_device(device):
+
+    from serial.tools.list_ports_common import ListPortInfo
+
+    log = MOD_LOGGER.get_child('check_device')
+    log.debug(f'Checking device: {device}...')
+
+    if not isinstance(device, ListPortInfo):
+        emsg = f'device must be of type `ListPortInfo`, not {type(device)}'
+        log.error(emsg)
+        raise TypeError(emsg)
+
+    # Both the vendor and product ID must match to be supported
+    if device.vid != EXPECTED_VID or device.pid != EXPECTED_PID:
+        log.warning(
+            f'Given device is not supported. (VID: {device.vid}, PID: {device.pid})'
+        )
+        return False
+
+    return bool(test_connection(device.device))
+
+
+def get_devices():
+    log = MOD_LOGGER.get_child('get_devices')
+
+    log.debug('Getting devices...')
+
+    ports = list_ports.comports()
+
+    log.debug(f'Found {len(ports)} devices.')
+    log.debug('Filtering and returning devices...')
+    return [
+        port for port in ports if port.vid == 0x32AC and port.pid == 0x20
+    ]
+
+
+def test_connection(port_name):
+    """
+    Test the connection to a given port.
+
+    Parameters:
+        port_name (str):
+            The name of the port to test the: connection to.
+
+    Returns:
+
+    """
+    log = MOD_LOGGER.get_child('test_connection')
+    log.debug(f'Testing connection to {port_name}...')
+
+    try:
+        with Serial(port_name, 115200) as s:
+            s.write(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+            s.flush()
+            log.debug('Connection test successful.')
+            return True
+    except SerialException:
+        log.debug('Connection test failed.')
+        return False
+
+
+DEVICES = get_devices()
+
+if len(DEVICES) == 0:
+    MOD_LOGGER.warning('No devices found. Please connect a device and try again.')

is_matrix_forge/led_matrix/helpers/status_handler.py

@@ -0,0 +1,14 @@
+# led_matrix_lib/status_handler.py
+
+
+_status = None
+
+
+def set_status(new_status):
+
+    global _status
+    _status = new_status
+
+
+def get_status():
+    return _status

is_matrix_forge/led_matrix/helpers/stream/__init__.py

@@ -0,0 +1,70 @@
+import cv2
+from serial import Serial, SerialException
+
+from is_matrix_forge.led_matrix.constants import *
+from is_matrix_forge.led_matrix.helpers.status_handler import get_status
+from is_matrix_forge.led_matrix import send_col
+
+from .errors import *
+from ...errors.matrix import MatrixConnectionError, MatrixInUseError
+
+
+def play_stream(dev, capture, mode: str) -> None:
+    """
+    Core routine for piping frames to the LED matrix via serial.
+
+    Parameters:
+        dev (`serial.tools.list_ports_common.ListPortInfo`):
+            The serial port descriptor returned by `serial.tools.list_ports`.
+
+        capture (`cv2.VideoCapture`):
+            An already-opened OpenCV capture object.
+
+        mode ({'camera', 'video'}):
+            Identifies the status flag and grayscale conversion table entry.
+
+    Returns:
+        None
+
+    Raises:
+        RuntimeError:
+            If the serial port is not open.
+    """
+    try:
+        with Serial(dev.device, DEFAULT_BAUDRATE) as s:
+
+            ok, first_frame = capture.read()
+
+            if not ok:
+                raise StreamSourceUnreadableError()
+    except SerialException as e:
+        raise MatrixInUseError from e
+
+    # ── Calculate scaling and crop once based on the first frame ───────
+    scale_y = HEIGHT / first_frame.shape[0]
+    scaled_w = int(round(first_frame.shape[1] * scale_y))
+    start_x = max(0, int(round(scaled_w / 2 - WIDTH / 2)))
+    end_x = min(scaled_w, start_x + WIDTH)
+    dim = (HEIGHT, scaled_w)
+
+    # ── Main pump loop ────────────────────────────────────────────────
+    while get_status() == mode:
+        ok, frame = capture.read()
+        if not ok:
+            break
+
+        gray     = cv2.cvtColor(frame, __GRAYSCALE_CVT[mode])
+        resized  = cv2.resize(gray, dim)
+        cropped  = resized[0:HEIGHT, start_x:end_x]
+
+        # Stream one column at a time
+        for x in range(cropped.shape[1]):
+            send_col(
+                dev,
+                s,
+                x,
+                [cropped[y, x] for y in range(HEIGHT)]
+            )
+        commit_cols(dev, s)
+
+    capture.release()

is_matrix_forge/led_matrix/helpers/stream/errors.py

@@ -0,0 +1,17 @@
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class MatrixStreamError(CustomRootException):
+    default_message= 'An error occurred while streaming to the LED matrix!'
+
+    def __init__(self, message=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 StreamSourceUnreadableError(MatrixStreamError):
+    def __init__(self):
+        super().__init__('The source is not readable.')

is_matrix_forge/led_matrix/led_matrix.py

@@ -0,0 +1,25 @@
+"""
+LED Matrix Module.
+
+This module provides a high-level interface for interacting with LED matrix devices.
+It combines functionality from various modules to provide a simple API for controlling
+LED matrices, displaying patterns, animations, and battery status.
+"""
+
+from __future__ import annotations
+
+# Standard library
+from pathlib import Path
+from typing import Optional, Union, List
+
+# Third-party
+from serial.tools.list_ports_common import ListPortInfo
+
+# Inspyre-Softworks
+from is_matrix_forge.led_matrix.display.grid import Grid, generate_blank_grid
+from is_matrix_forge.led_matrix.display.animations import goodbye_animation
+from is_matrix_forge.led_matrix.helpers.device import get_devices
+from is_matrix_forge.common.helpers import percentage_to_value
+
+
+

is_matrix_forge/led_matrix/status.py

@@ -0,0 +1,8 @@
+"""
+Author: Taylor B. tayjaybabee@gmail.com
+Date: 2025-05-09 23:20:37
+LastEditors: Taylor B. tayjaybabee@gmail.com
+LastEditTime: 2025-05-09 23:24:58
+FilePath: is_matrix_forge/led_matrix/status.py
+Description: 这是默认设置,可以在设置》工具》File Description中进行配置
+"""

is_matrix_forge/led_matrix/tools/__init__.py

@@ -0,0 +1,8 @@
+"""
+Author: Taylor B. tayjaybabee@gmail.com
+Date: 2025-05-12 22:17:04
+LastEditors: Taylor B. tayjaybabee@gmail.com
+LastEditTime: 2025-05-12 22:17:28
+FilePath: is_matrix_forge/led_matrix/tools/__init__.py
+Description: 这是默认设置,可以在设置》工具》File Description中进行配置
+"""

is_matrix_forge/led_matrix/tools/identify.py

@@ -0,0 +1,27 @@
+from is_matrix_forge.led_matrix import LEDMatrixController
+from is_matrix_forge.led_matrix.helpers.device import DEVICES
+from threading import Thread
+
+
+threads = []
+
+
+def identify_devices(devices=None):
+    global threads
+
+    if devices is None:
+        devices = DEVICES
+
+    controllers = []
+
+    for device in devices:
+        controllers.append(LEDMatrixController(device, 100))
+
+    for controller in controllers:
+        t = Thread(target=controller.identify)
+        threads.append(t)
+        t.start()
+
+
+if __name__ == "__main__":
+    identify_devices()

is_matrix_forge/led_matrix/utils/__init__.py

@@ -0,0 +1,41 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/utils/__init__.py
+ 
+
+Description:
+    
+
+"""
+import serial
+
+from is_matrix_forge.led_matrix import RESPONSE_SIZE, disconnect_dev, FWK_MAGIC
+
+
+def send_command_raw(dev, command, with_response=False):
+    """Send a command to the device.
+    Opens new serial connection every time"""
+    # print(f"Sending command: {command}")
+    try:
+        with serial.Serial(dev.device, 115200) as s:
+            s.write(command)
+
+            if with_response:
+                res = s.read(RESPONSE_SIZE)
+                # print(f"Received: {res}")
+                return res
+    except (IOError, OSError) as _ex:
+        disconnect_dev(dev.device)
+        # print("Error: ", ex)
+
+
+def send_command(dev, command, parameters=[], with_response=False):
+    return send_command_raw(dev, FWK_MAGIC + [command] + parameters, with_response)

is_matrix_forge/log_engine.py

@@ -0,0 +1,25 @@
+from inspy_logger import InspyLogger, Loggable
+from inspy_logger.constants import LEVEL_MAP
+
+
+LOG_LEVELS = [level for level in LEVEL_MAP.keys()]
+
+del LEVEL_MAP
+
+PROGNAME = 'LEDMatrixBattery'
+AUTHOR = 'Inspyre-Softworks'
+
+INSPY_LOG_LEVEL = 'INFO'
+
+ROOT_LOGGER = InspyLogger(PROGNAME, console_level='info', no_file_logging=True)
+
+
+__all__ = [
+    'AUTHOR',
+    'INSPY_LOG_LEVEL',
+    'Loggable',
+    'LOG_LEVELS',
+    'PROGNAME',
+    'ROOT_LOGGER',
+]
+

is_matrix_forge/monitor/__init__.py

@@ -0,0 +1,68 @@
+"""
+File: monitor.py
+Author: Inspyre-Softworks
+Description:
+    This file contains the PowerMonitor class, which is used to monitor the battery level of the system.
+"""
+# Standard library imports
+from pathlib import Path
+from threading import Thread
+from typing import Union, Optional
+
+# Third-party imports
+from serial.tools.list_ports_common import ListPortInfo
+
+# Inspyre-Softworks imports
+from easy_exit_calls import ExitCallHandler
+
+# Package imports
+from .errors import *
+from .helpers import get_plugged_status
+from is_matrix_forge.log_engine import ROOT_LOGGER as PARENT_LOGGER
+from is_matrix_forge.notify.sounds import PLUGGED_NOTIFY, UNPLUGGED_NOTIFY
+
+
+DEFAULT_PLUGGED_SOUND   = PLUGGED_NOTIFY
+DEFAULT_UNPLUGGED_SOUND = UNPLUGGED_NOTIFY
+
+ECH = ExitCallHandler()
+
+MOD_LOGGER = PARENT_LOGGER.get_child('monitor')
+
+
+def run_power_monitor(
+        device:                 ListPortInfo,
+        battery_check_interval: int = 5,
+        plugged_alert:          Optional[Union[str, Path]] = DEFAULT_PLUGGED_SOUND,
+        unplugged_alert:        Optional[Union[str, Path]] = DEFAULT_UNPLUGGED_SOUND,
+):
+    """
+    Run the power monitor.
+
+    Parameters:
+        device (ListPortInfo):
+            The LED matrix on which to display the battery level.
+
+        battery_check_interval (Optional[Union[int, float, str]]):
+            The interval (in seconds) at which to check the battery level.
+
+        plugged_alert (Optional[Union[str, Path]]):
+            The filepath to the sound to play when the device is plugged into power.
+
+        unplugged_alert (Optional[Union[str, Path]]):
+            The filepath to the sound to play when the device is unplugged from power.
+
+    """
+    monitor = PowerMonitor(
+        device,
+        battery_check_interval=battery_check_interval,
+        plugged_alert=plugged_alert,
+        unplugged_alert=unplugged_alert
+    )
+
+    try:
+        monitor.start()
+    except KeyboardInterrupt:
+        monitor.stop(without_salutation=True)
+
+    return monitor

is_matrix_forge/monitor/errors.py

@@ -0,0 +1,35 @@
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class PowerMonitorError(CustomRootException):
+    """
+    Base class for all PowerMonitor errors.
+
+    Class Attributes:
+        default_message (str): Read-Only. The default message for the error.
+    """
+    default_message = 'An error occurred while monitoring the battery!'
+
+
+class PowerMonitorNotRunningError(PowerMonitorError):
+    """
+    Raised when a method is called on a PowerMonitor instance that is not running, but should be to perform the action.
+    """
+    def __init__(self, message = None):
+        msg = 'The PowerMonitor is not running, can not perform action on a non-running instance!'
+        if message is not None:
+            msg += f'\n\nAdditional information from caller: {message}'
+
+        super().__init__(msg)
+
+
+class BatteryStateUnknownError(PowerMonitorError):
+    """
+    Raised when the state of the battery cannot be determined.
+    """
+    def __init__(self, message = None):
+        msg = 'The state of the battery cannot be determined!'
+        if message is not None:
+            msg += f'\n\nAdditional information from caller: {message}'
+
+        super().__init__(msg)

is_matrix_forge/monitor/events.py

@@ -0,0 +1,78 @@
+from is_matrix_forge.log_engine import ROOT_LOGGER
+from is_matrix_forge.monitor.monitor import PowerMonitor
+from is_matrix_forge.monitor.helpers import get_battery_percentage
+
+MOD_LOGGER = ROOT_LOGGER.get_child('monitor.events')
+
+
+def event_to_bool(event: str) -> bool:
+    """
+    Converts an event to a boolean.
+
+    Parameters:
+        event:
+            The string representation of the event to convert.
+
+    Returns:
+        bool:
+            The converted boolean value.
+
+    Raises:
+        ValueError:
+            If the event is not a valid boolean value.
+
+    Examples:
+        >>> event_to_bool('true')
+        True
+        >>> event_to_bool('false')
+        False
+        >>> event_to_bool('invalid')
+        Traceback (most recent call last):
+            ...
+        ValueError: invalid is not a valid boolean value.
+    """
+    event = event.lower().strip()
+
+    if event in ['on', 'true', 'plugged']:
+        return True
+    elif event in ['off', 'false', 'unplugged']:
+        return False
+    else:
+        raise ValueError(f'{event} is not a valid boolean value.')
+
+
+def __handle_device_plugged_in(power_monitor):
+    pm = power_monitor
+    if pm.plugged_in and not pm.controller.is_animating and (not pm.last_state or pm.last_state is None):
+        pm.notify('plugged')
+        pm.controller.clear()
+        pm._last_state = True
+
+
+def __handle_device_unplugged(power_monitor):
+    pm = power_monitor
+    if pm.unplugged and not pm.controller.is_animating and (pm.last_state or pm.last_state is None):
+        pm.notify('unplugged')
+        pm.controller.clear()
+        pm._last_state = False
+
+    pm.controller.draw_percentage(get_battery_percentage())
+
+
+def handle_event(event: str, power_monitor: PowerMonitor):
+    log = MOD_LOGGER.get_child('handle_event')
+    log.debug(f'Handling {event}...')
+
+    #if not isinstance(power_monitor, PowerMonitor):
+    #    raise TypeError(f'{power_monitor} is not a PowerMonitor instance.')
+    #else:
+    #   log.debug(f'{power_monitor} is a PowerMonitor instance.')
+
+    event = event_to_bool(event)
+
+    pm = power_monitor
+
+    if event:
+        __handle_device_plugged_in(pm)
+    else:
+        __handle_device_unplugged(pm)

is_matrix_forge/monitor/gui/errors.py

@@ -0,0 +1,35 @@
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class PowerMonitorGUIError(CustomRootException):
+    """
+    Base class for all PowerMonitor GUI errors.
+
+    Class Attributes:
+        default_message (str): Read-Only. The default message for the error.
+    """
+    default_message = 'An error occurred with the PowerMonitor GUI!'
+
+
+class MalformedWindowError(PowerMonitorGUIError):
+    """
+    Raised when a window is malformed or not properly initialized.
+
+    Class Attributes:
+        default_message (str): Read-Only. The default message for the error.
+    """
+    default_message = 'Window is malformed or not properly initialized!'
+
+    def __init__(self, message: str = None, **kwargs) -> None:
+        """
+        Initializes the MalformedWindowError.
+
+        Parameters:
+            message (Optional[str]):
+                The error message to be displayed. If None, uses the default message.
+        """
+        if message is not None:
+            self.default_message = f"{self.default_message}\n\n  Additional information from caller:\n    {message}"
+
+        super().__init__(message=self.default_message, **kwargs)
+

is_matrix_forge/monitor/gui/event/__init__.py

@@ -0,0 +1,8 @@
+from .event import Event
+from .collection import EventCollection
+
+
+__all__ = [
+    'Event',
+    'EventCollection'
+]