Mitsubishi MELCloud

Global cloud REST integration for Mitsubishi Electric heat pumps and ventilators paired into the MELCloud platform — predominantly EU and APAC residential / light-commercial deployments. Each MELCloud account becomes one GEM device row, and each Wi-Fi adaptor (MAC-567IF / MAC-568IF / MAC-577IF / MAC-587IF / etc.) on the account becomes a zone.

MELCloud vs Kumo Cloud

GEM already ships a mitsubishi_kumo_cloud driver. They are different platforms — pick by product, not by name:

Platform	Region	Typical product family	Driver
MELCloud	EU / APAC / global	ATA (ducted + ductless heat pumps), ATW (Ecodan air-to-water), Lossnay ERV	melcloud (this driver)
Kumo Cloud	North America only	Mitsubishi-USA ductless mini-splits	mitsubishi_kumo_cloud

If you set up the unit using the MELCloud mobile app, use this driver. If you set it up using the Kumo Cloud app, use the other one. The wire protocols are unrelated.

What this integration covers

• Power on / off for ATA, ATW (Zone1), and ERV adaptors.
• Setpoint (°C or °F per zone) for ATA and ATW.
• Operation mode (heat / cool / dry / fan / auto) for ATA.
• Fan speed (auto, 1–5) for ATA.
• Vane position vertical + horizontal for ATA — values pass through as-is; mapping varies by adaptor firmware.
• Status polling of room temperature, setpoint, mode, fan, and power on a configurable cadence (default 60 s).

What this integration does NOT cover (yet)

• Multi-zone ATW / Ecodan controls beyond Zone1 setpoint — weather compensation curves, Zone2 setpoints, hot-water-only mode, anti-legionella schedules. Use the MELCloud app.
• ERV write controls. Lossnay ERVs are surfaced read-only here.
• Energy reports. MELCloud's /Report/* endpoints are not yet wired.
• Vane-position semantic mapping. Numeric vane values pass through; the per-adaptor semantic (which number means "lowest sweep") is not standardized in Mitsubishi's API and we don't want to guess. Verify against your adaptor or use the MELCloud app to find the right number.

Prerequisites

• A registered MELCloud account at https://app.melcloud.com (free).
• Each Mitsubishi Wi-Fi adaptor commissioned and paired into that account via the MELCloud mobile app — this driver does not handle adaptor commissioning.
• Outbound HTTPS reachability from the GEM controller to app.melcloud.com.

Setup steps

1. Pair each Mitsubishi Wi-Fi adaptor into the MELCloud account using the mobile app.
2. In GEM admin → Devices → New Device, pick Mitsubishi MELCloud as the driver.
3. Enter the MELCloud email and password (the password is encrypted at rest).
4. Save. After ~10 seconds the device should show as connected.
5. Run the get_devices command — each entry shows BuildingID, DeviceID, and DeviceName.
6. For each indoor unit you want to control, create a zone in the climate subsystem with address = "<BuildingID>:<DeviceID>" (e.g. 12345:67890). Both ids are required because MELCloud's /Device/Get takes them both.
7. (Optional) Set zone.device_type to ata, atw, or erv if the driver mis-detects the device family. Default is ata.

Attribute reference

Device attributes

Name	Type	Required	Description
email	string	yes	MELCloud account email.
password	string	yes	MELCloud account password. Stored encrypted.
api_base	string	no	Override https://app.melcloud.com/Mitsubishi.Wifi.Client — only set if directed.
language	int	no	Login language code (default 0 = English). Affects error message language only.
status_interval	int	no	Poll cadence in ms (default 60000, minimum 30000). Indoor units only phone home ~60 s anyway.
request_timeout	int	no	Per-request timeout (default 15000 ms).

Zone attributes

Name	Type	Description
address	string	"<BuildingID>:<DeviceID>" (required).
device_type	string	ata / atw / erv. Override family detection if needed. Default ata.
state	string	Maintained by the driver: on / off.
system_mode	string	ATA only: heat / cool / dry / fan / auto.
setpoint	number	ATA: SetTemperature. ATW: SetTemperatureZone1.
temperature	number	ATA: RoomTemperature. ATW: RoomTemperatureZone1.
fan_mode	string	ATA only: auto or 1..5.

Zone address format

"<BuildingID>:<DeviceID>", e.g. 12345:67890. Both numeric ids come from get_devices. The colon separator is mandatory — without it /Device/Get won't know which building the device is in.

Commands

Command	Args	Notes
on / off	address	Power.
set_temperature	address, value	Setpoint in the device's configured unit.
set_mode	address, mode	ATA: heat / cool / dry / fan / auto. ATW: not yet implemented.
set_fan_mode	address, value	ATA only. auto or 1..5.
set_vane_vertical	address, value	ATA only. Numeric; mapping is per-adaptor.
set_vane_horizontal	address, value	ATA only. Numeric; mapping is per-adaptor.
get_devices	—	Enumerate every adaptor on the account.
get_status	optional address	Read one zone, or return the full cache.
refresh_token	—	Force a re-login (debug).

Known limitations

• Cloud-only. No LAN API exists for these adaptors; when Mitsubishi has an outage every zone goes offline.
• ~60-second response lag. Writes take effect on the next indoor-unit phone-home; status reflects the change after that.
• ATW Zone2 / hot-water / weather curves not exposed.
• ERV writes not exposed.
• Vane numeric mapping is honored as-typed because Mitsubishi's API doesn't standardize it across adaptor firmware revisions.

Troubleshooting

• login failed (ErrorId=1) — wrong email / password.
• login failed (ErrorId=2) — the MELCloud account isn't email-verified yet; finish verification in the mobile app.
• HTTP 401 on every call — the ContextKey expired (rare, but happens after long disconnects). The driver auto-re-logs-in on 401; if it persists, run refresh_token.
• HTTP 500 on a write — the cached device payload got out of sync (rare). Run get_status for the address to refresh the cache, then retry the write.
• Zone never updates — make sure zone.address is "<BuildingID>:<DeviceID>" with both numeric ids and the colon literally. Missing one half makes /Device/Get 400.
• Device disconnected after a long outage — MELCloud occasionally invalidates ContextKeys on multi-hour outages. refresh_token forces a fresh login.