Mitsubishi Electric Kumo

Control for Mitsubishi Electric ductless mini-split heat pumps (M-Series, Mr. Slim, residential City Multi) that have a Kumo Wi-Fi adapter (PAC-USWHS002-WF-2 or compatible) installed and onboarded.

The driver is local-first: once each adapter's crypto material is harvested (one sync_local_credentials run), status polling and all mode / setpoint / fan / vane commands go straight to the adapter over the LAN — signed HTTP requests on TCP 80, no internet required at runtime. The Kumo Cloud REST API remains as the automatic fallback, and as a pure cloud mode for sites that want it.

One cloud touch, then LAN

The adapters sign local requests with a per-device password + cryptoSerial that only the cloud account can reveal. sync_local_credentials fetches them once and stores them on the zones (encrypted). After that, the cloud is optional — a site keeps heating and cooling through an internet outage.

Prerequisites

• Each indoor unit has a Kumo Wi-Fi adapter installed and provisioned in the Kumo Cloud / Mitsubishi Comfort mobile app under one account.
• The GEM controller can reach app-prod.kumocloud.com over HTTPS (for login, credential harvest, and cloud fallback).
• For local control, GEM must reach each adapter on TCP 80. Give the adapters DHCP reservations — the local_address zone attribute stores a fixed IP.

Setup

1. Create a device of driver type mitsubishi_kumo_cloud.
2. Enter the Kumo Cloud username (email) and password exactly as used in the mobile app. The password attribute is encrypted at rest.
3. Send the get_devices command. The response lists indoor units with their serial and label.
4. For each indoor unit, create a zone with zone.address = the unit serial (12 alphanumeric characters).
5. Run sync_local_credentials. For each zone it stores local_password (encrypted) and crypto_serial, and fills local_address when the cloud reports the adapter's IP. Set local_address manually on any zone the cloud didn't report an IP for.
6. Done — with transport on its default (auto), zones with synced credentials poll and command locally; anything else uses the cloud.

Credential harvest paths

sync_local_credentials tries two sources:

• Legacy v2 accounts — the login response's zoneTable carries address, password, and cryptoSerial directly. Instant.
• Migrated (Mitsubishi Comfort) accounts — cryptoSerial comes from the V3 REST API and the adapter password arrives over a Socket.IO adapter_update event. The harvest polls for up to 60 seconds; re-run it if a unit reports has_password: false.

Attributes

Device

Name	Required	Type	Description
username	yes	string	Email used in the Kumo Cloud app.
password	yes	string (secure)	Password used in the Kumo Cloud app.
transport	no	string	auto (default): local when a zone has synced credentials, cloud otherwise/on failure. local: LAN only, never falls back. cloud: legacy cloud-only behavior.
status_interval	no	int (ms)	Poll cadence. Default 60000. Floor is 30000 while any zone polls the cloud; drops to 10000 when every zone is local.

Zone

zone.address is the indoor-unit serial. Local-control attributes (managed by sync_local_credentials, editable by hand):

Attribute	Type	Notes
local_address	string	Adapter LAN IP. Auto-filled when the cloud knows it; use a DHCP reservation.
local_password	string (secure)	Base64 adapter password used to sign local requests.
crypto_serial	string	Hex cryptoSerial used to sign local requests.

State attributes written as the driver polls (identical on both transports):

Attribute	Type	Notes
state	string	on / off summary.
mode	string	heat, cool, auto, dry, fan, or off. Local vent reports as fan; autoHeat/autoCool report as auto.
temperature	float	Current room temperature reported by the indoor unit.
heat_setpoint	float	Active heat setpoint.
cool_setpoint	float	Active cool setpoint.
fan_speed	string	Reported fan speed.
vane	string	Reported vane direction.
standby	boolean	Local transport only — unit is in standby.
filter_dirty	boolean	Local transport only — filter service flag.
defrost	boolean	Local transport only — defrost cycle active.

The attribute units (°F vs °C) follow whatever the unit was provisioned with in the Kumo Cloud app — the driver does not convert.

Commands

Command	Args	Notes
get_devices	—	Discovery; lists the indoor units linked to the account, with local_ready per matching zone.
sync_local_credentials	address (optional)	Harvest local credentials onto zones. Omit address to sync all zones.
on	address	Powers the indoor unit on. On the local path this restores the last known mode (or auto).
off	address	Powers it off.
set_mode	address, mode	Sets heat, cool, auto, dry, fan, or off.
set_temperature	address, temperature	Single-setpoint convenience. In cool mode it writes the cool setpoint; in heat mode the heat setpoint; otherwise both.
set_heat_setpoint	address, temperature	Heat setpoint only.
set_cool_setpoint	address, temperature	Cool setpoint only.
set_fan_speed	address, fan_speed	auto, superquiet, quiet, low, medium, high, powerful, superpowerful. On the local path medium→low and high→powerful (the hardware has five discrete speeds).
set_vane	address, vane	Vertical vane direction: auto, horizontal, midhorizontal, middle/midpoint, midvertical, vertical, swing.
get_status	address	Force a one-shot status read over the preferred transport.

Known limitations & quirks

• Local requests are signed over the exact request body bytes — the driver serializes once and sends those bytes. If you're debugging with curl, hash exactly what you send.
• Adapters are slow, single-connection HTTP servers; 1–8 s responses are normal. The driver serializes requests per adapter.
• If the cloud login fails but zones have synced credentials, the driver keeps running local-only and logs the outage. Cloud requests self-heal when connectivity returns.
• The Kumo Cloud login response shape has shifted between app versions. The driver tolerates both the historical 3-element array and the newer object form, but a future cloud change may need a small update.
• Setpoint changes in dry, fan, or off mode are silently dropped. Always set a heat/cool/auto mode first.
• Cloud polling is clamped to 30 s minimum (Kumo Cloud rate-limits and will eventually 429). Local polling may go down to 10 s.
• Humidity, error codes, and the City Multi central-controller pages are not exposed.

Troubleshooting

• mitsubishi kumo cloud login failed in the log — verify the email/password by signing into the mobile app first. The driver re-authenticates automatically on 401 / 403 responses. Zones with synced local credentials keep working local-only.
• sync_local_credentials returns has_password: false — Comfort-backend accounts deliver the password over Socket.IO; re-run the command (it polls up to 60 s) and confirm the unit is online in the app.
• Zone stays on cloud with transport: auto — the zone needs all three of local_address, local_password, crypto_serial.
• device_authentication_error from an adapter — its local credentials rotated (re-onboarded adapter). Re-run sync_local_credentials.
• mitsubishi kumo cloud devices found: 0 — the account contains no provisioned adapters, or the account-tree shape was unrecognized. Run get_devices and check the response.
• Polling pauses in the log — Kumo Cloud will rate-limit polling under ~30 s. Raise status_interval, or finish the local-credential sync so polling leaves the cloud entirely.