Midea-local python lib

中文版 / Chinese README

Control your Midea M-Smart appliances via local area network.

This library is part of https://github.com/georgezhao2010/midea_ac_lan code. It was separated to segregate responsibilities.

⭐If this component is helpful for you, please star it, it encourages me a lot.

Getting started

Finding your device

from midealocal.discover import discover

# Without knowing the ip address
discover()
# If you know the ip address
discover(ip_address="203.0.113.11")
# The device type is in hexadecimal as in midealocal/devices/TYPE
type_code = hex(list(discover().values())[0]["type"])[2:]

Getting data from device

from midealocal.discover import discover
from midealocal.devices import device_selector

token = "..."
key = "..."

# Get the first device
d = list(discover().values())[0]
# Select the device
ac = device_selector(
    name="AC",
    device_id=d["device_id"],
    device_type=d["type"],
    ip_address=d["ip_address"],
    port=d["port"],
    token=token,
    key=key,
    device_protocol=d["protocol"],
    model=d["model"],
    subtype=0,
    customize="",
)

# Connect and authenticate
ac.connect()

# Getting the attributes
print(ac.attributes)
# Setting the temperature
ac.set_target_temperature(23.0, None)
# Setting the swing
ac.set_swing(False, False)

command line tool

python3 -m midealocal.cli -h

midea-local.json config file

python3 -m midealocal.cli save writes your cloud username, password and cloud name to midea-local.json in the current directory (use --user to save it to your user config folder instead). Every midealocal.cli command then loads that file automatically, so you don't have to pass --username/--password/--cloud-name again.

{
  "username": "user@example.com",
  "password": "your-cloud-password",
  "cloud_name": "SmartHome"
}

All fields are optional; only include what you need. Run python3 -m midealocal.cli discover -h for the full option list.

midea-devices.json token/key cache

Every device needs a token/key pair, normally fetched from the cloud on each run. discover caches the pair that successfully connects to a device in midea-devices.json, keyed by device_id, and tries that cached pair first on every later run — before contacting the cloud at all. In practice this means only the first discover/setattr run for a given device needs your cloud credentials. If a cached key ever stops working (e.g. the device was re-paired), discover automatically falls back to fetching a fresh key from the cloud and updates the cache. The file is managed automatically; you don't need to create or edit it yourself.

{
  "devices": [
    {
      "device_id": "146235046630006",
      "token": "...",
      "key": "..."
    }
  ]
}

Development

This project uses uv for its development environment. After installing uv:

git clone https://github.com/midea-lan/midea-local.git
cd midea-local
./scripts/setup.sh          # Linux / macOS / WSL2  (Windows: scripts\setup.ps1)

This creates a .venv, installs all dependencies, and sets up the prek hooks. Run tools with uv run, e.g. uv run python -m pytest ./tests/. See the contributing guide for the full workflow and per-OS uv install instructions.

Contributing Guide

CONTRIBUTING 中文版CONTRIBUTING