matthias.lotz ba588842ad feat: Add automatic API documentation generation and device status monitoring

- Implement build script (build_docs.py) with AST parser to auto-generate HTML docs from docstrings
- Add comprehensive Google-style docstrings to all controllers and models
- Create static/description/index.html for Odoo Apps UI with module overview
- Generate api_reference.html (20.5 KB) from source code, linked from Odoo UI
- Add DOCUMENTATION_STRATEGY.md with comparison of 5 documentation approaches
- Create API.md with complete REST API documentation

Device Status Monitoring:
- Implement device_status_monitor.py with health checks and offline detection
- Add /status endpoint for device health overview
- Automatic offline detection after message_timeout_s

Config Push Architecture:
- Add POST /config endpoint to IoT Bridge for dynamic device management
- Auto-push device config from Odoo on create/write/unlink
- Implement device_manager.py for runtime device updates

E2E Tests:
- All 6 E2E tests passing (Create, Update, Push, Delete, Restart, Status Monitor)
- Test coverage for device lifecycle and config synchronization

Documentation is auto-generated via: ./build_docs.sh
View in Odoo: Settings → Apps → Open Workshop MQTT → API Reference

2026-02-15 11:03:22 +01:00

2.7 KiB

Raw Blame History

Deployment Guide

This guide covers production deployment of the IoT Bridge and its integration with Odoo.

Prerequisites

Docker and Docker Compose
Odoo 18 with open_workshop_mqtt installed
Mosquitto (or any MQTT broker)

Recommended Topology

odoo-dev (Odoo 18)
iot_bridge (this service)
mosquitto (MQTT broker)
Persistent volume for /data in the bridge container

Configuration

Required Environment Variables

MQTT_BROKER=mosquitto
MQTT_PORT=1883
BRIDGE_PORT=8080
ODOO_BASE_URL=http://odoo-dev:8069
ODOO_DATABASE=odoo
ODOO_USERNAME=admin

Optional Environment Variables

MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_CLIENT_ID=iot_bridge
MQTT_USE_TLS=false
BRIDGE_API_TOKEN=
LOG_LEVEL=INFO
LOG_FORMAT=json
LOG_FILE=

Docker Compose Example

version: '3.8'

services:
  iot-bridge:
    build: ./iot_bridge
    container_name: iot_bridge
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - bridge-data:/data
    environment:
      - MQTT_BROKER=mosquitto
      - MQTT_PORT=1883
      - BRIDGE_PORT=8080
      - ODOO_BASE_URL=http://odoo-dev:8069
      - ODOO_DATABASE=odoo
      - ODOO_USERNAME=admin
    networks:
      - odoo18-nw
    depends_on:
      - mosquitto
      - odoo-dev
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

  mosquitto:
    image: eclipse-mosquitto:2
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
    networks:
      - odoo18-nw

volumes:
  bridge-data:

networks:
  odoo18-nw:
    driver: bridge

Odoo Configuration

Set the bridge URL in Odoo (System Parameters):

Key: open_workshop_mqtt.bridge_url
Value: http://iot-bridge:8080

When devices are created/updated/deleted, Odoo will push the config to the bridge.

Persistence

Bridge config is stored in /data/config-active.yaml inside the container. Make sure the /data volume is persisted to survive restarts.

Health Checks

GET /health exposes current status.
Use Docker health checks to monitor readiness.

Security Notes

Set BRIDGE_API_TOKEN to protect POST /config.
Run on an internal network; expose the port only if necessary.
Use TLS for MQTT if broker supports it.

Rollback

Stop the bridge container.
Restore the previous image tag and restart.
The config file remains in /data/config-active.yaml.

Validation Checklist

GET /health returns status: ok.
GET /config returns the current device list.
Odoo device changes trigger POST /config.
MQTT subscriptions match configured devices.

2.7 KiB Raw Blame History