From c4e87a3125e02003a6043be31c399eb37308a655 Mon Sep 17 00:00:00 2001 From: Eduard Iten Date: Tue, 1 Jul 2025 22:51:17 +0200 Subject: [PATCH] docs: Add firmware manual and update main README - Create a new firmware manual (`firmware-manual.de.md`) to document the current features of the slave node. - Add a linked table of contents to the new manual. - Update the main `README.de.md` to link to the new firmware manual and the existing Modbus tool README. --- README.de.md | 2 + docs/firmware-manual.de.md | 82 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/firmware-manual.de.md diff --git a/README.de.md b/README.de.md index b007e9c..1a579f9 100644 --- a/README.de.md +++ b/README.de.md @@ -11,6 +11,8 @@ Die detaillierte Dokumentation befindet sich im Verzeichnis [`docs/`](./docs/): * **[Konzept](./docs/concept.de.md)**: Beschreibt die Systemarchitektur, die verwendeten Komponenten und die grundlegenden Design-Entscheidungen. * **[MODBUS Register](./docs/modbus-registers.de.md)**: Definiert die Register-Map für die Kommunikation mit den Slave-Nodes. * **[Projektplan](./docs/planning.de.md)**: Enthält den Entwicklungs- und Implementierungsplan. +* **[Firmware-Handbuch](./docs/firmware-manual.de.md)**: Beschreibt den Funktionsumfang und die Bedienung der Slave-Node-Firmware. +* **[Modbus Test-Tool](./software/tools/modbus_tool/README.de.md)**: Anleitung für das Python-basierte Kommandozeilen-Tool zum Testen der Slaves. ## Schnellstart diff --git a/docs/firmware-manual.de.md b/docs/firmware-manual.de.md new file mode 100644 index 0000000..6e72b3b --- /dev/null +++ b/docs/firmware-manual.de.md @@ -0,0 +1,82 @@ +# 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 `**: Setzt die Baudrate. +- **`modbus set slave_id `**: Setzt die Slave ID. +- **`valve show_config`**: Zeigt die aktuelle Ventil-Konfiguration. +- **`valve set_open_time `**: Setzt die maximale Öffnungszeit. +- **`valve set_close_time `**: Setzt die maximale Schließzeit. +- **`reset`**: Führt einen Neustart des Geräts durch. \ No newline at end of file