mbtoolcli 0.3.1__py3-none-any.whl

modbus_slave_sim/master.py

@@ -0,0 +1,647 @@
+"""
+Modbus Master client implementation.
+
+This module provides a Modbus Master client that can read and write
+to Modbus slave devices. Supports TCP, RTU, and ASCII protocols.
+"""
+
+import logging
+import time
+from typing import List, Optional, Union
+
+from pymodbus.client import ModbusTcpClient, ModbusSerialClient
+from pymodbus.exceptions import ModbusException
+from pymodbus.framer import Framer
+
+from .datatypes import (
+    ByteOrder,
+    DataType,
+    DATA_TYPE_REGISTERS,
+    convert_registers,
+    format_value,
+    int16_to_registers,
+    int32_to_registers,
+    float32_to_registers,
+)
+from .colors import c, CYAN_BOLD, MAGENTA, RED_BOLD, DIM, GREEN_BOLD, YELLOW, WHITE_BOLD, RED, BOLD
+
+logger = logging.getLogger(__name__)
+
+
+class ModbusMaster:
+    """
+    Modbus Master client.
+    
+    Provides read/write operations for Modbus slave devices with
+    support for various data types and protocols.
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 502,
+        mode: str = "tcp",
+        slave_id: int = 1,
+        timeout: float = 3.0,
+        # RTU/ASCII parameters
+        serial_port: Optional[str] = None,
+        baudrate: int = 9600,
+        parity: str = "N",
+        stopbits: int = 1,
+        bytesize: int = 8,
+    ):
+        """
+        Initialize the Modbus Master client.
+
+        Args:
+            host: TCP host address
+            port: TCP port or serial port
+            mode: Protocol mode ('tcp', 'rtu', 'ascii')
+            slave_id: Target slave device ID
+            timeout: Communication timeout in seconds
+            serial_port: Serial port path (for RTU/ASCII)
+            baudrate: Serial baud rate
+            parity: Serial parity (N, E, O)
+            stopbits: Serial stop bits
+            bytesize: Serial data bits
+        """
+        self.host = host
+        self.port = port
+        self.mode = mode.lower()
+        self.slave_id = slave_id
+        self.timeout = timeout
+        self.serial_port = serial_port or str(port)
+        self.baudrate = baudrate
+        self.parity = parity
+        self.stopbits = stopbits
+        self.bytesize = bytesize
+        self._client = None
+
+    def connect(self) -> bool:
+        """
+        Connect to the Modbus slave device.
+        
+        Returns:
+            True if connection successful, False otherwise
+        """
+        try:
+            if self.mode == "tcp":
+                self._client = ModbusTcpClient(
+                    host=self.host,
+                    port=self.port,
+                    timeout=self.timeout,
+                )
+            elif self.mode in ("rtu", "ascii"):
+                # Map mode to framer type
+                framer = Framer.RTU if self.mode == "rtu" else Framer.ASCII
+                
+                self._client = ModbusSerialClient(
+                    port=self.serial_port,
+                    framer=framer,
+                    baudrate=self.baudrate,
+                    parity=self.parity,
+                    stopbits=self.stopbits,
+                    bytesize=self.bytesize,
+                    timeout=self.timeout,
+                )
+            else:
+                raise ValueError(f"Unsupported mode: {self.mode}")
+
+            connected = self._client.connect()
+            if connected:
+                logger.info(f"Connected to {self.mode.upper()} device at {self._get_address()}")
+            else:
+                logger.error(f"Failed to connect to {self._get_address()}")
+            return connected
+
+        except Exception as e:
+            logger.error(f"Connection error: {e}")
+            return False
+
+    def disconnect(self):
+        """Disconnect from the Modbus slave device."""
+        if self._client:
+            self._client.close()
+            self._client = None
+            logger.info("Disconnected")
+
+    def _get_address(self) -> str:
+        """Get address string for logging."""
+        if self.mode == "tcp":
+            return f"{self.host}:{self.port}"
+        return self.serial_port
+
+    def scan_slaves(
+        self,
+        start: int = 1,
+        end: int = 247,
+        register: int = 0,
+        count: int = 1,
+        timeout_per: float = 0.5,
+    ) -> List[int]:
+        """Scan a range of slave IDs to discover active devices.
+
+        Reads a holding register from each slave ID to determine if it responds.
+
+        Args:
+            start: Starting slave ID (default 1)
+            end: Ending slave ID (default 247)
+            register: Register address to read (default 0)
+            count: Number of registers to read (default 1)
+            timeout_per: Timeout per slave in seconds (default 0.5)
+
+        Returns:
+            List of slave IDs that responded successfully
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return []
+
+        if not self._client.is_socket_open():
+            logger.error("Connection is not open")
+            return []
+
+        found_slaves = []
+        total = end - start + 1
+        self._client.timeout = timeout_per
+
+        for sid in range(start, end + 1):
+            self._client.comm_params.slave_id = sid
+            try:
+                result = self._client.read_holding_registers(address=register, count=count)
+                if not result.isError():
+                    found_slaves.append(sid)
+                    progress = c(f"[{sid - start + 1}/{total}]", DIM)
+                    print(f"  {progress} Slave ID {c(str(sid), GREEN_BOLD)} - {c('Found', GREEN_BOLD)}")
+                else:
+                    print(f"  {c(f'[{sid - start + 1}/{total}]', DIM)} Slave ID {c(str(sid), DIM)} - {c('No response', DIM)}", end="\r")
+            except Exception:
+                print(f"  {c(f'[{sid - start + 1}/{total}]', DIM)} Slave ID {c(str(sid), DIM)} - {c('No response', DIM)}", end="\r")
+
+        # Restore original slave_id
+        self._client.comm_params.slave_id = self.slave_id
+        self._client.timeout = self.timeout
+        print()
+
+        return found_slaves
+
+    def read_coils(
+        self,
+        address: int,
+        count: int = 1,
+    ) -> Optional[List[bool]]:
+        """
+        Read coils (FC01).
+        
+        Args:
+            address: Starting address
+            count: Number of coils to read
+            
+        Returns:
+            List of coil values or None on error
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return None
+
+        try:
+            result = self._client.read_coils(address=address, count=count)
+            if result.isError():
+                logger.error(f"Read coils error: {result}")
+                return None
+            return result.bits[:count]
+        except Exception as e:
+            logger.error(f"Read coils exception: {e}")
+            return None
+
+    def read_discrete_inputs(
+        self,
+        address: int,
+        count: int = 1,
+    ) -> Optional[List[bool]]:
+        """
+        Read discrete inputs (FC02).
+        
+        Args:
+            address: Starting address
+            count: Number of discrete inputs to read
+            
+        Returns:
+            List of discrete input values or None on error
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return None
+
+        try:
+            result = self._client.read_discrete_inputs(address=address, count=count)
+            if result.isError():
+                logger.error(f"Read discrete inputs error: {result}")
+                return None
+            return result.bits[:count]
+        except Exception as e:
+            logger.error(f"Read discrete inputs exception: {e}")
+            return None
+
+    def read_holding_registers(
+        self,
+        address: int,
+        count: int = 1,
+    ) -> Optional[List[int]]:
+        """
+        Read holding registers (FC03).
+        
+        Args:
+            address: Starting address
+            count: Number of registers to read
+            
+        Returns:
+            List of register values or None on error
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return None
+
+        try:
+            result = self._client.read_holding_registers(address=address, count=count)
+            if result.isError():
+                logger.error(f"Read holding registers error: {result}")
+                return None
+            return result.registers
+        except Exception as e:
+            logger.error(f"Read holding registers exception: {e}")
+            return None
+
+    def read_input_registers(
+        self,
+        address: int,
+        count: int = 1,
+    ) -> Optional[List[int]]:
+        """
+        Read input registers (FC04).
+        
+        Args:
+            address: Starting address
+            count: Number of registers to read
+            
+        Returns:
+            List of register values or None on error
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return None
+
+        try:
+            result = self._client.read_input_registers(address=address, count=count)
+            if result.isError():
+                logger.error(f"Read input registers error: {result}")
+                return None
+            return result.registers
+        except Exception as e:
+            logger.error(f"Read input registers exception: {e}")
+            return None
+
+    def write_single_coil(
+        self,
+        address: int,
+        value: bool,
+    ) -> bool:
+        """
+        Write single coil (FC05).
+        
+        Args:
+            address: Coil address
+            value: Coil value (True/False)
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return False
+
+        try:
+            result = self._client.write_coil(address=address, value=value)
+            if result.isError():
+                logger.error(f"Write single coil error: {result}")
+                return False
+            logger.info(f"Coil {address} written: {value}")
+            return True
+        except Exception as e:
+            logger.error(f"Write single coil exception: {e}")
+            return False
+
+    def write_single_register(
+        self,
+        address: int,
+        value: int,
+    ) -> bool:
+        """
+        Write single register (FC06).
+        
+        Args:
+            address: Register address
+            value: Register value (0-65535)
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return False
+
+        try:
+            result = self._client.write_register(address=address, value=value)
+            if result.isError():
+                logger.error(f"Write single register error: {result}")
+                return False
+            logger.info(f"Register {address} written: {value}")
+            return True
+        except Exception as e:
+            logger.error(f"Write single register exception: {e}")
+            return False
+
+    def write_multiple_coils(
+        self,
+        address: int,
+        values: List[bool],
+    ) -> bool:
+        """
+        Write multiple coils (FC15).
+        
+        Args:
+            address: Starting address
+            values: List of coil values
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return False
+
+        try:
+            result = self._client.write_coils(address=address, values=values)
+            if result.isError():
+                logger.error(f"Write multiple coils error: {result}")
+                return False
+            logger.info(f"Coils {address}-{address + len(values) - 1} written")
+            return True
+        except Exception as e:
+            logger.error(f"Write multiple coils exception: {e}")
+            return False
+
+    def write_multiple_registers(
+        self,
+        address: int,
+        values: List[int],
+    ) -> bool:
+        """
+        Write multiple registers (FC16).
+        
+        Args:
+            address: Starting address
+            values: List of register values
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._client:
+            logger.error("Not connected")
+            return False
+
+        try:
+            result = self._client.write_registers(address=address, values=values)
+            if result.isError():
+                logger.error(f"Write multiple registers error: {result}")
+                return False
+            logger.info(f"Registers {address}-{address + len(values) - 1} written")
+            return True
+        except Exception as e:
+            logger.error(f"Write multiple registers exception: {e}")
+            return False
+
+    def read_and_convert(
+        self,
+        address: int,
+        count: int,
+        data_type: DataType,
+        function_code: int = 3,
+        byte_order: ByteOrder = ByteOrder.ABCD,
+    ) -> Optional[Union[int, float, str, List[Union[int, float, str]]]]:
+        """
+        Read registers and convert to specified data type.
+
+        Args:
+            address: Starting address
+            count: Number of registers to read
+            data_type: Target data type
+            function_code: 1=coils, 2=discrete, 3=holding, 4=input
+            byte_order: Byte order for 32-bit types
+
+        Returns:
+            Converted value(s) or None on error
+        """
+        # Handle coils and discrete inputs (1-bit values)
+        if function_code == 1:
+            values = self.read_coils(address, count)
+            if values is None:
+                return None
+            return [1 if v else 0 for v in values]
+        elif function_code == 2:
+            values = self.read_discrete_inputs(address, count)
+            if values is None:
+                return None
+            return [1 if v else 0 for v in values]
+        
+        # Handle holding and input registers (16-bit values)
+        if function_code == 3:
+            registers = self.read_holding_registers(address, count)
+        else:
+            registers = self.read_input_registers(address, count)
+
+        if registers is None:
+            return None
+
+        # Calculate how many values we need
+        regs_per_value = DATA_TYPE_REGISTERS.get(data_type, 1)
+        
+        if data_type == DataType.HEX:
+            # For hex, return all registers formatted
+            return convert_registers(registers, data_type, count=count, byte_order=byte_order)
+        
+        # Convert multiple values
+        values = []
+        for i in range(0, len(registers), regs_per_value):
+            chunk = registers[i:i + regs_per_value]
+            if len(chunk) == regs_per_value:
+                value = convert_registers(chunk, data_type, count=regs_per_value, byte_order=byte_order)
+                values.append(value)
+        
+        if len(values) == 1:
+            return values[0]
+        return values
+
+    def write_converted(
+        self,
+        address: int,
+        value: Union[int, float],
+        data_type: DataType,
+        byte_order: ByteOrder = ByteOrder.ABCD,
+    ) -> bool:
+        """
+        Convert value and write to registers.
+
+        Args:
+            address: Starting address
+            value: Value to write
+            data_type: Data type of the value
+            byte_order: Byte order for 32-bit types
+
+        Returns:
+            True if successful, False otherwise
+        """
+        # Convert value to registers
+        if data_type == DataType.INT16:
+            registers = int16_to_registers(int(value), signed=True)
+        elif data_type == DataType.UINT16:
+            registers = int16_to_registers(int(value), signed=False)
+        elif data_type == DataType.INT32:
+            registers = int32_to_registers(int(value), signed=True, byte_order=byte_order)
+        elif data_type == DataType.UINT32:
+            registers = int32_to_registers(int(value), signed=False, byte_order=byte_order)
+        elif data_type == DataType.FLOAT32:
+            registers = float32_to_registers(float(value), byte_order=byte_order)
+        else:
+            logger.error(f"Cannot write with data type: {data_type}")
+            return False
+
+        # Write registers
+        if len(registers) == 1:
+            return self.write_single_register(address, registers[0])
+        else:
+            return self.write_multiple_registers(address, registers)
+
+    def poll(
+        self,
+        address: int,
+        count: int,
+        data_type: DataType,
+        function_code: int = 3,
+        interval: float = 1.0,
+        iterations: int = 0,
+        hex_format: bool = False,
+        byte_order: ByteOrder = ByteOrder.ABCD,
+        alarm: Optional[dict] = None,
+        output_file: Optional[str] = None,
+    ):
+        """
+        Poll registers continuously.
+
+        Args:
+            address: Starting address
+            count: Number of registers
+            data_type: Data type for display
+            function_code: 3 for holding, 4 for input registers
+            interval: Polling interval in seconds
+            iterations: Number of iterations (0 = infinite)
+            hex_format: Show hex values alongside
+            byte_order: Byte order for 32-bit types
+            alarm: Alarm config {"addr": int, "op": str, "value": int/float} to alert when condition met
+            output_file: Path to CSV file for logging results
+        """
+        iteration = 0
+        csv_fh = None
+        try:
+            if output_file:
+                csv_fh = open(output_file, "w", newline="")
+                import csv
+                writer = csv.writer(csv_fh)
+                writer.writerow(["iteration", "address", "value"])
+
+            while iterations == 0 or iteration < iterations:
+                iteration += 1
+                value = self.read_and_convert(address, count, data_type, function_code, byte_order=byte_order)
+
+                if value is not None:
+                    formatted = format_value(value, data_type, hex_format)
+                    line = f"{c(f'[{iteration}]', MAGENTA)} {c(formatted, CYAN_BOLD)}"
+
+                    # Check alarm
+                    if alarm is not None:
+                        alarm_msg = self._check_alarm(value, alarm, data_type)
+                        if alarm_msg:
+                            line += f"  {c(alarm_msg, RED_BOLD)}"
+
+                    print(line)
+
+                    # Write to CSV
+                    if csv_fh and isinstance(value, (int, float)):
+                        writer.writerow([iteration, address, value])
+                    elif csv_fh and isinstance(value, list):
+                        for i, v in enumerate(value):
+                            writer.writerow([iteration, address + i, v])
+                else:
+                    print(f"{c(f'[{iteration}]', MAGENTA)} {c('Error reading registers', RED_BOLD)}")
+
+                if iterations == 0:
+                    time.sleep(interval)
+
+        except KeyboardInterrupt:
+            print(f"\n{c('Polling stopped', YELLOW)}")
+        finally:
+            if csv_fh:
+                csv_fh.close()
+            print(c(f"Completed {iteration} iterations", DIM))
+
+    def _check_alarm(self, value, alarm: dict, data_type: DataType) -> Optional[str]:
+        """Check if value triggers alarm condition. Returns alarm message or None."""
+        addr = alarm["addr"]
+        op = alarm["op"]
+        threshold = alarm["value"]
+
+        if isinstance(value, list) and addr < len(value):
+            v = value[addr]
+        elif isinstance(value, (int, float)):
+            v = value
+        else:
+            return None
+
+        triggered = False
+        if op == ">":
+            triggered = v > threshold
+        elif op == "<":
+            triggered = v < threshold
+        elif op == ">=":
+            triggered = v >= threshold
+        elif op == "<=":
+            triggered = v <= threshold
+        elif op == "==":
+            triggered = v == threshold
+        elif op == "!=":
+            triggered = v != threshold
+        else:
+            return None
+
+        if triggered:
+            return f"!!! ALARM: register[addr] {op} {threshold} (current: {v}) !!!"
+        return None
+
+
+class MasterResult:
+    """Wrapper for master operation results."""
+
+    def __init__(
+        self,
+        success: bool,
+        data: Optional[Union[List[int], List[bool], int, float, str]] = None,
+        error: Optional[str] = None,
+    ):
+        self.success = success
+        self.data = data
+        self.error = error
+
+    def __repr__(self):
+        if self.success:
+            return f"MasterResult(success=True, data={self.data})"
+        return f"MasterResult(success=False, error={self.error})"