fieldsim 0.2.0__tar.gz

fieldsim-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

fieldsim-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      # `coverage run` instead of `pytest --cov`: fieldsim's pytest plugin is loaded
+      # from an entry point before pytest-cov starts, which would hide import-time lines.
+      - run: coverage run -m pytest
+      - run: coverage report
+      - run: coverage xml
+      - name: Example project tests
+        run: pytest examples

fieldsim-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+# Push a tag like v0.2.0 to publish to PyPI and create a GitHub release.
+# Run manually ("Run workflow") to publish the current main to TestPyPI first.
+#
+# Publishing uses PyPI Trusted Publishing (no API token): add this repository
+# and workflow as a trusted publisher on pypi.org and test.pypi.org, with
+# environments named "pypi" and "testpypi".
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check that the tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/fieldsim/__init__.py)
+          if [ "v$version" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match __version__ $version" >&2
+            exit 1
+          fi
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --verify-tag
+        env:
+          GH_TOKEN: ${{ github.token }}

fieldsim-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+site/
+.idea/
+.vscode/

fieldsim-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

fieldsim-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows
+[Semantic Versioning](https://semver.org/); until 1.0 minor versions may change
+the file format.
+
+## [0.2.0] - unreleased
+
+### Added
+
+- **Fault injection**: `latency` (with jitter), `drop` (optionally after executing the
+  request), `disconnect`, `exception` and `corrupt` (`bit_flip`, `truncate`, `garbage`,
+  `bad_length`, `transaction_id`, `bad_crc`). Faults can be limited by `probability`,
+  `function_codes` and `count`, declared in YAML or switched on from code with
+  `device.fault(...)`.
+- **Outages**: `go_offline()` / `go_online()` / `offline()` stop listening and drop all
+  clients, then come back on the same port.
+- **Scenarios**: a timeline of `set`, `release`, `fault` (with `duration`) and `offline`
+  steps per device.
+- **Virtual clock**: play long scenarios instantly and deterministically with
+  `clock="virtual"` and `advance()`.
+- **Modbus RTU over TCP** (`protocol: modbus_rtu_over_tcp`) with CRC checking.
+- **Write log**: `device.writes` and `wait_for_write(point)` to assert what a client sent.
+- **pytest plugin**: `modbus_device`, `fieldsim` and `make_modbus_device` fixtures, the
+  `@pytest.mark.fieldsim(...)` marker and `fieldsim_config` / `fieldsim_clock` /
+  `fieldsim_free_ports` ini options.
+- `BackgroundSimulator` to drive devices from synchronous code or other threads.
+- Release workflow publishing to PyPI with Trusted Publishing.
+
+### Changed
+
+- `ModbusTcpDevice` is now `ModbusDeviceSpec` (the old name remains as an alias).
+
+## [0.1.0a1]
+
+- First preview: YAML device definitions, value generators, asyncio Modbus TCP server
+  and the `fieldsim` CLI.

fieldsim-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 enesuslu15
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fieldsim-0.2.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.5
+Name: fieldsim
+Version: 0.2.0
+Summary: Virtual Modbus, OPC UA and S7 devices for testing industrial software without hardware.
+Project-URL: Homepage, https://github.com/enesuslu15/fieldsim
+Project-URL: Issues, https://github.com/enesuslu15/fieldsim/issues
+Author: enesuslu15
+License: MIT License
+        
+        Copyright (c) 2026 enesuslu15
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: iiot,industrial,modbus,opc-ua,plc,pytest,s7,simulator,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pymodbus<4,>=3.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fieldsim
+
+**Virtual industrial devices for testing software without hardware.**
+
+fieldsim starts fake Modbus devices (OPC UA and S7 are on the roadmap) from a YAML
+file, drives their values with generators, breaks them on purpose with fault
+injection and plays scripted scenarios — so you can test gateways, SCADA
+connectors and edge apps in CI, no PLC on your desk required.
+
+> Status: alpha (`0.2.0`). The file format may still change before 1.0.
+
+## Install
+
+```bash
+pip install fieldsim
+```
+
+## Test with pytest
+
+Installing fieldsim registers a pytest plugin. With no configuration at all you
+get a Modbus TCP device whose whole address space is plain memory:
+
+```python
+def test_gateway_writes_registers(modbus_device):
+    Gateway(modbus_device.host, modbus_device.port).write_register(100, 42)
+    event = modbus_device.wait_for_write(timeout=2)
+    assert event.address == 100 and event.values == (42,)
+```
+
+Point it at a device file to get named points, generators and scenarios:
+
+```python
+import pytest
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_reads_temperature(modbus_device):
+    modbus_device.set("temperature", 85.0)  # pauses the generator
+    assert Gateway(*modbus_device.address).temperature() == 85.0
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_survives_a_slow_plc(modbus_device):
+    with modbus_device.fault("latency", delay="800ms"):
+        assert Gateway(*modbus_device.address, timeout=1).temperature() is not None
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_retries_lost_responses(modbus_device):
+    with modbus_device.fault("drop", count=2) as fault:
+        Gateway(*modbus_device.address, retries=3).temperature()
+    assert fault.hits == 2
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_reconnects_after_outage(modbus_device):
+    gw = Gateway(*modbus_device.address)
+    with modbus_device.offline():
+        assert not gw.healthy()
+    assert gw.healthy()
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_writes_setpoint(modbus_device):
+    Gateway(*modbus_device.address).set_setpoint(80)
+    modbus_device.wait_for_write("setpoint", timeout=2)
+    assert modbus_device.get("setpoint") == 80
+
+
+@pytest.mark.fieldsim("boiler.yaml", clock="virtual")
+def test_overheat_alarm(modbus_device):
+    modbus_device.advance(600)  # ten minutes, instantly
+    ...
+```
+
+Fixtures and options:
+
+| | |
+|---|---|
+| `modbus_device` | The Modbus device of the simulation (choose with `mark.fieldsim(device="name")` if there are several). |
+| `fieldsim` | The whole running simulation: `fieldsim["plc-1"]`, `fieldsim.advance(10)`. |
+| `make_modbus_device` | Factory for ad-hoc devices: `make_modbus_device(registers={...}, unit_id=3)`. |
+| `@pytest.mark.fieldsim(config, device=, clock=, free_ports=)` | Per-test configuration. `config` is a YAML path (relative to the test file or rootdir) or a dict. |
+| ini `fieldsim_config`, `fieldsim_clock`, `fieldsim_free_ports` | Project-wide defaults. |
+
+Devices run in a background thread on free ports, so the fixtures work in plain,
+asyncio and trio tests, and with `pytest-xdist`. In async tests use
+`await device.wait_for_write_async(...)` and `await device.advance_async(...)`.
+
+## Describe a device
+
+```yaml
+# boiler.yaml
+version: 1
+devices:
+  - name: boiler-plc
+    protocol: modbus_tcp          # or modbus_rtu_over_tcp
+    port: 5020
+    registers:
+      coils:
+        - { name: pump_on, address: 0, value: true }
+      holding_registers:
+        - name: temperature
+          address: 0
+          type: float32
+          generator: { type: sine, min: 60, max: 90, period: 30s }
+        - { name: setpoint, address: 2, type: uint16, value: 75 }
+
+    faults:                       # active from the start
+      - { type: latency, delay: 20ms, jitter: 10ms }
+
+    scenario:                     # relative to device start
+      - { at: 30s, set: { temperature: 120 } }
+      - { at: 40s, fault: { type: exception, code: 6 }, duration: 5s }
+      - { at: 60s, offline: 10s }
+      - { at: 90s, release: [temperature] }
+```
+
+Run it standalone, e.g. as a service container in CI:
+
+```bash
+fieldsim validate boiler.yaml
+fieldsim run boiler.yaml
+```
+
+Get a JSON Schema for editor autocompletion with `fieldsim schema -o fieldsim.schema.json`.
+
+### Device options
+
+| Key | Meaning |
+|---|---|
+| `protocol` | `modbus_tcp`, or `modbus_rtu_over_tcp` for RTU frames (with CRC) tunnelled over TCP. |
+| `host`, `port` | Listen address. `port: 0` picks a free port. |
+| `unit_id` | Only answer this unit id (default: answer all). |
+| `unmapped` | `error` (exception 02 for undefined addresses, default) or `allow` (plain memory). |
+| `update_interval` | Generator refresh rate, e.g. `100ms`. |
+| `faults` | Faults active from the start (see below). |
+| `scenario` | Timed steps: `set`, `release`, `fault` (+ `duration`), `offline`. |
+| `seed` | Makes random faults reproducible. |
+
+Points live in `registers.coils`, `discrete_inputs`, `holding_registers` and
+`input_registers`, with `name`, `address`, `value`, `generator`, `description` and —
+for registers — `type` (`int16 uint16 int32 uint32 int64 uint64 float32 float64`),
+`byte_order` and `word_order`. Coils and holding registers take `writable: false`.
+
+Generators: `constant`, `sine`, `ramp` (`sawtooth` / `triangle` / `once`),
+`random_walk`, `sequence`.
+
+### Faults
+
+| Type | Effect |
+|---|---|
+| `latency` | Delay responses by `delay` + random `0..jitter`. |
+| `drop` | No response. `executed: true` still performs the request (lost reply). |
+| `disconnect` | Close the connection instead of answering. |
+| `exception` | Answer with Modbus exception `code` (default 6, SERVER DEVICE BUSY). |
+| `corrupt` | Damage the response: `bit_flip`, `truncate`, `garbage`, `bad_length` (TCP), `transaction_id` (TCP), `bad_crc` (RTU). |
+
+Every fault accepts `probability` (0..1), `function_codes` (list) and `count`
+(remove after N hits).
+
+## Use from Python
+
+```python
+from fieldsim import Simulator, VirtualClock
+
+clock = VirtualClock()
+async with Simulator.from_yaml("boiler.yaml", clock=clock) as sim:
+    plc = sim["boiler-plc"]
+    with plc.fault("corrupt", mode="bit_flip", probability=0.1):
+        await clock.advance(60)
+```
+
+From synchronous code use `BackgroundSimulator("boiler.yaml")` as a context
+manager; its device handles are thread-safe.
+
+## Supported Modbus function codes
+
+01 Read Coils · 02 Read Discrete Inputs · 03 Read Holding Registers · 04 Read Input Registers ·
+05 Write Single Coil · 06 Write Single Register · 15 Write Multiple Coils · 16 Write Multiple Registers
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pre-commit install
+coverage run -m pytest && coverage report
+```
+
+`coverage run` is used instead of `pytest --cov` because fieldsim's own pytest
+plugin is imported before pytest-cov starts measuring.
+
+## License
+
+MIT

fieldsim-0.2.0/README.md

@@ -0,0 +1,197 @@
+# fieldsim
+
+**Virtual industrial devices for testing software without hardware.**
+
+fieldsim starts fake Modbus devices (OPC UA and S7 are on the roadmap) from a YAML
+file, drives their values with generators, breaks them on purpose with fault
+injection and plays scripted scenarios — so you can test gateways, SCADA
+connectors and edge apps in CI, no PLC on your desk required.
+
+> Status: alpha (`0.2.0`). The file format may still change before 1.0.
+
+## Install
+
+```bash
+pip install fieldsim
+```
+
+## Test with pytest
+
+Installing fieldsim registers a pytest plugin. With no configuration at all you
+get a Modbus TCP device whose whole address space is plain memory:
+
+```python
+def test_gateway_writes_registers(modbus_device):
+    Gateway(modbus_device.host, modbus_device.port).write_register(100, 42)
+    event = modbus_device.wait_for_write(timeout=2)
+    assert event.address == 100 and event.values == (42,)
+```
+
+Point it at a device file to get named points, generators and scenarios:
+
+```python
+import pytest
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_reads_temperature(modbus_device):
+    modbus_device.set("temperature", 85.0)  # pauses the generator
+    assert Gateway(*modbus_device.address).temperature() == 85.0
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_survives_a_slow_plc(modbus_device):
+    with modbus_device.fault("latency", delay="800ms"):
+        assert Gateway(*modbus_device.address, timeout=1).temperature() is not None
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_retries_lost_responses(modbus_device):
+    with modbus_device.fault("drop", count=2) as fault:
+        Gateway(*modbus_device.address, retries=3).temperature()
+    assert fault.hits == 2
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_reconnects_after_outage(modbus_device):
+    gw = Gateway(*modbus_device.address)
+    with modbus_device.offline():
+        assert not gw.healthy()
+    assert gw.healthy()
+
+
+@pytest.mark.fieldsim("boiler.yaml")
+def test_gateway_writes_setpoint(modbus_device):
+    Gateway(*modbus_device.address).set_setpoint(80)
+    modbus_device.wait_for_write("setpoint", timeout=2)
+    assert modbus_device.get("setpoint") == 80
+
+
+@pytest.mark.fieldsim("boiler.yaml", clock="virtual")
+def test_overheat_alarm(modbus_device):
+    modbus_device.advance(600)  # ten minutes, instantly
+    ...
+```
+
+Fixtures and options:
+
+| | |
+|---|---|
+| `modbus_device` | The Modbus device of the simulation (choose with `mark.fieldsim(device="name")` if there are several). |
+| `fieldsim` | The whole running simulation: `fieldsim["plc-1"]`, `fieldsim.advance(10)`. |
+| `make_modbus_device` | Factory for ad-hoc devices: `make_modbus_device(registers={...}, unit_id=3)`. |
+| `@pytest.mark.fieldsim(config, device=, clock=, free_ports=)` | Per-test configuration. `config` is a YAML path (relative to the test file or rootdir) or a dict. |
+| ini `fieldsim_config`, `fieldsim_clock`, `fieldsim_free_ports` | Project-wide defaults. |
+
+Devices run in a background thread on free ports, so the fixtures work in plain,
+asyncio and trio tests, and with `pytest-xdist`. In async tests use
+`await device.wait_for_write_async(...)` and `await device.advance_async(...)`.
+
+## Describe a device
+
+```yaml
+# boiler.yaml
+version: 1
+devices:
+  - name: boiler-plc
+    protocol: modbus_tcp          # or modbus_rtu_over_tcp
+    port: 5020
+    registers:
+      coils:
+        - { name: pump_on, address: 0, value: true }
+      holding_registers:
+        - name: temperature
+          address: 0
+          type: float32
+          generator: { type: sine, min: 60, max: 90, period: 30s }
+        - { name: setpoint, address: 2, type: uint16, value: 75 }
+
+    faults:                       # active from the start
+      - { type: latency, delay: 20ms, jitter: 10ms }
+
+    scenario:                     # relative to device start
+      - { at: 30s, set: { temperature: 120 } }
+      - { at: 40s, fault: { type: exception, code: 6 }, duration: 5s }
+      - { at: 60s, offline: 10s }
+      - { at: 90s, release: [temperature] }
+```
+
+Run it standalone, e.g. as a service container in CI:
+
+```bash
+fieldsim validate boiler.yaml
+fieldsim run boiler.yaml
+```
+
+Get a JSON Schema for editor autocompletion with `fieldsim schema -o fieldsim.schema.json`.
+
+### Device options
+
+| Key | Meaning |
+|---|---|
+| `protocol` | `modbus_tcp`, or `modbus_rtu_over_tcp` for RTU frames (with CRC) tunnelled over TCP. |
+| `host`, `port` | Listen address. `port: 0` picks a free port. |
+| `unit_id` | Only answer this unit id (default: answer all). |
+| `unmapped` | `error` (exception 02 for undefined addresses, default) or `allow` (plain memory). |
+| `update_interval` | Generator refresh rate, e.g. `100ms`. |
+| `faults` | Faults active from the start (see below). |
+| `scenario` | Timed steps: `set`, `release`, `fault` (+ `duration`), `offline`. |
+| `seed` | Makes random faults reproducible. |
+
+Points live in `registers.coils`, `discrete_inputs`, `holding_registers` and
+`input_registers`, with `name`, `address`, `value`, `generator`, `description` and —
+for registers — `type` (`int16 uint16 int32 uint32 int64 uint64 float32 float64`),
+`byte_order` and `word_order`. Coils and holding registers take `writable: false`.
+
+Generators: `constant`, `sine`, `ramp` (`sawtooth` / `triangle` / `once`),
+`random_walk`, `sequence`.
+
+### Faults
+
+| Type | Effect |
+|---|---|
+| `latency` | Delay responses by `delay` + random `0..jitter`. |
+| `drop` | No response. `executed: true` still performs the request (lost reply). |
+| `disconnect` | Close the connection instead of answering. |
+| `exception` | Answer with Modbus exception `code` (default 6, SERVER DEVICE BUSY). |
+| `corrupt` | Damage the response: `bit_flip`, `truncate`, `garbage`, `bad_length` (TCP), `transaction_id` (TCP), `bad_crc` (RTU). |
+
+Every fault accepts `probability` (0..1), `function_codes` (list) and `count`
+(remove after N hits).
+
+## Use from Python
+
+```python
+from fieldsim import Simulator, VirtualClock
+
+clock = VirtualClock()
+async with Simulator.from_yaml("boiler.yaml", clock=clock) as sim:
+    plc = sim["boiler-plc"]
+    with plc.fault("corrupt", mode="bit_flip", probability=0.1):
+        await clock.advance(60)
+```
+
+From synchronous code use `BackgroundSimulator("boiler.yaml")` as a context
+manager; its device handles are thread-safe.
+
+## Supported Modbus function codes
+
+01 Read Coils · 02 Read Discrete Inputs · 03 Read Holding Registers · 04 Read Input Registers ·
+05 Write Single Coil · 06 Write Single Register · 15 Write Multiple Coils · 16 Write Multiple Registers
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pre-commit install
+coverage run -m pytest && coverage report
+```
+
+`coverage run` is used instead of `pytest --cov` because fieldsim's own pytest
+plugin is imported before pytest-cov starts measuring.
+
+## License
+
+MIT