fieldsim 0.2.0__py3-none-any.whl

fieldsim/protocols/modbus/framer.py

@@ -0,0 +1,196 @@
+"""Modbus framings over a TCP stream.
+
+* :class:`TcpFramer` - native Modbus TCP (MBAP header, no checksum).
+* :class:`RtuFramer` - RTU frames tunnelled over TCP (unit id + PDU + CRC16), as
+  spoken by many serial-to-Ethernet gateways.
+
+Each framer also knows how to damage its own frames for fault injection.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+import struct
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+MBAP_HEADER = struct.Struct(">HHHB")
+"""transaction id, protocol id, length (unit id + PDU), unit id"""
+
+MAX_PDU_SIZE = 253
+
+
+class FramingError(Exception):
+    """The byte stream is not valid; the connection should be dropped."""
+
+
+@dataclass(frozen=True)
+class Frame:
+    unit_id: int
+    pdu: bytes
+    transaction_id: int | None = None
+
+
+def _flip_bit(data: bytes, start: int, end: int, rng: random.Random) -> bytearray:
+    out = bytearray(data)
+    if end > start:
+        index = rng.randrange(start, end)
+        out[index] ^= 1 << rng.randrange(8)
+    return out
+
+
+class Framer(ABC):
+    name: str
+
+    @abstractmethod
+    async def read_frame(self, reader: asyncio.StreamReader) -> Frame | None:
+        """Read one request. ``None`` means "discard and keep reading".
+
+        Raises ``asyncio.IncompleteReadError`` on EOF and :class:`FramingError`
+        when the stream cannot be resynchronised.
+        """
+
+    @abstractmethod
+    def encode(self, frame: Frame) -> bytes: ...
+
+    @abstractmethod
+    def corrupt(self, data: bytes, mode: str, rng: random.Random) -> bytes:
+        """Return a damaged copy of an encoded response."""
+
+    def _corrupt_common(self, data: bytes, mode: str, rng: random.Random) -> bytes | None:
+        if mode == "truncate":
+            return data[: rng.randint(1, len(data) - 1)]
+        if mode == "garbage":
+            return rng.randbytes(len(data))
+        return None
+
+
+# --------------------------------------------------------------------------- Modbus TCP
+
+
+class TcpFramer(Framer):
+    name = "tcp"
+
+    async def read_frame(self, reader: asyncio.StreamReader) -> Frame:
+        header = await reader.readexactly(MBAP_HEADER.size)
+        transaction_id, protocol_id, length, unit_id = MBAP_HEADER.unpack(header)
+        if protocol_id != 0:
+            raise FramingError(f"protocol id {protocol_id} is not Modbus (0)")
+        if not 2 <= length <= MAX_PDU_SIZE + 1:
+            raise FramingError(f"invalid MBAP length {length}")
+        pdu = await reader.readexactly(length - 1)
+        return Frame(unit_id, pdu, transaction_id)
+
+    def encode(self, frame: Frame) -> bytes:
+        return (
+            MBAP_HEADER.pack(frame.transaction_id or 0, 0, len(frame.pdu) + 1, frame.unit_id)
+            + frame.pdu
+        )
+
+    def corrupt(self, data: bytes, mode: str, rng: random.Random) -> bytes:
+        common = self._corrupt_common(data, mode, rng)
+        if common is not None:
+            return common
+        if mode == "bit_flip":
+            return bytes(_flip_bit(data, MBAP_HEADER.size, len(data), rng))
+        transaction_id, protocol_id, length, unit_id = MBAP_HEADER.unpack_from(data)
+        if mode == "bad_length":
+            length = (length + rng.randint(1, 8)) & 0xFFFF
+        elif mode == "transaction_id":
+            transaction_id = (transaction_id + 1) & 0xFFFF
+        else:
+            raise ValueError(f"corrupt mode {mode!r} is not supported by Modbus TCP")
+        return MBAP_HEADER.pack(transaction_id, protocol_id, length, unit_id) + data[7:]
+
+
+# --------------------------------------------------------------------------- RTU over TCP
+
+
+def _make_crc_table() -> list[int]:
+    table = []
+    for byte in range(256):
+        crc = byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
+        table.append(crc)
+    return table
+
+
+_CRC_TABLE = _make_crc_table()
+
+
+def crc16(data: bytes) -> int:
+    """Modbus CRC-16 (polynomial 0xA001, initial value 0xFFFF)."""
+    crc = 0xFFFF
+    for byte in data:
+        crc = (crc >> 8) ^ _CRC_TABLE[(crc ^ byte) & 0xFF]
+    return crc
+
+
+def with_crc(data: bytes) -> bytes:
+    return data + crc16(data).to_bytes(2, "little")
+
+
+# Request PDU data length (after the function code) for fixed-size requests.
+_FIXED_REQUEST_DATA = {0x01: 4, 0x02: 4, 0x03: 4, 0x04: 4, 0x05: 4, 0x06: 4}
+_VARIABLE_REQUEST = {0x0F, 0x10}  # address(2) quantity(2) byte count(1) + data
+
+
+class RtuFramer(Framer):
+    """RTU framing has no length field; request size is derived from the function code."""
+
+    name = "rtu"
+
+    #: How long to wait for the rest of a request with an unknown function code.
+    unknown_request_gap = 0.05
+
+    async def read_frame(self, reader: asyncio.StreamReader) -> Frame | None:
+        head = await reader.readexactly(2)
+        fc = head[1]
+        if fc in _FIXED_REQUEST_DATA:
+            body = await reader.readexactly(_FIXED_REQUEST_DATA[fc] + 2)
+        elif fc in _VARIABLE_REQUEST:
+            fixed = await reader.readexactly(5)
+            body = fixed + await reader.readexactly(fixed[4] + 2)
+        else:
+            # Unknown length: take whatever arrives before the line goes quiet.
+            try:
+                body = await asyncio.wait_for(
+                    reader.read(MAX_PDU_SIZE + 2), self.unknown_request_gap
+                )
+            except asyncio.TimeoutError:
+                body = b""
+            if not body and reader.at_eof():
+                raise asyncio.IncompleteReadError(head, None)
+        frame = head + body
+        if len(frame) < 4 or crc16(frame[:-2]) != int.from_bytes(frame[-2:], "little"):
+            # A real RTU slave silently ignores frames with a bad checksum.
+            logger.debug("discarding RTU frame with bad CRC: %s", frame.hex(" "))
+            return None
+        return Frame(frame[0], frame[1:-2])
+
+    def encode(self, frame: Frame) -> bytes:
+        return with_crc(bytes([frame.unit_id]) + frame.pdu)
+
+    def corrupt(self, data: bytes, mode: str, rng: random.Random) -> bytes:
+        common = self._corrupt_common(data, mode, rng)
+        if common is not None:
+            return common
+        if mode == "bit_flip":
+            # Valid checksum over wrong data: the error only a plausibility check catches.
+            return with_crc(bytes(_flip_bit(data, 1, len(data) - 2, rng))[:-2])
+        if mode == "bad_crc":
+            out = bytearray(data)
+            out[-1] ^= 0xFF
+            return bytes(out)
+        raise ValueError(f"corrupt mode {mode!r} is not supported by RTU framing")
+
+
+FRAMERS: dict[str, type[Framer]] = {
+    "modbus_tcp": TcpFramer,
+    "modbus_rtu_over_tcp": RtuFramer,
+}

fieldsim/protocols/modbus/pdu.py

@@ -0,0 +1,157 @@
+"""Modbus PDU processing (transport independent).
+
+``handle_pdu`` takes a request PDU (function code + data) and returns the
+response PDU. Validation order follows the Modbus Application Protocol
+specification: function code (01), quantity / framing (03), address range (02),
+then execution (04).
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from collections.abc import Callable, Sequence
+
+from fieldsim.protocols.modbus.constants import (
+    ADDRESS_SPACE,
+    MAX_READ_BITS,
+    MAX_READ_REGISTERS,
+    MAX_WRITE_BITS,
+    MAX_WRITE_REGISTERS,
+    ExceptionCode,
+    FunctionCode,
+    ModbusError,
+)
+from fieldsim.protocols.modbus.datastore import ModbusDataStore, Table
+
+logger = logging.getLogger(__name__)
+
+_ADDR_QTY = struct.Struct(">HH")
+
+
+def pack_bits(bits: Sequence[bool]) -> bytes:
+    """Pack bits LSB-first, as Modbus does."""
+    out = bytearray((len(bits) + 7) // 8)
+    for i, bit in enumerate(bits):
+        if bit:
+            out[i // 8] |= 1 << (i % 8)
+    return bytes(out)
+
+
+def unpack_bits(data: bytes, count: int) -> list[bool]:
+    return [bool(data[i // 8] >> (i % 8) & 1) for i in range(count)]
+
+
+def exception_response(function_code: int, code: ExceptionCode | int) -> bytes:
+    return bytes([(function_code | 0x80) & 0xFF, code])
+
+
+def _addr_qty(data: bytes) -> tuple[int, int]:
+    if len(data) != 4:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "expected 4 data bytes")
+    address, quantity = _ADDR_QTY.unpack(data)
+    return address, quantity
+
+
+def _check_range(address: int, quantity: int, limit: int) -> None:
+    if not 1 <= quantity <= limit:
+        raise ModbusError(
+            ExceptionCode.ILLEGAL_DATA_VALUE, f"quantity {quantity} not in 1..{limit}"
+        )
+    if address + quantity > ADDRESS_SPACE:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_ADDRESS, "range exceeds address space")
+
+
+def _read_bits(table: Table) -> Handler:
+    def handler(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+        address, quantity = _addr_qty(data)
+        _check_range(address, quantity, MAX_READ_BITS)
+        payload = pack_bits(store.read_bits(table, address, quantity))
+        return bytes([fc, len(payload)]) + payload
+
+    return handler
+
+
+def _read_registers(table: Table) -> Handler:
+    def handler(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+        address, quantity = _addr_qty(data)
+        _check_range(address, quantity, MAX_READ_REGISTERS)
+        words = store.read_registers(table, address, quantity)
+        return bytes([fc, 2 * quantity]) + struct.pack(f">{quantity}H", *words)
+
+    return handler
+
+
+def _write_single_coil(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+    address, value = _addr_qty(data)
+    if value not in (0x0000, 0xFF00):
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "coil value must be 0x0000 or 0xFF00")
+    store.write_coils(address, [value == 0xFF00])
+    return bytes([fc]) + data
+
+
+def _write_single_register(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+    address, value = _addr_qty(data)
+    store.write_registers(address, [value])
+    return bytes([fc]) + data
+
+
+def _write_multiple_coils(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+    if len(data) < 5:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "request too short")
+    address, quantity = _ADDR_QTY.unpack_from(data)
+    byte_count = data[4]
+    if not 1 <= quantity <= MAX_WRITE_BITS or byte_count != (quantity + 7) // 8:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "bad quantity or byte count")
+    if len(data) != 5 + byte_count:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "byte count does not match payload")
+    _check_range(address, quantity, MAX_WRITE_BITS)
+    store.write_coils(address, unpack_bits(data[5:], quantity))
+    return bytes([fc]) + data[:4]
+
+
+def _write_multiple_registers(store: ModbusDataStore, fc: int, data: bytes) -> bytes:
+    if len(data) < 5:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "request too short")
+    address, quantity = _ADDR_QTY.unpack_from(data)
+    byte_count = data[4]
+    if not 1 <= quantity <= MAX_WRITE_REGISTERS or byte_count != 2 * quantity:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "bad quantity or byte count")
+    if len(data) != 5 + byte_count:
+        raise ModbusError(ExceptionCode.ILLEGAL_DATA_VALUE, "byte count does not match payload")
+    _check_range(address, quantity, MAX_WRITE_REGISTERS)
+    store.write_registers(address, list(struct.unpack_from(f">{quantity}H", data, 5)))
+    return bytes([fc]) + data[:4]
+
+
+Handler = Callable[[ModbusDataStore, int, bytes], bytes]
+
+HANDLERS: dict[int, Handler] = {
+    FunctionCode.READ_COILS: _read_bits(Table.COILS),
+    FunctionCode.READ_DISCRETE_INPUTS: _read_bits(Table.DISCRETE_INPUTS),
+    FunctionCode.READ_HOLDING_REGISTERS: _read_registers(Table.HOLDING_REGISTERS),
+    FunctionCode.READ_INPUT_REGISTERS: _read_registers(Table.INPUT_REGISTERS),
+    FunctionCode.WRITE_SINGLE_COIL: _write_single_coil,
+    FunctionCode.WRITE_SINGLE_REGISTER: _write_single_register,
+    FunctionCode.WRITE_MULTIPLE_COILS: _write_multiple_coils,
+    FunctionCode.WRITE_MULTIPLE_REGISTERS: _write_multiple_registers,
+}
+
+
+def handle_pdu(store: ModbusDataStore, pdu: bytes) -> bytes:
+    """Process one request PDU and return the response PDU."""
+    if not pdu:
+        raise ValueError("empty PDU")
+    fc = pdu[0]
+    handler = HANDLERS.get(fc)
+    if handler is None:
+        logger.debug("unsupported function code 0x%02X", fc)
+        return exception_response(fc, ExceptionCode.ILLEGAL_FUNCTION)
+    try:
+        return handler(store, fc, pdu[1:])
+    except ModbusError as exc:
+        logger.debug("fc 0x%02X -> exception %s: %s", fc, exc.code.name, exc)
+        return exception_response(fc, exc.code)
+    except Exception:
+        logger.exception("unexpected error while handling fc 0x%02X", fc)
+        return exception_response(fc, ExceptionCode.SERVER_DEVICE_FAILURE)

fieldsim/protocols/modbus/server.py

@@ -0,0 +1,135 @@
+"""asyncio Modbus server for TCP streams (Modbus TCP or RTU over TCP)."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+
+from fieldsim.core.faults import FaultInjector, FaultPlan
+from fieldsim.protocols.modbus.datastore import ModbusDataStore
+from fieldsim.protocols.modbus.framer import Frame, Framer, FramingError, TcpFramer
+from fieldsim.protocols.modbus.pdu import exception_response, handle_pdu
+
+logger = logging.getLogger(__name__)
+
+
+class ModbusTcpServer:
+    """Serves a :class:`ModbusDataStore` over a TCP listener.
+
+    Requests on one connection are processed in order; any number of clients
+    can be connected at once. Every request is run through the fault injector
+    first.
+    """
+
+    def __init__(
+        self,
+        store: ModbusDataStore,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 502,
+        unit_id: int | None = None,
+        framer: Framer | None = None,
+        faults: FaultInjector | None = None,
+    ):
+        self.store = store
+        self.unit_id = unit_id
+        self.framer = framer or TcpFramer()
+        self.faults = faults or FaultInjector()
+        self._host = host
+        self._port = port
+        self._server: asyncio.Server | None = None
+        self._clients: set[asyncio.Task[None]] = set()
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    @property
+    def serving(self) -> bool:
+        return self._server is not None
+
+    @property
+    def client_count(self) -> int:
+        return len(self._clients)
+
+    async def start(self) -> None:
+        if self._server is not None:
+            raise RuntimeError("server already started")
+        self._server = await asyncio.start_server(self._handle_client, self._host, self._port)
+        # With port 0 the OS picks a free port; remember the real one so that a
+        # restart after an outage comes back on the same address.
+        self._host, self._port = self._server.sockets[0].getsockname()[:2]
+        logger.info("modbus %s server listening on %s:%s", self.framer.name, self._host, self._port)
+
+    async def stop(self) -> None:
+        server, self._server = self._server, None
+        if server is None:
+            return
+        server.close()
+        clients = list(self._clients)
+        for task in clients:
+            task.cancel()
+        await asyncio.gather(*clients, return_exceptions=True)
+        await server.wait_closed()
+        logger.info("modbus server on %s:%s stopped", self._host, self._port)
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        task = asyncio.current_task()
+        assert task is not None
+        self._clients.add(task)
+        peer = writer.get_extra_info("peername")
+        logger.debug("client connected: %s", peer)
+        try:
+            while True:
+                frame = await self.framer.read_frame(reader)
+                if frame is None:
+                    continue
+                if self.unit_id is not None and frame.unit_id != self.unit_id:
+                    logger.debug("ignoring request for unit %s", frame.unit_id)
+                    continue
+                plan = self.faults.plan(frame.pdu[0])
+                data = self._respond(frame, plan)
+                if plan.delay:
+                    await asyncio.sleep(plan.delay)
+                if plan.disconnect:
+                    logger.info("fault: disconnecting %s", peer)
+                    break
+                if data is not None:
+                    writer.write(data)
+                    await writer.drain()
+        except FramingError as exc:
+            logger.warning("dropping %s: %s", peer, exc)
+        except (asyncio.IncompleteReadError, ConnectionError):
+            pass
+        finally:
+            self._clients.discard(task)
+            writer.close()
+            with contextlib.suppress(ConnectionError, OSError):
+                await writer.wait_closed()
+            logger.debug("client disconnected: %s", peer)
+
+    def _respond(self, frame: Frame, plan: FaultPlan) -> bytes | None:
+        """Process a request according to the fault plan; ``None`` means send nothing."""
+        if plan.disconnect:
+            return None
+        if plan.drop:
+            if plan.execute:
+                handle_pdu(self.store, frame.pdu)
+            logger.info("fault: dropped fc 0x%02X", frame.pdu[0])
+            return None
+        if plan.exception is not None:
+            response = exception_response(frame.pdu[0], plan.exception)
+        else:
+            response = handle_pdu(self.store, frame.pdu)
+        data = self.framer.encode(Frame(frame.unit_id, response, frame.transaction_id))
+        if plan.corrupt:
+            logger.info("fault: corrupting response (%s)", plan.corrupt)
+            data = self.framer.corrupt(data, plan.corrupt, self.faults.rng)
+        return data

fieldsim/pytest_plugin.py

@@ -0,0 +1,163 @@
+"""pytest plugin: virtual devices as fixtures.
+
+Installed automatically with fieldsim (``pytest11`` entry point)::
+
+    def test_gateway_reads_temperature(modbus_device):
+        modbus_device.set("temperature", 85.0)
+        assert read_temperature(modbus_device.host, modbus_device.port) == 85.0
+
+Configuration, from most to least specific:
+
+* ``@pytest.mark.fieldsim("devices.yaml", device="plc", clock="virtual")``
+* ini options ``fieldsim_config``, ``fieldsim_clock``, ``fieldsim_free_ports``
+* otherwise a single Modbus TCP device whose whole address space is plain memory
+
+Relative config paths are looked up next to the test file first, then in the
+rootdir. Devices run on free ports by default so tests can run in parallel.
+
+The fixtures are synchronous and the devices run in a background thread, so
+they work with plain, asyncio and trio tests alike. In async tests use the
+``*_async`` variants of blocking calls (``wait_for_write_async``,
+``advance_async``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from fieldsim.background import BackgroundSimulator, ConfigSource, DeviceHandle
+from fieldsim.config import ConfigError
+
+DEFAULT_DEVICE: dict[str, Any] = {
+    "name": "device",
+    "protocol": "modbus_tcp",
+    "port": 0,
+    "unmapped": "allow",
+}
+
+MARKER_DOC = (
+    "fieldsim(config=None, *, device=None, clock=None, free_ports=None): "
+    "configure the fieldsim fixtures for this test (config: YAML path or dict)"
+)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    parser.addini(
+        "fieldsim_config", "Default simulation file for the fieldsim fixtures.", default=""
+    )
+    parser.addini("fieldsim_clock", "'real' (default) or 'virtual'.", default="real")
+    parser.addini(
+        "fieldsim_free_ports",
+        "Ignore configured ports and let the OS pick free ones (default: true).",
+        type="bool",
+        default=True,
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line("markers", MARKER_DOC)
+
+
+def _find_file(request: pytest.FixtureRequest, value: str | Path) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    candidates = [Path(request.path).parent / path, Path(request.config.rootpath) / path]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]  # let the loader report a helpful "cannot read" error
+
+
+def _options(request: pytest.FixtureRequest) -> dict[str, Any]:
+    marker = request.node.get_closest_marker("fieldsim")
+    kwargs: dict[str, Any] = dict(marker.kwargs) if marker else {}
+    if marker and marker.args:
+        kwargs.setdefault("config", marker.args[0])
+
+    source: Any = kwargs.get("config")
+    if source is None:
+        ini_path = request.config.getini("fieldsim_config")
+        source = ini_path or None
+    if source is None:
+        source = {"devices": [DEFAULT_DEVICE]}
+    elif isinstance(source, str | Path):
+        source = _find_file(request, source)
+
+    free_ports = kwargs.get("free_ports")
+    return {
+        "config": source,
+        "device": kwargs.get("device"),
+        "clock": kwargs.get("clock") or request.config.getini("fieldsim_clock"),
+        "free_ports": request.config.getini("fieldsim_free_ports")
+        if free_ports is None
+        else free_ports,
+    }
+
+
+def _start(source: ConfigSource, *, clock: Any, free_ports: bool) -> BackgroundSimulator:
+    try:
+        sim = BackgroundSimulator(source, clock=clock, free_ports=free_ports)
+        sim.start()
+    except (ConfigError, ValueError) as exc:
+        pytest.fail(f"fieldsim: {exc}", pytrace=False)
+    except OSError as exc:
+        pytest.fail(f"fieldsim: cannot start devices: {exc}", pytrace=False)
+    return sim
+
+
+@pytest.fixture
+def fieldsim(request: pytest.FixtureRequest) -> Iterator[BackgroundSimulator]:
+    """The running simulator with every device of the configured file."""
+    options = _options(request)
+    sim = _start(options["config"], clock=options["clock"], free_ports=options["free_ports"])
+    try:
+        yield sim
+    finally:
+        sim.stop()
+
+
+@pytest.fixture
+def modbus_device(fieldsim: BackgroundSimulator, request: pytest.FixtureRequest) -> DeviceHandle:
+    """The Modbus device of the simulation (pick one with ``mark.fieldsim(device=...)``)."""
+    name = _options(request)["device"]
+    if name is not None:
+        return fieldsim[name]
+    candidates = [d for d in fieldsim if d.protocol.startswith("modbus")]
+    if len(candidates) != 1:
+        names = ", ".join(d.name for d in candidates) or "none"
+        pytest.fail(
+            f"fieldsim: modbus_device needs exactly one Modbus device, found: {names}. "
+            "Choose one with @pytest.mark.fieldsim(device='...').",
+            pytrace=False,
+        )
+    return candidates[0]
+
+
+@pytest.fixture
+def make_modbus_device() -> Iterator[Callable[..., DeviceHandle]]:
+    """Factory for ad-hoc devices, cleaned up after the test::
+
+    def test_two_plcs(make_modbus_device):
+        a = make_modbus_device(registers={"coils": [{"name": "run", "address": 0}]})
+        b = make_modbus_device(protocol="modbus_rtu_over_tcp", unit_id=2)
+    """
+    started: list[BackgroundSimulator] = []
+
+    def factory(
+        spec: Mapping[str, Any] | None = None, *, clock: Any = "real", **fields: Any
+    ) -> DeviceHandle:
+        device = {**DEFAULT_DEVICE, "name": f"device{len(started) + 1}", **(spec or {}), **fields}
+        sim = _start({"devices": [device]}, clock=clock, free_ports=True)
+        started.append(sim)
+        return sim[device["name"]]
+
+    try:
+        yield factory
+    finally:
+        for sim in reversed(started):
+            sim.stop()