Home Assistant Integration for Odoo 18 ERP
Real-time IoT device monitoring, control, and sharing — directly in your Odoo backend and portal.
v18.0.6.2 ·
Screenshots ·
Installation ·
Configuration ·
繁體中文
| Challenge | Solution |
|---|---|
| IoT data locked in Home Assistant | Unified dashboard inside your ERP |
| No business-level device sharing | User-based portal sharing with granular permissions |
| Disconnected monitoring tools | Real-time WebSocket bridge — no polling |
| Multi-site HA deployments | Multi-instance support with session-based switching |
| No audit trail for device states | Entity history recording with chart visualization |
WOOW Dashboard bridges Home Assistant and Odoo ERP, bringing real-time IoT device monitoring, control, and sharing into your business management platform. It connects to one or more Home Assistant instances via WebSocket and REST API, synchronizes entities, areas, and devices, and exposes them through Odoo's backend views and portal pages.
Whether you manage a smart office, a fleet of industrial sensors, or a building automation system, WOOW Dashboard lets your team monitor and control IoT devices without leaving Odoo — and share device access with external users through a secure portal.
- Home Assistant Integration — Real-time bidirectional communication via WebSocket and REST API with automatic reconnection and state synchronization.
- Multi-Instance Support — Connect and manage multiple Home Assistant instances from a single Odoo installation. Session-based instance selection with user preference persistence.
- Real-time Updates — Home Assistant state changes stream through the Odoo Bus bridge to connected browser sessions, providing instant UI updates without polling.
- Entity Management & Control — Full control for 10 device domains: switch, light, sensor, climate, cover, fan, automation, scene, script, and a generic fallback.
- Entity Kanban View — Custom Odoo kanban view with real-time state display, domain-specific controls, and inline entity interaction.
- Entity History — Record and visualize entity state changes over time with a dedicated chart-based timeline view.
- Area & Device Management — Bidirectional sync of areas and devices from Home Assistant. Visual area dashboard with device cards and embedded entity controllers.
- Device Area Inheritance — Entities automatically inherit their area from their parent device, with a "Follows Device" toggle for fine-grained control.
- Glances System Monitoring — View Home Assistant host system metrics (CPU, memory, disk, network) directly within Odoo through Glances integration.
- Portal Sharing — Share entities and entity groups with portal users. User-based permissions with configurable access levels (read-only or full control) and optional expiry dates.
- Portal Entity Control — Full device control on the portal with the same controller components as the backend, adapted for public access.
- Blueprint Wizard — Create Home Assistant automations from blueprints with a guided form wizard directly in Odoo.
- Internationalization — Full Traditional Chinese (zh_TW) translation coverage. All backend and portal interfaces support multi-language display.
- Custom Views — Purpose-built Odoo views including entity history timeline, entity kanban with real-time state, and area dashboard with device-first layout.
| Domain | Capabilities |
|---|---|
| switch | Toggle on/off |
| light | Toggle, brightness, color temperature |
| sensor | Read-only value display with attributes |
| climate | Temperature target, HVAC mode, fan mode |
| cover | Open, close, stop, position slider |
| fan | Toggle, speed control, oscillation |
| automation | Toggle enable/disable, manual trigger |
| scene | Activate scene |
| script | Execute, toggle on/off |
| generic | Basic state display for unsupported domains |
The entry page showing connected Home Assistant instances with connection status, entity/area counts, and quick navigation buttons.
System information panel with WebSocket connection status, hardware details, storage, and network monitoring.
Device cards organized by Home Assistant areas with area tabs. Each card shows embedded entity controllers for direct interaction — toggle lights, activate scenes, adjust settings.
All synchronized entities with real-time state display, domain filtering, area assignment, and group/tag organization. Switch between list and kanban views.
Detailed entity view showing state, domain, area assignment (with "Follows Device" toggle), groups, tags, labels, and custom properties. Includes "Share with Users" action for portal sharing.
All Home Assistant devices with manufacturer, model, area assignment, and associated entities.
HA instance form with connection settings, sync controls (Test Connection, Sync Registry, Sync Entities, Restart WebSocket), and instance identification.
WebSocket configuration page with connection status, instance management, API URL, and access token settings.
Portal users can view and control shared entities through a secure, responsive interface.
| Screenshot | Description |
|---|---|
 |
Portal Home — User's portal landing page with shared instance summary. |
 |
Instance List — Shared HA instances with entity and group counts. |
 |
Instance Detail — Shared entities with permission badges. |
 |
Entity Control — Light entity with brightness slider and toggle. |
 |
Entity Group — Responsive card grid with individual controllers. |
 |
Sensor View — Read-only sensor with value, unit, and attributes. |
┌───────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Browser (OWL) │ <───> │ Odoo Server │ <───> │ Home Assistant │
├───────────────────┤ ├──────────────────┤ ├──────────────────┤
│ OWL Components │ │ Models │ │ WebSocket API │
│ ha_data_service │ RPC │ ha_entity │ WS/ │ REST API │
│ ha_bus_bridge │ <────> │ ha_instance │ REST │ State Machine │
│ Entity Controllers│ │ ha_area/device │ <────> │ │
│ Chart Service │ │ HA API Client │ │ │
└───────────────────┘ └──────────────────┘ └──────────────────┘
▲ │
│ Odoo Bus Bridge │
└─────────────────────────────┘
(Real-time state propagation)
- Backend: Odoo models communicate with Home Assistant through a dedicated API client supporting both WebSocket subscriptions and REST calls.
- Frontend: OWL components consume data through a service layer (
ha_data_service) that handles RPC calls, caching, and reactive state management. - Real-time: A WebSocket bridge subscribes to Home Assistant state changes and relays them through the Odoo Bus to all connected browser sessions.
- Portal: Dedicated controllers serve portal pages with user-based access validation, fetching entity state through the same backend API client.
| Pattern | Usage |
|---|---|
| Service-First | Use useService("ha_data"), never direct RPC |
| Bus Notifications | Use bus_service.subscribe() for real-time updates |
| Reactive State | useState() + service callbacks |
| Entity Control | Shared useEntityControl hook across backend and portal |
| Component | Version |
|---|---|
| Odoo | 18.0+ (Community or Enterprise) |
| Home Assistant | 2024.1+ |
| Python | 3.10+ |
| websockets | Auto-installed via pre_init_hook |
base,web,mail,portal
This repository is the Odoo addon. Clone or download it directly into your Odoo addons directory:
# Clone into your Odoo addons path, renaming to odoo_ha_addon
git clone https://github.com/WOOWTECH/odoo-addon-odoo-ha-addon.git \
/path/to/odoo/addons/odoo_ha_addon
# Or download and extract the ZIP from GitHub ReleasesThen in Odoo:
- Go to Apps and click Update Apps List
- Search for and install WOOW Dashboard
The Python dependency
websocketsis automatically installed via thepre_init_hook— no manual pip install is required.
# Clone the repository
git clone https://github.com/WOOWTECH/odoo-addon-odoo-ha-addon.git
cd odoo-addon-odoo-ha-addon
# Set up environment
cp .env.example .env
# Start services
docker compose up -d
# Access Odoo at http://localhost:8069- Navigate to Settings > WOOW HA
- Click + New Instance and enter:
- Instance Name: A descriptive label for the Home Assistant instance
- API URL: Home Assistant base URL (e.g.,
http://homeassistant.local:8123) - Access Token: A Long-Lived Access Token generated in Home Assistant
- Click Test Connection to verify connectivity
- Click Sync Registry to import areas, devices, and labels
- Click Sync Entities to import all entities
The WebSocket connection will be established automatically, providing real-time state updates.
odoo_ha_addon/ # ← This repo (clone as odoo_ha_addon)
├── __manifest__.py # Odoo module manifest (v18.0.6.2)
├── __init__.py # Python package init
├── hooks.py # Install/uninstall hooks
├── models/ # Backend models & business logic
│ ├── common/ # Shared utilities (API client, helpers)
│ ├── ha_instance.py # HA instance management
│ ├── ha_entity.py # Entity model & WebSocket sync
│ ├── ha_area.py # Area bidirectional sync
│ ├── ha_device.py # Device management
│ ├── ha_entity_share.py # Portal sharing model
│ └── ... # Other models
├── controllers/ # HTTP & portal controllers
├── views/ # XML view definitions & templates
├── static/src/ # Frontend (OWL components, JS, SCSS)
│ ├── services/ # Service layer (ha_data, chart, bus bridge)
│ ├── actions/ # Client action pages (dashboards)
│ ├── views/ # Custom view types (hahistory, entity_kanban)
│ ├── components/ # Reusable UI components
│ ├── portal/ # Portal-specific components
│ └── hooks/ # Shared hooks (entity control)
├── security/ # Access rights & record rules
├── data/ # Initial data, menus, cron jobs
├── i18n/ # Translation files (zh_TW)
├── wizard/ # Wizard views (blueprint, clear instance)
├── tests/ # Unit, integration & E2E tests
├── docs/ # Technical documentation & screenshots
├── scripts/ # Development automation scripts
├── config/ # Docker & Nginx configuration
├── docker-compose.yml # Docker development environment
├── CHANGELOG.md # Release history (English)
└── CHANGELOG-tw.md # Release history (繁體中文)
- Backend Access: HA Admin and HA User groups with record-level security rules. Admins can manage instances and sync data; users can view and control assigned entities.
- Portal Access: User-based sharing with per-entity and per-group permission records. Supports read-only and full-control access levels with optional expiry dates.
- All Home Assistant API calls use Long-Lived Access Tokens stored in Odoo's encrypted credential store
- Portal entity access is validated against sharing records with
hmac.compare_digest()for timing-attack prevention - WebSocket connections use authenticated sessions with automatic token rotation
All backend API endpoints follow a standard response format:
{
"success": true,
"data": { ... },
"error": null
}| Endpoint | Method | Description |
|---|---|---|
/ha/entity/state |
POST | Get entity current state |
/ha/entity/control |
POST | Send control command to entity |
/ha/instance/sync |
POST | Trigger entity synchronization |
/portal/entity/<id>/state |
GET | Portal entity state (JSON polling) |
For complete API documentation, see docs/architecture/overview.md.
# Run unit tests
python -m pytest tests/ -v
# Run with Odoo test runner
./odoo-bin -d test_db -i odoo_ha_addon --test-enable --stop-after-init
# E2E tests (Playwright)
# See tests/e2e_tests/ for configurationSee CHANGELOG.md for the full release history.
- v18.0.6.2 — Portal breadcrumbs, live status sidebar, entity form control panel
- v18.0.6.1 — User-based sharing migration (token → user permissions)
- v18.0.6.0 — Portal sharing system, entity groups, portal controllers
- v18.0.5.0 — Blueprint wizard, Glances integration, entity history
Contributions are welcome. Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes with clear messages
- Ensure all tests pass
- Submit a pull request
For development setup details, see the Development Guide.
This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3).
See the LICENSE file for details.
- Issues: GitHub Issues
- Documentation: docs/
- Developer Guide: docs/guides/development.md
- Troubleshooting: docs/guides/troubleshooting.md
Developed and maintained by WOOWTECH