irrigation_system/docs/modbus-registers.en.md

🇩🇪 Deutsch | 🇬🇧 English

MODBUS Register Map Definition v1.0

1. Introduction

This document defines the MODBUS registers for the universal slave nodes of the irrigation system.

1.1. Addressing Philosophy

All registers are defined in a single, continuous list per register type (Input or Holding). A "Category" column logically assigns the function. The addresses are grouped in blocks to leave room for future extensions and to increase readability.

• 0x0000 - 0x000F: Valve control & status
• 0x0010 - 0x001F: Digital outputs (LEDs / relays)
• 0x0020 - 0x002F: Digital inputs (buttons / sensors)
• 0x00F0 - 0x00FF: General device configuration & status
• 0x0100 - 0x01FF: Firmware update mechanism

1.2. Used Function Codes

• 0x03 (Read Holding Registers): For reading 4xxxx registers.
• 0x04 (Read Input Registers): For reading 3xxxx registers.
• 0x06 (Write Single Register): For writing a single 4xxxx register.
• 0x10 (Write Multiple Registers): For writing multiple 4xxxx registers at once.

2. Input Registers (3xxxx, Read-Only)

Address (hex)	Name	Category	Description
0x0000	VALVE_STATE_MOVEMENT	Valve	Combined status register. High-Byte: Movement (0=Idle, 1=Opening, 2=Closing, 3=Error). Low-Byte: State (0=Closed, 1=Open).
0x0001	MOTOR_CURRENT_MA	Valve	Current motor current in milliamperes (mA).
0x0020	DIGITAL_INPUTS_STATE	Inputs	Bitmask of the digital inputs. Bit 0: Input 1, Bit 1: Input 2. 1=Active.
0x0021	BUTTON_EVENTS	Inputs	Event flags for buttons (Clear-on-Read). Bit 0: Button 1 pressed. Bit 1: Button 2 pressed.
0x00F0	FIRMWARE_VERSION_MAJOR_MINOR	System	e.g. 0x0102 for v1.2.
0x00F1	FIRMWARE_VERSION_PATCH	System	e.g. 3 for v1.2.3.
0x00F2	DEVICE_STATUS	System	0=OK, 1=General error.
0x00F3	UPTIME_SECONDS_LOW	System	Lower 16 bits of the uptime in seconds.
0x00F4	UPTIME_SECONDS_HIGH	System	Upper 16 bits of the uptime.
0x0100	FWU_LAST_CHUNK_CRC	Firmware-Update	Contains the CRC16 of the last data chunk received in the buffer.

3. Holding Registers (4xxxx, Read/Write)

Address (hex)	Name	Category	Description
0x0000	VALVE_COMMAND	Valve	1=Open, 2=Close, 0=Stop movement.
0x0001	MAX_OPENING_TIME_S	Valve	Safety timeout in seconds for the opening process.
0x0002	MAX_CLOSING_TIME_S	Valve	Safety timeout in seconds for the closing process.
0x0010	DIGITAL_OUTPUTS_STATE	Outputs	Bitmask for reading and writing the outputs. Bit 0: Output 1, Bit 1: Output 2. 1=ON, 0=OFF.
0x00F0	WATCHDOG_TIMEOUT_S	System	Timeout of the fail-safe watchdog in seconds. 0=Disabled.
0x0100	FWU_COMMAND	Firmware-Update	1: Verify Chunk: The last transmitted chunk was found to be valid by the client. The slave should now write it to flash. 2: Finalize Update: All chunks have been transmitted. Finalize installation and restart.
0x0101	FWU_CHUNK_OFFSET_LOW	Firmware-Update	Lower 16 bits of the 32-bit offset to which the next chunk is to be written.
0x0102	FWU_CHUNK_OFFSET_HIGH	Firmware-Update	Upper 16 bits of the 32-bit offset.
0x0103	FWU_CHUNK_SIZE	Firmware-Update	Size of the next chunk in bytes (max. 256).
0x0180	FWU_DATA_BUFFER	Firmware-Update	Start address of a 128x16-bit buffer (256 bytes). Corresponds to registers 40384 to 40511.

4. Detailed Firmware Update Process

This process is stateless and robust against transmission errors.

1. Client: Selects a chunk (max. 256 bytes) from the firmware file and calculates its CRC16.
2. Client: Writes the target offset (e.g. 0) to FWU_CHUNK_OFFSET_... and the size to FWU_CHUNK_SIZE.
3. Client: Writes the chunk data to the FWU_DATA_BUFFER (from address 0x0180).
4. Slave: Receives the data, places it in the RAM buffer and calculates the CRC. The result is provided in FWU_LAST_CHUNK_CRC (30256).
5. Client: Reads FWU_LAST_CHUNK_CRC and compares the value with the self-calculated CRC.
   • Error: Go back to step 3 to send the same chunk again.
   • Success: Continues with the next step.
6. Client: Writes the command 1 ("Verify Chunk") to FWU_COMMAND (40256).
7. Slave: Receives the command, takes the verified chunk from the RAM buffer and writes it to the correct location in the flash memory.
8. Client: Continues with the next chunk (back to step 1 with new offset and data).
9. Last Chunk: After the last chunk has been transferred and written to flash with command 1, the client writes the command 2 ("Finalize Update") to FWU_COMMAND.
10. Slave: Performs final checks and restarts so that MCUBoot can perform the installation.

Appendix: QDY30A Level Sensor Registers

These registers belong to the external level sensor and can also be addressed on the bus. According to the manufacturer, these are Holding Registers (4xxxx) that are read with function code 0x03.

Address (hex)	Name	R/W	Description
0x0000	NODE_ADDRESS	R/W	Device address of the sensor (1-255).
0x0001	BAUDRATE	R/W	0=1200, 1=2400, 2=4800, 3=9600, 4=19200, 5=38400, 6=57600, 7=115200.
0x0002	UNIT	R/W	0=None, 1=cm, 2=mm, 3=MPa, 4=Pa, 5=kPa.
0x0003	DECIMAL_PLACES	R/W	Number of decimal places for the measured value (0-3).
0x0004	CURRENT_MEASUREMENT	R	The scaled measured value as a signed 16-bit integer.
0x0005	MEASURING_RANGE_ZERO_POINT	R/W	Raw value for the zero point of the scale.
0x0006	MEASURING_RANGE_END_POINT	R/W	Raw value for the end point of the scale.