Package: midea-beautiful-air
This is a library that allows communication with Midea air conditioner and dehumidifier via the local area network.midea-beautiful-airThis 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 tobeautifulin English.This library inspired from the repository atmac-zhou/midea-msmartwhich provides similar functionality for air conditioners andbarban-dev/midea_inventor_dehumidifiercloud based functionality for dehumidifiers. This library may include verbatim or adapted portions of the code from those two projects.Thanks also toyitsushi's project,NeoAcheron's project,andersonshatch's project.Supported appliancesThe library works with Midea air conditioners and dehumidifiers supporting V2 and V3 protocol.Some examples of supported dehumidifiers:Comfee MDDF-16DEN7-WF or MDDF-20DEN7-WF (tested with 20L version)Inventor EVA ΙΟΝ Pro Wi-Fi (EP3-WiFi 16L/20L) (tested with 20L version)Inventor Eva II Pro Wi-Fi (EVP-WF16L/20L)Pro Breeze 30L Smart Dehumidifier with Wifi / App ControlMidea SmartDry dehumidifiers (22, 35, 50 pint models )Midea Cube dehumidifiers (20, 35, 50 pint models)It may as well work with other Midea Wi-Fi air conditioners and dehumidifiers.Dehumidifier dataThe following dehumidifier data is accessible through this library:on/off switch (boolean, can be set)current relative humidity (read-only)target relative humidity (can be set)active mode (can be set)fan speed (can be set)(an)ion mode status (boolean, can be set)tank is full (boolean, read-only)appliance name (read-only). Set through Midea mobile application.appliance serial number (read-only)appliance IPv4 address (read-only)token and key for local network access (read-only, only v3 appliances)filter replacement indicator (boolean, read-only, if supported on appliance)pump on/off switch (boolean, can be set, if supported on appliance)sleep mode on/off switch (boolean,  can be set, if supported on appliance)defrosting mode indicator (boolean, read-only, if supported on appliance)internal error code (read-only)appliance characteristics, i.e. support for special modes, fan presets etc (read-only)beep prompt (write-only)tank water level (read-only, if supported by appliance)current ambient temperature (read-only)Air Conditioner DataThe following air conditioner data is accessible through this library:on/off switch (boolean, can be set)target temperature(celsius, can be set)indoor temperature (celsius, read-only)outdoor temperature (celsius, read-only)active mode (can be set)air purifier mode (boolean, can be set)air drying mode (boolean, can be set)prevent freeze mode (boolean, can be set)comfort mode (boolean, can be set)horizontal swing operation (boolean, can be set)vertical swing operation (boolean, can be set)fahrenheit degree display (boolean, can be set)internal error code (read-only)appliance characteristics, i.e. support for special modes, fan presets etc (read-only)beep prompt (write-only)appliance name (read-only). Set through Midea mobile application.appliance serial number (read-only)appliance IPv4 address (read-only)token and key for local network access (read-only, only v3 appliances)DiscoveryThis 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. Seemidea_beautiful/midea.pyfor 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.Network considerationsDiscovery 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. address255.255.255.255, but it is possible to restrict broadcast subnet (e.g. 192.0.2.255)Local protocol supportLibrary supports following protocols:cloud based status reading and writing (no local access needed)v3 local protocol with compatible devices (requires TOKEN/KEY combination)v2 local protocol with compatible devicesLoggingCredentials information like username, password or token keys are redacted by default. When using command line, pass--no-redactoption to show them in the logs. You can use command line tool to display token and key (K1) data.Command Line UsageInstalling packageThe library requires Python 3.8 or later. Current version is tested with Python 3.11.pipinstall--upgrademidea-beautiful-airCommand line tool helpmidea-beautiful-air-cli--help
midea-beautiful-air-clidiscover--help
midea-beautiful-air-cliset--help
midea-beautiful-air-clistatus--helpDiscoveryDiscover appliances on the local network:midea-beautiful-air-clidiscover--accountACCOUNT_EMAIL--passwordPASSWORDShow tokens used to connect to appliances via local networkmidea-beautiful-air-clidiscover--accountACCOUNT_EMAIL--passwordPASSWORD--credentialsSearch for devices by providing explicit network addressmidea-beautiful-air-clidiscover--accountACCOUNT_EMAIL--passwordPASSWORD--address192.0.2.3--credentialsSearch for devices by providing broadcast addressmidea-beautiful-air-clidiscover--accountACCOUNT_EMAIL--passwordPASSWORD--address192.0.2.255--credentialsDiscovery when appliances are registered to a supported app:midea-beautiful-air-cli--verbose---logDEBUGdiscover--accountACCOUNT--passwordPASSWORD--credentials--appMSmartHomeDiscovery when appliances are registered to new API (note that it is easier to use--appoption):midea-beautiful-air-cli--verbose---logDEBUGdiscover--accountACCOUNT--passwordPASSWORD--credentials--appkeyAPPKEY--appidAPPID--hmackeyHMACKEY--iotkeyIOTKEY--apiurlhttps://mp-prod.appsmb.com/mas/v5/app/proxy?alias=--proxiedAppliance statusGet status of an appliance using known TOKEN and KEY (e.g. retrieved usingdiscovercommand)midea-beautiful-air-clistatus--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEYGet status of an appliance using Midea app credentialsmidea-beautiful-air-clistatus--ipAPPLIANCE_IP_ADDRESS--accountACCOUNT_EMAIL--passwordPASSWORDGet status of an appliance through Midea cloud API (note the usage of--idand--cloudoptions)midea-beautiful-air-clistatus--idAPPLIANCE_ID--accountACCOUNT_EMAIL--passwordPASSWORD--cloudSet appliance attributeFollowing are some examples of usage:Set target relative humidity (0-100)midea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--target-humidity55Sets operating mode (number 1 to 4)midea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--mode1Turn on/off ion mode (0 or 1)midea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--ion-mode1Turn appliance on/off mode (0 or 1)midea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--running1Turn on/off pump (0 or 1)midea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--pump1Combinations of multiple settingsmidea-beautiful-air-cliset--ipAPPLIANCE_IP_ADDRESS--tokenTOKEN--keyKEY--fan-speed60--target-humidity50Set target humidity through Midea cloud API (note the usage of--idand--cloudoptions)midea-beautiful-air-cliset--idAPPLIANCE_ID--accountACCOUNT_EMAIL--passwordPASSWORD--target-humidity55--cloudGet list of all settable attributes:midea-beautiful-air-cliset--helpSpecifying log levelLog level is specified using--logoption.SetDEBUGlevelmidea-beautiful-air-cli--logDEBUGdiscover--accountACCOUNT_EMAIL--passwordPASSWORDVery verbose level (may contain confidential information)midea-beautiful-air-cli--logNOTSETdiscover--accountACCOUNT_EMAIL--passwordPASSWORDSetWARNINGlevel (default log level if option was not specified)midea-beautiful-air-cli--logWARNINGdiscover--accountACCOUNT_EMAIL--passwordPASSWORDAdditional logging is enabled by passing--verboseoption. Redacting of sensitive information can be disabled by passing--no-redactoption.Code examplesDiscover appliances on local network:frommidea_beautifulimportfind_appliancesappliances=find_appliances(account="USER_EMAIL@example.com",# Account e-mailpassword="secret_password",# Account password)forapplianceinappliances:print(f"{appliance!r}")Get appliance state:frommidea_beautifulimportappliance_stateappliance=appliance_state(address=192.0.2.2,# APPLIANCE_IP_ADDRESStoken="TOKEN",# TOKEN obtained from Midea APIkey="KEY",# Token KEY obtained from Midea API)print(f"{appliance!r}")Get appliance state from cloud:frommidea_beautifulimportappliance_state,connect_to_cloudcloud=connect_to_cloud(account="USER_EMAIL@example.com",# Account e-mailpassword="secret_password",# Account passwordappname="MSmartHome")appliance=appliance_state(cloud=cloud,# Account e-mailid=appliance_id,# Appliance id obtained from Midea API)print(f"{appliance!r}")Build the libraryLibrary is automatically built, packaged and published toPyPIwhen a Git Hub release is published.Known issuesSome of values are not available on all appliances. Some appliances may acknowledge action which has no effect (e.g. ion mode)Temperature sensor is often under-reporting real ambient temperature. This may be due to sensor proximity to cooling pipes of the humidifier, algorithm or electronics error. The under-reporting depends on the active mode, and stronger modes may result in larger offset from real temperature.See alsohttps://github.com/nbogojevic/homeassistant-midea-dehumidifier-lanNoticeMidea, Inventor, Comfee', Pro Breeze, and other names are trademarks of their respective owners.