# 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

```yaml
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

```bash
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

```bash
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:**
```json
{
  "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