Differences

This shows you the differences between two versions of the page.

--- projekte:ionpy:ideen [2026/02/13 08:45] – ↷ Page moved from projekte:ideen to projekte:ionpy:ideen dominik
+++ projekte:ionpy:ideen [2026/02/13 09:16] (current) – [Implementierung (Code-Skizze)] dominik
@@ Line 1: / Line 1: @@
-====== ionpy Framework Erweiterungs-Spezifikation ======
+====== ionpy Framework: Erweiterte Architektur-Spezifikation (Vollständig) ======
-Dieses Dokument beschreibt die geplanten Erweiterungen für das ionpy-Framework zur Verbesserung der Benutzerinteraktion, Datenstrukturierung und Automatisierung.
+Dieses Dokument beschreibt die integrale Architektur-Erweiterung des ionpy-Frameworks. Es dient als verbindliche Grundlage für die Implementierung neuer Entitätstypen, haptischer Steuerungen und geräteübergreifender Automatisierung.
-===== 1. Synchronisations- & Sperrstrategie (Race Condition Protection) =====
+===== 1. Dynamische Eingabesynchronisation (Race Condition Schutz) =====
-Um Konflikte zwischen automatischem Polling und Benutzereingaben zu vermeiden, wird eine zweistufige Sperre implementiert.
+Um zu verhindern, dass Hintergrund-Polling Benutzereingaben im Frontend überschreibt, wird ein duales Sperrsystem implementiert.
 ==== 1.1 Backend: Mute-Timer (AbstractDevice) ====
-[cite_start]In der Basisklasse ''AbstractDevice'' wird ein Zeitstempel-Tracking eingeführt[cite: 117].
+[cite_start]In der Klasse ''AbstractDevice'' (hardware/base.py) wird eine zeitbasierte Sperre pro Entität eingeführt[cite: 117, 120].
-  * **Mechanismus**: Bei Ausführung von ''execute_command'' wird ein Mute-Timer (default 3s) für die spezifische ''entity_id'' gesetzt.
+  * [cite_start]**Mechanismus**: Ein Dictionary ''self._last_command_time: Dict[str, float]'' speichert den Zeitpunkt des letzten Schreibbefehls[cite: 11, 54].
-  * [cite_start]**Logik**: Die Methode ''update_entity'' verwirft eingehende Polling-Daten, solange der Timer aktiv ist[cite: 128].
+  * **Logik**:
-  * **Ziel**: Verhindert das Zurückspringen von Werten in der UI, während die Hardware den neuen Wert noch verarbeitet.
+    * [cite_start]Sobald ''execute_command()'' aufgerufen wird, erhält die ''entity_id'' einen Zeitstempel[cite: 13, 138].
+    * [cite_start]Die Methode ''update_entity()'' prüft diesen Zeitstempel: Liegt er weniger als **3,0 Sekunden** in der Vergangenheit, wird das Sample verworfen und nicht auf den Bus publiziert[cite: 87, 136].
+  * **Ziel**: Die Hardware hat Zeit, den Wert intern zu setzen, und der Polling-Loop liest keine "alten" Werte mehr zurück, während der User noch interagiert.
-==== 1.2 Frontend: Focus-Lock (Web-UI) ====
+==== 1.2 Frontend: Universeller Focus-Lock (JS) ====
-Universelle Sperre im JavaScript-Frontend (z.B. in ''settings.html'').
+In der Web-UI (settings.html) wird eine automatische Erkennung aktiver Eingabefelder implementiert.
-  * **Mechanismus**: Ein zentrales ''Set'' speichert die IDs aller Felder, die aktuell den Fokus haben (Event-Delegation via ''focusin'').
+  * **Mechanismus**: Nutzung eines ''Set()'' namens ''activeInputs''.
-  * **Logik**: Eingehende WebSocket-Updates werden ignoriert, wenn die Element-ID im ''Set'' registriert ist.
+  * **Event-Delegation**:
-  * **Beispiel**: Während ein User "12.5" in ein Feld tippt, darf ein eintreffendes Sample das Feld nicht auf "10.0" zurücksetzen.
+    * ''focusin'': Fügt die Element-ID zum Set hinzu.
+    * ''focusout'': Entfernt die ID nach einer kurzen Verzögerung (ca. 300-500ms).
+  * **WebSocket-Logik**: Die Funktion ''channel.onmessage'' prüft vor dem Update eines HTML-Elements, ob dessen ID im Set vorhanden ist. [cite_start]Falls ja, wird das Update verworfen[cite: 53, 54].
-===== 2. Strukturierte Daten: TableEntity =====
+===== 2. Strukturierte Daten: TableEntity (Deep Dive) =====
-Einführung einer komplexen Entität zur Abbildung von Speicherplätzen, Profilen und Sequenzen.
+Die ''TableEntity'' ist das Herzstück für komplexe Geräteeigenschaften wie Speicherplätze (M1-M10), Profil-Listen (Sequenzer) oder Zell-Übersichten.
-  * **Struktur**:
+==== 2.1 Datenstruktur & Schema ====
-    * ''columns'': Definition der Spalten (Name, Typ, Unit, Constraints).
+Eine ''TableEntity'' kapselt nicht nur Daten, sondern auch deren Bedeutung.
-    * ''value'': Eine Liste von Dictionaries (Rows).
+  * **Schema (columns)**: Definition der Spalten-Metadaten.
-  * **Beispiel (UDP3305 Sequenzer)**:
+    * Jede Spalte definiert: ''key'', ''name'', ''type'' (number/text/toggle/action), ''unit'', sowie Constraints (''min'', ''max'', ''step'').
-    * Spalten: ''Step'', ''Voltage (V)'', ''Current (A)'', ''Duration (s)''.
+  * **Daten (value)**: Eine Liste von Dictionaries, wobei jedes Dictionary eine Zeile darstellt.
-  * **Interaktion**: Das Frontend sendet bei Änderung ein Koordinaten-Objekt: ''{ "row": 0, "col": "volt", "val": 12.0 }''.
+  * **Typen**: Unterscheidung zwischen ''fixed_size'' (z.B. genau 10 Speicherplätze) und ''dynamic_size'' (Zeilen hinzufügbar/löschbar).
-===== 3. Gamepad Integration (Human Interface Device) =====
+==== 2.2 Erweiterte Interaktions-Logik ====
-Anbindung von Gamecontrollern zur haptischen Steuerung von Laborgeräten auf Basis von ''pygame''.
+  * **Row-Updates**: Das Frontend sendet Koordinaten-Pakete: ''{ "row": r, "col": "key", "val": value }''.
+  * **Atomic Row Actions**: Unterstützung einer Spalte vom Typ ''button''. Dies ermöglicht "Apply"-Buttons pro Zeile, um einen kompletten Parametersatz (z.B. Volt und Ampere eines Presets) gleichzeitig an die Hardware zu senden, um instabile Zustände zu vermeiden.
+  * **Active Row Tracking**: Ein zusätzliches Attribut ''active_row_index'' markiert die Zeile, die das Gerät aktuell tatsächlich verwendet (z.B. welcher Speicherplatz gerade geladen ist).
+  * **Zell-basiertes Muting**: Die Mute-Logik aus Kapitel 1 wird auf Zellebene angewendet, sodass eine Bearbeitung in Zeile 1 nicht die Live-Updates von Zeile 2 blockiert.
-==== 3.1 GamepadManager & Discovery ====
+===== 3. Gamepad-Integration (HID-Steuerung) =====
-Ein neuer System-Treiber scannt mittels ''pygame.joystick'' dynamisch nach angeschlossenen Controllern.
+Haptische Steuerung via USB-Controller, realisiert durch das ''pygame''-Subsystem.
-  * [cite_start]** gamepad.py**: Erbt von ''AbstractDevice''[cite: 116].
-  * **GamepadEntity**: Kapselt den gesamten Zustand (Achsen, Buttons, Hats) in einem einzigen Objekt.
-==== 3.2 Visualisierung ====
+==== 3.1 GamepadManager (hardware/system/gamepad.py) ====
-  * [cite_start]**Achsen**: Darstellung als Fadenkreuz oder analoge Level-Balken (analog zu ''NumericEntity'' mit ''UIMode.LEVEL'')[cite: 154].
+Ein neuer Treiber-Typ, der autonom nach Controllern sucht.
-  * **Buttons**: Darstellung als virtuelle Status-LEDs.
+  * [cite_start]**Discovery**: Nutzt ''pygame.joystick.get_count()'' und ''get_id()'', um Controller dynamisch zu finden, ohne Hardcoding in der Config[cite: 63, 64].
+  * [cite_start]**GamepadEntity**: Eine neue Entitätsklasse, die den Zustand (Axes, Buttons, Hats, Triggers) als Snapshot-Objekt im ''value''-Feld hält[cite: 135].
-===== 4. LogicService & Automation Bridge =====
+==== 3.2 Haptisches Feedback & Visualisierung ====
-Der zentrale Dienst zur Verknüpfung von Events (z.B. Gamepad -> Netzteil).
+  * [cite_start]**UI-Widgets**: Spezielle Web-Komponenten für Joysticks (Fadenkreuz) und Trigger (Druckempfindliche Balken via ''UIMode.LEVEL'')[cite: 422].
+  * **Sicherheitskonzept**: Implementierung eines "Deadman-Switch" (Totmannknopf). Steuerbefehle werden nur an andere Geräte weitergeleitet, wenn eine definierte Taste am Gamepad gehalten wird.
-  * [cite_start]**Funktionsweise**: Ein asynchroner Task in der Engine abonniert den ''EventBus''[cite: 86, 427].
+===== 4. LogicService: Die Automation Bridge =====
-  * **Regel-Engine**: Vergleicht eintreffende Samples mit einer JSON-basierten Regelliste.
+[cite_start]Zentraler asynchroner Dienst in der ''SystemEngine''[cite: 81], der als Vermittler zwischen dem Bus und den Geräte-Kommandos fungiert.
-  * **Beispiel-Regel**:
-<code>
-{
-  "trigger": { "device": "gamepad_0", "entity": "axis_1" },
-  "action": { "device": "psu_1", "entity": "ch1_v_set", "scale": 32.0 }
-}
-</code>
-  * **Cross-Device-Talking**: Ermöglicht es Geräten, aufeinander zu reagieren (z.B. Senke folgt der Spannung des Netzteils), ohne die Treiber-Logik zu verändern.
-===== 5. Neue Entitätstypen (Katalog) =====
+==== 4.1 Die Rule-Engine ====
-[cite_start]Erweiterung der ''structures/enums.py'' und ''structures/entities.py''[cite: 421, 414].
+[cite_start]Der Dienst abonniert den ''EventBus'' [cite: 85, 427] und prozessiert Regeln aus einer ''rules.json''.
+  * [cite_start]**Trigger**: Ein Sample von Gerät A (z.B. Gamepad-Achse oder BMS-Temperatur)[cite: 424].
+  * **Transformation (Scaling)**: Mathematische Umwandlung von Eingangswerten (z.B. Gamepad-Stick -1.0...+1.0) in Zielwerte (z.B. Netzteil 0.0...32.0 V).
+  * [cite_start]**Action**: Ausführung von ''engine.execute_command(target_dev, key, transformed_val)''[cite: 84, 433].
-^ Typ ^ Beschreibung ^ Beispiel ^
+==== 4.2 Cross-Device Szenarien (Beispiele) ====
-| **LogEntity** | Chronologischer Ereignis-Feed pro Gerät | "OVP triggered", "Calibration OK" |
+  * **Synchronisation**: Die elektronische Last (Senke) folgt automatisch der Spannung des Netzteils (Quelle), um eine konstante Leistung (CP-Mode) über das Framework zu simulieren.
-| **StatusIndicator** | Visuelle "LED"-Anzeige (Farben/Blinken) | Alarm-Status, Power-LED |
+  * **Master-Slave**: Zwei Netzteile werden so gekoppelt, dass Kanal 2 immer exakt dem Wert von Kanal 1 folgt.
-| **FileEntity** | Schnittstelle für Up/Downloads | Firmware-Update, Log-Export |
-| **XYGraphEntity** | Kennliniendarstellung (X vs Y statt Zeit) | U/I-Kurve, Bode-Plot |
-| **RangeEntity** | Kapselung von Start, Stopp und Step | Sweep-Definition (Frequenz) |
-| **ScheduleEntity** | Zeitbasierte Steuerbefehle | "Ausgang aus um 22:00 Uhr" |
-===== 6. Technische Basis =====
+===== 5. Erweiterter Entitäten-Katalog =====
-  * [cite_start]**Backend**: Python 3.10+, FastAPI (Asynchron), Pygame (Gamepad)[cite: 1, 437].
+[cite_start]Zusätzliche spezialisierte Typen für professionelle Laboranforderungen[cite: 421, 422, 423]:
-  * [cite_start]**Kommunikation**: JSON-Samples über asynchronen EventBus[cite: 86, 424].
-  * [cite_start]**Frontend**: HTML5/JS (WebSockets) für Echtzeit-Visualisierung[cite: 52, 427].
+^ Typ ^ UI-Repräsentation ^ Funktionalität ^
+| **LogEntity** | Scrollende Konsole | Lokaler Ereignis-Speicher für gerätespezifische Fehler (z.B. SCPI-Fehlermeldungen). |
+| **StatusIndicator** | Virtuelle LED | Farb-Mapping für Zustände (z.B. 0=Off, 1=OK/Grün, 2=Warnung/Gelb, 3=Alarm/Rot-Blinkend). |
+| **XYGraphEntity** | Kennlinien-Plot | Darstellung von X-Y-Beziehungen (z.B. Batterie-Entladekurve: Spannung über Kapazität). |
+| **FileEntity** | Upload/Download | Schnittstelle für Firmware-Dateien (z.B. ESPHome .bin) oder Konfigurations-Exports. |
+| **RangeEntity** | Multi-Slider/Input | Gruppiert logisch zusammengehörige Werte für Sweeps (Start, Stop, Step, Intervall). |
+| **ScheduleEntity** | Zeitplan-Editor | Verwaltung von Zeitereignissen (z.B. "Schalte Ausgang an Wochentagen um 08:00 Uhr an"). |
+===== 6. Implementierungs-Leitfaden für KI-Entwicklung =====
+  * [cite_start]**Concurrency**: Alle Logik-Operationen müssen asynchron (''async/await'') ausgeführt werden, um den Hardware-Poll-Loop nicht zu blockieren[cite: 1, 9].
+  * [cite_start]**Caching**: Die ''SystemEngine'' nutzt ihren ''state_cache'' als "Single Source of Truth" für die Logic-Regeln[cite: 81, 84].
+  * **Modularität**: Neue Entitäten müssen in ''structures/entities.py'' definiert und in der ''settings.html'' mit einem entsprechenden UI-Generator verknüpft werden.
+===== 7. Erweiterte Web-Views (Advanced Visualization) =====
+Um die wachsende Komplexität der Daten (Gamepad, BMS, IMU-Sensoren) beherrschbar zu machen, werden spezialisierte Views implementiert.
+==== 7.1 XYZ / 3D-Visualisierung (Spatial View) ====
+Diese View nutzt Bibliotheken wie **Three.js** oder **Plotly.js**, um Daten im dreidimensionalen Raum darzustellen.
+  * [cite_start]**Anwendungsfall A: IMU/Orientierung**: Visualisierung der Fluglage oder Position eines Sensors (basierend auf der ''VectorEntity'' [cite: 419]). [cite_start]Ein 3D-Modell (z.B. ein PCB oder eine Batteriebox) neigt sich in Echtzeit entsprechend der Daten aus dem ''VirtualLaboratory''[cite: 252, 263].
+  * **Anwendungsfall B: Multi-Parameter-Sweeps**: Darstellung von Abhängigkeiten wie "Effizienz über Eingangsspannung und Laststrom". Hierbei entsteht eine 3D-Oberfläche (Surface Plot).
+  * **Anwendungsfall C: Raum-Mapping**: Wenn Sensordaten mit Positionsdaten gekoppelt sind (z.B. Temperatur-Mapping einer Oberfläche).
+==== 7.2 Multi-Device Dashboard (Global View) ====
+[cite_start]Die aktuelle UI ist stark auf einzelne Tabs pro Gerät fokussiert[cite: 16]. Die ''Global View'' bricht diese Struktur auf.
+  * **Konzept**: Eine frei konfigurierbare Kachel-Ansicht (Grid-Layout), in der Entitäten verschiedener Geräte gemischt werden können.
+  * [cite_start]**Beispiel**: Ein "Power-Dashboard", das die Eingangsleistung vom ''UDP3305'' [cite: 303][cite_start], den Zellstatus vom ''JbdBms'' [cite: 145] [cite_start]und die Lastdaten der ''AtorchDL24'' [cite: 211] auf einer einzigen Seite zusammenfasst.
+==== 7.3 Logic-Flow Visualizer (Automation View) ====
+Da der geplante ''LogicService'' komplex werden kann, ist eine textuelle Regel-Liste oft unübersichtlich.
+  * **Konzept**: Eine Node-basierte Darstellung (ähnlich wie Node-RED).
+  * [cite_start]**Darstellung**: Blöcke repräsentieren Trigger (z.B. Gamepad [cite: 255][cite_start]), Logik-Gatter und Aktionen (z.B. Netzteil-Kommando [cite: 326]).
+  * [cite_start]**Live-Feedback**: Linien zwischen den Blöcken leuchten kurz auf, wenn ein Event über den ''EventBus'' fließt[cite: 85].
+==== 7.4 Session Replay & Analyse (History View) ====
+[cite_start]Basierend auf dem ''SessionManager''.
+  * **Konzept**: Eine Ansicht zum "Zurückspulen" vergangener Messungen.
+  * [cite_start]**Funktion**: Über eine Timeline kann eine aufgezeichnete Session (identifiziert durch die ''session_id'' ) ausgewählt werden. Die UI zeigt dann die historischen Daten so an, als würden sie gerade live passieren.
+  * **Vergleichs-Modus**: Zwei Sessions können übereinandergelegt werden (z.B. Entladekurve von Batterie A vs. Batterie B).
+==== 7.5 Synoptic View (Prozessgrafik) ====
+  * **Konzept**: Ein statisches Hintergrundbild (z.B. ein Foto deines Versuchsaufbaus oder ein Schaltplan), auf dem die Live-Werte der Entitäten an den physikalisch korrekten Stellen eingeblendet werden.
+  * **Nutzen**: Extrem intuitive Überwachung von komplexen Verdrahtungen.
+==== Sonstiges ====
+Was ich mir sonst noch vorstellen könnte:
+  * Virtuelle Instrumente (Skins): Dass du für das UDP3305 eine View baust, die exakt so aussieht wie die Frontplatte des echten Geräts. Das macht die Bedienung im Web viel natürlicher.
+  * Webcam-Integration mit Overlay: Wenn dein Pi eine Kamera hat, könntest du den Videostream anzeigen und die Messwerte (z.B. Temperatur) direkt über das Bild legen (ähnlich wie Augmented Reality).
+  * Alarm-Management: Eine View, die nur dann aufpoppt, wenn Grenzwerte überschritten werden (z.B. BMS-Alarm ).
+===== 7.6 Webcam & Augmented Reality (AR) Overlay =====
+Diese View kombiniert visuelles Feedback der Hardware mit den Live-Daten des EventBus.
+==== Architektur des Datenflusses ====
+  * **Video-Pfad**: Webcam -> OpenCV -> FastAPI StreamingResponse (MJPEG) -> Browser <img>.
+  * **Daten-Pfad**: Hardware -> EventBus -> WebSocket -> Browser Canvas.
+  * **Vorteil**: Die hohe Last des Videos beeinträchtigt nicht die Echtzeit-Messdaten auf dem Bus.
+==== Features ====
+  * **AR-Overlay**: Positionierung von Messwerten direkt über dem Videobild (z.B. Temperaturanzeige direkt auf dem Kühlkörper im Bild).
+  * **Visual CV**: Optionale Bilderkennung im Backend, die Ergebnisse (z.B. "Gerät eingeschaltet") als reguläre Samples auf den Bus publiziert.
+==== Implementierung (Code-Skizze) ====
+  * **Backend**: Neuer API-Endpunkt unter ''/api/video/stream''.
+  * **Frontend**: Dynamisches Canvas-Mapping. Koordinaten für Overlays werden in der ''config.yaml'' des Geräts gespeichert.
+==== 7.7 Visual Event Trigger (Virtual Sensor) ====
+Zusätzlich zum Videostream kann das System Bildbereiche (ROI) analysieren, um "virtuelle Sensoren" zu generieren.
+  * **Funktion**: Überwachung von analogen Anzeigen oder LEDs, die keine Datenschnittstelle besitzen.
+  * **Verarbeitung**:
+. ROI Definition via Koordinaten.
+. HSV-Farbraumfilterung zur Detektion von Statusfarben.
+. State-Machine zur Vermeidung von Bus-Spam (nur Änderungen werden publiziert).
+  * **Anwendung**: "BMS Alarm LED" -> EventBus -> "PSU OFF".
+==== 7.8 Optical Character Recognition (OCR) Sensor ====
+Verwandelt visuelle Anzeigen in digitale Datenströme.
+  * **Technologie**: Integration von ''Tesseract'' oder ''SSOCR'' in den Webcam-Treiber.
+  * **Datenfluss**:
+. Extraktion der Anzeige via ROI.
+. Bildvorbehandlung (Grayscale, Thresholding, Morphologie).
+. Konvertierung String -> Float/Int.
+. Publikation als ''NumericSample'' oder ''TextSample'' auf dem EventBus.
+  * **Anwendung**: Digitalisierung von Legacy-Hardware ohne Schnittstellen (DMMs, Waagen, analoge Anzeigen).
+===== 8. Zusammenfassung der Datenfluss-Architektur =====
+Der Datenfluss im erweiterten System folgt nun diesem Muster:
+  - [cite_start]**Hardware/Input** (z.B. Owon HDS [cite: 270] [cite_start]oder Gamepad) -> **Bus**[cite: 85].
+  - [cite_start]**LogicService** (Abonniert Bus) -> Berechnet Transformation -> **Engine.execute_command**[cite: 84].
+  - [cite_start]**Web-Views** (Abonnieren Bus via WebSocket [cite: 427]) -> Filtern nach Focus-Lock -> **Visualisierung** (3D, Table, Graph).