opensignalbox-interface 0.1.0__py3-none-any.whl

opensignalbox/interface/adapters/modbus/adapter.py

@@ -0,0 +1,485 @@
+"""
+Modbus adapter implementation.
+"""
+
+import logging
+import socket
+from typing import Any, Optional, Union
+
+import serial
+from opensignalbox.interface.adapters.base import BaseAdapter
+from opensignalbox.interface.models import AdapterTypeEnum
+
+logger = logging.getLogger(__name__)
+
+SERIAL_TIMEOUT = 1  # seconds
+NETWORK_TIMEOUT = 1  # seconds
+STATUS_UPDATE_PERIOD = 1  # seconds
+
+
+def modbus_crc(msg: bytearray) -> int:
+    """
+    Calculate Modbus CRC for a message.
+
+    Args:
+        msg: The message to calculate CRC for
+
+    Returns:
+        The calculated CRC
+    """
+    crc = 0xFFFF
+    for n in range(len(msg)):
+        crc ^= msg[n]
+        for _ in range(8):
+            if crc & 1:
+                crc >>= 1
+                crc ^= 0xA001
+            else:
+                crc >>= 1
+    return crc
+
+
+class ModbusAdapter(BaseAdapter):
+    """Adapter for Modbus communication."""
+
+    # Metadata for the API discovery
+    metadata = {
+        "supported_connection_types": [
+            "BasicIOModbusConnection",
+            "BellModbusConnection",
+        ],
+        "required_fields": ["systemName", "userName", "isNetwork"],
+        "optional_fields": [
+            "description",
+            "baud",
+            "address",
+            "serialPort",
+            "networkPort",
+            "enabled",
+        ],
+    }
+
+    @classmethod
+    def get_router(cls) -> Any:
+        """Get API router for Modbus adapter endpoints.
+
+        Returns:
+            FastAPI router with Modbus adapter specific endpoints
+        """
+        from fastapi import APIRouter, HTTPException
+        from opensignalbox.interface.models import (
+            AdapterBase,
+            AdapterCreate,
+            AdapterPublic,
+            AdapterUpdate,
+        )
+
+        router = APIRouter(tags=["adapters/modbus"])
+
+        @router.get("/{system_name}")
+        async def get_adapter(system_name: str):
+            """Get a Modbus adapter by system name."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                adapter = cls.adapter_controller.get(system_name)
+                if adapter.adapter_type != "Modbus":
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Modbus adapter '{system_name}' not found",
+                    )
+
+                # Convert BaseAdapter to AdapterPublic
+                adapter_dict = {
+                    "system_name": adapter.system_name,
+                    "user_name": adapter.user_name,
+                    "description": adapter.description,
+                    "adapter_type": adapter.adapter_type,
+                    "enabled": adapter.enabled,
+                    "error": adapter.error,
+                    "is_connected": adapter.is_connected,
+                    "is_network": adapter.is_network,
+                    "serial_port": adapter.serial_port,
+                    "baud": adapter.baud,
+                    "address": adapter.address,
+                    "network_port": adapter.network_port,
+                }
+                return AdapterPublic(**adapter_dict)
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404, detail=f"Adapter '{system_name}' not found"
+                ) from exc
+
+        @router.post("/")
+        async def create_adapter(adapter: AdapterCreate):
+            """Create a new Modbus adapter."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                # Extract common fields
+                adapter_base = AdapterBase(
+                    **adapter.model_dump(), adapter_type=AdapterTypeEnum.MODBUS
+                )
+
+                # Create the adapter
+                new_adapter = cls.adapter_controller.add(
+                    adapter_base, **adapter.model_dump()
+                )
+
+                # Convert BaseAdapter to AdapterPublic
+                adapter_dict = {
+                    "system_name": new_adapter.system_name,
+                    "user_name": new_adapter.user_name,
+                    "description": new_adapter.description,
+                    "adapter_type": new_adapter.adapter_type,
+                    "enabled": new_adapter.enabled,
+                    "is_connected": new_adapter.is_connected,
+                }
+                return AdapterPublic(**adapter_dict)
+            except FileExistsError as exc:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Adapter '{adapter.system_name}' already exists",
+                ) from exc
+            except TypeError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        @router.patch("/{system_name}")
+        async def update_adapter(system_name: str, adapter_update: AdapterUpdate):
+            """Update a Modbus adapter."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                # Check that the adapter exists and is Modbus type
+                adapter = cls.adapter_controller.get(system_name)
+                if adapter.adapter_type != "Modbus":
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Modbus adapter '{system_name}' not found",
+                    )
+
+                # Extract update fields
+                kwargs = {
+                    k: v
+                    for k, v in adapter_update.model_dump().items()
+                    if v is not None and k != "system_name"
+                }
+
+                # Update the adapter
+                updated_adapter = cls.adapter_controller.update(system_name, **kwargs)
+
+                # Convert BaseAdapter to AdapterPublic
+                adapter_dict = {
+                    "system_name": updated_adapter.system_name,
+                    "user_name": updated_adapter.user_name,
+                    "description": updated_adapter.description,
+                    "adapter_type": updated_adapter.adapter_type,
+                    "enabled": updated_adapter.enabled,
+                    "is_connected": updated_adapter.is_connected,
+                }
+                return AdapterPublic(**adapter_dict)
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404, detail=f"Adapter '{system_name}' not found"
+                ) from exc
+
+        @router.delete("/{system_name}")
+        async def delete_adapter(system_name: str):
+            """Delete a Modbus adapter."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                # Check that the adapter exists and is Modbus type
+                adapter = cls.adapter_controller.get(system_name)
+                if adapter.adapter_type != "Modbus":
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Modbus adapter '{system_name}' not found",
+                    )
+
+                cls.adapter_controller.remove(system_name)
+                return {"status": "success"}
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404, detail=f"Adapter '{system_name}' not found"
+                ) from exc
+
+        @router.post("/{system_name}/connect")
+        async def connect_adapter(system_name: str):
+            """Connect a Modbus adapter."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                adapter = cls.adapter_controller.get(system_name)
+                if adapter.adapter_type != "Modbus":
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Modbus adapter '{system_name}' not found",
+                    )
+
+                adapter.connect()
+                return {"status": "success", "connected": adapter.is_connected}
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404, detail=f"Adapter '{system_name}' not found"
+                ) from exc
+
+        @router.post("/{system_name}/disconnect")
+        async def disconnect_adapter(system_name: str):
+            """Disconnect a Modbus adapter."""
+            if not cls.adapter_controller:
+                raise HTTPException(
+                    status_code=500, detail="Adapter controller not initialized"
+                )
+
+            try:
+                adapter = cls.adapter_controller.get(system_name)
+                if adapter.adapter_type != "Modbus":
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Modbus adapter '{system_name}' not found",
+                    )
+
+                adapter.disconnect()
+                return {"status": "success", "connected": adapter.is_connected}
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404, detail=f"Adapter '{system_name}' not found"
+                ) from exc
+
+        return router
+
+    def __init__(
+        self,
+        system_name: str,
+        user_name: str,
+        description: str = "",
+        enabled: bool = True,
+        is_network: bool = False,
+        serial_port: Optional[str] = None,
+        baud: int = 9600,
+        address: Optional[str] = None,
+        network_port: Optional[int] = 0,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(system_name, user_name, description)
+        self.adapter_type = AdapterTypeEnum.MODBUS
+        self.enabled = enabled
+        self.is_network = is_network
+        self.serial_port = serial_port
+        self.baud = baud
+        self.address = address
+        self.network_port = network_port
+        self.connection: Union[serial.Serial, socket.socket, None] = None
+        self.tid = 0  # Transaction ID for Modbus TCP
+
+    def attempt_connect(self) -> None:
+        """Attempt to connect to the Modbus device."""
+        logger.info(
+            f"Connecting to Modbus device: {self.system_name} ({self.adapter_type})"
+        )
+        if self.is_network:
+            self._connect_network()
+        else:
+            self._connect_serial()
+
+    def _connect_network(self) -> None:
+        """Connect to a Modbus TCP device."""
+        if not self.address:
+            raise ValueError("Network address is required for network connection")
+
+        self.connection = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.connection.settimeout(NETWORK_TIMEOUT)
+        logger.info(
+            f"Connecting to Modbus TCP device at {self.address}:{self.network_port}"
+        )
+        self.connection.connect((self.address, self.network_port))
+
+    def _connect_serial(self) -> None:
+        """Connect to a Modbus RTU device."""
+        if not isinstance(self.serial_port, str):
+            self.serial_port = f"COM{self.serial_port}"
+
+        self.connection = serial.Serial(
+            port=self.serial_port,
+            baudrate=self.baud,
+            bytesize=serial.EIGHTBITS,
+            parity=serial.PARITY_NONE,
+            stopbits=serial.STOPBITS_ONE,
+            timeout=SERIAL_TIMEOUT,
+        )
+
+    def attempt_disconnect(self) -> None:
+        """Attempt to disconnect from the Modbus device."""
+        if self.connection:
+            self.connection.close()
+            self.connection = None
+            self.is_connected = False
+            logger.debug(
+                f"Disconnected from Modbus device: {self.system_name} ({self.adapter_type})"
+            )
+
+    def attempt_write(self, data: bytearray) -> None:
+        """
+        Write data to the Modbus device.
+
+        Args:
+            data: The data to write
+
+        Raises:
+            ConnectionError: If not connected to a device
+            IOError: If the write fails
+        """
+        if not self.connection:
+            raise ConnectionError("Not connected to a device")
+
+        if self.is_network:
+            self._write_network(data)
+        else:
+            self._write_serial(data)
+
+    def _write_network(self, data: bytearray) -> None:
+        """Write data to a Modbus TCP device."""
+        if not isinstance(self.connection, socket.socket):
+            raise ConnectionError("Invalid network connection")
+
+        # Increment transaction ID
+        self.tid = (self.tid + 1) % 65536
+
+        # Create MBAP header
+        mbap = bytearray(
+            [
+                (self.tid >> 8) & 0xFF,  # Transaction ID high byte
+                self.tid & 0xFF,  # Transaction ID low byte
+                0x00,  # Protocol ID high byte
+                0x00,  # Protocol ID low byte
+                (len(data) >> 8) & 0xFF,  # Length high byte
+                len(data) & 0xFF,  # Length low byte
+            ]
+        )
+
+        # Prepend MBAP header to data
+        message = mbap + data
+
+        # Send data
+        self.connection.sendall(message)
+
+    def _write_serial(self, data: bytearray) -> None:
+        """Write data to a Modbus RTU device."""
+        if not isinstance(self.connection, serial.Serial):
+            raise ConnectionError("Invalid serial connection")
+
+        # Calculate CRC
+        crc = modbus_crc(data)
+
+        # Append CRC to data
+        message = data + bytearray([(crc & 0xFF), (crc >> 8) & 0xFF])
+
+        # Send data
+        self.connection.write(message)
+
+    def attempt_read(self) -> bytearray:
+        """
+        Read data from the Modbus device.
+
+        Returns:
+            The read data
+
+        Raises:
+            ConnectionError: If not connected to a device
+            IOError: If the read fails
+        """
+        if not self.connection:
+            raise ConnectionError("Not connected to a device")
+
+        # Read response
+        if self.is_network:
+            return self._read_network()
+        else:
+            return self._read_serial()
+
+    def _read_network(self) -> bytearray:
+        """Read data from a Modbus TCP device."""
+        if not isinstance(self.connection, socket.socket):
+            raise ConnectionError("Invalid network connection")
+
+        # Read MBAP header (7 bytes)
+        mbap = self.connection.recv(7)
+        if len(mbap) != 7:
+            raise IOError("Failed to read MBAP header")
+
+        # Extract length from MBAP header
+        length = (mbap[4] << 8) | mbap[5] - 1  # Subtract 1 for unit ID byte
+
+        # Read data
+        data = self.connection.recv(length)
+        if len(data) != length:
+            raise IOError("Failed to read complete response")
+
+        # Check transaction ID
+        tid = (mbap[0] << 8) | mbap[1]
+        if tid != self.tid:
+            self.connection.recv(1024)  # Flush buffer
+            raise IOError(
+                f"Transaction ID mismatch: expected {self.tid}, got {tid}. Flushing buffer."
+            )
+
+        return bytearray(data[2:])  # Skip function code and unit ID byte
+
+    def _read_serial(self) -> bytearray:
+        """Read data from a Modbus RTU device."""
+        if not isinstance(self.connection, serial.Serial):
+            raise ConnectionError("Invalid serial connection")
+
+        # Read function code and length (2 bytes)
+        header = self.connection.read(2)
+        if len(header) != 2:
+            raise IOError("Failed to read response header")
+
+        # Extract function code
+        function_code = header[1]
+
+        # Check for exception response
+        if function_code & 0x80:
+            exception_code = self.connection.read(1)
+            raise IOError(f"Modbus exception: {exception_code[0]}")
+
+        # Select length based on function code
+        if function_code == 15:  # Write multiple coils
+            length = 4
+        elif function_code == 3:  # Read holding registers
+            header += self.connection.read(1)
+            length = header[-1]
+        else:
+            length = 2
+
+        # Read data and CRC
+        data = self.connection.read(length + 2)  # +2 for CRC
+        if len(data) != length + 2:
+            raise IOError("Failed to read complete response")
+
+        # Verify CRC
+        message = header + data[:-2]
+        crc = modbus_crc(bytearray(message))
+        received_crc = (data[-1] << 8) | data[-2]
+
+        if crc != received_crc:
+            raise IOError("CRC check failed")
+
+        # Return data without CRC
+        return bytearray(data[:-2])

opensignalbox/interface/interfaces/__init__.py

@@ -0,0 +1,3 @@
+"""
+Interface implementations for opensignalbox-interface.
+"""

opensignalbox/interface/interfaces/base.py

@@ -0,0 +1,170 @@
+"""
+Base interface classes and types for opensignalbox-interface module.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+from opensignalbox.interface.models import Interface
+
+
+class InterfaceHandler(ABC):
+    """Base abstract class for all interface handlers."""
+
+    # Interface controller reference for API routes
+    interface_controller = None
+    adapter_controller = None
+
+    @classmethod
+    def init(cls, output_variables, input_variable_subs, variable_update_callback):
+        """Initialize handler with controller references."""
+        cls.output_variables = output_variables
+        cls.input_variable_subs = input_variable_subs
+        cls.variable_update_callback = variable_update_callback
+
+    @classmethod
+    def set_controllers(cls, interface_controller, adapter_controller):
+        """Set the interface and adapter controller references for API routes.
+
+        Args:
+            interface_controller: The interface controller instance
+            adapter_controller: The adapter controller instance
+        """
+        cls.interface_controller = interface_controller
+        cls.adapter_controller = adapter_controller
+
+    @staticmethod
+    @abstractmethod
+    def add(interface: Interface) -> Interface:
+        """Add a new interface.
+
+        Args:
+            interface: The interface to add
+
+        Returns:
+            The initialized interface with additional runtime fields
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def update(interface: Interface, fields: Dict[str, Any]) -> None:
+        """Update an existing interface.
+
+        Args:
+            interface: The interface to update
+            fields: The fields to update
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def remove(interface: Interface) -> None:
+        """Remove an interface.
+
+        Args:
+            interface: The interface to remove
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def handle_variable_update(
+        interface: Interface, variable: str, json_data: str
+    ) -> None:
+        """Handle an update to a subscribed variable.
+
+        Args:
+            interface: The interface associated with the variable
+            variable: The name of the variable that was updated
+            json_data: The serialized JSON data of the variable update
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def connect(interface: Interface) -> bool:
+        """Connect to the interface.
+
+        Args:
+            interface: The interface to connect
+
+        Returns:
+            True if connection was successful, False otherwise
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def disconnect(interface: Interface) -> None:
+        """Disconnect from the interface.
+
+        Args:
+            interface: The interface to disconnect
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def read_data(interface: Interface) -> None:
+        """Read data.
+
+        Args:
+            interface: The interface to read data for
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def write_data(interface: Interface) -> None:
+        """Write data to hardware using the adapter.
+
+        Args:
+            interface: The interface to write data for
+        """
+        pass
+
+    @classmethod
+    def get_router(cls) -> Optional[Any]:
+        """Get API router for this interface type.
+
+        Returns:
+            Optional FastAPI router to be included in the API
+            Returns None if no custom routes are needed
+
+        Example:
+            ```python
+            @classmethod
+            def get_router(cls):
+                from fastapi import APIRouter
+
+                router = APIRouter()
+
+                @router.get("/my-interface/status")
+                async def get_status():
+                    # Access interfaces via the controller reference
+                    interfaces = cls.interface_controller.get_all()
+                    return {"status": "ok", "interface_count": len(interfaces)}
+
+                return router
+            ```
+        """
+        return None
+
+    @classmethod
+    @abstractmethod
+    def load_from_json(cls, interface_data: Any) -> None:
+        """Load interface data from JSON."""
+
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def save_to_json(interface: Interface) -> Any:
+        """Save interface data to JSON.
+
+        Returns:
+            A dictionary representation of the interface data
+        """
+        # Default implementation returns simple model dump
+        pass

opensignalbox/interface/interfaces/basicio/__init__.py

@@ -0,0 +1,3 @@
+"""
+Basic IO interface implementation.
+"""