Atrea aMotion for Home Assistant

Home Assistant custom integration for Atrea HRV and ERV units equipped with the aMotion control system.

The integration uses local websocket communication and is designed around the reality that aMotion is not just a thermostat-style device. Depending on the unit capabilities, it can expose ventilation control, comfort control, bypass control, and telemetry.

Dashboard Card

A dedicated Lovelace card for this integration is available here: alexelite/atrea-amotion-card

Preview

Current Direction

The integration is being refactored to be capability-driven.

That means entity creation is based on what the unit actually exposes at runtime, especially through:

• discovery
• ui_control_scheme
• ui_diagram_scheme
• ui_info

For units like the currently tested Elementary aM-CE board, the intended entity model is:

• separate fan entities for supply and extract when independent fan control is available
• a climate entity for temperature request and work regime
• a select entity for bypass mode when bypass control is exposed
• sensor entities for telemetry and active states

Installation

HACS

1. Open HACS in Home Assistant.
2. Go to Integrations.
3. Open the menu and choose Custom repositories.
4. Add this GitHub repository as an Integration.
5. Search for Atrea aMotion.
6. Install it.
7. Restart Home Assistant.
8. Add the integration from Settings -> Devices & services.

Manual

1. Copy custom_components/atrea_amotion into your Home Assistant custom_components directory.
2. Restart Home Assistant.
3. Add the integration from Settings -> Devices & services.

Configuration

Before setting up the integration, make sure the unit has a local user account configured. The integration requires local username/password authentication and cannot access the unit without a local user.

The integration can automatically discover compatible units on your local network during setup.

If a unit is found, it will be shown in the config flow so you can select it and enter only the login details. Units that are already configured in Home Assistant are marked in the list.

If nothing is discovered, you can still continue by entering the host manually. The integration can also help recover from IP address changes by recognizing the same unit again when possible.

The integration connects directly to the unit over the local network.

Status

This project is actively evolving.

The current implementation focuses on:

• local websocket transport
• capability discovery
• separate supply and extract fan support
• climate support for work regime and target temperature
• bypass control as a select entity
• telemetry and active-state sensors
• fan setpoint sensors for requested supply / extract speed, plus actual fan factor telemetry
• bypass/runtime sensors such as bypass_estim, damper_io_state, and fan operating hours
• filter/service sensors such as next filter check, last filter replacement, days remaining, and maintenance registers
• localized active-state notifications derived from websocket states.active plus baseStates
• a card-ready notification payload exposed on the climate entity attributes and the active_notifications sensor
• a button action to confirm filter replacement and reset the filter interval on the unit
• switch actions to enable or disable Modbus TCP and firmware auto update
• a maintenance button to request a unit reboot
• a text action to edit the unit name from Home Assistant

Some protocol features are intentionally documented first and planned for later implementation, especially:

• temporary override duration and automatic rollback
• scenes
• calendars
• triggers
• Modbus TCP support
• broader support validation across more aMotion variants

Protocol Notes

Working protocol and entity-model notes are kept here:

• docs/WEBSOCKET_API.md
• docs/ENTITY_STRATEGY.md

These files are meant to be the reference for future changes so the integration stays coherent as more capabilities and unit variants are added.

Localized Notifications

The integration now treats websocket active states as a first-class UI model instead of exposing only raw booleans.

Observed pipeline:

ui_info.states.active
        +
ui_diagram_scheme.baseStates
        +
translations/en.json state_messages
        ↓
normalized notifications payload

The coordinator builds a stable per-message structure with fields such as:

• id
• code
• purpose
• severity
• kind
• prefix
• message
• message_code
• full_message

This normalized payload is exposed in two places:

• climate attributes:
  • notifications
  • warning_count
  • fault_count
  • highest_severity
  • primary_message
  • has_warning
  • has_fault
• sensor.active_notifications:
  • state = normalized notification count
  • attributes = same aggregate payload as above

The dedicated Lovelace card is expected to consume that normalized payload directly and only fall back to generic warning / fault flags when paired with an older integration build.

Attribution

This integration was inspired by and originally derived from the work of @xbezdick on an earlier aMotion Atrea integration.

That earlier work helped establish the initial Home Assistant support path for aMotion units. This project continues from that starting point but expands the design toward a broader multi-platform model, because the aMotion system exposes much more than a single climate abstraction can comfortably represent.

Notes

• This integration uses local websocket communication.
• Cloud access is not required for the observed local control flow.
• Different aMotion boards and unit configurations may expose different capabilities, so runtime detection is preferred over hardcoded assumptions.