Home Assistant custom integration for Midea air conditioners via a Blaueis gateway (Raspberry Pi).
Requires Home Assistant 2024.12+ and a running blaueis-libmidea gateway on your network.
New to Blaueis Midea? The QUICKSTART walks through everything end to end:
- Wire the AC's dongle port to a Raspberry Pi through a level shifter.
- Install the gateway on the Pi with the one-line installer and setup wizard.
- Add the integration in Home Assistant through the Marketplace (HACS before Home Assistant 2026.11).
- Connect — enter the Pi's address and PSK, and the AC becomes a climate entity.
A single config entry per gateway produces two HA devices:
- AC device — climate entity with mode, target temperature, fan speed, swing, and presets (turbo, eco, sleep, frost protection). Plus individual sensors and switches for everything else the unit exposes. Only features your AC actually has appear — the integration queries B5 capabilities on startup and hides what isn't supported.
- Gateway device — Pi health sensors (CPU, RAM, temperature, disk, uptime).
| Platform | Source | Examples |
|---|---|---|
| Climate | Hardcoded single entity | Mode, temp, fan, swing, presets |
| Sensor | Auto-mapped from glossary | Indoor/outdoor temp, compressor freq, coil temps, energy, error codes |
| Binary sensor | Auto-mapped (read-only bool) | Follow Me status, compressor idle |
| Switch | Auto-mapped (writable bool) | Self-clean, screen display, dry clean |
| Select | Auto-mapped (writable enum) | Breezeless mode, swing angle positions |
| Number | Auto-mapped (slider constraint) | Fan speed fine control, louver angle (1-100) |
Couples any HA temperature sensor to the AC's Follow Me / I Feel function. The AC uses the external sensor's reading instead of its built-in thermistor for the control loop.
Setup: Settings → Devices & Services → Blaueis Midea → Configure → pick a temperature sensor. Then enable the "Blaueis Follow Me" switch entity.
How it works: A 15-second timer reads the source sensor and sends the temperature to the AC via the Follow Me protocol frame. Every 30 seconds it also re-asserts the Follow Me flag as a keepalive. If HA stops or the connection drops, the AC reverts to its built-in sensor within ~60 seconds (protocol timeout).
The integration sends a B5 capability query at startup. The response determines which features become entities. Standalone entities for fields without B5 confirmation stay hidden. The climate entity provides basic mode fallbacks when B5 data is unavailable. The glossary YAML in blaueis-core defines all known Midea AC fields, their wire encoding, B5 cap IDs, and HA metadata.
Beyond the standard climate controls, the integration decodes C1 group queries (compressor frequency, coil temperatures T1-T4, EEV position, DC bus voltage, fan speeds, fault flags, runtime counters) and B1 property responses (louver angles). These appear as sensor entities, many disabled by default to keep the UI clean.
- Home Assistant 2026.11 or newer: Settings → Marketplace → Add from link →
fabcoded/blaueis-ha-midea, install Blaueis Midea AC, restart Home Assistant. - Before 2026.11: HACS → ⋮ → Custom repositories →
https://github.com/fabcoded/blaueis-ha-midea, type Integration; download Blaueis Midea AC, restart Home Assistant.
Until the first regular release only release candidates exist, which both stores hide by default; QUICKSTART shows how to opt in.
Then Settings → Devices & Services → Add Integration → Blaueis Midea AC, enter host / port / PSK.
Manual (non-HACS) installation is covered in docs/integration.md.
HA <--WebSocket (AES-256-GCM)--> Pi Gateway <--UART 9600 baud--> AC indoor unit
The gateway runs on a Raspberry Pi connected to the AC's CN3 connector, impersonating the OEM WiFi dongle. The HA integration connects over encrypted WebSocket — no cloud, no polling delay. State changes push immediately.
- docs/integration.md — install, configure, entity model, debugging, reload-vs-restart.
- docs/feature_gating.md — how the offer gate surfaces in HA (the two offering sites); the model lives in the sibling repo.
- Flight recorder design (in sibling repo) — what the HA "Download Diagnostics" bundle contains.
HA UI → Settings → Devices & Services → Blaueis Midea → ⋮ → Download Diagnostics. The JSON includes both the HA-side and gateway-side flight-recorder rings, merged by timestamp. Full frame-level capture with provenance tracking — no need to raise log levels.
This is a hobby project, answered on a best-effort basis, with no promise of response times or releases. It is developed and tested against one unit, a Midea XtremeSaveBlue split air conditioner; other Midea units that speak the same serial protocol are likely to work in part.
- Questions, setup help, and reports of which units work: Discussions.
- Bugs and feature requests: Issues; the bug form asks for the versions and the diagnostics bundle described under Debugging.
- Gateway, installer or protocol problems: blaueis-libmidea issues.
See CONTRIBUTING.md — covers setup, test expectations, the citation rule, and HA-specific reminders (reload vs restart, declarative YAML, cap-gated defaults).
- blaueis-libmidea — the Python library this integration consumes (installed from PyPI as
blaueis-coreandblaueis-client). - blaueis-esphome — ESP32 port of the gateway (placeholder).
- blaueis-hvacshark — Wireshark Lua dissector, live-capture dongle, protocol specs.
- blaueis-hvacshark-traces — capture sessions used to derive the protocol.
This integration builds on community research, own hardware captures, and publicly available documentation. A deep thank you to the open-source and home-automation community — especially the contributors around Home Assistant and the broader maker community — for their tireless research work and for publishing their findings openly.
Community projects that materially informed this work:
- dudanov/MideaUART — ESP/Arduino library for Midea UART.
- chemelli74/midea-local — Python client for the Midea LAN protocol.
- reneklootwijk/node-mideahvac — Node.js driver for Midea AC.
- NeoAcheron/midea-ac-py — early Python Midea AC implementation.
- wuwentao/midea_ac_lan — HA integration covering a broad Midea device set.
- Countless forum threads, GitHub issues, and pull requests in the HA and ESPHome communities.
If you believe your work is referenced here without proper attribution, or you have licensing concerns, please open an issue — we will respond promptly.
CC0 1.0 Universal — public-domain dedication. No warranty.