irrigation_system/docs/modbus-registers.de.md

🇩🇪 Deutsch | 🇬🇧 English | 🇫🇷 Français | 🇪🇸 Español

MODBUS Register Map Definition v1.0

1. Einleitung

Dieses Dokument definiert die MODBUS-Register für die universellen Slave-Nodes des Bewässerungssystems.

1.1. Adressierungs-Philosophie

Alle Register sind in einer einzigen, durchgehenden Liste pro Register-Typ (Input oder Holding) definiert. Eine Spalte "Zugehörigkeit" ordnet die Funktion logisch zu. Die Adressen sind in Blöcken gruppiert, um Raum für zukünftige Erweiterungen zu lassen und die Lesbarkeit zu erhöhen.

• 0x0000 - 0x000F: Ventilsteuerung & Status
• 0x0010 - 0x001F: Digitale Ausgänge (LEDs / Relais)
• 0x0020 - 0x002F: Digitale Eingänge (Taster / Sensoren)
• 0x00F0 - 0x00FF: Allgemeine Gerätekonfiguration & Status
• 0x0100 - 0x01FF: Firmware-Update-Mechanismus

1.2. Verwendete Funktionscodes

• 0x03 (Read Holding Registers): Zum Lesen von 4xxxx Registern.
• 0x04 (Read Input Registers): Zum Lesen von 3xxxx Registern.
• 0x06 (Write Single Register): Zum Schreiben eines einzelnen 4xxxx Registers.
• 0x10 (Write Multiple Registers): Zum Schreiben mehrerer 4xxxx Register am Stück.

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

Adresse (hex)	Name	Zugehörigkeit	Beschreibung
0x0000	VALVE_STATE_MOVEMENT	Ventil	Kombiniertes Status-Register. High-Byte: Bewegung (0=Idle, 1=Öffnet, 2=Schliesst, 3=Fehler). Low-Byte: Zustand (0=Geschlossen, 1=Geöffnet).
0x0001	MOTORSTROM_OPEN_MA	Ventil	Motorstrom beim Öffnen in Milliampere (mA).
0x0002	MOTORSTROM_CLOSE_MA	Ventil	Motorstrom beim Schließen in Milliampere (mA).
0x0020	DIGITAL_INPUTS_STATE	Eingänge	Bitmaske der digitalen Eingänge. Bit 0: Eingang 1, Bit 1: Eingang 2. 1=Aktiv.
0x0021	BUTTON_EVENTS	Eingänge	Event-Flags für Taster (Clear-on-Read). Bit 0: Taster 1 gedrückt. Bit 1: Taster 2 gedrückt.
0x00F0	FIRMWARE_VERSION_MAJOR_MINOR	System	z.B. 0x0102 für v1.2.
0x00F1	FIRMWARE_VERSION_PATCH	System	z.B. 3 für v1.2.3.
0x00F2	DEVICE_STATUS	System	0=OK, 1=Allgemeiner Fehler.
0x00F3	UPTIME_SECONDS_LOW	System	Untere 16 Bit der Uptime in Sekunden.
0x00F4	UPTIME_SECONDS_HIGH	System	Obere 16 Bit der Uptime.
0x00F5	SUPPLY_VOLTAGE_MV	System	Aktuelle Versorgungsspannung in Millivolt (mV).
0x0100	FWU_LAST_CHUNK_CRC	Firmware-Update	Enthält den CRC16 des zuletzt im Puffer empfangenen Daten-Chunks.

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

Adresse (hex)	Name	Zugehörigkeit	Beschreibung
0x0000	VALVE_COMMAND	Ventil	1=Öffnen, 2=Schliessen, 0=Bewegung stoppen.
0x0001	MAX_OPENING_TIME_S	Ventil	Sicherheits-Timeout in Sekunden für den Öffnen-Vorgang.
0x0002	MAX_CLOSING_TIME_S	Ventil	Sicherheits-Timeout in Sekunden für den Schliessen-Vorgang.
0x0003	END_CURRENT_THRESHOLD_OPEN_MA	Ventil	Minimaler Stromschwellenwert in mA zur Endlagenerkennung beim Öffnen.
0x0004	END_CURRENT_THRESHOLD_CLOSE_MA	Ventil	Minimaler Stromschwellenwert in mA zur Endlagenerkennung beim Schliessen.
0x0010	DIGITAL_OUTPUTS_STATE	Ausgänge	Bitmaske zum Lesen und Schreiben der Ausgänge. Bit 0: Ausgang 1, Bit 1: Ausgang 2. 1=AN, 0=AUS.
0x00F0	WATCHDOG_TIMEOUT_S	System	Timeout des Fail-Safe-Watchdogs in Sekunden. 0=Deaktiviert.
0x00F1	DEVICE_RESET	System	Schreibt 1 um das Gerät neu zu starten.
0x0100	FWU_COMMAND	Firmware-Update	1: Verify Chunk: Der zuletzt übertragene Chunk wurde vom Client als gültig befunden. Der Slave soll ihn nun ins Flash schreiben. 2: Finalize Update: Alle Chunks sind übertragen. Installation abschliessen und neu starten.
0x0101	FWU_CHUNK_OFFSET_LOW	Firmware-Update	Untere 16 Bit des 32-Bit-Offsets, an den der nächste Chunk geschrieben werden soll.
0x0102	FWU_CHUNK_OFFSET_HIGH	Firmware-Update	Obere 16 Bit des 32-Bit-Offsets.
0x0103	FWU_CHUNK_SIZE	Firmware-Update	Grösse des nächsten Chunks in Bytes (max. 256).
0x0180	FWU_DATA_BUFFER	Firmware-Update	Startadresse eines 128x16-bit Puffers (256 Bytes). Entspricht den Registern 40384 bis 40511.

4. Detaillierter Firmware-Update-Prozess

Dieser Prozess ist zustandslos und robust gegen Übertragungsfehler.

1. Client: Wählt einen Chunk (max. 256 Bytes) aus der Firmware-Datei und berechnet dessen CRC16.
2. Client: Schreibt den Ziel-Offset (z.B. 0) in FWU_CHUNK_OFFSET_... und die Grösse in FWU_CHUNK_SIZE.
3. Client: Schreibt die Chunk-Daten in den FWU_DATA_BUFFER (ab Adresse 0x0180).
4. Slave: Empfängt die Daten, legt sie im RAM-Puffer ab und berechnet den CRC. Das Ergebnis wird in FWU_LAST_CHUNK_CRC (30256) bereitgestellt.
5. Client: Liest FWU_LAST_CHUNK_CRC und vergleicht den Wert mit dem selbst berechneten CRC.
   • Fehler: Gehe zurück zu Schritt 3, um den gleichen Chunk erneut zu senden.
   • Erfolg: Fährt mit dem nächsten Schritt fort.
6. Client: Schreibt den Befehl 1 ("Verify Chunk") in FWU_COMMAND (40256).
7. Slave: Empfängt den Befehl, nimmt den verifizierten Chunk aus dem RAM-Puffer und schreibt ihn an die richtige Stelle im Flash-Speicher.
8. Client: Fährt mit dem nächsten Chunk fort (zurück zu Schritt 1 mit neuem Offset und Daten).
9. Letzter Chunk: Nachdem der letzte Chunk übertragen und mit Befehl 1 ins Flash geschrieben wurde, schreibt der Client den Befehl 2 ("Finalize Update") in FWU_COMMAND.
10. Slave: Führt Abschlussprüfungen durch und startet neu, damit MCUBoot die Installation durchführt.

Anhang: QDY30A Füllstandsensor Register

Diese Register gehören zum externen Füllstandsensor und können auf dem Bus ebenfalls adressiert werden. Es handelt sich laut Hersteller um Holding Registers (4xxxx), die mit Funktionscode 0x03 gelesen werden.

Adresse (hex)	Name	R/W	Beschreibung
0x0000	NODE_ADDRESS	R/W	Geräteadresse des Sensors (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=Keine, 1=cm, 2=mm, 3=MPa, 4=Pa, 5=kPa.
0x0003	DECIMAL_PLACES	R/W	Anzahl der Dezimalstellen für den Messwert (0-3).
0x0004	CURRENT_MEASUREMENT	R	Der skalierte Messwert als vorzeichenbehafteter 16-Bit-Integer.
0x0005	MEASUREMENT_RANGE_ZERO_POINT	R/W	Rohwert für den Nullpunkt der Skala.
0x0006	MEASUREMENT_RANGE_END_POINT	R/W	Rohwert für den Endpunkt der Skala.