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 also ships a Mitsubishi Electric Kumo Cloud driver. They are different platforms — pick by product, not by name:

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

The names above are exactly what you choose in the driver dropdown on the device row. If you commissioned 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 for ATA and ATW (Zone1) — the value is passed straight through to MELCloud with no unit conversion (MELCloud expresses setpoints in Celsius; see Setpoints and units below).
• 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 ventilation controls beyond power. For Lossnay ERV adaptors only power on/off is wired (and power state is read back); fan speed, ventilation mode, and bypass are not exposed. Use the MELCloud app.
• 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 — this driver does not handle adaptor commissioning.
2. In GEM admin, go to System → Devices → Add Device and pick Mitsubishi MELCloud as the driver.
3. Enter the MELCloud account Email and Password (the password is stored encrypted at rest).
4. Save the device. After ~10 seconds it should show as connected.
5. Run the get_devices command (the device's command runner, or System → Commands). Each entry lists the adaptor's buildingId, deviceId, name, and detected type (ata / atw / erv).
6. For each indoor unit you want to control, create a zone (System → Zones → Add Zone) and:
   • set its Device to this MELCloud device — this is what binds the zone to the driver; a zone bound to no device never polls or accepts commands;
   • set its Address to <buildingId>:<deviceId> (e.g. 12345:67890) — both numeric ids, separated by a colon;
   • leave the Subsystem on Climate (the editor pre-selects it, since the driver hints climate and Climate is one of the default subsystems).
7. (Optional) Set the zone's device_type attribute to ata, atw, or erv only if the driver mis-detects the family. The family is otherwise taken from get_devices, falling back to ata.

note

This driver does not auto-create zones. Each indoor unit must be added as a zone by hand (step 6), bound to the MELCloud device and given the buildingId:deviceId address. A zone bound to the wrong device, or with a missing/malformed address, is silently skipped by the status poller.

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, range 30000–600000). Indoor units only phone home ~60 s anyway, so polling faster gains nothing.
request_timeout	int	no	Per-request timeout in ms (default 15000, range 2000–60000).

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.

These zone attribute names are cataloged, so they autocomplete in the Attribute editor's name picker and can drive attribute triggers (for example, a trigger on temperature or on system_mode changing to cool). The driver writes setpoint / temperature as numbers and state / system_mode / fan_mode as strings; state is maintained on every device family (ATA / ATW / ERV).

Zone address format

<buildingId>:<deviceId>, e.g. 12345:67890. Both numeric ids come from get_devices. The colon separator is mandatory — an address with no colon is rejected before any cloud call (the zone logs invalid zone address); a wrong building or device id makes the cloud read fail and the zone never updates.

Setpoints and units

GEM performs no temperature unit conversion for this driver. Whatever number you send with set_temperature is written verbatim to MELCloud's setpoint field (SetTemperature for ATA, SetTemperatureZone1 for ATW Zone1), and the same raw number is read back into the setpoint and temperature zone attributes. MELCloud's cloud API expresses setpoints and room temperatures in Celsius, so send Celsius values regardless of what the MELCloud mobile app displays. A zone temperature_unit attribute, if you set one, is ignored by this driver.

Commands

Command	Args	Notes
on / off	address	Power. Works for ATA, ATW, and ERV.
set_temperature	address, value	Setpoint, written verbatim — no unit conversion (send Celsius; see Setpoints and units above). ATA → SetTemperature, ATW → SetTemperatureZone1.
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 ventilation controls (fan speed, ventilation mode, bypass) not exposed — only power on/off and the reported power state.
• Vane numeric mapping is honored as-typed because Mitsubishi's API doesn't standardize it across adaptor firmware revisions. The vane commands accept a numeric value only (auto / swing text is not translated).

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 — confirm the zone's Device is set to this MELCloud device and its Address is <buildingId>:<deviceId> with both numeric ids and the literal colon. A zone bound to no device, or with a malformed address, is silently skipped by the poller.
• Device disconnected after a long outage — MELCloud occasionally invalidates ContextKeys on multi-hour outages. refresh_token forces a fresh login.

Related documentation

• Mitsubishi Electric Kumo Cloud — the North-American sibling platform; pick that driver for Kumo-Cloud-commissioned mini-splits.
• Zones — create one zone per indoor unit, bound to this device, with the buildingId:deviceId address.
• Subsystems — the Climate subsystem these zones belong to.
• Devices — add and configure the MELCloud account device.
• Commands — the command grid and Test runner for get_devices, set_mode, set_temperature, and the rest.