open_workshop/open_workshop_mqtt

Open Workshop MQTT

MQTT IoT Bridge for Odoo 18 - Sidecar-Container-Architektur

Architektur-Übersicht

┌─────────────┐      MQTT       ┌──────────────┐     REST API    ┌────────────┐
│  Shelly PM  │ ────────────────► │ IoT Bridge   │ ──────────────► │   Odoo 18  │
│  (Hardware) │                  │  (Container) │                 │ (Business) │
└─────────────┘                  └──────────────┘                 └────────────┘
                                        │                                │
                                        ▼                                │
                                 ┌──────────────┐                        │
                                 │ Mosquitto    │ ◄──────────────────────┘
                                 │ MQTT Broker  │    (Config via API)
                                 └──────────────┘

Komponenten

1. IoT Bridge (Separater Docker Container)

   • MQTT Client (subscribed auf Device-Topics)
   • Session Detection Engine (State Machine)
   • Event-Parsing & Normalisierung
   • REST Client für Odoo-Kommunikation
   • Image: iot_mqtt_bridge_for_odoo
   • Source: iot_bridge/ Verzeichnis

2. Odoo Module (Business Logic)

   • Device-Management UI
   • REST API für Bridge (/ows/iot/config, /ows/iot/event)
   • Event-Speicherung & Session-Verwaltung
   • Analytics & Reporting

3. MQTT Broker (Mosquitto)

   • Message-Transport zwischen Hardware und Bridge

Features

• ✅ Sidecar-Pattern - Bridge als separater Container (Docker Best Practice)
• ✅ Klare Trennung - Odoo = Business, Bridge = MQTT/Retry/Queue
• ✅ Auto-Config - Bridge holt Device-Config von Odoo via REST API
• ✅ Session Detection - Dual-Threshold, Debounce, Timeout (in Bridge)
• ✅ Flexible Parsers - Shelly PM Mini G3, Tasmota, Generic JSON
• ✅ Analytics - Pivot tables and graphs for runtime analysis
• ✅ Auto-Reconnect - Exponential backoff on MQTT connection loss
• ✅ Idempotenz - Event-UID verhindert Duplikate

Installation

1. Docker Compose Setup

services:
  odoo:
    # ... existing config ...
  
  iot_bridge:
    image: iot_mqtt_bridge_for_odoo
    build:
      context: ./extra-addons/open_workshop/open_workshop_mqtt/iot_bridge
    environment:
      ODOO_URL: http://odoo:8069
      ODOO_TOKEN: ${IOT_BRIDGE_TOKEN}
      MQTT_URL: mqtt://mosquitto:1883
    depends_on:
      - odoo
      - mosquitto
    restart: unless-stopped

2. Odoo Module Installation

docker compose exec odoo odoo -u open_workshop_mqtt

3. Bridge Token generieren

Odoo UI:

• Settings → Technical → System Parameters
• Create: ows_iot.bridge_token = <generated-token>

Add to .env:

IOT_BRIDGE_TOKEN=<same-token>

4. Start Services

docker compose up -d

Quick Start

1. Add Device in Odoo

   • MQTT → Devices → Create
   • Device ID: shellypmminig3-48f6eeb73a1c
   • MQTT Topic: shaperorigin/status/pm1:0
   • Parser: Shelly PM Mini G3
   • Session Strategy: Power Threshold
     • Standby: 20W
     • Working: 100W
     • Debounce: 3s / 15s

2. Bridge Auto-Config

   • Bridge holt Device-Config via GET /ows/iot/config
   • Subscribed auf Topic automatisch
   • Startet Session Detection

3. Monitor Sessions

   • MQTT → Sessions
   • View runtime analytics in Pivot/Graph views

Session Detection Strategies

Power Threshold (Recommended)

• Dual threshold detection (standby/working)
• Configurable debounce timers
• Timeout detection
• Reference: python_prototype/session_detector.py

Last Will Testament

• Uses MQTT LWT for offline detection
• Immediate session end on device disconnect

Manual

• Start/stop sessions via buttons or MQTT commands

Configuration Example

Shelly PM Mini G3:

{
  "standby_threshold_w": 20,
  "working_threshold_w": 100,
  "start_debounce_s": 3,
  "stop_debounce_s": 15,
  "message_timeout_s": 20
}

Optional: Maintenance Integration

Install open_workshop_mqtt_maintenance (separate module) to link MQTT devices to maintenance.equipment.

Technical Reference

See python_prototype/ directory for:

• Implementation reference
• Test suite (pytest)
• Session detection logic
• MQTT client implementation

Support

• Documentation: See python_prototype/README.md
• Issues: GitHub Issues
• Tests: pytest python_prototype/tests/ -v

License

LGPL-3