Ordnerstruktur

Die OSSM-Firmware folgt einer modularen, featurebasierten Architektur. Jedes Feature befindet sich in einem eigenen Namespace-Ordner, wodurch die Codebasis einfacher zu navigieren und zu verwalten ist.

Durchsuchen Sie den Quellcode auf GitHub: Software/src/

Überblick

main.cpp

platformio.ini

Ordner	Zweck
`include/boost/`	Nur-Header-Bibliotheken (Boost.SML-Zustandsmaschine)
`lib/StrokeEngine/`	Bewegungsmusterbibliothek (modifiziert)
`src/`	Hauptquellcode
`test/`	Unit-Tests

Designphilosophie

Die Firmware verwendet eine featurebasierte Organisation, in der zusammengehöriger Code gemeinsam abgelegt ist:

Namespaces statt Klassen – Features sind als Namespace-Funktionen und nicht als Klassenmethoden organisiert
Zusammengehörige Dateien – Der Header, die Implementierung und der zugehörige Code jedes Features befinden sich im selben Ordner
Globale Zustandsstrukturen – Der gemeinsame Zustand wird über dedizierte Zustandsstrukturen und nicht über Klassenmitglieder verwaltet
Zustandslose Module – Feature-Funktionen arbeiten mit dem globalen Zustand, was das Testen und Nachvollziehen erleichtert

Die OSSM-Klasse in ossm/OSSM.h wird aus Gründen der Abwärtskompatibilität mit der BLE-Befehlsverarbeitung beibehalten. Neue Funktionen sollten zustandslose Namespace-Funktionen verwenden.

Kernanwendung (`src/ossm/`)

Der Ordner ossm/ enthält die Kernanwendungslogik, geordnet nach Features.

Events.h

OSSM.h

OSSM.cpp

Ordner	Zweck
`state/`	Zustandsmaschinenarchitektur
`pages/`	UI-Bildschirme
`homing/`	Homing-Sequenz
`menu/`	Menünavigation
`simple_penetration/`	Einfacher Penetrationsmodus
`stroke_engine/`	StrokeEngine-Modus
`pattern_controls/`	Benutzeroberfläche zur Musterauswahl
`play_controls/`	Wiedergabe-/Pause-/Geschwindigkeitssteuerung

Zustandsmaschine (`ossm/state/`)

Aus Gründen der Übersichtlichkeit und Testbarkeit sind die Zustandsmaschinenkomponenten getrennt.

Datei	Zweck
`machine.h`	Übergangstabellendefinition mit Boost.SML
`actions.h` / `actions.cpp`	Zustandsübergangsaktionen (Anzeigeaktualisierungen, Motorsteuerung)
`guards.h` / `guards.cpp`	Bedingte Prüfungen für Übergänge
`state.h` / `state.cpp`	Initialisierung der Zustandsmaschine und globale Instanz

Zustandsstrukturen verwalten verschiedene Aspekte der Anwendung:

Datei	Zweck
`session.h`	Aktuelle Sitzung (Startzeit, Anzahl der Hübe, Distanz)
`settings.h`	Benutzereinstellungen (Geschwindigkeit, Hub, Empfindung, Tiefe, Muster)
`calibration.h`	Referenzzustand (Sensor-Offset, Hubschritte, Referenzstatus)
`motion.h`	Bewegungsziele (Position, Geschwindigkeit, Zeit)
`menu.h`	Aktuelle Menüauswahl
`ble.h`	Status der Bluetooth-Verbindung
`error.h`	Fehlermeldungen

Einzelheiten zur Funktionsweise der Zustandsmaschine finden Sie unter Zustandsmaschinenarchitektur.

UI-Seiten (`ossm/pages/`)

Jeder Bildschirm in der Benutzeroberfläche verfügt über ein eigenes Modul.

Modul	Beschreibung
`hello.h`	Startbildschirm mit animierten Logos
`preflight.h`	Sicherheitskontrollbildschirm „Geschwindigkeit zum Starten reduzieren“.
`error.h`	Fehleranzeige mit Hilfemöglichkeit
`update.h`	OTA-Aktualisierungsbildschirme (prüfen, aktualisieren, kein Update)
`wifi.h`	WiFi-Konfigurationsportal
`help.h`	Hilfe- und Supportinformationen

Betriebsmodi

Jeder Betriebsmodus ist mit seiner Bewegungssteuerungslogik ein eigenständiges Modul.

Modul	Beschreibung
`simple_penetration/`	Einfache Hin- und Herbewegung mit kontrollierter Geschwindigkeit
`stroke_engine/`	Komplexe Muster mithilfe der StrokeEngine-Bibliothek

Steuerungsoberflächen

Modul	Beschreibung
`menu/`	Hauptmenünavigation und Rendering
`pattern_controls/`	Musterauswahlschnittstelle für den StrokeEngine-Modus
`play_controls/`	Geschwindigkeits-, Hub-, Tiefen- und Empfindungssteuerung

Funktionsmodule

Modul	Beschreibung
`homing/`	Referenzfahrt (Vorwärtsscan, Rückwärtsscan, Kalibrierung)

Hardware-Services (`src/services/`)

Der Ordner services/ stellt Hardware-Abstraktionsschichten bereit.

stepper.h

stepper.cpp

display.h

display.cpp

encoder.h

encoder.cpp

led.h

led.cpp

board.h

board.cpp

tasks.h

tasks.cpp

wm.h

wm.cpp

nimble.h

nimble.cpp

queue.h

queue.cpp

command.hpp

state.hpp

patterns.hpp

gpio.hpp

wifi.hpp

config.hpp

Datei	Zweck
`stepper.h/.cpp`	Motorsteuerung (FastAccelStepper)
`display.h/.cpp`	OLED-Display (U8g2)
`encoder.h/.cpp`	Drehgebereingang
`led.h/.cpp`	RGB-LED-Statusanzeige
`board.h/.cpp`	Platineninitialisierung
`tasks.h/.cpp`	FreeRTOS-Aufgabenverwaltung
`wm.h/.cpp`	WiFi-Manager
`communication/`	BLE- und WiFi-Kommunikation

Einzelheiten zum BLE-Protokoll finden Sie unter BLE-Kommunikation.

Konstanten (`src/constants/`)

Konfigurationswerte und Enumerationen sind im Ordner constants/ zentralisiert.

Config.h

Pins.h

Menu.h

Version.h

UserConfig.h

Images.h

LogTags.h

Datei	Zweck
`Config.h`	Systemkonfiguration (Geschwindigkeiten, Limits, Timeouts)
`Pins.h`	GPIO-Pin-Definitionen
`Menu.h`	Enum der Menüoptionen
`Version.h`	Informationen zur Firmware-Version
`UserConfig.h`	Vom Benutzer konfigurierbare Einstellungen
`Images.h`	Bitmap-Assets für die Anzeige
`LogTags.h`	ESP-IDF-Protokollierungstags
`copy/`	Lokalisierte Zeichenfolgen

Informationen zu Konfigurationsoptionen finden Sie unter Konfiguration.

Dienstprogramme (`src/utils/`)

Hilfsfunktionen und -klassen, die in der gesamten Codebasis verwendet werden.

StateLogger.h

RecursiveMutex.h

StrokeEngineHelper.h

format.h

analog.h

update.h

ble.h

Datei	Zweck
`StateLogger.h`	Protokolliert Zustandsmaschinenübergänge zum Debuggen
`RecursiveMutex.h`	Thread-sicherer Mutex-Wrapper für ESP32
`StrokeEngineHelper.h`	StrokeEngine-Integrationsdienstprogramme
`format.h`	Hilfsprogramme zur Zeichenfolgenformatierung
`analog.h`	Mittelung und Verarbeitung analoger Eingänge
`update.h`	OTA-Update-Dienstprogramme
`ble.h`	BLE-Hilfsfunktionen

Datenstrukturen (`src/structs/`)

Gemeinsame Datentypen, die modulübergreifend verwendet werden.

SettingPercents.h

LanguageStruct.h

Points.h

Datei	Zweck
`SettingPercents.h`	Benutzereinstellungen als Prozentsätze (0-100)
`LanguageStruct.h`	Sprachkonfiguration
`Points.h`	Koordinaten- und Punktstrukturen

Umgebung	Zweck
`development`	Lokale Entwicklung mit Debug-Protokollierung
`staging`	Tests vor der Veröffentlichung
`production`	Release-Builds mit Optimierungen
`test`	Unit-Test-Konfiguration

Ordnerstruktur

Ordnerstruktur

Überblick

Designphilosophie

Kernanwendung (`src/ossm/`)

Zustandsmaschine (`ossm/state/`)

UI-Seiten (`ossm/pages/`)

Betriebsmodi

Steuerungsoberflächen

Funktionsmodule

Hardware-Services (`src/services/`)

Konstanten (`src/constants/`)

Dienstprogramme (`src/utils/`)

Datenstrukturen (`src/structs/`)

Bibliotheken

Boost.SML (`include/boost/sml.hpp`)

StrokeEngine (`lib/StrokeEngine/`)

Build-Konfiguration

Weiterführende Literatur

Zustandsmaschine

Konfiguration

Anzeigeservice

BLE-Kommunikation

Auf dieser Seite