Why is there an address offset of +1 between ModbusDeviceContext and BaseModbusDataBlock?

[MrWaloo]

Hi there,

Regarding these 2 lines in ModbusDeviceContext getValues and setValues:

pymodbus/pymodbus/datastore/context.py

Line 121 in 97c3bbf

address += 1

pymodbus/pymodbus/datastore/context.py

Line 132 in 97c3bbf

address += 1

--> There is an offset of +1 between ModbusDeviceContext and BaseModbusDataBlock.

---

In my Modbus Server application, I have to fetch the registers' value on every request (if the last actualisation is too old), so I made my own class based on ModbusSparseDataBlock:

	class MyModbusSparseDataBlock(ModbusSparseDataBlock):
	(...)
		def getValues(self, address, count=1) -> list[int] | list[bool] | ExcCodes:
			'''Function called when the server reads values from this data block.
			We override it to fetch the latest command values before returning them.
			'''
			self.log.debug(f"{self.name}: DataBlock: Getting values from address {address} count {count}")
			values = super().getValues(address, count)
			if isinstance(values, ExcCodes):
				self.log.error(f"{self.name}: DataBlock: ExcCodes")
				return values
			(...) # fetching values

In my example self.name = 'Eq1', here the log for a single request of 2 registers at address 2 (sorry if the log format does not fit the rules) :

0013|[2026-01-18 18:11:30] INFO  : Server listening.
0014|[2026-01-18 18:11:46] DEBUG  : Connected to server
0015|[2026-01-18 18:11:46] DEBUG  : recv: 0x0 0x1 0x0 0x0 0x0 0x6 0x1 0x3 0x0 0x2 0x0 0x2 extra data:
0016|[2026-01-18 18:11:46] DEBUG  : Processing: 0x0 0x1 0x0 0x0 0x0 0x6 0x1 0x3 0x0 0x2 0x0 0x2
0017|[2026-01-18 18:11:46] DEBUG  : decoded PDU function_code(3 sub -1) -> ReadHoldingRegistersRequest(dev_id=0, transaction_id=0, address=2, count=2, bits=[], registers=[], status=1, retries=0)
0018|[2026-01-18 18:11:46] DEBUG  : getValues: fc-[3] address-3: count-2
0019|[2026-01-18 18:11:46] DEBUG  : Eq1: DataBlock: Getting values from address 3 count 2

We see the incoming request asks for register address 2 but ModbusSparseDataBlock.getValues is called with address 3

I think that the two lines address += 1 should be removed or at least I have to make a address -= 1, but it does not make any sense.

Am I wrong somewhere in my implementation?
Am I the only one having troubles with this offset?
Is it actually an issue?

As I could find out these 2 lines come from #2354 for the release 3.8.0.
The zero-mode is the default mode because the address in a request is coded on 2 bytes and is from 0 to 65535 (0x0000 to 0xFFFF) as described in the chapter 4.4 of the MODBUS Application Protocol Specification V1.1b3.
To me, these lines should be deleted.

I can make a PR if you agree with me, but I don't know if there is a pytest test case and don't know pytest, so I won't be able to fix the test case in the same PR. But if I do the PR, I will let it editable so any test case can be fixed later.

edit: in the same Modbus specification document, the data model is described in the chapter 4.3 as follows:

For each of the primary tables, the protocol allows individual selection of 65536 data items,
and the operations of read or write of those items are designed to span multiple consecutive
data items up to a data size limit which is dependent on the transaction function code.
(...)
MODBUS logical reference numbers, which are used in MODBUS functions, are unsigned
integer indices starting at zero.

So the values of *DataBlock should start at 0.

[janiversen]

There is a difference between how you define registers and how you address/request registers because it is very old code.

Change to use the simulator datablock if you do not want the +1 difference.

[janiversen]

We do not want to change the old data blocks as it would break all existing usages.

[MrWaloo]

Are the other datablocks (not simulator datablocks) meant to disappear in a future release?

[janiversen]

They will exist in all v3.x versions, but are expected to be removed in v4.0.

There is a new datastore in the works, a simplified version of the current simulator datastore which will be released in v3.x and in v4.x will be the only datastore. The current server and simulator will grow together in v4.x.

Once v4.0 is released the last v3.x will be in active maintenance for at least a year.

[janiversen]

Forgot to say, after SimData/SimCore goes into production it is possible that somebody changes the current datablock s to internally use SimData in that case they will re main in v4.x

[MrWaloo]

In the new datablock, will there still be this +1 offset?

[janiversen]

Please take a look at the sim datablock which is in production, it do not have the +1 rule, neither will newer datablocks.