msmart-ng

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.

Supported Devices

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 and 0xCC) are supported. See the usage section for how to check compatibility.

Note On Cloud Usage

This library (and its Home Assistant integration midea-ac-py) works locally. No internet connection is required to control your device.

However, for newer "V3" devices, the Midea Cloud is used to acquire a token & key for device authentication. Once retrieved and saved, no further cloud connection is required. Devices are not linked to the library’s built-in accounts and concerned users may supply their own account credentials if they prefer.

Features

Async Support

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

from msmart.device import AirConditioner as AC

# Build device
device = AC(ip=DEVICE_IP, port=6444, device_id=int(DEVICE_ID))

# Get capabilities
await device.get_capabilities()

# Get current state
await device.refresh()

Device Discovery

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

from msmart.discover import Discover

# Discover all devices on the network
devices = await Discover.discover()

# Discover a single device by IP
device = await Discover.discover_single(DEVICE_IP)

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

Reduced Dependencies

Many external dependencies have been replaced with standard Python modules.

Code Quality Improvements

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

Installing

To install, use pip to install msmart-ng, and remove the old msmart package if necessary.

pip uninstall msmart
pip install msmart-ng

Usage

Command Line Interface (CLI)

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

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

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

Discover

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

$ msmart-ng discover
INFO:msmart.cli:Discovering all devices on local 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 the supported property is True.

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

Warning: V3 Device Users

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.

Note: V1 Device Owners

Owners of V1 devices might encounter the following error:

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

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

Query

Query device state and capabilities with the msmart-ng query subcommand.

$ msmart-ng query <HOST>

Add --capabilities to query capabilities of the device before requesting the state.

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

Note: For CC devices, either the --auto argument or the --device_type argument must be specified.

Control

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

Enumerated settings like operational_mode, fan_speed, and swing_mode can accept integer or string values. e.g. operational_mode=cool, fan_speed=100 or swing_mode=both.

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

Boolean settings like display_on and beep can accept integer or string values. e.g. display_on=True or beep=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.

Note: For CC devices, either the --auto argument or the --device_type argument must be specified.

Home Assistant

To control your Midea AC units via Home Assistant, use the mill1000/midea-ac-py integration.

Python

To control devices programmatically, see the included Python example.

Docker

A docker image is available on ghcr.io at ghcr.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 --help
usage: msmart-ng [-h] [-v] {discover,query,control,download} ...

Troubleshooting

• 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.

Ecosystem

These projects are utilizing msmart-ng.

• mill1000/midea-ac-py - Home Assistant Integration
• sidey79/midea-mqtt - MQTT Bridge

Gratitude

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

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