Skip to content

Providing a Lua File

Jump to bottom
Simone Chemelli edited this page Aug 21, 2026 · 2 revisions

Midea devices use Lua files to describe parts of their device protocol and capabilities. These files can be useful when debugging a device, investigating unsupported features, or contributing new device implementations to midea-local.

There are two ways to obtain the Lua file:

  • Using the command-line interface (CLI)
  • Providing the device details, including its serial number (S/N)

Download via CLI

The easiest way to download the Lua file from a Midea device is using the midea-local command-line interface. Alongside the Lua script, the CLI also downloads a companion plugin file for the same device.

Prerequisites

Make sure midea-local is installed:

pip install midea-local

You will also need one of the following to identify the device:

  • Its IP address, with the device powered on and reachable on your local network, or
  • Its Serial Number (S/N) — get this from the Midea app, or via python3 -m midealocal.cli discover --host <ip> --get_sn

Downloading also requires logging into a Midea cloud account (see Cloud account below).

Download the Lua file

Run:

python3 -m midealocal.cli download -h

Option A — by IP address:

python3 -m midealocal.cli download --host 192.168.1.100

This auto-discovers the device and reads its type, S/N, and model directly from the network.

Option B — by Serial Number (works even if the device isn't reachable right now):

python3 -m midealocal.cli download --device-sn <32-character-SN>

If the S/N is the standard 32-character hex format, the device type is parsed automatically from it. If your S/N doesn't follow that format, or auto-detection fails, supply the type explicitly as a hex string (no 0x prefix):

python3 -m midealocal.cli download --device-sn <SN> --device-type ac

Cloud account

Downloading requires logging into a Midea cloud account. You have three options, in order of convenience:

  1. Do nothing. If you pass no credentials, the tool falls back to a built-in preset test account on the default cloud (NetHome Plus). This works for many devices but may not cover every model.
  2. Pass credentials inline: 
    python3 -m midealocal.cli download --host 192.168.1.100 \
  --username you@example.com --password yourpassword --cloud-name "美的美居"
    Supported values for --cloud-name (-cn): 美的美居, SmartHome, Midea Air, NetHome Plus, Ariston Clima — use whichever app you registered the device with.
  3. Save credentials once, reuse automatically: 
    python3 -m midealocal.cli save --username you@example.com --password yourpassword --cloud-name "美的美居"
    This writes midea-local.json (in the current directory by default, or your OS user-config folder if you add --user). On future runs the CLI loads this file automatically, so you can drop the --username/--password/--cloud-name flags entirely.

Output

On success you'll see two log lines with the exact paths written, e.g.:

Downloaded lua file: ./<filename>.lua
Downloaded plugin file: ./<filename>

The file names come directly from Midea's cloud response (they're not fixed by the tool), so check the log output rather than assuming a naming pattern.

Add -d / --debug to any command for verbose logging, which is useful for troubleshooting a failed login or discovery.

Note: The exact command-line syntax may depend on the installed midea-local version. Run python3 -m midealocal.cli -h to see the commands and options available in your version.

Provide the Device Details

If you cannot download the Lua file yourself, you can provide the device details instead. The developers can use this information to retrieve the Lua file from the Midea service.

Please provide all available device information, especially:

  • Device model
  • Device type
  • Device ID
  • Serial number (S/N)
  • Midea cloud/server region
  • Firmware version
  • Any other information shown by the Midea app

The serial number (S/N) is particularly important, as it can be used to uniquely identify the device and retrieve the corresponding Lua definition.

Where to find the device details

The exact location depends on the device and the version of the Midea app. Typically, the information can be found in the device's Settings, Device Information, or About section.

When opening an issue, please provide the device information in a format similar to:

Model: XXXXX
Device type: XXXXX
Device ID: XXXXX
S/N: XXXXX
Firmware: XXXXX
Region: XXXXX

When reporting an unsupported device

If you are reporting an unsupported device or feature, please attach the Lua file if you were able to download it.

If you cannot download it, provide the complete device details above, including the S/N. This gives developers the information needed to investigate the device and obtain its Lua definition.

Clone this wiki locally