hobbyhimmel/odoo_mqtt
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2d483e08ad
odoo_mqtt/iot_bridge/ARCHITECTURE.md
matthias.lotz e2229fa137 Phase 4.3: Update project documentation 
- Add ARCHITECTURE.md with component overview and runtime data flow
- Add DEVELOPMENT.md with local setup, testing, and debugging workflows
- Update README.md links and development documentation references
- Fix outdated API models reference in related docs section
- Update optimization plan status for Phase 4.3 progress
2026-02-19 19:19:44 +01:00

2.6 KiB
Raw Blame History

IoT Bridge Architecture

Überblick

Der IoT Bridge Service ist ein eigenständiger Python-Microservice zwischen MQTT-Geräten und Odoo. Er verarbeitet MQTT-Messwerte, erkennt Sessions über eine Zustandsmaschine und liefert Events zuverlässig per HTTP an Odoo.

Komponenten

  • main.py: Einstiegspunkt, startet Bootstrap + ServiceManager.
  • core/bootstrap.py: Lädt Konfiguration (YAML + ENV), initialisiert Logging.
  • core/service_manager.py: Orchestrierung von MQTT-Client, EventQueue, DeviceManager, HTTP-Server, Status-Monitor.
  • clients/mqtt_client.py: MQTT-Verbindung, Reconnect, Subscribe/Unsubscribe.
  • clients/odoo_client.py: Event-POSTs an Odoo mit Timeout-/Fehlerbehandlung.
  • core/event_queue.py: Thread-sichere Queue mit Retry/Backoff.
  • core/device_manager.py: Geräte-Lifecycle, Topic-Routing, SessionDetector-Erzeugung.
  • core/session_detector.py: Zustandsmaschine (idle/starting/standby/working/stopping).
  • api/server.py: FastAPI-Endpunkte (/health, /config) inklusive Config-Push.
  • utils/status_monitor.py: Online/Offline-Status über last_seen.

Laufzeitfluss

  1. MQTT-Nachricht trifft ein (mqtt_client).
  2. device_manager.route_message(...) ordnet Topic einem Gerät zu.
  3. Parser extrahiert Nutzdaten (apower), SessionDetector verarbeitet Messwert.
  4. Entstehende Events werden in die EventQueue gelegt.
  5. EventQueue versucht Zustellung an Odoo (odoo_client.send_event) mit Backoff.
  6. Bei Config-Push (POST /config) werden Geräte-/Broker-Parameter live übernommen.

Konfigurationsmodell

  • Primärquelle: Odoo Push auf /config.
  • Persistenz: aktive Konfiguration nach /data/config-active.yaml.
  • Fallback: lokale config.yaml / config.dev.yaml beim Start.
  • Priorität: Persisted Config > lokale Datei > Defaults.

Zuständigkeiten und Grenzen

  • Bridge ist zuständig für MQTT-Ingestion, Session-Logik und zuverlässige Event-Delivery.
  • Odoo ist zuständig für Geräteverwaltung, UI und Persistenz der Domänendaten.
  • Bridge verarbeitet keine Business-Workflows aus Odoo, sondern liefert normalisierte technische Events.

Nicht-funktionale Aspekte

  • Resilienz: Retry-Queue mit Exponential Backoff.
  • Observability: strukturierte JSON-Logs (structlog) + Health-Endpoint.
  • Betrieb: Docker-ready, zustandsarme Komponenten mit klaren Persistenzpunkten (/data).

Wichtige Designentscheidungen (kurz)

  • Push-Architektur statt Polling für Konfigurationsänderungen.
  • Entkopplung MQTT-Eingang und Odoo-Ausgang über Queue.
  • Session-Erkennung als deterministische Zustandsmaschine.
  • Status-Monitor getrennt von Session-Erkennung (Online/Offline vs. Arbeitssession).