-
- Open Workshop MQTT
-IoT Device Integration with Intelligent Session Detection
-
- 
-
-
- ')
+ else:
+ in_code_block = False
+ html_lines.append('')
+ continue
+
+ if in_code_block:
+ html_lines.append(line.replace('&', '&').replace('<', '<').replace('>', '>'))
+ continue
+
+ # Empty lines
+ if not line.strip():
+ if in_list:
+ html_lines.append('' if isinstance(in_list, str) and in_list == 'ul' else '')
+ in_list = False
+ html_lines.append('')
+ continue
+
+ # Headers
+ if line.startswith('# '):
+ html_lines.append(f'{format_inline(content)}') + + # Regular paragraphs + else: + if in_list: + html_lines.append('
{format_inline(line)}
') + + # Close open lists + if in_list: + html_lines.append('' if in_list == 'ul' else '') + + return '\n'.join(html_lines) + + +def format_inline(text): + """Format inline Markdown (bold, italic, code, links).""" + # Links [text](url) + text = re.sub(r'\[([^\]]+)\]\(([^\)]+)\)', r'\1', text) + + # Bold **text** + text = re.sub(r'\*\*([^\*]+)\*\*', r'\1', text) + + # Italic *text* + text = re.sub(r'\*([^\*]+)\*', r'\1', text) + + # Inline code `code` + text = re.sub(r'`([^`]+)`', r'\1', text)
+
+ # Arrows →
+ text = text.replace('→', '→')
+
+ return text
+
+
+def build_index_html():
+ """Convert README.md to index.html for Odoo Apps UI."""
+ print("📄 Converting README.md to index.html...")
+
+ if not README_FILE.exists():
+ print(f"⚠️ README.md not found at {README_FILE}")
+ return False
+
+ md_content = README_FILE.read_text(encoding='utf-8')
+ body_html = markdown_to_html(md_content)
+
+ # Wrap in Odoo-styled HTML template
+ html = f"""
+
+
+
+
+ Generated from README.md | Run ./build_docs.sh to update after changes
+
\1', html)
-
- # Bold (Args:, Returns:, etc.)
- html = re.sub(r'^(Args?:|Returns?:|Raises?:|Example?:|Note?:|See Also?:|Side Effects?:|HTTP Status Codes?:|Protocol?:|Event Types?:|State Machine?:|Session Lifecycle?:|Statistics Tracked?:|Related Models?:|Bridge Integration?:|Config Push Architecture?:|Payload Structure?:|Event Flow?:|Idempotency?:|SQL Constraints?:|Fields Overview?:)(.*)$',
- r'\1\2', html, flags=re.MULTILINE)
-
- # Paragraphs
- html = '' + html.replace('\n\n', '
') + '
' - - # Line breaks - html = html.replace('\n', '
-
- Generated from source code docstrings
- Run ./build_docs.sh to regenerate after code changes
-
-
REST API for IoT Bridge integration
Get IoT device configuration for Bridge
Returns JSON with all active devices and their session configs
Example Response:
{
Receive IoT event from Bridge and process device/session state changes.
This is the main API endpoint that receives events from the IoT Bridge microservice.
All events are idempotent via event_uid to prevent duplicate processing.
Protocol: JSON-RPC 2.0 (params must be wrapped in "params" object)
Args:
Returns:
HTTP Status Codes:
Side Effects:
Example Request (JSON-RPC 2.0):
Example Response (Success):
Example Response (Duplicate):
See Also:
Process IoT event: create or update mqtt.session
Args:
IoT Event Log - Records all events received from IoT Bridge.
This model stores every event submitted via POST /ows/iot/event endpoint.
Events are immutable (readonly=True) and serve as audit trail for device
activity and session detection.
Idempotency:
Event Types:
Event Flow:
Payload Structure:
Related Models:
Example:
SQL Constraints:
Fields Overview:
Create event and auto-link to mqtt.device and mqtt.session
Return payload as Python dict
Mark event as processed (or failed)
MQTT IoT Device Model - Represents a physical device monitored via MQTT.
This model stores device configuration and current state for IoT devices
monitored through the Bridge microservice. It supports automatic config
push to the Bridge when devices are created, updated, or deleted.
State Machine:
Config Push Architecture:
Related Models:
Bridge Integration:
Example:
Fields Overview:
Auto-subscribe when device is added to running connection
or when topic_pattern changes
DEPRECATED: Auto-subscribe disabled - use standalone IoT Bridge container
Open sessions view for this device
Manually start a session
Manually stop a session
Parse strategy_config JSON and return as dict
Override create to push config to bridge after device creation
Override write to push config to bridge after device update
Override unlink to push config to bridge after device deletion
Manual action to push config to bridge.
Called from UI button.
MQTT Device Work Session - Represents a detected work session from IoT device.
Sessions are automatically created by the IoT Bridge when power consumption
crosses the working threshold and are finalized when power drops below
standby threshold. The Bridge implements a 5-state state machine with
debounce timers to avoid false triggers.
Session Lifecycle:
Events that create/update sessions:
Statistics Tracked:
Related Models:
Example:
Fields Overview:
Parse metadata JSON and return as dict
Create or update session from MQTT event
Args:
Returns:
Get all running sessions, optionally filtered by device
Args:
Returns:
-
- Generated from source code docstrings
- Run ./build_docs.sh to regenerate after code changes
-
-
- - This module provides seamless integration between Odoo 18 and IoT devices via MQTT protocol. - It enables real-time monitoring of industrial equipment with intelligent work session detection - based on power consumption patterns. -
-IoT Device Integration with MQTT
-Track IoT devices (Shelly PM, Tasmota) via MQTT with automatic status updates.
-Automatic work session detection using configurable power thresholds and debounce timers.
-Track device states: offline → idle → active → idle → offline
-JSON-RPC 2.0 API for event submission from IoT Bridge with idempotency support.
-Bridge receives configuration updates instantly when devices are created/modified.
-Track average power, peak power, duration, and total energy for each work session.
-
- - The module works in conjunction with the IoT Bridge microservice: -
-This module provides seamless integration between Odoo 18 and IoT devices via MQTT protocol. It enables real-time monitoring of industrial equipment with intelligent work session detection based on power consumption patterns.
-
- 1. Copy the module to your Odoo addons directory
- 2. Update the apps list
- 3. Install Open Workshop MQTT module
- 4. Configure system parameter: open_workshop_mqtt.bridge_url (e.g., http://iot-bridge:8080)
- 5. Deploy IoT Bridge microservice (Docker Compose recommended)
-
+Key Features
+ +Real-time Device Monitoring
+Track IoT devices (Shelly PM, Tasmota) via MQTT with automatic status updates.
+ +Intelligent Session Detection
+Automatic work session detection using configurable power thresholds and debounce timers. Session Detection is implemented in the IoT Bridge microservice, which sends events to Odoo when sessions start/stop.
+ +Device State Management
+Track device states: offline → idle → active → idle → offline
+ +REST API
+JSON-RPC 2.0 API for event submission from IoT Bridge with idempotency support.
+ +Automatic Config Push
+Bridge receives configuration updates instantly when devices are created/modified.
+ +Session Analytics
+Track average power, peak power, duration, and total energy for each work session.
+ +Architecture
+ +The module works in conjunction with the IoT Bridge microservice:
+ ++
+ +- IoT Device publishes MQTT messages (power, voltage, state)
+- IoT Bridge subscribes to topics, detects sessions, sends events to Odoo
+- Odoo Module receives events via REST API, tracks devices/sessions
+- Automatic Config Push updates Bridge when devices change
+Installation
+ ++
+ +- Copy the module to your Odoo addons directory
+- Update the apps list
+- Install
+Open Workshop MQTTmodule- Configure system parameter:
+open_workshop_mqtt.bridge_url(e.g., http://iot-bridge:8080)- Deploy IoT Bridge microservice (Docker Compose recommended)
+Command Line Installation
+ +# Install via command line ./odoo-bin -d DATABASE -i open_workshop_mqtt --stop-after-init # Or via Odoo Apps UI Settings → Apps → Update Apps List → Search "mqtt" → Install --
Set system parameter for Bridge URL:
-Key: open_workshop_mqtt.bridge_url -Value: http://iot-bridge:8080-
Add IoT device:
-shellypmminig3-xxxshellypmminig3-xxx/status/pm1:0shelly_pmNavigate to IoT Bridge → Devices
-Navigate to IoT Bridge → Sessions
-Set system parameter for Bridge URL:
-Navigate to IoT Bridge → Events
-+Key: open_workshop_mqtt.bridge_url +Value: http://iot-bridge:8080 +-
Submit IoT event from Bridge (JSON-RPC 2.0)
-+2. Create Device
+ +Add IoT device:
+
shellypmminig3-xxxshellypmminig3-xxx/status/pm1:0shelly_pmNavigate to IoT Bridge → Devices
+ +Navigate to IoT Bridge → Sessions
+ +Navigate to IoT Bridge → Events
+ +Submit IoT event from Bridge (JSON-RPC 2.0)
+ +
{
"jsonrpc": "2.0",
"params": {
@@ -183,55 +158,50 @@ Value: http://iot-bridge:8080
"payload": {"power_w": 125.5}
}
}
-
- Event Types: device_online, device_offline, session_started, session_stopped, session_heartbeat, session_timeout
-For full API documentation, see: API.md in module directory
mqtt.device - Device registrymqtt.session - Work sessionsiot.event - Event historyEvent Types: device_online, device_offline, session_started, session_stopped, session_heartbeat, session_timeout
-README.mdIMPLEMENTATION_PLAN.mdiot_bridge/README.mdNote: To update API documentation after code changes, run: ./build_docs.sh
For issues and feature requests, please contact the development team.
-For complete API documentation, see: API.md (auto-generated from source code)
-- This module is licensed under MIT License. -
-ows.mqtt.device - Device registryows.mqtt.session - Work sessionsows.iot.event - Event historyREADME.mdIMPLEMENTATION_PLAN.mdiot_bridge/README.mdNote: To update documentation after code changes, run: ./build_docs.sh
For issues and feature requests, please contact the development team.
+ +This module is licensed under MIT License.
+ +
+ Generated from README.md | Run ./build_docs.sh to update after changes
+