Merge branch 'dev'

Author: janiversen

API_changes.rst

@@ -2,7 +2,27 @@ API changes
 ===========
 Versions (X.Y.Z) where Z > 0 e.g. 3.0.1 do NOT have API changes!
 
+API changes 3.10.0
 -----------------
+- ModbusSlaveContext replaced by ModbusDeviceContext
+- payload removed (replaced by "convert_to/from_registers")
+- slave=, slaves= replaced by device_id=, device_ids=
+- slave request names changed to device
+- bit handling order is LSB (last byte) -> MSB (first byte)
+  readCoils and other bit functions now return bit in logical order (NOT byte order)
+
+  Older versions had LSB -> MSB pr byte
+  V3.10 have LSB -> MSB across bytes.
+
+  Example:
+  Hex bytes: 0x00 0x01
+  Older versions would deliver False * 8 True False * 7
+  V3.10 deliver True False * 15
+
+  Hex bytes: 0x01 0x03
+  Older versions would deliver True False * 7 True True False * 6
+  V3.10 deliver True True False * 6 True False * 7
+
 API changes 3.9.0
 -----------------
 - Python 3.9 is reaching end of life, and no longer supported.

AUTHORS.rst

@@ -25,6 +25,7 @@ Thanks to
 - banana-sun
 - Blaise Thompson
 - Breina
+- brherger
 - CapraTheBest
 - cgernert
 - corollaries
@@ -41,13 +42,15 @@ Thanks to
 - Dries
 - duc996
 - efdx
+- Erlend E. Aasland
 - Esco441-91
 - Farzad Panahi
 - Fredo70
 - Gao Fang
 - Ghostkeeper
 - Hangyu Fan
 - Hayden Roche
+- igorbga
 - Iktek
 - Ilkka Ollakka
 - Jakob Ruhe
@@ -67,6 +70,8 @@ Thanks to
 - Kürşat Aktaş
 - laund
 - Logan Gunthorpe
+- Luke Hoggatt
+- Mark Deneen
 - Marko Luther
 - Martyy
 - Máté Szabó

CHANGELOG.rst

@@ -7,6 +7,27 @@ helps make pymodbus a better product.
 
 :ref:`Authors`: contains a complete list of volunteers have contributed to each major version.
 
+Version 3.10.0
+-------------
+* Raise runtimeerror if listen() fails. (#2697)
+* Correct values parameter in setValues. (#2696)
+* Correct return from getValues. (#2695)
+* Add request fc to exceptionResponse. (#2694)
+* DummyProtocol is not async (#2686)
+* Handle "little" for multiple values in to_registers (#2678)
+* Remove unused const. (#2676)
+* Add retries to ModbusPDU class (#2672)
+* Don't invoke `trace_connect` callback twice (#2670)
+* ensure unpacking of proper length during decoding (#2664) (#2665)
+* README clean-up (#2659)
+* Bump coverage to 95,5% (#2658)
+* Simplify response rejection. (#2657)
+* Bump coverage to 93%. (#2656)
+* Solve ModbusDeviceContext bug. (#2653)
+* Bit handling LSB -> MSB across bytes. (#2634)
+* Change slave to device_id and slave= to device_id=. (#2600)
+* Remove payload. (#2524)
+
 Version 3.9.2
 -------------
 * Reactivate simulator validate. (#2643)

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2008-2023 Pymodbus
+Copyright 2008-2025 Pymodbus
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions

README.rst

@@ -12,9 +12,9 @@ PyModbus - A Python Modbus Stack
    :target: https://gurubase.io/g/pymodbus
    :alt: PyModbus Guru
 
-Pymodbus is a full Modbus protocol implementation offering client/server with synchronous/asynchronous API and simulators.
+Pymodbus is a full Modbus protocol implementation offering a client and server with synchronous/asynchronous API and simulators.
 
-Our releases is defined as X.Y.Z, and we have strict rules what to release when:
+Our releases follow the pattern `X.Y.Z`. We have strict rules for what different version number updates mean:
 
 - **Z**, No API changes! bug fixes and smaller enhancements.
 - **Y**, API changes, bug fixes and bigger enhancements.
@@ -23,10 +23,13 @@ Our releases is defined as X.Y.Z, and we have strict rules what to release when:
 Upgrade examples:
 
 - 3.9.0 -> 3.9.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
 - 2.5.4 -> 3.0.0: Major changes in the application might be needed
 
-Current release is `3.9.2 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.9.2>`_.
+It is always recommended to read the CHANGELOG as well as the API_changes files.
+
+Current release is `3.10.0 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.10.0>`_.
 
 Bleeding edge (not released) is `dev <https://github.com/pymodbus-dev/pymodbus/tree/dev>`_.
 
@@ -124,10 +127,10 @@ server, the server is handy to verify the functionality of an application.
 
 The simulator and/or server is often used to simulate real life devices testing
 applications. The server is excellent to perform high volume testing (e.g.
-houndreds of devices connected to the application). The advantage of the server is
-that it runs not only a "normal" computers but also on small ones like Raspberry PI.
+hundreds of devices connected to the application). The advantage of the server is
+that it runs not only on "normal" computers but also on small ones like a Raspberry PI.
 
-Since the library is written in python, it allows for easy scripting and/or integration into their existing
+Since the library is written in python, it allows for easy scripting and/or integration into existing
 solutions.
 
 For more information please browse the project documentation:
@@ -240,7 +243,7 @@ The repository contains a number of important branches and tags.
 
 Example Code
 ------------
-For those of you that just want to get started fast, here you go::
+For those of you who just want to get started quickly, here you go::
 
     from pymodbus.client import ModbusTcpClient
 
@@ -289,7 +292,7 @@ solving issues:
 There are 2 bigger projects ongoing:
 
    * rewriting the internal part of all clients (both sync and async)
-   * Add features to and simulator, and enhance the web design
+   * Add features to the simulator, and enhance the web design
 
 
 Development instructions
@@ -326,7 +329,7 @@ you can also do extended testing::
 Internals
 ^^^^^^^^^
 
-There are no documentation of the architecture (help is welcome), but most classes and
+There is no documentation of the architecture (help is welcome), but most classes and
 methods are documented:
 
 `Pymodbus internals <https://pymodbus.readthedocs.io/en/dev/source/internals.html>`_

doc/index.rst

@@ -8,6 +8,7 @@ Please select a topic in the left hand column.
    :caption: Contents:
    :hidden:
 
+   source/upgrade_40
    source/api_changes
    source/client
    source/server
@@ -20,6 +21,5 @@ Please select a topic in the left hand column.
    source/changelog
    source/internals
    source/roadmap
-   source/upgrade_40
 
 .. include:: ../README.rst

doc/source/_static/examples.tgz

@@ -15,8 +15,8 @@ It is allowed to have multiple client objects that e.g. each communicate with a
 
 Client performance
 ------------------
-There are currently a big performance gap between the 2 clients
-(try it on your computer :github:`examples/client_performance.py`).
+There are currently a big performance gap between the 2 clients.
+
 This is due to a rather old implementation of the synchronous client, we are currently working to update the client code.
 Our aim is to achieve a similar data rate with both clients and at least double the data rate while keeping the stability.
 Table below is a test with 1000 calls each reading 10 registers.
@@ -127,12 +127,12 @@ Synchronous example
 
     from pymodbus.client import ModbusTcpClient
 
-    client = ModbusTcpClient('MyDevice.lan')   # Create client object
-    client.connect()                           # connect to device
-    client.write_coil(1, True, slave=1)        # set information in device
-    result = client.read_coils(2, 3, slave=1)  # get information from device
-    print(result.bits[0])                      # use information
-    client.close()                             # Disconnect device
+    client = ModbusTcpClient('MyDevice.lan')       # Create client object
+    client.connect()                               # connect to device
+    client.write_coil(1, True, device_id=1)        # set information in device
+    result = client.read_coils(2, 3, device_id=1)  # get information from device
+    print(result.bits[0])                          # use information
+    client.close()                                 # Disconnect device
 
 The line :mod:`client.connect()` connects to the device (or comm port). If this cannot connect successfully within
 the timeout it throws an exception. After this initial connection, further
@@ -147,22 +147,22 @@ Asynchronous example
 
     from pymodbus.client import AsyncModbusTcpClient
 
-    client = AsyncModbusTcpClient('MyDevice.lan')    # Create client object
-    await client.connect()                           # connect to device, reconnect automatically
-    await client.write_coil(1, True, slave=1)        # set information in device
-    result = await client.read_coils(2, 3, slave=1)  # get information from device
-    print(result.bits[0])                            # use information
-    client.close()                                   # Disconnect device
+    client = AsyncModbusTcpClient('MyDevice.lan')        # Create client object
+    await client.connect()                               # connect to device, reconnect automatically
+    await client.write_coil(1, True, device_id=1)        # set information in device
+    result = await client.read_coils(2, 3, device_id=1)  # get information from device
+    print(result.bits[0])                                # use information
+    client.close()                                       # Disconnect device
 
 The line :mod:`client = AsyncModbusTcpClient('MyDevice.lan')` only creates the object; it does not activate
 anything.
 
 The line :mod:`await client.connect()` connects to the device (or comm port), if this cannot connect successfully within
 the timeout it throws an exception. If connected successfully reconnecting later is handled automatically
 
-The line :mod:`await client.write_coil(1, True, slave=1)` is an example of a write request, set address 1 to True on device 1 (slave).
+The line :mod:`await client.write_coil(1, True, device_id=1)` is an example of a write request, set address 1 to True on device 1.
 
-The line :mod:`result = await client.read_coils(2, 3, slave=1)` is an example of a read request, get the value of address 2, 3 and 4 (count = 3) from device 1 (slave).
+The line :mod:`result = await client.read_coils(2, 3, device_id=1)` is an example of a read request, get the value of address 2, 3 and 4 (count = 3) from device 1.
 
 The last line :mod:`client.close()` closes the connection and render the object inactive.
 
@@ -194,13 +194,13 @@ Client device addressing
 ------------------------
 
 With **TCP**, **TLS** and **UDP**, the tcp/ip address of the physical device is defined when creating the object.
-Logical devices represented by the device is addressed with the :mod:`slave=` parameter.
+Logical devices represented by the device is addressed with the :mod:`device_id=` parameter.
 
 With **Serial**, the comm port is defined when creating the object.
-The physical devices are addressed with the :mod:`slave=` parameter.
+The physical devices are addressed with the :mod:`device_id=` parameter.
 
-:mod:`slave=0` is defined as broadcast in the modbus standard, but pymodbus treats it as a normal device.
-please note :mod:`slave=0` can only be used to address devices that truly have id=0 ! Using :mod:`slave=0` to
+:mod:`device_id=0` is defined as broadcast in the modbus standard, but pymodbus treats it as a normal device.
+please note :mod:`device_id=0` can only be used to address devices that truly have id=0 ! Using :mod:`device_id=0` to
 address a single device with id not 0 is against the protocol.
 
 If an application is expecting multiple responses to a broadcast request, it must call :mod:`client.execute` and deal with the responses.
@@ -217,7 +217,7 @@ All simple request calls (mixin) return a unified result independent whether it
 The application should evaluate the result generically::
 
     try:
-        rr = await client.read_coils(1, 1, slave=1)
+        rr = await client.read_coils(1, 1, device_id=1)
     except ModbusException as exc:
         _logger.error(f"ERROR: exception in pymodbus {exc}")
         raise exc

doc/source/_static/examples.zip

@@ -31,13 +31,6 @@ Source: :github:`examples/simple_sync_client.py`
 .. literalinclude:: ../../examples/simple_sync_client.py
 
 
-Client performance sync vs async
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Source: :github:`examples/client_performance.py`
-
-.. literalinclude:: ../../examples/client_performance.py
-
-
 Advanced examples
 -----------------
 
@@ -88,14 +81,6 @@ Source: :github:`examples/custom_msg.py`
     :noindex:
 
 
-Client payload
-^^^^^^^^^^^^^^
-Source: :github:`examples/client_payload.py`
-
-.. automodule:: examples.client_payload
-    :undoc-members:
-    :noindex:
-
 Client synchronous
 ^^^^^^^^^^^^^^^^^^
 Source: :github:`examples/client_sync.py`
@@ -132,15 +117,6 @@ Source: :github:`examples/server_hook.py`
     :noindex:
 
 
-Server payload
-^^^^^^^^^^^^^^
-Source: :github:`examples/server_payload.py`
-
-.. automodule:: examples.server_payload
-    :undoc-members:
-    :noindex:
-
-
 Server synchronous
 ^^^^^^^^^^^^^^^^^^
 Source: :github:`examples/server_sync.py`
@@ -186,15 +162,6 @@ Source: :github:`examples/message_parser.py`
     :noindex:
 
 
-Modbus forwarder
-^^^^^^^^^^^^^^^^
-Source: :github:`examples/modbus_forwarder.py`
-
-.. automodule:: examples.modbus_forwarder
-    :undoc-members:
-    :noindex:
-
-
 Examples contributions
 ----------------------