From bf89a62daa46f3efd0ff61e2d0aa8fd9f1925c41 Mon Sep 17 00:00:00 2001 From: Maximilian Lechner Date: Thu, 26 Feb 2026 20:10:38 +0000 Subject: [PATCH 1/2] readme --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) diff --git a/README.md b/README.md index 97a1003..e6bef15 100644 --- a/README.md +++ b/README.md @@ -136,3 +136,161 @@ max_paket_box/ ├── tests/ │ ├── test_paketbox.py # Umfassende Unit Tests ... (rest of content continues same as original) + + +### Modulare Architektur (Version 0.7.0) +Das System wurde in separate Module aufgeteilt: +- **`paketbox.py`**: Hauptsteuerung und GPIO-Event-Loop +- **`handler.py`**: GPIO-Handler und Motor-Steuerungsfunktionen +- **`state.py`**: Zentrale Zustandsverwaltung für Thread-Sicherheit +- **`config.py`**: Alle Konfigurationen und GPIO-Pin-Zuordnungen +- **`PaketBoxState.py`**: Enum-Definitionen für Tür- und Motorstatus +- **`TimerManager.py`**: Sichere Verwaltung von Motor-Timern +- **`mqtt.py`**: MQTT-Integration mit Fallback-Mechanismus + +## ⚙️ Konfiguration (config.py) + +Die `config.py` enthält alle Systemparameter und GPIO-Pin-Zuordnungen: + +### Timer & Steuerung +```python +CLOSURE_DELAY = 60 # Verzögerung vor dem Schließen der Klappen (Sekunden) +CLOSURE_TIMER_SECONDS = 65 # Zeit zum automatischen Schließen der Klappen +OPENING_TIMER_SECONDS = 65 # Zeit zum automatischen Öffnen der Klappen +DEBOUNCE_TIME = 0.2 # Entprellungszeit für Sensoren (Sekunden) +``` + +### Türverriegelung +```python +TIME_LOCK_DOOR = "00:00" # Uhrzeit: Türverriegelung aktiviert +TIME_UNLOCK_DOOR = "05:30" # Uhrzeit: Türverriegelung deaktiviert (Lieferung möglich) +``` + +## 🔄 Automatische Versionierung + +Das Projekt verwendet automatische Versionierung basierend auf [Conventional Commits](https://www.conventionalcommits.org/): + +```bash +feat: neue Funktion → MINOR Version (0.7.0 → 0.8.0) +fix: Bugfix → PATCH Version (0.7.0 → 0.7.1) +BREAKING CHANGE: → MAJOR Version (0.7.0 → 1.0.0) +``` + +**Setup**: `python setup_versioning.py` +**Dokumentation**: Siehe `VERSIONING.md` + +## 🌐 MQTT-Integration + +Das System unterstützt MQTT für IoT-Benachrichtigungen: + +```bash +# MQTT-Konfiguration über Umgebungsvariablen +export MQTT_BROKER="your-mqtt-broker.local" +export MQTT_USER="username" +export MQTT_PASS="password" + +# Oder Standard-Fallback-Werte verwenden (für Tests) +python paketbox.py # Verwendet Fallback-Werte wenn MQTT nicht verfügbar +``` + +**MQTT-Topics**: +- `home/raspi/paketbox_text` - Statusnachrichten +- `home/raspi/paketbox` - Paket-Zusteller-Events +- `home/raspi/briefkasten` - Briefkasten-Events +- `home/raspi/paketboxleeren` - Paketbox-Entleerungs-Events + +## 🛡️ Lichtschranke - Sicherheitseinrichtung + +Die Lichtschranke ist eine kritische Sicherheitseinrichtung zum Schutz vor Einklemmungen: + +### Funktionsweise +- **PIN 10** erfasst kontinuierlich den Betriebszustand +- **Auslösung**: Wenn die Schranke unterbrochen wird (z.B. Finger/Hand im Weg) +- **Notfall-Reaktion**: Motor stoppt sofort, um Verletzungen zu vermeiden +- **Überwachung**: System protokolliert jede Auslösung im Logger + +### Automatische Reaktion +```python +if GPIO.input(10) == FALLING: # Lichtschranke unterbrochen + handler.set_light_barrier_triggered(True) + logger.info("Lichtschranke hat ausgelöst - Notfall!") + handler.notHaltMotoren() # Alle Motoren stoppen sofort +``` + +### Sicherheitsprotokoll +- ✅ **Sofortiger Motorstopp** bei Erkennung von Hindernissen +- ✅ **Fehlerprotokollierung** für Wartungsstatistiken +- ✅ **Manuelle Rückstellung** erforderlich nach Auslösung +- ✅ **Integrale Prüfung** bei System-Reset + +Diese Funktion entspricht Sicherheitsanforderungen für automatische Türsysteme. + +## ⚠️ Sicherheit & Fehlerbehandlung + +### Automatische Fehlererkennung +- **Lichtschran-Auslösung**: Sofortiger Motorstopp bei Oberflächenblockade +- **Motor-Blockage**: Erkennung wenn Klappen nicht öffnen/schließen +- **GPIO-Fehler**: Behandlung von Hardware-Fehlern +- **Timer-Management**: Sichere Abbruchfunktionen für alle Timer +- **Error-Recovery**: Automatische Wiederherstellung nach Fehlern + +### Reset-Funktionen +```python +# Manueller Reset bei Fehlerzuständen +handler.ResetErrorState() # Setzt alle Fehler zurück +handler.ResetDoors() # Bringt Türen in sicheren Zustand +``` + +### Deployment +```bash +# Lokal testen (immer zuerst!) +python paketbox.py + +# Tests ausführen vor Deployment +python tests/run_tests.py + +# Auf Raspberry Pi übertragen +./deploy_paketbox.sh pi 192.168.1.100 /home/pi/paketbox # Linux/macOS +deploy_paketbox.bat pi 192.168.1.100 /home/pi/paketbox # Windows +``` + +## 🧪 Test-Coverage + +Die Test-Suite deckt ab: +- ✅ Alle GPIO-Event-Handler (Klappen, Türen, Sensoren) +- ✅ Alle Motor-Steuerungsfunktionen (Öffnen/Schließen mit Timern) +- ✅ Tür-Verriegelung/Entriegelung +- ✅ Komplette Lieferzyklen (End-to-End) +- ✅ Fehlererkennung und Wiederherstellung +- ✅ Thread-sichere Zustandsverwaltung +- ✅ GPIO-Debouncing und Timer-Operationen +- ✅ MQTT-Integration (mit Fallback) +- ✅ Motor-Blockage-Szenarien + +### Validierung +```bash +# Kritische Validierung nach Änderungen +python tests/run_tests.py # Alle Tests müssen bestehen +python paketbox.py # Anwendung muss ohne Fehler starten +``` + +## 📊 System-Requirements + +### Laufzeit-Abhängigkeiten +- **Python 3.7+**: Hauptsprache +- **Standard-Bibliotheken**: threading, logging, time, enum +- **Optional**: paho-mqtt (für MQTT-Funktionalität) +- **Hardware**: RPi.GPIO (nur auf Raspberry Pi) + +### Entwicklungs-Abhängigkeiten +- **unittest**: Für Tests (integriert) +- **unittest.mock**: Für Hardware-Mocking (integriert) +- **Keine externen Tools**: Vollständig in Python implementiert + +## Lizenz +MIT + +## Autoren +- Andreas Beyer +- Maximilian Lechner + From 44e989a9654975e3bbb5089bea6f13486a317de7 Mon Sep 17 00:00:00 2001 From: Maximilian Lechner Date: Thu, 26 Feb 2026 20:15:15 +0000 Subject: [PATCH 2/2] readme --- README.md | 39 +++++---------------------------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index e6bef15..4913187 100644 --- a/README.md +++ b/README.md @@ -135,10 +135,12 @@ max_paket_box/ ├── mqtt.py # MQTT-Integration für IoT-Benachrichtigungen ├── tests/ │ ├── test_paketbox.py # Umfassende Unit Tests - ... (rest of content continues same as original) - +│ └── run_tests.py # Test Runner mit detailliertem Output +├── paketbox.log # Strukturierte Log-Datei +└── README.md # Diese Datei +``` -### Modulare Architektur (Version 0.7.0) +### Modulare Architektur (Version 0.8.0) Das System wurde in separate Module aufgeteilt: - **`paketbox.py`**: Hauptsteuerung und GPIO-Event-Loop - **`handler.py`**: GPIO-Handler und Motor-Steuerungsfunktionen @@ -166,16 +168,6 @@ TIME_LOCK_DOOR = "00:00" # Uhrzeit: Türverriegelung aktiviert TIME_UNLOCK_DOOR = "05:30" # Uhrzeit: Türverriegelung deaktiviert (Lieferung möglich) ``` -## 🔄 Automatische Versionierung - -Das Projekt verwendet automatische Versionierung basierend auf [Conventional Commits](https://www.conventionalcommits.org/): - -```bash -feat: neue Funktion → MINOR Version (0.7.0 → 0.8.0) -fix: Bugfix → PATCH Version (0.7.0 → 0.7.1) -BREAKING CHANGE: → MAJOR Version (0.7.0 → 1.0.0) -``` - **Setup**: `python setup_versioning.py` **Dokumentation**: Siehe `VERSIONING.md` @@ -209,14 +201,6 @@ Die Lichtschranke ist eine kritische Sicherheitseinrichtung zum Schutz vor Einkl - **Notfall-Reaktion**: Motor stoppt sofort, um Verletzungen zu vermeiden - **Überwachung**: System protokolliert jede Auslösung im Logger -### Automatische Reaktion -```python -if GPIO.input(10) == FALLING: # Lichtschranke unterbrochen - handler.set_light_barrier_triggered(True) - logger.info("Lichtschranke hat ausgelöst - Notfall!") - handler.notHaltMotoren() # Alle Motoren stoppen sofort -``` - ### Sicherheitsprotokoll - ✅ **Sofortiger Motorstopp** bei Erkennung von Hindernissen - ✅ **Fehlerprotokollierung** für Wartungsstatistiken @@ -241,19 +225,6 @@ handler.ResetErrorState() # Setzt alle Fehler zurück handler.ResetDoors() # Bringt Türen in sicheren Zustand ``` -### Deployment -```bash -# Lokal testen (immer zuerst!) -python paketbox.py - -# Tests ausführen vor Deployment -python tests/run_tests.py - -# Auf Raspberry Pi übertragen -./deploy_paketbox.sh pi 192.168.1.100 /home/pi/paketbox # Linux/macOS -deploy_paketbox.bat pi 192.168.1.100 /home/pi/paketbox # Windows -``` - ## 🧪 Test-Coverage Die Test-Suite deckt ab: