fieldsim 0.2.0__py3-none-any.whl

fieldsim/core/types.py

@@ -0,0 +1,133 @@
+"""Numeric data types and their encoding into 16-bit registers.
+
+Industrial protocols move data around as 16-bit words. A ``float32`` occupies two
+words, an ``int64`` four, and vendors disagree about the order of bytes inside a
+word and of words inside a value. This module is the single place that knows how
+to turn Python numbers into words and back.
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+from collections.abc import Sequence
+from typing import Literal, get_args
+
+RegisterType = Literal[
+    "int16", "uint16", "int32", "uint32", "int64", "uint64", "float32", "float64"
+]
+"""Data type of a register-backed point."""
+
+Order = Literal["big", "little"]
+"""Byte order inside a word, or word order inside a multi-word value."""
+
+REGISTER_TYPES: tuple[RegisterType, ...] = get_args(RegisterType)
+
+_STRUCT_FORMAT: dict[RegisterType, str] = {
+    "int16": "h",
+    "uint16": "H",
+    "int32": "i",
+    "uint32": "I",
+    "int64": "q",
+    "uint64": "Q",
+    "float32": "f",
+    "float64": "d",
+}
+
+INTEGER_RANGES: dict[RegisterType, tuple[int, int]] = {
+    "int16": (-(2**15), 2**15 - 1),
+    "uint16": (0, 2**16 - 1),
+    "int32": (-(2**31), 2**31 - 1),
+    "uint32": (0, 2**32 - 1),
+    "int64": (-(2**63), 2**63 - 1),
+    "uint64": (0, 2**64 - 1),
+}
+
+FLOAT32_MAX = 3.4028234663852886e38
+
+Number = int | float
+
+
+def register_count(data_type: RegisterType) -> int:
+    """Number of 16-bit registers a value of ``data_type`` occupies."""
+    return struct.calcsize(">" + _STRUCT_FORMAT[data_type]) // 2
+
+
+def is_integer_type(data_type: RegisterType) -> bool:
+    return data_type in INTEGER_RANGES
+
+
+def coerce(value: Number, data_type: RegisterType, *, clamp: bool = False) -> Number:
+    """Validate ``value`` for ``data_type`` and return it in canonical form.
+
+    With ``clamp=False`` (user supplied values) anything that does not fit raises
+    :class:`ValueError`. With ``clamp=True`` (generator output) floats are rounded
+    and out-of-range values are saturated to the type limits, the way a real
+    device's ADC or scaling block would.
+    """
+    if isinstance(value, bool):
+        value = int(value)
+    if not isinstance(value, int | float):
+        raise TypeError(f"expected a number, got {type(value).__name__}")
+
+    if data_type in INTEGER_RANGES:
+        lo, hi = INTEGER_RANGES[data_type]
+        if isinstance(value, float):
+            if math.isnan(value):
+                raise ValueError(f"NaN cannot be stored as {data_type}")
+            if math.isinf(value):
+                if not clamp:
+                    raise ValueError(f"{value} cannot be stored as {data_type}")
+                return hi if value > 0 else lo
+            if clamp:
+                value = round(value)
+            elif not value.is_integer():
+                raise ValueError(f"{value} is not a whole number, but {data_type} requires one")
+            value = int(value)
+        if lo <= value <= hi:
+            return value
+        if clamp:
+            return max(lo, min(hi, value))
+        raise ValueError(f"{value} is out of range for {data_type} [{lo}, {hi}]")
+
+    result = float(value)
+    if data_type == "float32" and math.isfinite(result) and abs(result) > FLOAT32_MAX:
+        if clamp:
+            return math.copysign(FLOAT32_MAX, result)
+        raise ValueError(f"{value} is out of range for float32")
+    return result
+
+
+def encode(
+    value: Number,
+    data_type: RegisterType,
+    byte_order: Order = "big",
+    word_order: Order = "big",
+) -> list[int]:
+    """Encode ``value`` into a list of 16-bit register values."""
+    raw = struct.pack(">" + _STRUCT_FORMAT[data_type], coerce(value, data_type))
+    words = [raw[i : i + 2] for i in range(0, len(raw), 2)]
+    if word_order == "little":
+        words.reverse()
+    if byte_order == "little":
+        words = [w[::-1] for w in words]
+    return [int.from_bytes(w, "big") for w in words]
+
+
+def decode(
+    words: Sequence[int],
+    data_type: RegisterType,
+    byte_order: Order = "big",
+    word_order: Order = "big",
+) -> Number:
+    """Decode 16-bit register values back into a Python number."""
+    expected = register_count(data_type)
+    if len(words) != expected:
+        raise ValueError(f"{data_type} needs {expected} registers, got {len(words)}")
+    chunks = [w.to_bytes(2, "big") for w in words]
+    if byte_order == "little":
+        chunks = [c[::-1] for c in chunks]
+    if word_order == "little":
+        chunks.reverse()
+    (value,) = struct.unpack(">" + _STRUCT_FORMAT[data_type], b"".join(chunks))
+    return value  # type: ignore[no-any-return]

fieldsim/protocols/modbus/__init__.py

@@ -0,0 +1,18 @@
+"""Modbus TCP simulation."""
+
+from fieldsim.protocols.modbus.constants import ExceptionCode, FunctionCode, ModbusError
+from fieldsim.protocols.modbus.datastore import ModbusDataStore, PointLayout, Table, WriteEvent
+from fieldsim.protocols.modbus.device import ModbusDevice
+from fieldsim.protocols.modbus.server import ModbusTcpServer
+
+__all__ = [
+    "ExceptionCode",
+    "FunctionCode",
+    "ModbusDataStore",
+    "ModbusDevice",
+    "ModbusError",
+    "ModbusTcpServer",
+    "PointLayout",
+    "Table",
+    "WriteEvent",
+]

fieldsim/protocols/modbus/constants.py

@@ -0,0 +1,42 @@
+"""Modbus function codes, exception codes and protocol limits."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class FunctionCode(IntEnum):
+    READ_COILS = 0x01
+    READ_DISCRETE_INPUTS = 0x02
+    READ_HOLDING_REGISTERS = 0x03
+    READ_INPUT_REGISTERS = 0x04
+    WRITE_SINGLE_COIL = 0x05
+    WRITE_SINGLE_REGISTER = 0x06
+    WRITE_MULTIPLE_COILS = 0x0F
+    WRITE_MULTIPLE_REGISTERS = 0x10
+
+
+class ExceptionCode(IntEnum):
+    ILLEGAL_FUNCTION = 0x01
+    ILLEGAL_DATA_ADDRESS = 0x02
+    ILLEGAL_DATA_VALUE = 0x03
+    SERVER_DEVICE_FAILURE = 0x04
+    SERVER_DEVICE_BUSY = 0x06
+    GATEWAY_PATH_UNAVAILABLE = 0x0A
+    GATEWAY_TARGET_FAILED = 0x0B
+
+
+class ModbusError(Exception):
+    """Aborts request processing and is answered with a Modbus exception response."""
+
+    def __init__(self, code: ExceptionCode, message: str = ""):
+        self.code = code
+        super().__init__(message or code.name)
+
+
+# Limits from the Modbus Application Protocol Specification V1.1b3.
+MAX_READ_BITS = 2000
+MAX_READ_REGISTERS = 125
+MAX_WRITE_BITS = 1968
+MAX_WRITE_REGISTERS = 123
+ADDRESS_SPACE = 65536

fieldsim/protocols/modbus/datastore.py

@@ -0,0 +1,203 @@
+"""Modbus memory: four tables of bits and 16-bit registers, addressable by point name."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from fieldsim.config import HoldingRegisterPoint, InputRegisterPoint, RegisterMap
+from fieldsim.core.datastore import PointNotFoundError, Value
+from fieldsim.core.types import Order, RegisterType, coerce, decode, encode, register_count
+from fieldsim.protocols.modbus.constants import ExceptionCode, ModbusError
+
+
+class Table(str, Enum):
+    COILS = "coils"
+    DISCRETE_INPUTS = "discrete_inputs"
+    HOLDING_REGISTERS = "holding_registers"
+    INPUT_REGISTERS = "input_registers"
+
+    @property
+    def is_bit(self) -> bool:
+        return self in (Table.COILS, Table.DISCRETE_INPUTS)
+
+
+@dataclass(frozen=True)
+class PointLayout:
+    name: str
+    table: Table
+    address: int
+    count: int
+    data_type: RegisterType | None
+    byte_order: Order
+    word_order: Order
+    writable: bool
+
+    @property
+    def addresses(self) -> range:
+        return range(self.address, self.address + self.count)
+
+
+@dataclass(frozen=True)
+class WriteEvent:
+    """A write performed by a Modbus client."""
+
+    table: Table
+    address: int
+    values: tuple[int, ...] | tuple[bool, ...]
+    points: tuple[str, ...]
+
+
+WriteListener = Callable[[WriteEvent], None]
+
+
+class ModbusDataStore:
+    """Single source of truth is the raw register/bit memory.
+
+    Named points are views over that memory, so a client writing half of a
+    ``float32`` behaves exactly as it would on real hardware.
+
+    Not thread-safe: use it from the event loop that runs the server.
+    """
+
+    def __init__(self, registers: RegisterMap, *, unmapped: Literal["error", "allow"] = "error"):
+        self._unmapped = unmapped
+        self._bits: dict[Table, dict[int, bool]] = {Table.COILS: {}, Table.DISCRETE_INPUTS: {}}
+        self._words: dict[Table, dict[int, int]] = {
+            Table.HOLDING_REGISTERS: {},
+            Table.INPUT_REGISTERS: {},
+        }
+        self._points: dict[str, PointLayout] = {}
+        self._owners: dict[Table, dict[int, PointLayout]] = {t: {} for t in Table}
+        self._listeners: list[WriteListener] = []
+
+        for coil in registers.coils:
+            self._add(Table.COILS, coil.name, coil.address, coil.value, writable=coil.writable)
+        for di in registers.discrete_inputs:
+            self._add(Table.DISCRETE_INPUTS, di.name, di.address, di.value, writable=False)
+        for hr in registers.holding_registers:
+            self._add(Table.HOLDING_REGISTERS, hr.name, hr.address, hr.value, hr, hr.writable)
+        for ir in registers.input_registers:
+            self._add(Table.INPUT_REGISTERS, ir.name, ir.address, ir.value, ir, writable=False)
+
+    def _add(
+        self,
+        table: Table,
+        name: str,
+        address: int,
+        value: Value,
+        reg: HoldingRegisterPoint | InputRegisterPoint | None = None,
+        writable: bool = True,
+    ) -> None:
+        layout = PointLayout(
+            name=name,
+            table=table,
+            address=address,
+            count=register_count(reg.type) if reg else 1,
+            data_type=reg.type if reg else None,
+            byte_order=reg.byte_order if reg else "big",
+            word_order=reg.word_order if reg else "big",
+            writable=writable,
+        )
+        self._points[name] = layout
+        for a in layout.addresses:
+            self._owners[table][a] = layout
+        self._store(layout, value)
+
+    # ------------------------------------------------------------------ by name
+
+    def names(self) -> list[str]:
+        return list(self._points)
+
+    def point(self, name: str) -> PointLayout:
+        try:
+            return self._points[name]
+        except KeyError:
+            raise PointNotFoundError(name, self._points) from None
+
+    def points(self) -> list[PointLayout]:
+        return list(self._points.values())
+
+    def get(self, name: str) -> Value:
+        layout = self.point(name)
+        if layout.data_type is None:
+            return self._bits[layout.table][layout.address]
+        words = [self._words[layout.table][a] for a in layout.addresses]
+        return decode(words, layout.data_type, layout.byte_order, layout.word_order)
+
+    def set(self, name: str, value: Value, *, clamp: bool = False) -> None:
+        layout = self.point(name)
+        if layout.data_type is not None:
+            value = coerce(value, layout.data_type, clamp=clamp)
+        self._store(layout, value)
+
+    def _store(self, layout: PointLayout, value: Value) -> None:
+        if layout.data_type is None:
+            self._bits[layout.table][layout.address] = bool(value)
+            return
+        words = encode(value, layout.data_type, layout.byte_order, layout.word_order)
+        table = self._words[layout.table]
+        for a, w in zip(layout.addresses, words, strict=True):
+            table[a] = w
+
+    # ------------------------------------------------------------------ raw access
+
+    def read_bits(self, table: Table, address: int, count: int) -> list[bool]:
+        if not table.is_bit:
+            raise ValueError(f"{table.value} is not a bit table")
+        self._check(table, address, count, writing=False)
+        bits = self._bits[table]
+        return [bits.get(a, False) for a in range(address, address + count)]
+
+    def read_registers(self, table: Table, address: int, count: int) -> list[int]:
+        if table.is_bit:
+            raise ValueError(f"{table.value} is not a register table")
+        self._check(table, address, count, writing=False)
+        words = self._words[table]
+        return [words.get(a, 0) for a in range(address, address + count)]
+
+    def write_coils(self, address: int, values: Sequence[bool]) -> None:
+        points = self._check(Table.COILS, address, len(values), writing=True)
+        bits = self._bits[Table.COILS]
+        for offset, value in enumerate(values):
+            bits[address + offset] = bool(value)
+        self._notify(WriteEvent(Table.COILS, address, tuple(bool(v) for v in values), points))
+
+    def write_registers(self, address: int, values: Sequence[int]) -> None:
+        points = self._check(Table.HOLDING_REGISTERS, address, len(values), writing=True)
+        words = self._words[Table.HOLDING_REGISTERS]
+        for offset, value in enumerate(values):
+            words[address + offset] = value & 0xFFFF
+        self._notify(WriteEvent(Table.HOLDING_REGISTERS, address, tuple(values), points))
+
+    def _check(self, table: Table, address: int, count: int, *, writing: bool) -> tuple[str, ...]:
+        """Validate a raw access and return the names of the points it touches."""
+        owners = self._owners[table]
+        touched: dict[str, None] = {}
+        for a in range(address, address + count):
+            owner = owners.get(a)
+            if owner is None:
+                if self._unmapped == "error":
+                    raise ModbusError(
+                        ExceptionCode.ILLEGAL_DATA_ADDRESS, f"{table.value}[{a}] is not mapped"
+                    )
+                continue
+            if writing and not owner.writable:
+                raise ModbusError(
+                    ExceptionCode.ILLEGAL_DATA_ADDRESS, f"{owner.name!r} is read-only"
+                )
+            touched[owner.name] = None
+        return tuple(touched)
+
+    # ------------------------------------------------------------------ events
+
+    def add_write_listener(self, listener: WriteListener) -> Callable[[], None]:
+        """Call ``listener`` after every client write. Returns a function that unsubscribes."""
+        self._listeners.append(listener)
+        return lambda: self._listeners.remove(listener)
+
+    def _notify(self, event: WriteEvent) -> None:
+        for listener in list(self._listeners):
+            listener(event)

fieldsim/protocols/modbus/device.py

@@ -0,0 +1,115 @@
+"""Modbus device: datastore + generators + faults + scenario + server."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+
+from fieldsim.config import CorruptFault, FaultSpec, ModbusDeviceSpec, check_corrupt_mode
+from fieldsim.core.clock import Clock
+from fieldsim.core.device import Device
+from fieldsim.core.generators import build_generator
+from fieldsim.protocols.modbus.datastore import ModbusDataStore, WriteEvent
+from fieldsim.protocols.modbus.framer import FRAMERS
+from fieldsim.protocols.modbus.server import ModbusTcpServer
+
+
+class ModbusDevice(Device[ModbusDataStore]):
+    """A virtual Modbus device built from a :class:`ModbusDeviceSpec`.
+
+    Besides the common :class:`Device` API it records every client write, so a
+    test can assert on what the software under test sent::
+
+        event = await device.wait_for_write("setpoint")
+        assert device.get("setpoint") == 80
+    """
+
+    def __init__(self, spec: ModbusDeviceSpec, *, clock: Clock | None = None):
+        self.protocol = spec.protocol
+        store = ModbusDataStore(spec.registers, unmapped=spec.unmapped)
+        generators = {
+            point.name: build_generator(point.generator)
+            for point in spec.registers.all_points()
+            if point.generator is not None
+        }
+        super().__init__(
+            spec.name,
+            store,
+            generators,
+            update_interval=spec.update_interval,
+            faults=spec.faults,
+            scenario=spec.scenario,
+            seed=spec.seed,
+            clock=clock,
+        )
+        self.spec = spec
+        self.server = ModbusTcpServer(
+            store,
+            host=spec.host,
+            port=spec.port,
+            unit_id=spec.unit_id,
+            framer=FRAMERS[spec.protocol](),
+            faults=self.faults,
+        )
+        self.writes: list[WriteEvent] = []
+        self._write_cursor = 0
+        self._write_signal = asyncio.Event()
+        store.add_write_listener(self._on_write)
+
+    @property
+    def host(self) -> str:
+        return self.server.host
+
+    @property
+    def port(self) -> int:
+        return self.server.port
+
+    @property
+    def unit_id(self) -> int:
+        """Unit id clients should use (1 when the device answers every unit id)."""
+        return 1 if self.spec.unit_id is None else self.spec.unit_id
+
+    async def _start_server(self) -> None:
+        await self.server.start()
+
+    async def _stop_server(self) -> None:
+        await self.server.stop()
+
+    def validate_fault(self, spec: FaultSpec) -> None:
+        if isinstance(spec, CorruptFault):
+            check_corrupt_mode(spec.mode, self.protocol)
+
+    # ------------------------------------------------------------------ write log
+
+    def _on_write(self, event: WriteEvent) -> None:
+        self.writes.append(event)
+        self._write_signal.set()
+
+    def clear_writes(self) -> None:
+        self.writes.clear()
+        self._write_cursor = 0
+
+    async def wait_for_write(self, point: str | None = None, timeout: float = 5.0) -> WriteEvent:
+        """Wait for a client write (touching ``point``, if given) and return it.
+
+        Writes are consumed in order: each call returns the next matching write
+        that no earlier call has returned, including writes that happened before
+        the call. Raises :class:`TimeoutError` if none arrives in time.
+        """
+        if point is not None:
+            self.store.point(point)  # validates the name
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            for index in range(self._write_cursor, len(self.writes)):
+                event = self.writes[index]
+                if point is None or point in event.points:
+                    self._write_cursor = index + 1
+                    return event
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                target = f"to {point!r} " if point else ""
+                raise TimeoutError(f"no write {target}within {timeout}s on {self.name!r}")
+            self._write_signal.clear()
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self._write_signal.wait(), remaining)