# 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](#1-übersicht)
- [2. Implementierte Features](#2-implementierte-features)
  - [2.1. Modbus RTU Server](#21-modbus-rtu-server)
  - [2.2. Ventilsteuerung (Simuliert)](#22-ventilsteuerung-simuliert)
  - [2.3. Digitale Ein- und Ausgänge](#23-digitale-ein--und-ausgänge)
  - [2.4. Systemfunktionen](#24-systemfunktionen)
  - [2.5. Fail-Safe Watchdog](#25-fail-safe-watchdog)
  - [2.6. Simulierter Firmware-Update-Prozess](#26-simulierter-firmware-update-prozess)
  - [2.7. Persistente Einstellungen](#27-persistente-einstellungen)
- [3. Kommandozeilen-Interface (Shell)](#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.