Home Assistant custom integration for MELCloud Home.
Fan speed and vane now work from HomeKit. Bridged to HomeKit, an air conditioning unit used to appear as a bare thermostat offering temperature and mode, with no way to change the fan or the vane. The bridge recognises a fan speed control and a swing control by a fixed set of names that these units do not use, so neither control was ever built. Each air conditioning unit now gets a fan entity alongside its climate entity, carrying the unit's power, its fan speed and whether the vane is swinging, and all three come through. The speed slider has one step for each speed the unit actually has. The fan is a new entity, so restart Home Assistant to pick it up. See docs/homekit.md if the tile does not appear, and for the handful of behaviours that catch people out.
The same entity is picked up automatically by Alexa and Google Home once you expose it to them. Alexa should offer both the speed and the swing, and Google Home offers the speed, because its fan has no swing control. I have tested HomeKit only.
This entity is there for those ecosystems and is additive. The climate entity is unchanged and keeps its own fan speed and vane dropdowns, including the individual vane positions that a swing switch cannot express, so if you drive the integration from the Home Assistant UI alone you can ignore the new entity entirely. A unit with no vane gets no swing control, and switching swing on sets the vane for the next time the unit runs without starting a stopped unit. Reported in #318.
Every command now reaches your unit. The integration used to check whether a unit already looked like it was at the value you asked for and skip sending anything if it was. That check ran against its own copy of the unit, which a command you had just sent could already have made out of date, so changing a value and changing it straight back did nothing the second time, and choosing a value in Home Assistant that you had just set in the MELCloud app sent nothing at all. Reported in #310 and discussion #135.
Entities no longer go "unavailable" when MELCloud has a bad moment. A single request that timed out, dropped, or came back with a server error used to turn every sensor and climate entity unavailable until the next request succeeded. It now keeps the last known values through up to two failed requests in a row. A third in a row still shows as unavailable, because at that point something is genuinely wrong. Reported in #309.
If you have an automation that passes a mode to climate.set_temperature or water_heater.set_temperature without wanting it applied, remove it from the call. The integration used to read the temperature and discard the mode. It now sets both.
See CHANGELOG.md for full history.
- Full climate control (power, temperature, modes, fan speeds, vane directions)
- Energy monitoring with Home Assistant Energy Dashboard support
- Sensors (room temperature, outdoor temperature*, WiFi signal, connection status)
- Real-time updates via WebSocket push, plus 60-second polling (30-minute for outdoor temperature)
*Always created; reads unknown on units that don't report an outdoor temperature
- Zone 1 & Zone 2 climate control with preset modes (Room/Flow/Curve) - Zone 2 auto-detected
- DHW tank control via water heater platform
- System power switch
- Multiple sensors (temperatures, operation status, 6 telemetry sensors)
- Energy monitoring* (consumed, produced, COP - Energy Dashboard compatible)
- Cooling mode* (Cool Room/Cool Flow presets)
- Real-time updates via WebSocket push
*Auto-detected from device capabilities - see docs/entities.md for details
- Home Assistant 2025.8.0 or newer
- MELCloud Home account with configured devices
- Internet connection for cloud API access
This integration supports Mitsubishi Electric air conditioning units connected via MELCloud Home WiFi adapters (MAC-5xx series).
Supported systems: Wall-mounted splits, ducted systems, and console units tested and working.
Note: If your system uses the classic MELCloud app (not MELCloud Home), use the official Home Assistant MELCloud integration instead.
For complete hardware compatibility including specific models, WiFi adapters, and technical notes, see SUPPORTED_DEVICES.md.
- Status: Production-ready (tested on real hardware)
- Supported systems: Mitsubishi Electric Ecodan heat pumps with FTC controllers
- Core features: Zone 1 & Zone 2 heating, DHW control, 3-way valve systems, telemetry sensors, energy monitoring*
- Optional features: Cooling mode (capability-based), energy monitoring (capability-based)
*Feature availability auto-detected from device capabilities
For tested controller models and capability details, see SUPPORTED_DEVICES.md.
Or manually: open HACS, search for "MELCloud Home", click "Download", and restart Home Assistant.
- Download the latest release from GitHub
- Extract the
melcloudhomefolder to yourcustom_componentsdirectory - Restart Home Assistant
Or manually: Settings → Devices & Services → Add Integration → search "MELCloud Home"
Enter your MELCloud Home credentials (email and password). Your devices will be automatically discovered and added.
Changes made with the remote control, the MELCloud Home app, or a schedule appear in Home Assistant within seconds — no more waiting for the next poll.
It's on by default and there's nothing to set up. If the connection ever drops, the integration automatically falls back to regular 60-second polling, so your devices keep working either way.
To turn it off: Settings → Devices & Services → MELCloud Home → Configure → switch off "Real-time updates".
The "Real-time updates" sensor (under the MELCloud Home service device, Diagnostic section) shows whether the live connection is currently active.
This integration uses UUID-based entity IDs to ensure automations never break when device names change. Entity IDs follow the format {domain}.melcloudhome_{short_id}_{entity_name} where short_id is derived from the device UUID.
Device names are set to friendly names from your MELCloud Home account (e.g., "Living Room").
climate.living_room_climate), breaking automations. To preserve IDs, delete and re-add the integration instead.
See docs/entities.md for complete entity ID reference.
The integration creates the following entities for each device:
Air-to-Air (ATA) Systems:
- Climate control (HVAC modes, temperature, fan speeds, swing)
- Fan (fan speed, vane oscillation, unit power — gives HomeKit a speed slider and swing switch)
- Sensors (room temperature, outdoor temperature, WiFi signal, energy consumption)
- Binary sensors (error state, connection status)
Air-to-Water (ATW) Heat Pumps:
- Climate control (Zone 1 & Zone 2 heating/cooling with preset modes)
- Water heater (DHW tank control)
- System power switch
- Sensors (temperatures, operation status, telemetry, WiFi signal, energy*)
- Binary sensors (error state, connection status, forced DHW active)
*Energy monitoring auto-detected from device capabilities
Complete entity reference: See docs/entities.md for detailed entity IDs, control options, and configuration examples.
Apple HomeKit: See docs/homekit.md for what the fan entity looks like in the Home app, how to get it bridged, and the behaviour that surprises people.
- Check Home Assistant logs for errors
- Verify your MELCloud Home credentials
- Ensure devices are configured in the MELCloud Home app
- Check your internet connection
- Verify MELCloud Home service is accessible
- Review the integration logs for API errors
If changes made with the remote or MELCloud app take up to a minute to show in Home Assistant, real-time updates may not be connected:
- Check the logs for
WebSocket connected/WebSocket connection lostmessages - Verify the toggle is on: Settings → Devices & Services → MELCloud Home → Configure
- Updates still arrive via 60-second polling even when the WebSocket is down
- Some devices may not report energy data
- Check if device shows energy consumption in the MELCloud Home app
- Energy sensors require 30 minutes for initial data
- Go to Settings → Devices & Services
- Find "MELCloud Home" integration
- Click the three dots and select "Download diagnostics"
- Share the file when reporting issues
The integration uses conservative polling intervals to respect API limits:
- Climate/Sensors: 60 seconds
- Energy Data: 30 minutes
- Outdoor Temperature: 30 minutes
These intervals balance update frequency with API rate limits. Real-time updates don't add polling load — the WebSocket is a single long-lived connection, and it only triggers an extra state refresh when a device actually changes.
Test Coverage:
- Integration tests: Climate control, sensors, config flow, diagnostics
- API tests: Authentication, device control, data parsing
- Quality gates: All PRs require passing tests and coverage checks
Documentation:
- Using MELCloud Home with Apple HomeKit - What appears in the Home app and how it behaves
- Architecture Overview - Visual system architecture with mermaid diagrams
- Testing Best Practices - Development setup and testing guidelines
- Architecture Decision Records - Key architectural decisions
- Issues: GitHub Issues
- Documentation: GitHub Repository
This project is licensed under the MIT License - see the LICENSE file for details.
This is an unofficial integration and is not affiliated with, endorsed by, or connected to Mitsubishi Electric or MELCloud. Use at your own risk.
Developed by Andrew Blake (@andrew-blake)
Contributors:
- @mrdjtoto - real-time updates: WebSocket protocol investigation, captures, and implementation (#174-#176)