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.1 KiB

Raw Blame History

Feature Request: Device Online/Offline Status

Summary

The device status in Odoo is always shown as Offline. We need a reliable Online/Offline indicator that reflects whether a device is connected to the broker or actively sending MQTT messages.

Goals

Show Online when the device is connected or has sent a recent message.
Show Offline when the device is no longer connected or stopped sending messages.
Provide a clear reason for Offline where possible (timeout, broker disconnect, bridge offline).
Keep the system robust if Odoo or the bridge restarts.

Non-Goals

We do not need device-side firmware changes.
We do not need exact broker connection state for every device if not supported by the device.

User Stories

As a workshop operator, I want to see whether a machine is online at a glance.
As a technician, I want to know when a device went offline and why.
As an admin, I want the status to survive restarts and recover quickly.

Proposed Behavior

Online if a device has sent a message within a configurable timeout (e.g., 30s).
Offline if no message is received within the timeout.
Optionally use MQTT LWT if available to improve accuracy.
Odoo shows:
- status: online/offline
- last_seen_at
- offline_reason (timeout, broker_disconnect, bridge_offline)

Data Needed

Per device: last_seen_at (timestamp), online_state (bool), offline_reason (string), last_online_at (timestamp)

Acceptance Criteria

Device status changes to Online within 1 message after device starts sending.
Device status changes to Offline within timeout + 1 interval when messages stop.
Status is visible in Odoo list and form views.
Restarting the bridge keeps or quickly restores status.

Risks

Devices that publish very infrequently may appear Offline unless timeout is tuned.
Some devices might not support MQTT LWT; fallback to last_seen is required.

Open Questions

What timeout should be the default (30s, 60s, 120s)?
Do we want a separate heartbeat topic or use existing power messages?
Should Odoo be updated by push (events) or poll from the bridge?

2.1 KiB Raw Blame History