serialpro 0.1.0__tar.gz

serialpro-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: serialpro
+Version: 0.1.0
+Summary: 串口封装
+Author: LiuWei
+Author-email: 183074632@qq.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pyserial (>=3.5,<4.0)
+Description-Content-Type: text/markdown
+
+

serialpro-0.1.0/SerialPro/serial_pro.py

@@ -0,0 +1,487 @@
+import serial
+
+
+class SerialPro:
+    """三菱FX3U PLC RS232串口通讯类 (Format 1 专用协议)"""
+
+    # 协议常量
+    ENQ = b'\x05'  # 请求帧的起始标志, 上位机 → PLC 的所有读写命令都以 ENQ 开头, 告诉 PLC："我有一条请求要发给你，请做好接收准备"
+    ACK = b'\x06'  # PLC 返回的正面应答, "命令接收成功，写入操作已执行"
+    NAK = b'\x15'  # PLC 返回的错误应答, "命令格式有误 / 校验码不匹配 / 地址非法"
+    STX = b'\x02'  # PLC 响应数据的起始标志, BR/WR 读操作中，PLC 返回数据帧以 STX 开头
+    ETX = b'\x03'  # PLC 响应数据域的结束标志, "数据部分到此结束，后面两位是校验码"
+
+    # 支持的元件类型
+    BIT_DEVICES = ('X', 'Y', 'M', 'S', 'T', 'C')
+    WORD_DEVICES = ('D', 'T', 'C', 'R')
+    """
+    三菱 FX3U PLC 支持的元件类型：
+    
+    位元件 (ON/OFF 两态)：
+        X — 输入继电器，物理输入端子状态（只读）
+        Y — 输出继电器，驱动物理输出端子（可读写）
+        M — 辅助继电器，内部逻辑标志位
+        S — 状态继电器，用于步进梯形图或通用标志
+        T — 定时器线圈状态，ON表示正在计时
+        C — 计数器线圈状态，ON表示计数达到设定值
+
+    字元件 (16位数值 0–65535)：
+        D — 数据寄存器，存储数值数据
+        T — 定时器当前计时值
+        C — 计数器当前计数值
+        R — 文件寄存器，扩展存储，断电保持
+    """
+
+    def __init__(self, port='COM1', baud_rate=9600, station='00', timeout=1.0):
+        """初始化SerialPro.
+
+        Args:
+            port: 串口号, 如 'COM1'.
+            baud_rate: 波特率, 默认9600.
+            station: 站号, 两位十六进制字符串, 默认'00'.
+            timeout: 读写超时时间(秒).
+        """
+        self.port = port
+        self.baud_rate = baud_rate
+        self.station = station.upper()
+        self.timeout = timeout
+        self._serial = None
+
+    # ==================== 连接管理 ====================
+
+    def open(self):
+        """打开串口连接，配置为 9600,7,E,1"""
+        if self._serial is not None and self._serial.is_open:
+            return
+
+        self._serial = serial.Serial(
+            port=self.port,
+            baudrate=self.baud_rate,
+            bytesize=serial.SEVENBITS,
+            parity=serial.PARITY_EVEN,
+            stopbits=serial.STOPBITS_ONE,
+            timeout=self.timeout
+        )
+        self._serial.reset_input_buffer()
+        self._serial.reset_output_buffer()
+
+    def close(self):
+        """关闭串口连接"""
+        if self._serial is not None and self._serial.is_open:
+            self._serial.close()
+        self._serial = None
+
+    def is_connected(self):
+        """检查是否已连接.
+
+        Returns:
+            bool: True表示已连接, False表示未连接.
+        """
+        return self._serial is not None and self._serial.is_open
+
+    # ==================== 内部方法 ====================
+
+    @staticmethod
+    def _calc_checksum(data_str):
+        """计算和校验码.
+
+        Args:
+            data_str: 待校验的ASCII字符串.
+
+        Returns:
+            str: 两位十六进制大写校验码.
+        """
+        total = sum(ord(c) for c in data_str)
+        return f"{total & 0xFF:02X}"
+
+    def _format_bit_address(self, device, addr):
+        """格式化位元件地址.
+
+        Args:
+            device: 位元件类型, 如 'X', 'Y', 'M'.
+            addr: 十进制地址值.
+
+        Returns:
+            str: 格式化后的地址字符串, 如 'X0001'.
+
+        Raises:
+            ValueError: 当元件类型不支持时抛出.
+        """
+        if device.upper() not in self.BIT_DEVICES:
+            raise ValueError(f"不支持的位元件类型: {device}")
+        return f"{device.upper()}{addr:04d}"
+
+    def _format_word_address(self, device, addr):
+        """格式化字元件地址.
+
+        Args:
+            device: 字元件类型, 如 'D', 'T', 'C'.
+            addr: 十进制地址值.
+
+        Returns:
+            str: 格式化后的地址字符串, 如 'D0123'.
+
+        Raises:
+            ValueError: 当元件类型不支持时抛出.
+        """
+        if device.upper() not in self.WORD_DEVICES:
+            raise ValueError(f"不支持的字元件类型: {device}")
+        return f"{device.upper()}{addr:04d}"
+
+    def _send_and_receive(self, cmd_body, expect_stx=False):
+        """发送命令并接收PLC响应.
+
+        Args:
+            cmd_body: ENQ之后、校验码之前的命令体字符串.
+            expect_stx: 是否期望STX开头的数据响应(读操作), False则期望ACK(写操作).
+
+        Returns:
+            str or bool: 读操作返回响应数据字符串, 写操作返回True/False.
+
+        Raises:
+            RuntimeError: 当串口未打开时抛出.
+        """
+        if not self.is_connected():
+            raise RuntimeError("串口未打开, 请先调用 open()")
+
+        checksum = self._calc_checksum(cmd_body)
+        full_cmd = self.ENQ + cmd_body.encode('ascii') + checksum.encode('ascii')
+
+        self._serial.reset_input_buffer()
+        self._serial.write(full_cmd)
+
+        if expect_stx:
+            return self._read_stx_response()
+        else:
+            return self._read_ack_response()
+
+    def _read_stx_response(self):
+        """读取STX开头的多字节响应帧.
+
+        Returns:
+            str or None: 解码后的响应数据字符串, 收到NAK或解析失败返回None.
+        """
+        stx = self._serial.read(1)
+        if stx == self.NAK:
+            _ = self._serial.read(4)
+            return None
+        if stx != self.STX:
+            return None
+
+        buffer = bytearray()
+        while True:
+            ch = self._serial.read(1)
+            if not ch or ch == self.ETX:
+                break
+            buffer.extend(ch)
+
+        _ = self._serial.read(2)  # 丢弃校验码
+        return buffer.decode('ascii')
+
+    def _read_ack_response(self):
+        """读取ACK/NAK响应.
+
+        Returns:
+            bool: ACK返回True, NAK或超时返回False.
+        """
+        ack = self._serial.read(1)
+        if ack == self.ACK:
+            _ = self._serial.read(4)
+            return True
+        elif ack == self.NAK:
+            _ = self._serial.read(4)
+            return False
+        return False
+
+    # ==================== 位元件读写 ====================
+
+    def read_bits(self, device, start_addr, count, delay='A'):
+        """批量读取位元件 (BR指令), BR: bit read.
+
+        Args:
+            device: 位元件类型, 'X'/'Y'/'M'/'S'/'T'/'C'.
+            start_addr: 起始地址(十进制).
+            count: 读取数量.
+            delay: 消息等待时间, '0'-'F' 对应 0-150ms, 默认'A'(100ms).
+
+        Returns:
+            str or None: 成功返回由'0'和'1'组成的位状态字符串, 失败返回None.
+        """
+        addr_str = self._format_bit_address(device, start_addr)
+        cmd_body = f"{self.station}FFBR{delay}{addr_str}{count:02X}"
+
+        response = self._send_and_receive(cmd_body, expect_stx=True)
+        if response is None or not isinstance(response, str):
+            return None
+        return response[4:]  # 去掉 station(2) + PLC_No(2)
+
+    def write_bits(self, device, start_addr, values, delay='A'):
+        """批量写入位元件 (BW指令).
+
+        Args:
+            device: 位元件类型, 'Y'/'M'/'S'/'T'/'C'.
+            start_addr: 起始地址(十进制).
+            values: 写入值, 字符串(如'10101')或列表(如[1,0,1,0,1]).
+            delay: 消息等待时间, '0'-'F' 对应 0-150ms.
+
+        Returns:
+            bool: True表示写入成功, False表示失败.
+        """
+        if isinstance(values, (list, tuple)):
+            values = ''.join('1' if v else '0' for v in values)
+
+        count = len(values)
+        addr_str = self._format_bit_address(device, start_addr)
+        cmd_body = f"{self.station}FFBW{delay}{addr_str}{count:02X}{values}"
+
+        return self._send_and_receive(cmd_body, expect_stx=False)
+
+    def read_bit(self, device, addr, delay='A'):
+        """读取单个位元件状态.
+
+        Args:
+            device: 位元件类型, 'X'/'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            bool or None: True(ON) / False(OFF), 失败返回None.
+        """
+        result = self.read_bits(device, addr, 1, delay)
+        if result is None or len(result) == 0:
+            return None
+        return result[0] == '1'
+
+    def write_bit(self, device, addr, value, delay='A'):
+        """写入单个位元件.
+
+        Args:
+            device: 位元件类型, 'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+            value: True/1 为ON, False/0 为OFF.
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            bool: True表示写入成功, False表示失败.
+        """
+        val_str = '1' if value else '0'
+        return self.write_bits(device, addr, val_str, delay)
+
+    def force_on(self, device, addr, delay='A'):
+        """强制置位 (等同于write_bit ON).
+
+        Args:
+            device: 位元件类型, 'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            bool: True表示操作成功, False表示失败.
+        """
+        return self.write_bit(device, addr, True, delay)
+
+    def force_off(self, device, addr, delay='A'):
+        """强制复位 (等同于write_bit OFF).
+
+        Args:
+            device: 位元件类型, 'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            bool: True表示操作成功, False表示失败.
+        """
+        return self.write_bit(device, addr, False, delay)
+
+    # ==================== 字元件读写 ====================
+
+    def read_words(self, device, start_addr, count, delay='A'):
+        """批量读取字元件 (WR指令).
+
+        Args:
+            device: 字元件类型, 'D'/'T'/'C'/'R'.
+            start_addr: 起始地址(十进制).
+            count: 读取的字数量.
+            delay: 消息等待时间, '0'-'F' 对应 0-150ms.
+
+        Returns:
+            list[int] or None: 成功返回整数列表(0-65535), 失败返回None.
+        """
+        addr_str = self._format_word_address(device, start_addr)
+        cmd_body = f"{self.station}FFWR{delay}{addr_str}{count:02X}"
+
+        response = self._send_and_receive(cmd_body, expect_stx=True)
+        if response is None or not isinstance(response, str):
+            return None
+
+        data = response[4:]  # 去掉 station(2) + PLC_No(2)
+        result = []
+        for i in range(0, len(data), 4):
+            if i + 4 <= len(data):
+                result.append(int(data[i:i + 4], 16))
+        return result
+
+    def write_words(self, device, start_addr, values, delay='A'):
+        """批量写入字元件 (WW指令).
+
+        Args:
+            device: 字元件类型, 'D'/'T'/'C'/'R'.
+            start_addr: 起始地址(十进制).
+            values: 写入值列表, 每个值范围0-65535.
+            delay: 消息等待时间, '0'-'F' 对应 0-150ms.
+
+        Returns:
+            bool: True表示写入成功, False表示失败.
+        """
+        addr_str = self._format_word_address(device, start_addr)
+        count = len(values)
+        data_str = ''.join(f"{v & 0xFFFF:04X}" for v in values)
+        cmd_body = f"{self.station}FFWW{delay}{addr_str}{count:02X}{data_str}"
+
+        return self._send_and_receive(cmd_body, expect_stx=False)
+
+    def read_word(self, device, addr, delay='A'):
+        """读取单个字元件.
+
+        Args:
+            device: 字元件类型, 'D'/'T'/'C'/'R'.
+            addr: 元件地址(十进制).
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            int or None: 成功返回0-65535的整数值, 失败返回None.
+        """
+        result = self.read_words(device, addr, 1, delay)
+        if result is None or len(result) == 0:
+            return None
+        return result[0]
+
+    def write_word(self, device, addr, value, delay='A'):
+        """写入单个字元件.
+
+        Args:
+            device: 字元件类型, 'D'/'T'/'C'/'R'.
+            addr: 元件地址(十进制).
+            value: 写入值, 范围0-65535.
+            delay: 消息等待时间, '0'-'F'.
+
+        Returns:
+            bool: True表示写入成功, False表示失败.
+        """
+        return self.write_words(device, addr, [value], delay)
+
+    # ==================== 编程口协议 (备用) ====================
+
+    def _calc_prog_port_address(self, device, addr):
+        """计算编程口协议中的地址值.
+
+        字元件: address = addr * 2 + 0x1000
+        位元件: address = addr // 8 + 0x0100
+
+        Args:
+            device: 元件类型.
+            addr: 十进制地址.
+
+        Returns:
+            int: 编程口协议使用的十六进制地址值.
+        """
+        if device.upper() in self.WORD_DEVICES:
+            return addr * 2 + 0x1000
+        else:
+            return addr // 8 + 0x0100
+
+    def read_device_raw(self, device, addr, byte_count):
+        """使用编程口协议读取设备 (命令码 '0').
+
+        Args:
+            device: 元件类型, 如 'D', 'M', 'X', 'Y'.
+            addr: 地址(十进制).
+            byte_count: 读取字节数.
+
+        Returns:
+            str or None: 成功返回响应数据字符串, 失败返回None.
+        """
+        addr_val = self._calc_prog_port_address(device, addr)
+        addr_hex = f"{addr_val:04X}"
+        bytes_hex = f"{byte_count:02X}"
+
+        body = '0' + addr_hex + bytes_hex + chr(0x03)
+        checksum = self._calc_checksum(body)
+        full_cmd = self.STX + body.encode('ascii') + checksum.encode('ascii')
+
+        self._serial.reset_input_buffer()
+        self._serial.write(full_cmd)
+
+        return self._read_stx_response()
+
+    def write_device_raw(self, device, addr, byte_count, data_str):
+        """使用编程口协议写入设备 (命令码 '1').
+
+        Args:
+            device: 元件类型, 如 'D', 'M', 'X', 'Y'.
+            addr: 地址(十进制).
+            byte_count: 写入字节数.
+            data_str: 写入数据(ASCII十六进制字符串).
+
+        Returns:
+            bool: True表示写入成功, False表示失败.
+        """
+        addr_val = self._calc_prog_port_address(device, addr)
+        addr_hex = f"{addr_val:04X}"
+        bytes_hex = f"{byte_count:02X}"
+
+        body = '1' + addr_hex + bytes_hex + data_str + chr(0x03)
+        checksum = self._calc_checksum(body)
+        full_cmd = self.STX + body.encode('ascii') + checksum.encode('ascii')
+
+        self._serial.reset_input_buffer()
+        self._serial.write(full_cmd)
+
+        ack = self._serial.read(1)
+        return ack == self.ACK
+
+    def force_on_raw(self, device, addr):
+        """使用编程口协议强制置位 (命令码 '7').
+
+        Args:
+            device: 位元件类型, 'X'/'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+
+        Returns:
+            bool: True表示操作成功, False表示失败.
+        """
+        addr_val = self._calc_prog_port_address(device, addr)
+        addr_hex = f"{addr_val:04X}"
+
+        body = '7' + addr_hex + chr(0x03)
+        checksum = self._calc_checksum(body)
+        full_cmd = self.STX + body.encode('ascii') + checksum.encode('ascii')
+
+        self._serial.reset_input_buffer()
+        self._serial.write(full_cmd)
+
+        ack = self._serial.read(1)
+        return ack == self.ACK
+
+    def force_off_raw(self, device, addr):
+        """使用编程口协议强制复位 (命令码 '8').
+
+        Args:
+            device: 位元件类型, 'X'/'Y'/'M'/'S'/'T'/'C'.
+            addr: 元件地址(十进制).
+
+        Returns:
+            bool: True表示操作成功, False表示失败.
+        """
+        addr_val = self._calc_prog_port_address(device, addr)
+        addr_hex = f"{addr_val:04X}"
+
+        body = '8' + addr_hex + chr(0x03)
+        checksum = self._calc_checksum(body)
+        full_cmd = self.STX + body.encode('ascii') + checksum.encode('ascii')
+
+        self._serial.reset_input_buffer()
+        self._serial.write(full_cmd)
+
+        ack = self._serial.read(1)
+        return ack == self.ACK

serialpro-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "serialpro"
+version = "0.1.0"
+description = "串口封装"
+authors = [
+    {name = "LiuWei",email = "183074632@qq.com"}
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pyserial (>=3.5,<4.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"