Midea air conditioner serial protocol library — codec, state management, gateway daemon, async client, and CLI tools.
Requires Python 3.11+. Status: active, feature-complete. Target platform for the gateway daemon is a Raspberry Pi on the Wi-Fi dongle UART bus at 9600 8N1; the library itself is platform-neutral.
| Package | What it is |
|---|---|
blaueis-core |
Pure-Python codec, CRC/checksum, glossary-driven field decode, AES-256-GCM crypto, DebugRing handler. No I/O. |
blaueis-gateway |
Async UART↔WebSocket bridge. Runs on the Pi as a systemd service. Flight-recorder, slot pool, correlation engine. |
blaueis-client |
Async WebSocket client + Device wrapper (connection supervision, B5 capability discovery, status-DB survives reconnects). |
blaueis-tools |
CLI utilities — capture replay, inspection. |
Home Assistant users: follow the quickstart in blaueis-ha-midea — it covers wiring, this installer, and the HA-side integration end to end.
Install the gateway on a Raspberry Pi:
bash -c "$(curl -sL https://raw.githubusercontent.com/fabcoded/blaueis-libmidea/main/scripts/install.sh)"The installer pins the gateway to the latest published GitHub release. No
release exists yet, so today it warns and installs main (development code);
--ref <tag|branch> picks a version explicitly — see
docs/operations.md §2.
Hardware, in short: the AC's Wi-Fi dongle port (CN3) is a 5 V TTL UART, 9600 8N1, on 4 pins; connect it to the Pi's primary UART (header pins 8/10) through a bidirectional 5 V↔3.3 V level shifter; power the Pi from its own 5.1 V supply and leave CN3's 5 V pin unconnected; the Pi's UART must be freed from the serial console first, and from Bluetooth too on Zero/3/4. See docs/operations.md §1 for the canonical reference.
| Command | Purpose |
|---|---|
blaueis-gw status |
State of all instances |
blaueis-gw logs <name> -f |
Follow an instance's log |
blaueis-gw configure |
Add another AC or edit an instance |
sudo blaueis-gw update |
Check for a newer release; --apply installs it, --ref <tag> picks a version, --rollback reverts it |
sudo blaueis-gw uninstall |
Remove the gateway |
See docs/operations.md for config + systemd details.
On a development machine (use the client library):
git clone https://github.com/fabcoded/blaueis-libmidea.git
cd blaueis-libmidea
pip install -e packages/blaueis-core -e packages/blaueis-clientEach package has its own pytest root — cd in before running:
cd packages/blaueis-core && python3 -m pytest # 61
cd packages/blaueis-gateway && python3 -m pytest # 43
cd packages/blaueis-client && python3 -m pytest # 147packages/blaueis-core/src/blaueis/core/data/glossary.yaml— field glossary: every field the library reads or writes, with units, ranges, availability, and capability gating. Self-documenting — read it directly; the file header explains the schema.- docs/architecture.md — package map, dependencies, logger names.
- docs/ws_protocol.md — WebSocket wire reference (every frame type).
- docs/operations.md — install, systemd, config, update, debug, troubleshoot.
- CHANGELOG.md — what each release changes.
- docs/releasing.md — release pipeline (PyPI trusted publishing, draft GitHub release) and the maintainer's release steps.
- docs/versioning.md — the version numbers (protocol, packages, gateway build string), what is compared, and the compatibility rules.
- docs/flight_recorder.md — rolling in-memory debug buffer (design + rationale).
- docs/status_db.md — status dictionary schema and merge logic.
- docs/feature_gating.md — the offer gate: capability / mode / interlock axes, the
gate:block schema, the evaluator, and bit-position anchors.
A note on the name. Blaueis is a small glacier in the Bavarian Alps, retreating year by year. Use energy responsibly — climate change is real.
Not affiliated with any commercial entity or the Berchtesgaden National Park administration.
See CONTRIBUTING.md — covers setup, test expectations, the citation rule, and what good PRs look like.
Blaueis is an umbrella of open-protocol HVAC tooling. Sibling repos:
- blaueis-ha-midea — Home Assistant custom integration that consumes this library via a gateway.
- blaueis-esphome — ESPHome external component porting the gateway protocol to ESP32 (placeholder, not yet implemented).
- blaueis-hvacshark — Wireshark Lua dissector, live-capture dongle, and protocol specifications.
- blaueis-hvacshark-traces — capture sessions and offline-analysis scripts used to derive the protocol.
Protocol knowledge in this library 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, especially thorough on 0xC0 / 0x40 frame decoding.
- chemelli74/midea-local — Python client for the Midea LAN protocol; deep capability (B5) reference.
- reneklootwijk/node-mideahvac — Node.js driver covering multiple Midea product families.
- NeoAcheron/midea-ac-py — early Python Midea AC implementation and historical reference.
- wuwentao/midea_ac_lan — HA integration covering broad Midea device coverage.
- 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.