kmtronic-usb-relay 25.0.0__py3-none-any.whl

kmtronic_usb_relay/com_utils.py

@@ -0,0 +1,303 @@
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+import serial
+import serial.tools.list_ports
+
+logger = logging.getLogger(__name__)
+
+class SerialComUtils:
+    """
+    User-friendly utility class for serial COM port communication.
+
+    This class provides methods for discovering available serial ports,
+    connecting/disconnecting to a port, and sending/receiving data.
+    It also supports context management for safe resource handling.
+    """
+
+    # --- Initialization and Configuration ---
+
+    def __init__(
+        self,
+        baudrate: int = 9600,
+        bytesize: int = serial.EIGHTBITS,
+        stopbits: int = serial.STOPBITS_ONE,
+        parity: str = serial.PARITY_NONE,
+        timeout: Optional[float] = 2.5,
+    ):
+        """
+        Initialize SerialComUtils with serial parameters.
+
+        Args:
+            baudrate (int): Serial baudrate (default: 9600).
+            bytesize (int): Number of data bits (default: serial.EIGHTBITS).
+            stopbits (int): Number of stop bits (default: serial.STOPBITS_ONE).
+            parity (str): Parity setting (default: serial.PARITY_NONE).
+            timeout (float, optional): Read timeout in seconds, or None for blocking mode (default: 2.5).
+        """
+        self.connection: Optional[serial.Serial] = None
+        self.baudrate = baudrate
+        self.bytesize = bytesize
+        self.stopbits = stopbits
+        self.parity = parity
+        self.timeout = timeout
+
+    def get_connection_params(self) -> Dict[str, Any]:
+        """
+        Get the current serial connection parameters.
+
+        Returns:
+            dict: Dictionary containing baudrate, bytesize, stopbits, parity, and timeout.
+        """
+        return {
+            "baudrate": self.baudrate,
+            "bytesize": self.bytesize,
+            "stopbits": self.stopbits,
+            "parity": self.parity,
+            "timeout": self.timeout,
+        }
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the SerialComUtils instance.
+
+        Returns:
+            str: Human-readable summary of the current configuration and port.
+        """
+        port = self.connection.port if self.connection and self.connection.is_open else None
+        return (
+            f"<SerialComUtils(port={port}, baudrate={self.baudrate}, "
+            f"bytesize={self.bytesize}, stopbits={self.stopbits}, "
+            f"parity={self.parity}, timeout={self.timeout})>"
+        )
+
+    # --- Port Discovery and Info ---
+
+    @staticmethod
+    def get_port_names() -> List[str]:
+        """
+        List all available COM port device names.
+
+        Returns:
+            List[str]: List of device names (e.g., ['COM1', 'COM2']).
+        """
+        return [port.device for port in serial.tools.list_ports.comports()]
+
+    @staticmethod
+    def get_port_details() -> List[Dict[str, Any]]:
+        """
+        Get details of all available COM ports.
+
+        Returns:
+            List[dict]: Each dict contains:
+                - device (str): COM port number (e.g., 'COM1')
+                - description (str): Port description
+                - hwid (str): Hardware ID
+        """
+        return [
+            {
+                "device": port.device,
+                "description": port.description,
+                "hwid": port.hwid
+            }
+            for port in serial.tools.list_ports.comports()
+        ]
+
+    @staticmethod
+    def format_port_detail(port_info: Dict[str, Any]) -> str:
+        """
+        Format a port info dictionary as a readable string.
+
+        Args:
+            port_info (dict): Dictionary with keys 'device', 'description', 'hwid'.
+
+        Returns:
+            str: Formatted string describing the port.
+        """
+        return (
+            f"Device: {port_info['device']}, "
+            f"Description: {port_info['description']}, "
+            f"HWID: {port_info['hwid']}"
+        )
+
+    @staticmethod
+    def log_port_details(port_name: Optional[str] = None) -> None:
+        """
+        Log details of all COM ports or a specific port if port_name is given.
+
+        Args:
+            port_name (str, optional): Device name of the port (e.g., 'COM3').
+        """
+        ports = SerialComUtils.get_port_details()
+        if port_name:
+            for port in ports:
+                if port["device"] == port_name:
+                    logger.info(SerialComUtils.format_port_detail(port))
+                    return
+            logger.warning(f"Port {port_name} not found.")
+        else:
+            for port in ports:
+                logger.info(SerialComUtils.format_port_detail(port))
+
+    @staticmethod
+    def get_busy_ports() -> List[str]:
+        """
+        Attempt to list COM ports that are currently in use (best effort).
+
+        Returns:
+            List[str]: List of port device names that are in use.
+        """
+        busy_ports = []
+        for port in SerialComUtils.get_port_names():
+            try:
+                with serial.Serial(port) as s:
+                    pass
+            except (OSError, serial.SerialException):
+                busy_ports.append(port)
+        return busy_ports
+
+    # --- Connection Management ---
+
+    @property
+    def is_connected(self) -> bool:
+        """
+        Check if the serial connection is open.
+
+        Returns:
+            bool: True if connected, False otherwise.
+        """
+        return self.connection is not None and self.connection.is_open
+
+    def connect(self, port: str) -> bool:
+        """
+        Open a connection to a COM port with the configured parameters.
+
+        Args:
+            port (str): Device name of the port (e.g., 'COM3').
+
+        Returns:
+            bool: True if connection was successful, False otherwise.
+        """
+        try:
+            self.connection = serial.Serial(
+                port=port,
+                baudrate=self.baudrate,
+                bytesize=self.bytesize,
+                stopbits=self.stopbits,
+                parity=self.parity,
+                timeout=self.timeout
+            )
+            logger.info(f"Connected to {port}")
+            return True
+        except serial.SerialException as e:
+            logger.error(f"Failed to connect to {port}: {e}")
+            self.connection = None
+            return False
+
+    def open_connection(self, port: str) -> bool:
+        """
+        Alias for connect. Opens a connection to the specified port.
+
+        Args:
+            port (str): Device name of the port.
+
+        Returns:
+            bool: True if connection was successful, False otherwise.
+        """
+        return self.connect(port)
+
+    def disconnect(self) -> bool:
+        """
+        Alias for close_connection. Closes the serial connection.
+
+        Returns:
+            bool: True if disconnected or already closed, False if error occurred.
+        """
+        return self.close_connection()
+
+    def close_connection(self) -> bool:
+        """
+        Close the connection to the COM port.
+
+        Returns:
+            bool: True if disconnected or already closed, False if error occurred.
+        """
+        if self.connection and self.connection.is_open:
+            try:
+                self.connection.close()
+                logger.info("Disconnected.")
+                self.connection = None
+                return True
+            except Exception as e:
+                logger.error(f"Error while disconnecting: {e}")
+                return False
+        self.connection = None
+        return True
+
+    # --- Data Transfer ---
+
+    def send(self, data: bytes) -> bool:
+        """
+        Send data to the serial port.
+
+        Args:
+            data (bytes): Bytes to send.
+
+        Returns:
+            bool: True if sent, False if not connected.
+        """
+        if self.is_connected:
+            self.connection.write(data)
+            return True
+        else:
+            logger.warning("No open connection. Cannot send data.")
+            return False
+
+    def receive(self, size: int = 1, as_int_list: bool = False) -> Optional[Union[bytes, List[int]]]:
+        """
+        Receive data from the serial port.
+
+        Args:
+            size (int): Number of bytes to read (default: 1).
+            as_int_list (bool): If True, return a list of ints instead of bytes.
+
+        Returns:
+            bytes or List[int] or None: Received data, or None if not connected.
+        """
+        if self.is_connected:
+            data = self.connection.read(size)
+            if as_int_list:
+                return list(data)
+            return data
+        else:
+            logger.warning("No open connection. Cannot receive data.")
+            return None
+
+    # --- Context Management ---
+
+    def __enter__(self) -> "SerialComUtils":
+        """
+        Enter the runtime context related to this object.
+
+        Returns:
+            SerialComUtils: The instance itself.
+        """
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[object],
+    ) -> None:
+        """
+        Exit the runtime context and close the serial connection.
+
+        Args:
+            exc_type: Exception type.
+            exc_val: Exception value.
+            exc_tb: Exception traceback.
+        """
+        self.close_connection()
+
+

kmtronic_usb_relay/four_channel_relay.py

@@ -0,0 +1,229 @@
+import logging
+import time
+from typing import Dict, List, Optional
+
+from kmtronic_usb_relay.com_utils import SerialComUtils
+
+logger = logging.getLogger(__name__)
+
+class RelayController:
+    """Controller for KMTronic 4-Channel USB Relay devices.
+
+    Example:
+        with RelayController("COM4") as relay:
+            relay.turn_on(1)
+            relay.turn_off(2)
+            print(relay.statuses)
+    """
+
+    RELAY_COUNT = 4
+    STATUS_ON = "ON"
+    STATUS_OFF = "OFF"
+
+    def __init__(
+        self,
+        com_port: str,
+        switch_delay: float = 1.0,
+        serial_utils: Optional[SerialComUtils] = None,
+        auto_connect: bool = True,
+    ):
+        """
+        Initialize the RelayController.
+
+        Args:
+            com_port (str): The COM port to which the relay board is connected (e.g., 'COM4').
+            switch_delay (float): Delay in seconds after switching a relay (default: 1.0).
+            serial_utils (Optional[SerialComUtils]): Custom SerialComUtils instance for testing/mocking.
+            auto_connect (bool): Automatically open connection on init (default: True).
+        """
+        self.com_port = com_port
+        self.switch_delay = switch_delay
+        self.serial_utils = serial_utils or SerialComUtils()
+        self._is_connected = False
+        if auto_connect:
+            self.connect()
+
+    @property
+    def is_connected(self) -> bool:
+        """
+        Check if the relay controller is connected to the COM port.
+
+        Returns:
+            bool: True if connected, False otherwise.
+        """
+        return self.serial_utils.is_connected if self.serial_utils else False
+
+    def connect(self) -> None:
+        """
+        Open the serial connection to the relay board.
+
+        Raises:
+            Exception: If the connection cannot be established.
+        """
+        if not self.is_connected:
+            try:
+                self._is_connected = self.serial_utils.open_connection(self.com_port)
+                logger.info(f"Connected to relay on {self.com_port}")
+            except Exception as e:
+                logger.error(f"Failed to open serial connection on {self.com_port}: {e}")
+                raise
+
+    def close(self) -> None:
+        """
+        Close the serial connection to the relay board.
+
+        This method is safe to call multiple times.
+        """
+        try:
+            result = self.serial_utils.close_connection()
+            self._is_connected = not result
+            logger.info("Serial connection closed.")
+        except Exception as e:
+            logger.warning(f"Error closing serial connection: {e}")
+
+    def turn_on(self, relay_number: int) -> None:
+        """
+        Turn ON the specified relay.
+
+        Args:
+            relay_number (int): Relay number to turn ON (1-4).
+
+        Raises:
+            ValueError: If relay_number is out of range.
+            Exception: If sending the command fails.
+        """
+        self._validate_relay_number(relay_number)
+        self._send_relay_command(relay_number, True)
+
+    def turn_off(self, relay_number: int) -> None:
+        """
+        Turn OFF the specified relay.
+
+        Args:
+            relay_number (int): Relay number to turn OFF (1-4).
+
+        Raises:
+            ValueError: If relay_number is out of range.
+            Exception: If sending the command fails.
+        """
+        self._validate_relay_number(relay_number)
+        self._send_relay_command(relay_number, False)
+
+    @property
+    def statuses(self) -> Dict[str, str]:
+        """
+        Get the status of all relays as a dictionary.
+
+        Returns:
+            Dict[str, str]: Dictionary mapping relay names (e.g., 'R1') to their status ('ON' or 'OFF').
+        """
+        return self.get_statuses()
+
+    def get_statuses(self) -> Dict[str, str]:
+        """
+        Query and return the status of all relays.
+
+        Returns:
+            Dict[str, str]: Dictionary mapping relay names (e.g., 'R1') to their status ('ON' or 'OFF').
+            Returns an empty dict if communication fails.
+        """
+        status_cmd = bytes([0xFF, 0x09, 0x00])
+        try:
+            self.serial_utils.send(status_cmd)
+            response: Optional[List[int]] = self.serial_utils.receive(
+                self.RELAY_COUNT, as_int_list=True
+            )
+        except Exception as e:
+            logger.error(f"Failed to communicate with relay board: {e}")
+            return {}
+
+        if not response or len(response) < self.RELAY_COUNT:
+            logger.error("Failed to read relay status or incomplete response.")
+            return {}
+
+        relay_status = {
+            f"R{i}": self.STATUS_ON if byte == 1 else self.STATUS_OFF
+            for i, byte in enumerate(response, start=1)
+        }
+        logger.info("Relay statuses: %s", ", ".join(f"{k}: {v}" for k, v in relay_status.items()))
+        return relay_status
+
+    def __enter__(self) -> "RelayController":
+        """
+        Enter the runtime context related to this object.
+
+        Returns:
+            RelayController: The connected relay controller instance.
+        """
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[object],
+    ) -> None:
+        """
+        Exit the runtime context and close the serial connection.
+
+        Args:
+            exc_type: Exception type.
+            exc_val: Exception value.
+            exc_tb: Exception traceback.
+        """
+        self.close()
+
+    # --- Internal helpers ---
+
+    def _send_relay_command(self, relay_number: int, turn_on: bool) -> None:
+        """
+        Send a command to turn a relay ON or OFF.
+
+        Args:
+            relay_number (int): Relay number (1-4).
+            turn_on (bool): True to turn ON, False to turn OFF.
+
+        Raises:
+            Exception: If sending the command fails.
+        """
+        cmd = bytes([0xFF, relay_number, 0x01 if turn_on else 0x00])
+        logger.debug(
+            "Sending command: %s to relay %d (%s)",
+            cmd.hex(), relay_number, "ON" if turn_on else "OFF"
+        )
+        try:
+            self.serial_utils.send(cmd)
+            time.sleep(self.switch_delay)
+        except Exception as e:
+            logger.error(f"Failed to send command to relay {relay_number}: {e}")
+            raise
+
+    def _validate_relay_number(self, relay_number: int) -> None:
+        """
+        Validate that the relay number is within the allowed range.
+
+        Args:
+            relay_number (int): Relay number to validate.
+
+        Raises:
+            ValueError: If relay_number is not between 1 and RELAY_COUNT.
+        """
+        if not (1 <= relay_number <= self.RELAY_COUNT):
+            raise ValueError(
+                f"relay_number must be between 1 and {self.RELAY_COUNT}, got {relay_number}."
+            )
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    print("Hello Kmtronic USB Relay User!")
+
+    # Example: Using RelayController directly
+    print("\n--- Example: RelayController ---")
+    try:
+        with RelayController("COM4") as relay:
+            relay.turn_on(1)
+            relay.turn_off(2)
+            print(f"Relay statuses: {relay.statuses}")
+    except Exception as e:
+        print(f"Error: {e}")

kmtronic_usb_relay/four_channel_relay_api.py

@@ -0,0 +1,165 @@
+import os
+import sys
+from typing import Any, Dict, Optional
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Path
+import uvicorn
+
+from kmtronic_usb_relay.four_channel_relay import RelayController
+from kmtronic_usb_relay.com_utils import SerialComUtils
+
+def create_app(com_port: str, controller: Optional[RelayController] = None) -> FastAPI:
+    """
+    Create and configure a FastAPI app for the KMTronic 4-Channel USB Relay.
+
+    Args:
+        com_port: Serial port for the relay board.
+        controller: Optional RelayController instance (for testing/mocking).
+
+    Returns:
+        Configured FastAPI app.
+    """
+    relay_controller = controller or RelayController(com_port)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        relay_controller.close()
+
+    app = FastAPI(title="KMTronic USB Relay API", lifespan=lifespan)
+
+    @app.get("/health", response_model=Dict[str, str])
+    def health_check() -> Dict[str, str]:
+        """Health check endpoint."""
+        return {"status": "ok"}
+
+    @app.get("/", response_model=Dict[str, Any])
+    def root() -> Dict[str, Any]:
+        endpoints = [
+            {"path": route.path, "methods": list(route.methods)}
+            for route in app.routes
+            if hasattr(route, "path") and hasattr(route, "methods")
+        ]
+        return {
+            "message": "KMTronic USB Relay API is running.",
+            "endpoints": endpoints
+        }
+
+    @app.get("/relay/status", response_model=Dict[str, Any])
+    def get_status() -> Dict[str, Any]:
+        """Get the status of all relays."""
+        return relay_controller.get_statuses()
+
+    @app.post("/relay/{relay_number}/on", response_model=Dict[str, Any])
+    def turn_on(
+        relay_number: int = Path(..., ge=1, le=4, description="Relay number (1-4)")
+    ) -> Dict[str, Any]:
+        """Turn ON the specified relay."""
+        try:
+            relay_controller.turn_on(relay_number)
+            return {"result": "Relay turned ON", "relay": relay_number}
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+    @app.post("/relay/{relay_number}/off", response_model=Dict[str, Any])
+    def turn_off(
+        relay_number: int = Path(..., ge=1, le=4, description="Relay number (1-4)")
+    ) -> Dict[str, Any]:
+        """Turn OFF the specified relay."""
+        try:
+            relay_controller.turn_off(relay_number)
+            return {"result": "Relay turned OFF", "relay": relay_number}
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+    return app
+
+def get_app() -> FastAPI:
+    """
+    Get a FastAPI app instance for ASGI servers (e.g., uvicorn).
+    Uses the KMTRONIC_COM_PORT environment variable or defaults to 'COM4'.
+    """
+    com_port = os.getenv("KMTRONIC_COM_PORT", "COM4")
+    return create_app(com_port)
+
+class RelayControllerApi:
+    """
+    User-friendly wrapper to run the FastAPI server for KMTronic USB Relay.
+
+    Example:
+        api = RelayControllerApi("COM4")
+        api.run()
+    """
+
+    def __init__(self, com_port: str = "COM4", controller: Optional[RelayController] = None):
+        """
+        Initialize the API server wrapper.
+
+        Args:
+            com_port: Serial port for the relay board (e.g., "COM4" or "/dev/ttyUSB0").
+            controller: Optional RelayController instance for testing/mocking.
+        """
+        self.app = create_app(com_port, controller)
+
+    def run(self, host: str = "127.0.0.1", port: int = 8000, reload: bool = False) -> None:
+        """
+        Start the FastAPI server using uvicorn.
+
+        Args:
+            host: Hostname or IP address to bind the server.
+            port: Port number to bind the server.
+            reload: Enable auto-reload (for development).
+        """
+        uvicorn.run(self.app, host=host, port=port, reload=reload)
+
+def select_com_port() -> Optional[str]:
+    """
+    Helper to select a COM port interactively if not provided.
+    Returns the selected COM port or None if not available.
+    """
+    ports = SerialComUtils.get_port_names()
+    if not ports:
+        print("No serial COM ports found. Please connect your relay and try again.")
+        return None
+    print("Available COM ports:")
+    for idx, port in enumerate(ports, 1):
+        print(f"  {idx}: {port}")
+    while True:
+        selection = input(f"Select COM port [1-{len(ports)}]: ").strip()
+        if selection.isdigit() and 1 <= int(selection) <= len(ports):
+            return ports[int(selection) - 1]
+        print("Invalid selection. Please try again.")
+
+def main() -> None:
+    """
+    Command-line entry point to run the API server.
+
+    Usage:
+        ``python -m src.kmtronic_usb_relay.four_channel_relay_api [COM_PORT] [--host HOST] [--port PORT] [--reload]``
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Run KMTronic USB Relay API server.")
+    parser.add_argument(
+        "com_port",
+        nargs="?",
+        default=None,
+        help="COM port for relay board (e.g., COM4 or /dev/ttyUSB0)."
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind the server (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8000, help="Port to bind the server (default: 8000)")
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload (for development)")
+    args = parser.parse_args()
+
+    com_port = args.com_port or os.getenv("KMTRONIC_COM_PORT")
+    if not com_port:
+        com_port = select_com_port()
+        if not com_port:
+            sys.exit(1)
+
+    api = RelayControllerApi(com_port)
+    api.run(host=args.host, port=args.port, reload=args.reload)
+
+if __name__ == "__main__":
+    main()

kmtronic_usb_relay/four_channel_relay_gui.py

@@ -0,0 +1,324 @@
+import logging
+import threading
+from typing import List, Optional
+
+import customtkinter as ctk
+import tkinter.messagebox as messagebox
+
+from kmtronic_usb_relay.com_utils import SerialComUtils
+from kmtronic_usb_relay.four_channel_relay import RelayController
+
+class RelayControllerGui:
+    """
+    User-friendly GUI for KMTronic USB 4-channel relay module.
+    Provides an interface to connect, control, and monitor relays.
+    """
+
+    def __init__(
+        self,
+        com_port: str = "",
+        controller: Optional[RelayController] = None,
+        relay_names: Optional[List[str]] = None,
+    ):
+        """
+        Initialize the RelayControllerGui.
+
+        Args:
+            com_port (str): Default COM port to select.
+            controller (Optional[RelayController]): Optional pre-initialized RelayController.
+            relay_names (Optional[List[str]]): Optional list of relay names for labeling buttons.
+        """
+        self.controller = controller
+        self.com_port = com_port
+        self.relay_names = relay_names or [f"Relay {i}" for i in range(1, 5)]
+        ctk.set_appearance_mode("dark")
+        ctk.set_default_color_theme("dark-blue")
+        self.root = ctk.CTk()
+        self.root.title("KMTronic USB Relay Controller")
+        self.root.protocol("WM_DELETE_WINDOW", self.close)
+        self.relay_buttons: List[ctk.CTkButton] = []
+        self.combobox = None
+        self.conn_btn = None
+        self._build_ui()
+        self._update_ui()
+
+    def _build_ui(self):
+        """
+        Build the main UI layout, including port selection, relay controls, and action buttons.
+        """
+        main = ctk.CTkFrame(self.root, fg_color="#23272e")
+        main.pack(padx=1, pady=1, fill="both", expand=True)
+        self._build_port_group(main)
+        self._build_relay_group(main)
+        self._build_action_group(main)
+
+    def _build_port_group(self, parent):
+        """
+        Build the serial port selection group in the UI.
+
+        Args:
+            parent: The parent widget to attach this group to.
+        """
+        port_group = ctk.CTkFrame(parent, border_color="#1976D2", border_width=2, fg_color="#23272e")
+        port_group.pack(fill="x", pady=(0, 4), padx=1, ipady=2, ipadx=2)
+        ctk.CTkLabel(
+            port_group, text="Port:", width=50, anchor="w", text_color="#B0B8C1",
+            font=ctk.CTkFont(size=13, weight="bold")
+        ).grid(row=0, column=0, padx=(4, 1), pady=4, sticky="w")
+        ports = SerialComUtils.get_port_names()
+        self.combobox = ctk.CTkComboBox(
+            port_group, values=ports, width=120, fg_color="#23272e", border_color="#1976D2"
+        )
+        self.combobox.grid(row=0, column=1, padx=1, pady=4, sticky="w")
+        self.combobox.set(self.com_port if self.com_port in ports else (ports[0] if ports else ""))
+        ctk.CTkButton(
+            port_group, text="⟳", width=28, command=self.refresh_ports,
+            fg_color="#23272e", border_color="#1976D2"
+        ).grid(row=0, column=2, padx=1, pady=4)
+        self.conn_btn = ctk.CTkButton(
+            port_group, text="Connect", fg_color="#444c56", hover_color="#1976D2",
+            width=90, command=self._toggle_connection
+        )
+        self.conn_btn.grid(row=0, column=3, padx=(6, 1), pady=4)
+        port_group.grid_columnconfigure(4, weight=1)
+
+    def _build_relay_group(self, parent):
+        """
+        Build the relay control buttons in the UI.
+
+        Args:
+            parent: The parent widget to attach this group to.
+        """
+        relay_group = ctk.CTkFrame(parent, border_color="#388E3C", border_width=2, fg_color="#23272e")
+        relay_group.pack(fill="x", pady=(0, 4), padx=1, ipady=2, ipadx=2)
+        ctk.CTkLabel(
+            relay_group, text="Relay Controls", font=ctk.CTkFont(size=15, weight="bold"),
+            text_color="#A5D6A7"
+        ).pack(anchor="w", padx=4, pady=(4, 6))
+        row = ctk.CTkFrame(relay_group, fg_color="#23272e")
+        row.pack(fill="x", padx=6, pady=(0, 4))
+        for i in range(1, 5):
+            col = ctk.CTkFrame(row, fg_color="#23272e")
+            col.pack(side="left", padx=6, expand=True)
+            relay_label = self.relay_names[i - 1] if i - 1 < len(self.relay_names) else f"Relay {i}"
+            ctk.CTkLabel(
+                col, text=relay_label, width=60, anchor="center", text_color="#B0B8C1",
+                font=ctk.CTkFont(size=12, weight="bold")
+            ).pack(pady=(0, 2))
+            btn = ctk.CTkButton(
+                col, text="OFF", fg_color="#444c56", hover_color="#388E3C", width=70,
+                command=lambda n=i: self._toggle_relay(n)
+            )
+            btn.pack()
+            self.relay_buttons.append(btn)
+
+    def _build_action_group(self, parent):
+        """
+        Build the action buttons group (e.g., Refresh Status) in the UI.
+
+        Args:
+            parent: The parent widget to attach this group to.
+        """
+        btn_frame = ctk.CTkFrame(parent, fg_color="#23272e", border_color="#F57C00", border_width=2)
+        btn_frame.pack(fill="x", pady=(4, 0), padx=1, ipady=2, ipadx=2)
+        ctk.CTkButton(
+            btn_frame, text="Refresh Status", command=self._update_status_labels, width=120,
+            fg_color="#444c56", hover_color="#F57C00", text_color="#FFA726"
+        ).pack(side="right", padx=(0, 4))
+
+    def refresh_ports(self):
+        """
+        Refresh the list of available serial ports and update the port selection combobox.
+        Enables or disables the connect button based on port availability.
+        """
+        ports = SerialComUtils.get_port_names()
+        if self.combobox:
+            self.combobox.configure(values=ports)
+            self.combobox.set(self.com_port if self.com_port in ports else (ports[0] if ports else ""))
+        if self.conn_btn:
+            self.conn_btn.configure(state="normal" if ports else "disabled")
+
+    def _toggle_connection(self):
+        """
+        Handle connect/disconnect button click.
+        Starts a background thread to connect or disconnect from the relay controller.
+        """
+        if self.controller:
+            self._run_in_thread(self._disconnect_threaded)
+        else:
+            if self.conn_btn:
+                self.conn_btn.configure(state="disabled", text="Connecting...")
+            self._run_in_thread(self._connect_threaded)
+
+    def _connect_threaded(self):
+        """
+        Attempt to connect to the relay controller in a background thread.
+        On success, updates the UI and relay status. On failure, shows an error dialog.
+        """
+        port = self.combobox.get() if self.combobox else ""
+        try:
+            if self.controller:
+                self.controller.close()
+                self.controller = None
+            controller = RelayController(port, switch_delay=0.1)
+            statuses = controller.get_statuses()  # <-- FIXED
+            if statuses:
+                self.root.after(0, self._on_connect_success, controller, port)
+            else:
+                raise Exception("Failed to read relay status after connecting.")
+        except Exception as e:
+            logging.error(f"Connection failed: {e}")
+            self.root.after(0, lambda: messagebox.showerror("Connection Error", str(e)))
+            self.root.after(0, self._update_ui)
+        finally:
+            self.root.after(0, self._enable_connect_btn)
+
+    def _disconnect_threaded(self):
+        """
+        Disconnect from the relay controller in a background thread.
+        Updates the UI and enables the connect button after disconnecting.
+        """
+        try:
+            if self.controller:
+                self.controller.close()
+                self.controller = None
+        except Exception as e:
+            logging.error(f"Disconnection failed: {e}")
+            self.root.after(0, lambda: messagebox.showerror("Disconnection Error", str(e)))
+        finally:
+            self.root.after(0, self._update_ui)
+            self.root.after(0, self._enable_connect_btn)
+
+    def _on_connect_success(self, controller: RelayController, port: str):
+        """
+        Callback for successful connection.
+        Sets the controller, updates the UI, and refreshes relay statuses.
+
+        Args:
+            controller (RelayController): The connected relay controller instance.
+            port (str): The COM port used for connection.
+        """
+        self.controller = controller
+        self.com_port = port
+        self._update_ui()
+        self._update_status_labels()
+
+    def _enable_connect_btn(self):
+        """
+        Enable the connect/disconnect button after a connection or disconnection attempt.
+        Updates the button text based on connection state.
+        """
+        if self.conn_btn:
+            self.conn_btn.configure(state="normal", text="Disconnect" if self.controller else "Connect")
+
+    def _toggle_relay(self, relay_number: int):
+        """
+        Toggle the state of a relay in a background thread.
+
+        Args:
+            relay_number (int): The relay number to toggle (1-4).
+        """
+        if self.controller:
+            self._run_in_thread(lambda: self._toggle_relay_worker(relay_number))
+
+    def _toggle_relay_worker(self, relay_number: int):
+        """
+        Worker function to toggle relay state.
+        Reads current status and switches relay ON/OFF accordingly.
+
+        Args:
+            relay_number (int): The relay number to toggle (1-4).
+        """
+        try:
+            statuses = self.controller.get_statuses()
+            relay_key = f"R{relay_number}"
+            if statuses.get(relay_key) == "ON":
+                self.controller.turn_off(relay_number)  # <-- FIXED
+            else:
+                self.controller.turn_on(relay_number)   # <-- FIXED
+        except Exception as e:
+            self.root.after(0, lambda e=e: messagebox.showerror("Relay Error", str(e)))
+        self.root.after(0, self._update_status_labels)
+
+    def _update_status_labels(self):
+        """
+        Update the relay button labels and colors to reflect current relay states.
+        If not connected, sets all buttons to unknown state.
+        """
+        if self.controller:
+            try:
+                statuses = self.controller.get_statuses()  # <-- FIXED
+                for i in range(4):
+                    status = statuses.get(f"R{i+1}", "Unknown")
+                    color = "green" if status == "ON" else "red" if status == "OFF" else "gray"
+                    text = status if status in ("ON", "OFF") else "?"
+                    self.relay_buttons[i].configure(text=text, fg_color=color)
+            except Exception as e:
+                messagebox.showerror("Status Error", str(e))
+                for btn in self.relay_buttons:
+                    btn.configure(text="?", fg_color="gray")
+        else:
+            for btn in self.relay_buttons:
+                btn.configure(text="?", fg_color="gray")
+
+    def _update_ui(self):
+        """
+        Update the UI elements (button states, labels) based on connection state.
+        Disables relay buttons if not connected.
+        """
+        is_connected = self.controller is not None
+        if self.conn_btn:
+            self.conn_btn.configure(
+                text="Disconnect" if is_connected else "Connect",
+                fg_color="green" if is_connected else "gray"
+            )
+        for btn in self.relay_buttons:
+            btn.configure(state="normal" if is_connected else "disabled")
+
+    def _run_in_thread(self, func):
+        """
+        Run a function in a background thread to avoid blocking the UI.
+
+        Args:
+            func (Callable): The function to run in a thread.
+        """
+        threading.Thread(target=func, daemon=True).start()
+
+    def run(self):
+        """
+        Start the GUI main loop. Call this method to launch the application.
+        """
+        try:
+            self.root.mainloop()
+        except Exception as e:
+            print(f"Unexpected error: {e}")
+
+    def close(self):
+        """
+        Close the GUI and release resources.
+        Closes the relay controller connection and destroys the main window.
+        """
+        if self.controller:
+            self.controller.close()
+            self.controller = None
+        if self.root.winfo_exists():
+            self.root.destroy()
+
+    def __del__(self):
+        """
+        Destructor to ensure resources are released when the object is deleted.
+        """
+        try:
+            self.close()
+        except Exception:
+            pass
+
+def main():
+    """
+    Entry point for running the GUI as a standalone application.
+    """
+    print("\n--- KMTronic USB Relay Controller GUI ---")
+    RelayControllerGui().run()
+
+if __name__ == "__main__":
+    main()

kmtronic_usb_relay-25.0.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.3
+Name: kmtronic-usb-relay
+Version: 25.0.0
+Summary: Python library for KMTronic USB Relay
+Keywords: python,KMTronic,USB,relay,app
+Author: chaitu-ycr
+Author-email: chaitu-ycr <chaitu.ycr@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2025 chaitu-ycr
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Dist: pyserial
+Requires-Dist: customtkinter
+Requires-Dist: fastapi[all]
+Requires-Python: >=3.10, <=3.14
+Project-URL: documentation, https://chaitu-ycr.github.io/automotive-test-kit/packages/kmtronic_usb_relay
+Project-URL: homepage, https://github.com/chaitu-ycr/automotive-test-kit
+Project-URL: repository, https://github.com/chaitu-ycr/automotive-test-kit
+Description-Content-Type: text/markdown
+
+# kmtronic_usb_relay
+
+This project is a Python package for controlling KMTronics USB relay boards. It provides a simple interfaces to interact with the relays, allowing you to turn them on and off programmatically.
+
+It also includes a GUI and FastApi implementation for easy control of the relays.
+
+## usage
+
+### kmtronic_usb_relay_gui
+
+```cmd
+python -m src.kmtronic_usb_relay.four_channel_relay_gui
+```
+
+![kmtronic_usb_relay_gui](./images/four_channel_relay_gui.png)
+
+### kmtronic_usb_relay_api
+
+```cmd
+python -m src.kmtronic_usb_relay.four_channel_relay_api
+```
+
+![kmtronic_usb_relay_api](./images/four_channel_relay_api.png)
+
+## [source manual](https://chaitu-ycr.github.io/automotive-test-kit/packages/kmtronic_usb_relay/#source-manual)

kmtronic_usb_relay-25.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kmtronic_usb_relay/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kmtronic_usb_relay/com_utils.py,sha256=gJSJC3rd60QpEKhro-xbRwmIZ-usYsmdlbch3EFa6UI,9621
+kmtronic_usb_relay/four_channel_relay.py,sha256=2W8WSfm5V6bxvtInuTlcNhVkLGh0jl4AR0JHNvurcRk,7542
+kmtronic_usb_relay/four_channel_relay_api.py,sha256=SRAUCsCRODSZVrVhNmloFzMRp04jHvYFKLoD2If9Kao,5944
+kmtronic_usb_relay/four_channel_relay_gui.py,sha256=1ub1Ah9iFMwrnnpAmBiQJL7ptPkjCKaSsGsiXOTNyrM,13059
+kmtronic_usb_relay-25.0.0.dist-info/WHEEL,sha256=5h_Q-_6zWQhhADpsAD_Xpw7gFbCRK5WjOOEq0nB806Q,79
+kmtronic_usb_relay-25.0.0.dist-info/METADATA,sha256=RCFIJAOKsXq2PSH9O6SxUTAgdRIl5VMG81-RQzHsHO4,2798
+kmtronic_usb_relay-25.0.0.dist-info/RECORD,,

kmtronic_usb_relay-25.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.18
+Root-Is-Purelib: true
+Tag: py3-none-any