KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

melcloudhome

★ 134 Open GitHub ↗

MELCloudHome - Home Assistant Integration

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MELCloud Home

[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/hacs/integration)
[![GitHub Release](https://img.shields.io/github/release/andrew-blake/melcloudhome.svg)](https://github.com/andrew-blake/melcloudhome/releases)
![License](https://img.shields.io/github/license/andrew-blake/melcloudhome.svg)
[![Test](https://github.com/andrew-blake/melcloudhome/workflows/Test/badge.svg)](https://github.com/andrew-blake/melcloudhome/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/andrew-blake/melcloudhome/graph/badge.svg?token=WW97CHORNS)](https://codecov.io/gh/andrew-blake/melcloudhome)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fandrew-blake%2Fmelcloudhome%2Fmain%2Fpyproject.toml)

Home Assistant custom integration for **MELCloud Home**.

## What's New in v2.4.1

**Entity names now follow your Home Assistant language.** Sensor and binary sensor names (WiFi signal, Room temperature, Frost protection, Holiday mode, and others) previously always displayed in English regardless of your Home Assistant language setting - they're now translated correctly. Identified and diagnosed by [@Jan-Arild-Blekken](https://github.com/Jan-Arild-Blekken).

**New devices going forward will get entity IDs that match their translated name** for a few diagnostic sensors, including the COP sensor and the minimum/maximum frost and overheat protection sensors. This doesn't affect any of your existing entities.

Norwegian (nb) translations added (thanks @Jan-Arild-Blekken).

See [CHANGELOG.md](CHANGELOG.md) for full history.

## Features

### Air-to-Air (ATA) - Air Conditioning

- 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](#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

### Air-to-Water (ATW) - Heat Pumps

- 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](#real-time-updates) via WebSocket push

*Auto-detected from device capabilities - see [docs/entities.md](docs/entities.md) for details

## Requirements

- Home Assistant 2025.8.0 or newer
- MELCloud Home account with configured devices
- Internet connection for cloud API access

## Supported Devices

### Air-to-Air (ATA) - Air Conditioning Units

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](SUPPORTED_DEVICES.md).

### Air-to-Water (ATW) - Heat Pumps

- **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](SUPPORTED_DEVICES.md).

## Installation

### HACS (Recommended)

[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=andrew-blake&repository=melcloudhome&category=integration)

Or manually: open HACS, search for "MELCloud Home", click "Download", and restart Home Assistant.

### Manual Installation

1. Download the latest release from [GitHub](https://github.com/andrew-blake/melcloudhome/releases)
2. Extract the `melcloudhome` folder to your `custom_components` directory
3. Restart Home Assistant

## Configuration

[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=melcloudhome)

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.

## Real-Time Updates

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.

## Important Notes

### Stable Entity IDs

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").

**⚠️ Warning:** If you delete entities and use the "Recreate entity IDs" option, entity IDs will change to name-based IDs (e.g., `climate.living_room_climate`), breaking automations. To preserve IDs, delete and re-add the integration instead.

See [docs/entities.md](docs/entities.md) for complete entity ID reference.

## Entities

The integration creates the following entities for each device:

**Air-to-Air (ATA) Systems:**

- Climate control (HVAC modes, temperature, fan speeds, swing)
- 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](docs/entities.md) for detailed entity IDs, control options, and configuration examples.

## Troubleshooting

### Integration Not Loading

- Check Home Assistant logs for errors
- Verify your MELCloud Home credentials
- Ensure devices are configured in the MELCloud Home app

### Entities Not Updating

- Check your internet connection
- Verify MELCloud Home service is accessible
- Review the integration logs for API errors

### Out-of-Band Changes Slow to Appear

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 lost` messages
- Verify the toggle is on: Settings → Devices & Services → MELCloud Home → Configure
- Updates still arrive via 60-second polling even when the WebSocket is down

### Energy Sensor Unavailable

- 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

### Export Diagnostics

1. Go to **Settings** → **Devices & Services**
2. Find "MELCloud Home" integration
3. Click the three dots and select "Download diagnostics"
4. Share the file when reporting issues

## API Rate Limiting

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.

## Development & Code Quality

[![Coverage Sunburst](https://codecov.io/gh/andrew-blake/melcloudhome/graphs/sunburst.svg?token=WW97CHORNS)](https://codecov.io/gh/andrew-blake/melcloudhome)

**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:**

- [Architecture Overview](docs/architecture.md) - Visual system architecture with mermaid diagrams
- [Testing Best Practices](docs/testing-best-practices.md) - Development setup and testing guidelines
- [Architecture Decision Records](docs/README.md#architecture-decision-records-adrs) - Key architectural decisions

## Support

- **Issues**: [GitHub Issues](https://github.com/andrew-blake/melcloudhome/issues)
- **Documentation**: [GitHub Repository](https://github.com/andrew-blake/melcloudhome)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This is an unofficial integration and is not affiliated with, endorsed by, or connected to Mitsubishi Electric or MELCloud. Use at your own risk.

## Credits

Developed by Andrew Blake ([@andrew-blake](https://github.com/andrew-blake))

**Contributors:**

- [@mrdjtoto](https://github.com/mrdjtoto) - real-time updates: WebSocket protocol investigation, captures, and implementation (#174-#176)

melcloudhome

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README