modbus-sim 0.1.0__py3-none-any.whl

modbus_sim/client.py

@@ -0,0 +1,257 @@
+"""A small Modbus master for trying the simulator out (and for its own CLI).
+
+::
+
+    from modbus_sim.client import ModbusClient
+    with ModbusClient("127.0.0.1", 5020) as c:
+        c.read_holding_registers(100, 2, unit=3)        # -> [status, frequency]
+        c.write_register(0, 1, unit=3)
+
+``ModbusClient.serial("/dev/pts/7")`` talks RTU on a serial line or pty instead, and
+``framing="rtu"`` speaks RTU over TCP. It is deliberately minimal: one request at a
+time, no retries. For real projects use pymodbus or similar.
+"""
+from __future__ import annotations
+
+import os
+import select
+import socket
+import struct
+import sys
+import time
+
+from . import frame
+
+EXCEPTIONS = {
+    1: "illegal function", 2: "illegal data address", 3: "illegal data value",
+    4: "server device failure", 5: "acknowledge", 6: "server device busy",
+    8: "memory parity error", 10: "gateway path unavailable",
+    11: "gateway target device failed to respond",
+}
+
+
+class ModbusError(Exception):
+    """The device answered with an exception code."""
+
+    def __init__(self, function: int, code: int):
+        self.function, self.code = function, code
+        super().__init__(f"function {function:#04x}: exception {code:#04x} "
+                         f"({EXCEPTIONS.get(code, 'unknown')})")
+
+
+class ProtocolError(Exception):
+    """The answer did not fit the request (wrong transaction, unit, CRC, length)."""
+
+
+class ModbusClient:
+    def __init__(self, host: str = "127.0.0.1", port: int = 5020, timeout: float = 2.0,
+                 framing: str = "tcp"):
+        if framing not in ("tcp", "rtu"):
+            raise ValueError("framing is tcp or rtu")
+        self.host, self.port, self.timeout, self.framing = host, port, timeout, framing
+        self._sock: socket.socket | None = None
+        self._fd: int | None = None
+        self._serial = None
+        self._transaction = 0
+
+    @classmethod
+    def serial(cls, path: str, baudrate: int = 19200, parity: str = "E",
+               timeout: float = 2.0) -> "ModbusClient":
+        client = cls(timeout=timeout, framing="rtu")
+        client.host, client.port = path, None
+        client._serial_args = (baudrate, parity)
+        return client
+
+    # --- connection ---
+
+    def connect(self) -> "ModbusClient":
+        if self.port is None:
+            self._open_serial(self.host, *self._serial_args)
+        else:
+            self._sock = socket.create_connection((self.host, self.port), timeout=self.timeout)
+            self._sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        return self
+
+    def _open_serial(self, path: str, baudrate: int, parity: str) -> None:
+        if is_pty(path):
+            import tty
+            self._fd = os.open(path, os.O_RDWR | os.O_NOCTTY)
+            tty.setraw(self._fd)
+            return
+        try:
+            import serial  # type: ignore[import-untyped]
+        except ImportError:
+            raise OSError("a serial port needs pyserial: pip install 'modbus-sim[serial]'"
+                          ) from None
+        self._serial = serial.Serial(path, baudrate, parity=parity, timeout=self.timeout)
+
+    def close(self) -> None:
+        if self._sock is not None:
+            self._sock.close()
+            self._sock = None
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+        if self._serial is not None:
+            self._serial.close()
+            self._serial = None
+
+    def __enter__(self) -> "ModbusClient":
+        if self._sock is None and self._fd is None and self._serial is None:
+            self.connect()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # --- raw I/O ---
+
+    def _send(self, data: bytes) -> None:
+        if self._sock is not None:
+            self._sock.sendall(data)
+        elif self._fd is not None:
+            os.write(self._fd, data)
+        elif self._serial is not None:
+            self._serial.write(data)
+        else:
+            raise OSError("not connected")
+
+    def _recv(self, n: int, deadline: float) -> bytes:
+        data = b""
+        while len(data) < n:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise TimeoutError("no (complete) answer")
+            if self._sock is not None:
+                self._sock.settimeout(left)
+                try:
+                    chunk = self._sock.recv(n - len(data))
+                except socket.timeout:
+                    raise TimeoutError("no (complete) answer") from None
+                if not chunk:
+                    raise ConnectionError("connection closed by the device")
+            elif self._fd is not None:
+                ready, _, _ = select.select([self._fd], [], [], left)
+                chunk = os.read(self._fd, n - len(data)) if ready else b""
+            else:
+                self._serial.timeout = left
+                chunk = self._serial.read(n - len(data))
+            data += chunk
+        return data
+
+    def request(self, pdu: bytes, unit: int = 1) -> bytes:
+        """Send a request PDU, return the response PDU; raises ModbusError on an exception."""
+        deadline = time.monotonic() + self.timeout
+        if self.framing == "tcp":
+            self._transaction = (self._transaction + 1) & 0xFFFF
+            self._send(frame.mbap(self._transaction, unit, pdu))
+            transaction, protocol, length, answered = frame.parse_mbap(
+                self._recv(frame.MBAP_LEN, deadline))
+            body = self._recv(length - 1, deadline)
+            if transaction != self._transaction or protocol != 0:
+                raise ProtocolError(f"answer has transaction {transaction}, "
+                                    f"expected {self._transaction}")
+            if answered != unit:
+                raise ProtocolError(f"answer from unit {answered}, expected {unit}")
+        else:
+            self._discard_input()
+            self._send(frame.add_crc(bytes([unit]) + pdu))
+            if unit == 0:
+                return b""  # broadcast: nobody answers
+            packet = self._recv(3, deadline)
+            total = frame.response_length(packet)
+            if total is None:
+                raise ProtocolError(f"cannot frame the answer {packet.hex()}")
+            packet += self._recv(total - 3, deadline)
+            if not frame.check_crc(packet):
+                raise ProtocolError("CRC error in the answer")
+            if packet[0] != unit:
+                raise ProtocolError(f"answer from unit {packet[0]}, expected {unit}")
+            body = packet[1:-2]
+        if body and body[0] == (pdu[0] | 0x80):
+            raise ModbusError(pdu[0], body[1] if len(body) > 1 else 0)
+        if not body or body[0] != pdu[0]:
+            raise ProtocolError(f"unexpected answer {body.hex()}")
+        return body
+
+    def _discard_input(self) -> None:
+        """Drop left-overs of an earlier, broken answer before a new RTU request."""
+        if self._sock is not None:
+            self._sock.setblocking(False)
+            try:
+                while self._sock.recv(512):
+                    pass
+            except (BlockingIOError, OSError):
+                pass
+            finally:
+                self._sock.setblocking(True)
+        elif self._fd is not None:
+            while select.select([self._fd], [], [], 0)[0]:
+                if not os.read(self._fd, 512):
+                    break
+        elif self._serial is not None:
+            self._serial.reset_input_buffer()
+
+    # --- function codes ---
+
+    def _read_bits(self, function: int, address: int, count: int, unit: int) -> list[bool]:
+        body = self.request(struct.pack(">BHH", function, address, count), unit)
+        data = body[2:]
+        return [bool(data[i // 8] >> (i % 8) & 1) for i in range(count)]
+
+    def read_coils(self, address: int, count: int = 1, unit: int = 1) -> list[bool]:
+        return self._read_bits(1, address, count, unit)
+
+    def read_discrete_inputs(self, address: int, count: int = 1, unit: int = 1) -> list[bool]:
+        return self._read_bits(2, address, count, unit)
+
+    def _read_regs(self, function: int, address: int, count: int, unit: int) -> list[int]:
+        body = self.request(struct.pack(">BHH", function, address, count), unit)
+        if body[1] != 2 * count or len(body) != 2 + 2 * count:
+            raise ProtocolError(f"expected {count} registers, got {body[1] // 2}")
+        return list(struct.unpack(f">{count}H", body[2:]))
+
+    def read_holding_registers(self, address: int, count: int = 1, unit: int = 1) -> list[int]:
+        return self._read_regs(3, address, count, unit)
+
+    def read_input_registers(self, address: int, count: int = 1, unit: int = 1) -> list[int]:
+        return self._read_regs(4, address, count, unit)
+
+    def write_coil(self, address: int, value: bool, unit: int = 1) -> None:
+        self.request(struct.pack(">BHH", 5, address, 0xFF00 if value else 0), unit)
+
+    def write_register(self, address: int, value: int, unit: int = 1) -> None:
+        self.request(struct.pack(">BHH", 6, address, value & 0xFFFF), unit)
+
+    def write_coils(self, address: int, values: list[bool], unit: int = 1) -> None:
+        data = bytearray((len(values) + 7) // 8)
+        for i, value in enumerate(values):
+            if value:
+                data[i // 8] |= 1 << (i % 8)
+        self.request(struct.pack(">BHHB", 15, address, len(values), len(data)) + bytes(data),
+                     unit)
+
+    def write_registers(self, address: int, values: list[int], unit: int = 1) -> None:
+        self.request(struct.pack(f">BHHB{len(values)}H", 16, address, len(values),
+                                 2 * len(values), *[v & 0xFFFF for v in values]), unit)
+
+    def read_device_identification(self, unit: int = 1, code: int = 2) -> dict[int, str]:
+        """Objects 0.. (vendor, product code, revision, ...) as {id: text}."""
+        result: dict[int, str] = {}
+        object_id = 0
+        while True:
+            body = self.request(bytes([0x2B, 0x0E, code, object_id]), unit)
+            more, next_id, count = body[4], body[5], body[6]
+            offset = 7
+            for _ in range(count):
+                oid, length = body[offset], body[offset + 1]
+                result[oid] = body[offset + 2:offset + 2 + length].decode("latin-1")
+                offset += 2 + length
+            if more != 0xFF:
+                return result
+            object_id = next_id
+
+
+def is_pty(path: str) -> bool:
+    return sys.platform != "win32" and (path.startswith("/dev/pts/")
+                                        or path.startswith("/dev/ttys"))

modbus_sim/control.py

@@ -0,0 +1,207 @@
+"""Control channel of a running bench: inject faults, set and read values from outside.
+
+One JSON object per line in, one per line out. ``device`` is a device name or unit ID::
+
+    {"device": "vfd", "inject": "trip", "params": {"code": 7}}     -> {"ok": true}
+    {"device": "vfd", "clear": true}         (or "clear": "trip")  -> {"ok": true}
+    {"device": 3, "set": {"speed_reference": 25.0}}  (null = back to model/source)
+    {"device": "vfd", "get": ["output_frequency"]}   (or "get": true for all points)
+        -> {"ok": true, "values": {"output_frequency": 12.5}}
+    {"list": true} -> {"ok": true, "devices": {"vfd": {"unit": 3, "profile": "vfd",
+                                                      "faults": {...}, "requests": 12}}}
+
+Anything invalid gets ``{"ok": false, "error": "..."}``; the connection stays open.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import socket
+import socketserver
+import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .bench import Bench
+    from .device import Device, Point
+
+CONTROL_PORT = 5021
+_MAX_LINE = 65536
+
+
+class _Handler(socketserver.StreamRequestHandler):
+    def setup(self) -> None:
+        super().setup()
+        self.server.connections.add(self.request)
+
+    def finish(self) -> None:
+        self.server.connections.discard(self.request)
+        super().finish()
+
+    def handle(self) -> None:
+        try:
+            while True:
+                raw = self.rfile.readline(_MAX_LINE)
+                if not raw:
+                    return
+                if len(raw) >= _MAX_LINE and not raw.endswith(b"\n"):
+                    self.wfile.write(json.dumps({"ok": False, "error": "line too long"})
+                                     .encode() + b"\n")
+                    self.wfile.flush()
+                    self.request.shutdown(socket.SHUT_WR)
+                    return
+                if not raw.strip():
+                    continue
+                answer = self.server.control.handle(raw)
+                self.wfile.write(json.dumps(answer).encode() + b"\n")
+        except OSError:
+            return
+
+
+class _Server(socketserver.ThreadingTCPServer):
+    daemon_threads = True
+    allow_reuse_address = os.name != "nt"
+
+    def __init__(self, address, handler):
+        self.address_family = socket.getaddrinfo(address[0], address[1],
+                                                 type=socket.SOCK_STREAM)[0][0]
+        self.connections: set[socket.socket] = set()
+        super().__init__(address, handler)
+
+
+class ControlServer:
+    def __init__(self, bench: "Bench", host: str = "127.0.0.1", port: int = CONTROL_PORT):
+        self.bench, self.host, self.port = bench, host, port
+        self._server: _Server | None = None
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> int:
+        self._server = _Server((self.host, self.port), _Handler)
+        self._server.control = self
+        self.port = self._server.server_address[1]
+        self._thread = threading.Thread(target=self._server.serve_forever,
+                                        kwargs={"poll_interval": 0.05}, daemon=True,
+                                        name="modbus-sim-control")
+        self._thread.start()
+        return self.port
+
+    def stop(self) -> None:
+        if self._server is None:
+            return
+        self._server.shutdown()
+        self._server.server_close()
+        for connection in list(self._server.connections):
+            try:
+                connection.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+        self._thread.join(timeout=5)
+        self._server = self._thread = None
+
+    def handle(self, raw: bytes | str) -> dict[str, Any]:
+        try:
+            request = json.loads(raw)
+            if not isinstance(request, dict):
+                raise ValueError("a request is a JSON object")
+            return self._handle(request)
+        except ValueError as error:  # includes JSONDecodeError and FaultError
+            return {"ok": False, "error": str(error)}
+        except Exception as error:  # never drop the connection with a traceback
+            return {"ok": False, "error": f"{type(error).__name__}: {error}"}
+
+    def _handle(self, request: dict) -> dict[str, Any]:
+        if request.get("list"):
+            return {"ok": True, "devices": {name: self._describe(dev)
+                                            for name, dev in self.bench.devices.items()}}
+        device = self.bench.find(request.get("device"))
+        if request.get("clear"):
+            kind = request["clear"]
+            if kind is True:
+                device.faults.clear()
+            elif isinstance(kind, str):
+                device.faults.clear(kind)
+            else:
+                raise ValueError("'clear' must be true or a fault name")
+        elif "inject" in request:
+            kind, params = request["inject"], request.get("params") or {}
+            if not isinstance(kind, str):
+                raise ValueError("'inject' must be a fault name")
+            if not isinstance(params, dict):
+                raise ValueError("'params' must be an object")
+            device.faults.inject(kind, **params)
+        elif "set" in request:
+            self._set(device, request["set"])
+        elif "get" in request:
+            return {"ok": True, "values": self._get(device, request["get"])}
+        else:
+            raise ValueError("a request needs 'list', 'clear', 'inject', 'set' or 'get'")
+        return {"ok": True}
+
+    @staticmethod
+    def _point(device: "Device", name: Any) -> "Point":
+        point = device.points.get(name) if isinstance(name, str) else None
+        if point is None:
+            raise ValueError(f"{device.name} has no point {name!r} "
+                             f"(points: {', '.join(device.points)})")
+        return point
+
+    def _set(self, device: "Device", values: Any) -> None:
+        if not isinstance(values, dict) or not values:
+            raise ValueError("'set' must be a non-empty object like {\"setpoint\": 80}")
+        parsed = []
+        for name, value in values.items():
+            point = self._point(device, name)
+            kind = point.spec.type
+            if value is None:
+                pass
+            elif kind == "string":
+                if not isinstance(value, str):
+                    raise ValueError(f"{name}: expected a string")
+            elif kind == "bool":
+                if not isinstance(value, bool):
+                    raise ValueError(f"{name}: expected true or false")
+            elif isinstance(value, bool) or not isinstance(value, (int, float)) \
+                    or not math.isfinite(value):
+                raise ValueError(f"{name}: expected a finite number or null")
+            parsed.append((point, value))
+        with device.lock:  # all or nothing, atomic against the Modbus side
+            for point, value in parsed:
+                if point.spec.model or point.signal is not None:
+                    point.override = value
+                elif value is not None:
+                    point.stored = value
+                if device.frozen is not None:
+                    device.frozen[point.name] = point.live()
+
+    def _get(self, device: "Device", names: Any) -> dict[str, Any]:
+        if names is True:
+            names = list(device.points)
+        if not isinstance(names, list):
+            raise ValueError("'get' must be true or a list of point names")
+        with device.lock:
+            result = {}
+            for name in names:
+                value = self._point(device, name).value()
+                if isinstance(value, float) and not math.isfinite(value):
+                    value = str(value)  # JSON has no inf/nan
+                result[name] = value
+            return result
+
+    @staticmethod
+    def _describe(device: "Device") -> dict[str, Any]:
+        return {"unit": device.unit, "profile": device.profile.name,
+                "faults": device.faults.snapshot(), "requests": device.requests}
+
+
+def send_control(request: dict, host: str = "127.0.0.1", port: int = CONTROL_PORT,
+                 timeout: float = 2.0) -> dict:
+    """Send one request to a bench's control port; raises OSError if it cannot be reached."""
+    with socket.create_connection((host, port), timeout=timeout) as sock, \
+            sock.makefile("rwb") as stream:
+        stream.write(json.dumps(request).encode() + b"\n")
+        stream.flush()
+        line = stream.readline()
+    if not line:
+        raise OSError("control port closed the connection")
+    return json.loads(line)

modbus_sim/datatypes.py

@@ -0,0 +1,123 @@
+"""Values <-> 16-bit registers, with the word and byte orders found in real devices.
+
+Word order names follow the usual convention for a 32-bit value whose big-endian
+bytes are A B C D:
+
+=====  ===============  ================================================
+order  registers        seen in
+=====  ===============  ================================================
+ABCD   [AB, CD]         the Modbus default (big endian), most PLCs
+CDAB   [CD, AB]         word-swapped: many energy meters, Schneider, Eastron
+BADC   [BA, DC]         byte-swapped
+DCBA   [DC, BA]         little endian
+=====  ===============  ================================================
+
+64-bit values extend the same rule (word order and byte order). Only types of
+32 bits or more are affected; 16-bit types are always one plain register.
+"""
+from __future__ import annotations
+
+import math
+import struct
+
+WORD_ORDERS = ("ABCD", "CDAB", "BADC", "DCBA")
+
+# type -> (struct format, registers)
+_NUMERIC = {
+    "uint16": (">H", 1), "int16": (">h", 1),
+    "uint32": (">I", 2), "int32": (">i", 2), "float32": (">f", 2),
+    "uint64": (">Q", 4), "int64": (">q", 4), "float64": (">d", 4),
+}
+_RANGES = {
+    "uint16": (0, 0xFFFF), "int16": (-0x8000, 0x7FFF),
+    "uint32": (0, 0xFFFFFFFF), "int32": (-0x80000000, 0x7FFFFFFF),
+    "uint64": (0, 0xFFFFFFFFFFFFFFFF), "int64": (-(1 << 63), (1 << 63) - 1),
+}
+REGISTER_TYPES = (*_NUMERIC, "string")
+BIT_TYPES = ("bool",)
+TYPES = REGISTER_TYPES + BIT_TYPES
+
+
+def is_integer(kind: str) -> bool:
+    return kind in _RANGES
+
+
+def is_float(kind: str) -> bool:
+    return kind in ("float32", "float64")
+
+
+def registers(kind: str, length: int | None = None) -> int:
+    """Number of registers a value of `kind` occupies (`length` for strings)."""
+    if kind == "string":
+        if not length or length < 1:
+            raise ValueError("a string needs a length in registers")
+        return length
+    if kind in _NUMERIC:
+        return _NUMERIC[kind][1]
+    raise ValueError(f"{kind!r} is not a register type")
+
+
+def _order(raw: bytes, order: str) -> bytes:
+    if len(raw) <= 2 or order == "ABCD":
+        return raw
+    words = [raw[i:i + 2] for i in range(0, len(raw), 2)]
+    if order in ("CDAB", "DCBA"):
+        words.reverse()
+    if order in ("BADC", "DCBA"):
+        words = [w[::-1] for w in words]
+    return b"".join(words)
+
+
+def _to_words(raw: bytes) -> list[int]:
+    return list(struct.unpack(f">{len(raw) // 2}H", raw))
+
+
+def _from_words(words: list[int]) -> bytes:
+    return struct.pack(f">{len(words)}H", *words)
+
+
+def saturate(kind: str, raw: float) -> int:
+    """Round and clamp to the integer type's range (devices saturate rather than wrap)."""
+    low, high = _RANGES[kind]
+    if math.isnan(raw):
+        return 0
+    if math.isinf(raw):
+        return high if raw > 0 else low
+    return int(min(max(round(raw), low), high))
+
+
+def encode(value, kind: str, order: str = "ABCD", scale: float = 1.0,
+           length: int | None = None) -> list[int]:
+    """Engineering value -> registers. Integers are value/scale, rounded and clamped."""
+    if kind == "string":
+        data = str(value).encode("latin-1", "replace")[:2 * length]
+        return _to_words(data.ljust(2 * length, b"\0"))
+    fmt, _ = _NUMERIC[kind]
+    if is_float(kind):
+        raw = float(value) / scale
+        if kind == "float32" and math.isfinite(raw) and abs(raw) > 3.4028234663852886e38:
+            raw = math.copysign(math.inf, raw)
+        data = struct.pack(fmt, raw)
+    else:
+        data = struct.pack(fmt, saturate(kind, float(value) / scale))
+    return _to_words(_order(data, order))
+
+
+def decode(words: list[int], kind: str, order: str = "ABCD", scale: float = 1.0):
+    """Registers -> engineering value (inverse of :func:`encode`)."""
+    data = _from_words(words)
+    if kind == "string":
+        return data.rstrip(b"\0").decode("latin-1")
+    fmt, _ = _NUMERIC[kind]
+    raw = struct.unpack(fmt, _order(data, order))[0]
+    if scale == 1.0:
+        return raw if is_integer(kind) else float(raw)
+    return raw * scale
+
+
+def fits(value: float, kind: str, scale: float = 1.0) -> bool:
+    """True if `value` can be written to an integer register of `kind` without clamping."""
+    if not is_integer(kind):
+        return True
+    low, high = _RANGES[kind]
+    return low <= round(value / scale) <= high