Repository files navigation

A Python library for local control of Midea (and associated brands) smart air conditioners. Designed for ease of integration, with async support and minimal dependencies.

This library supports air conditioners from Midea and several associated brands that use the following Android apps or their iOS equivalents:

• Artic King (com.arcticking.ac)
• Midea Air (com.midea.aircondition.obm)
• NetHome Plus (com.midea.aircondition)
• SmartHome/MSmartHome (com.midea.ai.overseas)
• Toshiba AC NA (com.midea.toshiba)
• 美的美居 (com.midea.ai.appliances)

Note: Only air conditioners (type 0xAC) are supported. See theusage section for how to check compatibility.

The library fully supports async/await, allowing non-blocking communication with devices.

frommsmart.deviceimportAirConditionerasAC# Build devicedevice=AC(ip=DEVICE_IP,port=6444,device_id=int(DEVICE_ID))# Get capabilitiesawaitdevice.get_capabilities()# Get current stateawaitdevice.refresh()

Automatically discover devices on the local network or an individual device by IP or hostname.

frommsmart.discoverimportDiscover# Discover all devices on the networkdevices=awaitDiscover.discover()# Discover a single device by IPdevice=awaitDiscover.discover_single(DEVICE_IP)

Note: V3 devices are automatically authenticated via the NetHome Plus cloud.

Many external dependencies have been replaced with standard Python modules.

• Type annotated for clarity.
• Code style and import sorting enforced by autopep8 and isort.
• Unit tests validated by Github Actions.
• Naming conventions follow PEP8.

To install, use pip to installmsmart-ng, and remove the oldmsmart package if necessary.

pip uninstall msmartpip install msmart-ng

Interact with devices using a simple command-line tool that supports device discovery, querying, and control.

$ msmart-ng --helpusage: msmart-ng [-h] [-v] {discover,query,control,download} ...

For more details on each subcommand and its available options, runmsmart-ng <command> --help

Discover devices on the local network with themsmart-ng discover subcommand.

$ msmart-ng discoverINFO:msmart.cli:Discovering all devices onlocal network....INFO:msmart.cli:Found 1 devices.INFO:msmart.cli:Found device:{'ip':'10.100.1.140','port': 6444,'id': 15393162840672,'online': True,'supported': True,'type':<DeviceType.AIR_CONDITIONER:172>,'name':'net_ac_F7B4','sn':'000000P0000000Q1F0C9D153F7B40000','key': None,'token': None}

Ensure the device type is 0xAC and thesupported property is True.

Save the device ID, IP address, and port. Version 3 devices will also require thetoken andkey fields to control the device.

For V3 devices, it's highly recommended to save your token and key values in a secure place. In the event that the cloud become unavailable, having these on hand will allow you to continue controlling your device locally.

Owners of V1 devices might encounter the following error:

ERROR:msmart.discover:V1 device not supported yet.

Please report this error with the output ofmsmart-ng discover --debug to help improve support.

Query device state and capabilities with themsmart-ng query subcommand.

$ msmart-ng query<HOST>

Add--capabilities to list available capabilities of the device.

Note: Version 3 devices need to specify either the--auto argument or the--token,--key and--id arguments to make a connection.

Control a device with themsmart-ng control subcommand. The command takes key-value pairs of settings to control.

Enumerated settings likeoperational_mode,fan_speed, andswing_mode can accept integer or string values. e.g.operational_mode=cool,fan_speed=100 orswing_mode=both.

Number settings liketarget_temperature can accept floating point or integer values. e.g.target_temperature=20.5.

Boolean settings likedisplay_on andbeep can accept integer or string values. e.g.display_on=True orbeep=0.

$ msmart-ng control<HOST> operational_mode=cool target_temperature=20.5 fan_speed=100 display_on=True beep=0

Note: Version 3 devices need to specify either the--auto argument or the--token,--key and--id arguments to make a connection.

To control your Midea AC units via Home Assistant, use thismidea-ac-py fork.

To control devices programmatically, see the included Pythonexample.

A docker image is available on ghcr.io atghcr.io/mill1000/msmart-ng. Ensure the container is run with--network=host to allow device discovery on the local network via broadcast.

$ docker run --network=host ghcr.io/mill1000/msmart-ng:latest --helpusage: msmart-ng [-h] [-v] {discover,query,control,download} ...

• If devices are not being discovered, ensure your devices are on the same subnet as your computer.
• If a cloud connection can not be made, try using a credentials from a different region with the--region argument or manually specifying a NetHome Plus account.

This project is a fork ofmac-zhou/midea-msmart, and builds upon the work of

• dudanov/MideaUART
• NeoAcheron/midea-ac-py
• andersonshatch/midea-ac-py
• yitsushi/midea-air-condition