Merge branch 'dev'

Author: janiversen

.github/workflows/ci.yml

@@ -77,7 +77,7 @@ jobs:
       - name: Type check with zuban
         if: matrix.run_lint == true
         run: |
-          uv run zuban check pymodbus examples
+          uv run zuban check pymodbus examples test
 
       - name: ruff
         if: matrix.run_lint == true

AUTHORS.rst

@@ -48,6 +48,7 @@ Thanks to
 - Erlend E. Aasland
 - Esco441-91
 - Farzad Panahi
+- Federico
 - FedericoMusa
 - Fredo70
 - Gao Fang

CHANGELOG.rst

@@ -7,6 +7,19 @@ helps make pymodbus a better product.
 
 :ref:`Authors`: contains a complete list of volunteers have contributed to each major version.
 
+Version 3.12.1
+--------------
+* SimDevice / SimRuntime fixes. (#2871)
+* No inter_frame_time check for baudrate > 38000. (#2882)
+* Fix smaller bugs in test, part 2. (#2880)
+* simulator startup armoring and update 3.x docs (#2877)
+* Fix smaller bugs in test, part 1. (#2879)
+* Update README.rst. (#2878)
+* Coverage limit is 99.95% (to allow a little margin).
+* Removed simulator README, due to unused.
+* fix: add warning log when using internal default simulator config (#2874)
+* Document simulator entrypoint in README (#2873)
+
 Version 3.12.0
 --------------
 * Upgrade library versions installed by pip. (#2868)

MAKE_RELEASE.rst

@@ -14,8 +14,8 @@ Prepare/make release on dev.
    * Control / Update API_changes.rst
    * Update CHANGELOG.rst
       * Add commits from last release, but selectively !
-        git log --oneline v3.12.0..HEAD > commit.log
-        git log --pretty="%an" v3.12.0..HEAD | sort -uf > authors.log
+        git log --oneline v3.12.1..HEAD > commit.log
+        git log --pretty="%an" v3.12.1..HEAD | sort -uf > authors.log
         update AUTHORS.rst and CHANGELOG.rst
         cd doc; ./build_html
    * rm -rf build/* dist/*

README.rst

@@ -12,7 +12,8 @@ PyModbus - A Python Modbus Stack
    :target: https://gurubase.io/g/pymodbus
    :alt: PyModbus Guru
 
-Pymodbus is a full Modbus protocol implementation offering a client and server with synchronous/asynchronous API and simulators.
+Pymodbus is a full Modbus protocol implementation offering a client, server and simulator with synchronous/asynchronous API.
+Please observe that pymodbus follows the standard modbus and have only limited support for non-standard devices.
 
 Our releases follow the pattern `X.Y.Z`. We have strict rules for what different version number updates mean:
 
@@ -22,9 +23,9 @@ Our releases follow the pattern `X.Y.Z`. We have strict rules for what different
 
 Upgrade examples:
 
-- 3.9.0 -> 3.9.2: just plugin the new version, no changes needed.
+- 3.12.0 -> 3.12.2: just plugin the new version, no changes needed.
                   Remark fixing bugs, can lead to a different behaviors/returns
-- 3.8.0 -> 3.9.0: Smaller changes to the pymodbus calls might be needed
+- 3.10.0 -> 3.12.0: Smaller changes to the pymodbus calls might be needed (Check `API_changes <https://github.com/pymodbus-dev/pymodbus/blob/dev/API_changes.rst>`_)
 - 2.5.4 -> 3.0.0: Major changes in the application might be needed
 
 **REMARK**: As can be seen from the above Pymodbus do NOT follow the semver.org standard.
@@ -35,7 +36,7 @@ as well as the
 `API_changes <https://github.com/pymodbus-dev/pymodbus/blob/dev/API_changes.rst>`_
 files.
 
-Current release is `3.12.0 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.12.0>`_.
+Current release is `3.12.1 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.12.1>`_.
 
 Bleeding edge (not released) is `dev <https://github.com/pymodbus-dev/pymodbus/tree/dev>`_.
 
@@ -44,7 +45,7 @@ and all API changes are `documented <https://pymodbus.readthedocs.io/en/latest/s
 
 A big thanks to all the `volunteers <https://pymodbus.readthedocs.io/en/latest/source/authors.html>`_ that helps make pymodbus a great project.
 
-Source code on `github <https://github.com/pymodbus-dev/pymodbus>`_
+Source code is available on `github <https://github.com/pymodbus-dev/pymodbus>`_
 
 Full documentation for newest releases as well as the bleeding edge (dev) `readthedocs <https://pymodbus.readthedocs.io>`_
 
@@ -53,9 +54,9 @@ Pymodbus in a nutshell
 Pymodbus consist of 5 parts:
 
 - **client**, connect to your favorite device(s)
-- **server**, simulate your favorite device(s)
+- **server**, create your own device(s)
 - **simulator**, an html based server simulator
-- **examples**, showing both simple and advances usage
+- **examples**, showing both simple and advanced usage
 
 Common features
 ^^^^^^^^^^^^^^^
@@ -66,7 +67,7 @@ Common features
 * Does not have third party dependencies, apart from pyserial (optional)
 * Very lightweight project
 * Requires Python >= 3.10
-* Thorough test suite, that test all corners of the library
+* Thorough test suite, that test all corners of the library (100% test coverage)
 * Automatically tested on Windows, Linux and MacOS combined with python 3.10 - 3.14
 * Strongly typed API (py.typed present)
 
@@ -78,21 +79,20 @@ Client Features
 ^^^^^^^^^^^^^^^
 * Asynchronous API and synchronous API for applications
 * Very simple setup and call sequence (just 6 lines of code)
-* Utilities to convert int/float to/from multiple registers
-* Encoder/decoder to help with standard python data types
+* Utilities to convert python data types to/from multiple registers
 
 `Client documentation <https://pymodbus.readthedocs.io/en/latest/source/client.html>`_
 
 
 Server Features
 ^^^^^^^^^^^^^^^
 * Asynchronous implementation for high performance
-* Synchronous API classes for convenience
-* Simulate real life devices
+* Synchronous API classes for convenience (runs async internally)
+* Emulate real life devices
 * Full server control context (device information, counters, etc)
 * Different backend datastores to manage register values
 * Callback to intercept requests/responses
-* Work on RS485 in parallel with other devices
+* Work limited on RS485 in parallel with other devices
 
 `Server documentation <https://pymodbus.readthedocs.io/en/latest/source/server.html>`_
 
@@ -198,7 +198,7 @@ Clone the source, and make a virtual environment::
    cd pymodbus
    python3 -m venv .venv
 
-Activate the virtual environment, this command needs repeated in every new terminal::
+Activate the virtual environment, this command needs to be repeated in every new terminal::
 
    source .venv/bin/activate
 
@@ -210,9 +210,9 @@ or the bleeding edge::
 
    git checkout dev
 
-Some distributions have an old pip, which needs to be upgraded:
-
-   pip install --upgrade pip
+.. note::
+   Please always make your changes in a branch, and never submit a pull request
+   from dev.
 
 Install required development tools in editable mode::
 
@@ -223,7 +223,7 @@ Install all (allows creation of documentation etc) in editable mode::
     pip install -e ".[all]"
 
 .. note::
-   The use of the ``-e`` (editable) flag is recommended when working on the ``dev`` branch. 
+   The use of the ``-e`` (editable) flag is recommended when making changes. 
    It registers the ``pymodbus`` namespace in your virtual environment using pointers to the 
    source directory. This ensures that any changes you make to the core library are 
    immediately reflected when running examples or tests.
@@ -263,17 +263,35 @@ need, feel free to submit them so others can benefit.
 Also, if you have a question, please `create a post in discussions q&a topic <https://github.com/pymodbus-dev/pymodbus/discussions/new?category=q-a>`_,
 so that others can benefit from the results.
 
-- If you think, that something in the code is broken/not running well, please `open an issue <https://github.com/pymodbus-dev/pymodbus/issues/new>`_,
-  read the Template-text first and then post your issue with your setup information.
+If you think, that something in the code is broken/not running well, please `open an issue <https://github.com/pymodbus-dev/pymodbus/issues/new>`_,
+read the Template-text first and then post your issue with your setup information.
 
 `Example documentation <https://pymodbus.readthedocs.io/en/dev/source/examples.html>`_
 
-Troubleshooting the dev branch
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Ready to go simulator
+^^^^^^^^^^^^^^^^^^^^^
+The simulator can be started directly using the installed entry point::
+
+    pymodbus.simulator --modbus_device device_try
+
+**Configuration Parameters:**
+
+To ensure the simulator starts with the correct data context, use the following flags:
+
+* ``--json_file``: Path to the configuration JSON (defaults to the internal ``setup.json``).
+* ``--modbus_server``: Selects the server type from the JSON ``server_list``.
+* ``--modbus_device``: Selects the device registers from the JSON ``device_list``.
+* ``--http_port``: Port for the Web UI (default: 8081).
+* ``--log``: Sets the log level (default: info).
+
+.. note:: Starting the simulator without explicit parameters may load an internal default configuration.
+
+Troubleshooting examples
+^^^^^^^^^^^^^^^^^^^^^^^^
 If you encounter errors while running examples, please check:
 
 1. **Namespace Error** (``*** ERROR --> PyModbus not found``): 
-   The package is not registered. Please ensure you followed the installation 
+   The pymodbus package is not registered/installed. Please ensure you followed the installation 
    steps in the `Install with github`_ section above.
 
 2. **Directory Error** (``*** ERROR --> THIS EXAMPLE needs the example directory...``): 
@@ -283,7 +301,8 @@ If you encounter errors while running examples, please check:
 
 Contributing
 ------------
-Just fork the repo and raise your Pull Request against :code:`dev` branch.
+Just fork the repo and raise your Pull Request against :code:`dev` branch, but please never
+make your changes on the :code:`dev` branch
 
 We always have more work than time, so feel free to open a discussion / issue on a theme you want to solve.
 
@@ -330,6 +349,11 @@ Test your changes::
    cd test
    pytest
 
+or
+   ./check_ci.sh
+
+This command also generates the coverage files, which are stored in :code:`build/cov``
+
 you can also do extended testing::
 
    pytest --cov         <-- Coverage html report in build/html

check_ci.sh

@@ -8,6 +8,6 @@ trap 'echo "\"${last_command}\" command filed with exit code $?."' EXIT
 codespell
 ruff check --fix --exit-non-zero-on-fix .
 pylint --recursive=y examples pymodbus test
-zuban check pymodbus examples
+zuban check pymodbus examples test
 pytest -x --cov --numprocesses auto
 echo "Ready to push"

doc/source/_static/examples.tgz

@@ -5,6 +5,27 @@ Configuring the pymodbus simulator is done with a json file, or if only
 using the datastore simulator a python dict (same structure as the
 device part of the json file).
 
+
+Starting the Simulator
+----------------------
+
+The simulator is invoked via the command line entry point. The following parameters allow you to select your configuration and control the server behavior:
+
+* ``--json_file``: 
+    Path to the JSON configuration file. 
+    **Note:** The simulator will validate the existence of this file and fail to start with an error message if it is missing.
+* ``--modbus_server``: 
+    Selects which server configuration to load from the ``server_list``.
+* ``--modbus_device``: 
+    Selects which device registers to load from the ``device_list``.
+* ``--http_host`` / ``--http_port``: 
+    Defines the binding address and port for the Web UI (default port: 8081).
+* ``--log``: 
+    Sets the logging level (choices: critical, error, warning, info, debug).
+* ``--custom_actions_module``: 
+    Optional Python file for custom register behaviors.
+
+
 Json file layout
 ----------------
 

doc/source/_static/examples.zip

@@ -23,7 +23,7 @@ Usage examples
 
 Class definitions
 ^^^^^^^^^^^^^^^^^
-.. autoclass:: pymodbus.constants.DataType
+.. autoclass:: pymodbus.simulator.DataType
     :members:
     :undoc-members:
     :member-order: bysource