irrigation_system/docs/firmware-manual.de.md

Firmware-Handbuch (Slave Node)

Status: Work in Progress (WIP)

Dieses Dokument beschreibt den aktuellen Funktionsumfang der Firmware für den slave_node des Bewässerungssystems.

Inhaltsverzeichnis

• 1. Übersicht
• 2. Implementierte Features
  • 2.1. Modbus RTU Server
  • 2.2. Ventilsteuerung (Simuliert)
  • 2.3. Digitale Ein- und Ausgänge
  • 2.4. Systemfunktionen
  • 2.5. Fail-Safe Watchdog
  • 2.6. Simulierter Firmware-Update-Prozess
  • 2.7. Persistente Einstellungen
• 3. Kommandozeilen-Interface (Shell)

1. Übersicht

Die Firmware macht aus einem Standard-Mikrocontroller (wie dem Bluepill STM32F103) einen intelligenten Modbus-Slave, der zur Steuerung eines motorisierten Ventils und zur Überwachung einfacher digitaler Sensoren dient.

2. Implementierte Features

2.1. Modbus RTU Server

• Schnittstelle: Läuft auf der Standard-UART-Schnittstelle des Boards.
• Konfiguration: Baudrate und Slave-ID können über die Shell zur Laufzeit geändert und persistent gespeichert werden.
• Register-Map: Implementiert die in docs/modbus-registers.de.md definierte Register-Map.

2.2. Ventilsteuerung (Simuliert)

• Zustandsmaschine: Eine virtuelle Ventilsteuerung simuliert die Zustände "Geöffnet", "Geschlossen" und die Bewegungen "Öffnet" und "Schließt".
• Zeitbasierte Bewegung: Die Dauer für einen vollständigen Öffnungs- oder Schließvorgang kann über Modbus-Register (MAX_OEFFNUNGSZEIT_S, MAX_SCHLIESSZEIT_S) konfiguriert werden.
• Befehle: Das Ventil kann über das VENTIL_BEFEHL-Register gestartet, gestoppt und in die jeweilige Richtung bewegt werden.

2.3. Digitale Ein- und Ausgänge

• Ausgänge: Der Zustand von zwei digitalen Ausgängen kann über das DIGITAL_AUSGAENGE_ZUSTAND-Register gelesen und geschrieben werden. In der aktuellen Implementierung ist dies rein virtuell und wird nur geloggt.
• Eingänge: Der Zustand von zwei digitalen Eingängen wird im DIGITAL_EINGAENGE_ZUSTAND-Register abgebildet. Diese sind für den Anschluss von Tastern oder Sensoren vorgesehen.
• Taster-Events: Das TASTER_EVENTS-Register speichert Bit-Flags für "gedrückt"-Events und wird beim Lesen automatisch zurückgesetzt (Clear-on-Read).

2.4. Systemfunktionen

• Uptime: Die Firmware zählt die Sekunden seit dem letzten Start und stellt sie über zwei 16-Bit-Register zur Verfügung.
• Firmware-Version: Die Version (vX.Y.Z) ist fest einkompiliert und kann über die entsprechenden Register ausgelesen werden.
• Gerätestatus: Ein einfaches Statusregister (DEVICE_STATUS) zeigt den allgemeinen Zustand des Geräts an (0 = OK).

2.5. Fail-Safe Watchdog

• Funktionsweise: Ein Timer wird bei jeder erfolgreichen Modbus-Kommunikation zurückgesetzt.
• Timeout: Läuft der Timer ab (Timeout konfigurierbar über WATCHDOG_TIMEOUT_S), wird als Sicherheitsmaßnahme automatisch der Befehl zum Schließen des Ventils ausgelöst.
• Aktivierung: Das Schreiben eines Wertes > 0 in das Register aktiviert den Watchdog. Das Schreiben einer 0 deaktiviert ihn.

2.6. Simulierter Firmware-Update-Prozess

• Protokoll: Der in der Modbus-Dokumentation beschriebene, zustandslose Update-Prozess ist vollständig implementiert.
• Datenempfang: Das Gerät kann Firmware-Chunks (max. 256 Bytes) im FWU_DATA_BUFFER empfangen.
• CRC-Verifizierung: Nach dem Empfang eines Chunks berechnet der Slave dessen CRC16 und stellt das Ergebnis im FWU_LAST_CHUNK_CRC-Register bereit, damit der Client die Übertragung überprüfen kann.
• Flash-Schreiben (Simuliert): Der Befehl zum Schreiben eines verifizierten Chunks ins Flash wird aktuell nur geloggt. Es finden keine echten Schreiboperationen statt.
• Finalisierung (Simuliert): Der Befehl zum Abschluss des Updates und Neustart wird ebenfalls nur geloggt.

2.7. Persistente Einstellungen

• Technologie: Das Zephyr Settings Subsystem wird mit NVS (Non-Volatile Storage) auf einer dedizierten Flash-Partition verwendet.
• Gespeicherte Werte:
  • Modbus Baudrate
  • Modbus Slave ID
  • Maximale Öffnungszeit des Ventils
  • Maximale Schließzeit des Ventils

3. Kommandozeilen-Interface (Shell)

Die Firmware bietet eine Shell über die RTT-Schnittstelle für Debugging und Konfiguration.

• modbus get: Zeigt die aktuelle Modbus-Konfiguration (Baudrate, Slave ID).
• modbus set baudrate <wert>: Setzt die Baudrate.
• modbus set slave_id <wert>: Setzt die Slave ID.
• valve show_config: Zeigt die aktuelle Ventil-Konfiguration.
• valve set_open_time <sekunden>: Setzt die maximale Öffnungszeit.
• valve set_close_time <sekunden>: Setzt die maximale Schließzeit.
• reset: Führt einen Neustart des Geräts durch.