Change slave to device_id and slave= to device_id=. (#2600)

Author: janiversen

API_changes.rst

@@ -2,13 +2,15 @@ API changes
 ===========
 Versions (X.Y.Z) where Z > 0 e.g. 3.0.1 do NOT have API changes!
 
------------------
-API changes 3.9.0
+API changes 4.0.0
 -----------------
 - Python 3.9 is reaching end of life, and no longer supported.
   Depending on the usage the code might still work
-- Start*Server, custom_functions -> custom_pdu (handled by Modbus<x>Server)
-- payload removed (replaced by "convert_combined_to/from_registers")
+- Start*Server, custom_functions is now custom_pdu (handled by Modbus<x>Server)
+- 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
 
 API changes 3.8.0
 -----------------

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

doc/source/_static/examples.tgz

@@ -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

@@ -11,7 +11,7 @@ Datastore classes
     :members:
     :member-order: bysource
 
-.. autoclass:: pymodbus.datastore.ModbusSlaveContext
+.. autoclass:: pymodbus.datastore.ModbusDeviceContext
     :members:
     :member-order: bysource
 

doc/source/client.rst

@@ -72,7 +72,7 @@
             },
             {
                 "value": 17,
-                "text": "report_slave_id",
+                "text": "report_device_id",
                 "selected": false
             },
             {
@@ -131,7 +131,7 @@
             },
             {
                 "value": 4,
-                "text": "SLAVE_FAILURE",
+                "text": "DEVICE_FAILURE",
                 "selected": false
             },
             {
@@ -141,7 +141,7 @@
             },
             {
                 "value": 6,
-                "text": "SLAVE_BUSY",
+                "text": "DEVICE_BUSY",
                 "selected": false
             },
             {
@@ -164,4 +164,4 @@
         "call_rows": [],
         "foot": "not active",
         "result": "ok"
-    }
+    }

doc/source/library/datastore.rst

@@ -87,7 +87,7 @@ Server configuration examples
                 "comm": "tcp",
                 "host": "0.0.0.0",
                 "port": 5020,
-                "ignore_missing_slaves": false,
+                "ignore_missing_devices": false,
                 "framer": "socket",
                 "identity": {
                     "VendorName": "pymodbus",
@@ -123,7 +123,7 @@ Server configuration examples
                 "port": 5020,
                 "certfile": "certificates/pymodbus.crt",
                 "keyfile": "certificates/pymodbus.key",
-                "ignore_missing_slaves": false,
+                "ignore_missing_devices": false,
                 "framer": "tls",
                 "identity": {
                     "VendorName": "pymodbus",
@@ -138,7 +138,7 @@ Server configuration examples
                 "comm": "udp",
                 "host": "0.0.0.0",
                 "port": 5020,
-                "ignore_missing_slaves": false,
+                "ignore_missing_devices": false,
                 "framer": "socket",
                 "identity": {
                     "VendorName": "pymodbus",

doc/source/library/simulator/calls_response.rst

@@ -20,12 +20,11 @@ The following bullet points are what the maintainers focus on:
 - 4.0.0, with:
     - Simulator datastore, with simple configuration
     - Remove remote_datastore
-    - Remove BinaryPayload
     - Server becomes Simulator
     - client async with sync/async API
     - Only one datastore, but with different API`s
 - 4.1.0, with:
-    - ModbusControlBlock pr slave
+    - ModbusControlBlock pr device
     - New custom PDU (function codes)
     - New serial forwarder
     - GUI client, to analyze devices

doc/source/library/simulator/config.rst

@@ -0,0 +1,47 @@
+Pymodbus 4.0 upgrade procedure
+==============================
+
+Pymodbus 4.0 contains a number of incompatibilities with Pymodbus 3.x, however
+most of these are simple edits.
+
+Python 3.9
+----------
+Python 3.9 is reaching end of life and from october 2025 no longer receives security updates.
+
+Pymodbus starting with v4.0 start using python 3.10 features, and thus users need to update to
+at least python v3.10
+
+Users that cannot upgrade the python version, should not upgrade pymodbus to v4.X
+
+
+Start<x>Server
+--------------
+custom_funcion= is changed to custom_pdu= and is handled by Modbus<x>Server.
+
+
+payload classes removed
+-----------------------
+Please replace by result.convert_from_registers() and/or convert_to_registers()
+
+
+Simple replacements
+-------------------
+
+please replace
+- slave= with device_id=
+- slaves= with device_ids=
+- ModbusServerContext(slaves=) with ModbusServerContext(devices=)
+
+please rename
+- ModbusSlaveContext to ModbusDeviceContext
+- RemoteSlaveContext to RemoteDeviceContext
+- report_slave_id() with report_device_id()
+- diag_read_slave_message_count with diag_read_device_message_count
+- diag_read_slave_no_response_count with diag_read_device_no_response_count
+- diag_read_slave_nak_count with diag_read_device_nak_count
+- diag_read_slave_busy_count with diag_read_device_busy_count
+- ReturnSlaveMessageCountRequest with ReturnDeviceMessageCountRequest
+- ReturnSlaveNoResponseCountRequest with ReturnDeviceNoResponseCountRequest
+- ReturnSlaveNAKCountRequest with ReturnDeviceNAKCountRequest
+- ReturnSlaveBusyCountRequest with ReturnDeviceBusyCountRequest
+- ReturnSlaveBusCharacterOverrunCountRequest with ReturnDeviceBusCharacterOverrunCountRequest