This is a library that allows communication with Midea air conditioner and dehumidifier via the local area network.
This library allows discovering Midea air conditioners and dehumidifiers on local network, getting their state and controlling then. The name comes from Chinese name for Midea (美的) which translates to beautiful in English.
This library inspired from the repository at mac-zhou/midea-msmart which provides similar functionality for air conditioners and barban-dev/midea_inventor_dehumidifier cloud based functionality for dehumidifiers. This library may include verbatim or adapted portions of the code from those two projects.
Thanks also to yitsushi's project, NeoAcheron's project, andersonshatch's project.
The library works with Midea air conditioners and dehumidifiers supporting V2 and V3 protocol.
Some examples of supported dehumidifiers:
It may as well work with other Midea Wi-Fi air conditioners and dehumidifiers.
The following dehumidifier data is accessible through this library:
The following air conditioner data is accessible through this library:
This library is able to discover appliances on local network. This is done by broadcasting UDP packets to port 6445. Appliances will respond to this broadcast with their description packet. Following discovery, communication switches to TCP over port 6444. This communication is encrypted, and, for appliances with version 3 firmware the library needs a token/key (K1) combination associated to each appliance. This can be either provided as arguments or retrieved from Midea app account. Once obtained, the token/key (K1) pair can be reused for an appliance multiple times. The library can also retrieve the list of registered appliances from Midea app account and obtain additional information for devices (eg. name).
Library connects to Midea cloud API using credentials from NetHome Plus mobile app. You can use other Midea app mobile applications if you obtain their application key and id. See midea_beautiful/midea.py for some examples. Application key and application id must match, otherwise library won't be able to sign in.
The discovery should work on Linux and Windows based systems, however as of 2022 it doesn't work in Windows Subsystem for Linux and may not work in Docker containers or VMs as it depends network capabilities. For example, a VM or a container needs to have rights to broadcast to physical network to make discovery work. One workaround, if physical network access is not possible, is to run discovery from non-virtualized environment host.
If this discovery mechanism doesn't work on particular set-up, it is still possible to either target appliances directly using their IP address, when it is known, or to retrieve or set their status using cloud service.
Discovery requires that both the appliance and the machine performing discovery are on the same broadcast subnet. By default library issues broadcast to all network, i.e. address 255.255.255.255, but it is possible to restrict broadcast subnet (e.g. 192.0.2.255)
Library supports following protocols:
Credentials information like username, password or token keys are redacted by default. When using command line, pass --no-redact option to show them in the logs. You can use command line tool to display token and key (K1) data.
pip install --upgrade midea-beautiful-air
midea-beautiful-air-cli --help
midea-beautiful-air-cli discover --help
midea-beautiful-air-cli set --help
midea-beautiful-air-cli status --help
Discover appliances on the local network:
midea-beautiful-air-cli discover --account ACCOUNT_EMAIL --password PASSWORD
Show tokens used to connect to appliances via local network
midea-beautiful-air-cli discover --account ACCOUNT_EMAIL --password PASSWORD --credentials
Search for devices by providing explicit network address
midea-beautiful-air-cli discover --account ACCOUNT_EMAIL --password PASSWORD --address 192.0.2.3 --credentials
Search for devices by providing broadcast address
midea-beautiful-air-cli discover --account ACCOUNT_EMAIL --password PASSWORD --address 192.0.2.255 --credentials
Discovery when appliances are registered to a supported app:
midea-beautiful-air-cli --verbose ---log DEBUG discover --account ACCOUNT --password PASSWORD --credentials --app MSmartHome
Discovery when appliances are registered to new API (note that it is easier to use --app option):
midea-beautiful-air-cli --verbose ---log DEBUG discover --account ACCOUNT --password PASSWORD --credentials --appkey APPKEY --appid APPID --hmackey HMACKEY --iotkey IOTKEY --apiurl https://mp-prod.appsmb.com/mas/v5/app/proxy?alias= --proxied
Get status of an appliance using known TOKEN and KEY (e.g. retrieved using discover command)
midea-beautiful-air-cli status --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY
Get status of an appliance using Midea app credentials
midea-beautiful-air-cli status --ip APPLIANCE_IP_ADDRESS --account ACCOUNT_EMAIL --password PASSWORD
Get status of an appliance through Midea cloud API (note the usage of --id and --cloud options)
midea-beautiful-air-cli status --id APPLIANCE_ID --account ACCOUNT_EMAIL --password PASSWORD --cloud
Following are some examples of usage:
Set target relative humidity (0-100)
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --target-humidity 55
Sets operating mode (number 1 to 4)
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --mode 1
Turn on/off ion mode (0 or 1)
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --ion-mode 1
Turn appliance on/off mode (0 or 1)
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --running 1
Turn on/off pump (0 or 1)
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --pump 1
Combinations of multiple settings
midea-beautiful-air-cli set --ip APPLIANCE_IP_ADDRESS --token TOKEN --key KEY --fan-speed 60 --target-humidity 50
Set target humidity through Midea cloud API (note the usage of --id and --cloud options)
midea-beautiful-air-cli set --id APPLIANCE_ID --account ACCOUNT_EMAIL --password PASSWORD --target-humidity 55 --cloud
Get list of all settable attributes:
midea-beautiful-air-cli set --help
Log level is specified using --log option.
Set DEBUG level
midea-beautiful-air-cli --log DEBUG discover --account ACCOUNT_EMAIL --password PASSWORD
Very verbose level (may contain confidential information)
midea-beautiful-air-cli --log NOTSET discover --account ACCOUNT_EMAIL --password PASSWORD
Set WARNING level (default log level if option was not specified)
midea-beautiful-air-cli --log WARNING discover --account ACCOUNT_EMAIL --password PASSWORD
Additional logging is enabled by passing --verbose option. Redacting of sensitive information can be disabled by passing --no-redact option.
Discover appliances on local network:
from midea_beautiful import find_appliances
appliances = find_appliances(
account="USER_EMAIL@example.com", # Account e-mail
password="secret_password", # Account password
)
for appliance in appliances:
print(f"{appliance!r}")
Get appliance state:
from midea_beautiful import appliance_state
appliance = appliance_state(
address=192.0.2.2, # APPLIANCE_IP_ADDRESS
token="TOKEN", # TOKEN obtained from Midea API
key="KEY", # Token KEY obtained from Midea API
)
print(f"{appliance!r}")
Get appliance state from cloud:
from midea_beautiful import appliance_state, connect_to_cloud
cloud = connect_to_cloud(
account="USER_EMAIL@example.com", # Account e-mail
password="secret_password", # Account password
appname="MSmartHome"
)
appliance = appliance_state(
cloud=cloud, # Account e-mail
id=appliance_id, # Appliance id obtained from Midea API
)
print(f"{appliance!r}")
Library is automatically built, packaged and published to PyPI when a Git Hub release is published.
Midea, Inventor, Comfee', Pro Breeze, and other names are trademarks of their respective owners.
FAQs
A library to control Midea appliances via the local network
We found that midea-beautiful-air demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.