Control the Midea PortaSplit locally with Home Assistant and operate it securely

The Midea PortaSplit can be controlled directly on the local network through Home Assistant after setup. To do this, the community integration requires two device-specific credentials from the Midea cloud: a token and a key.

This article walks through selecting, setting up, and securing the integration. The solutions described come from the community and are not officially supported by either Midea or Home Assistant. Firmware or cloud changes can therefore affect their behavior at any time. Background information on the token interface and the ambiguous shutdown warning can be found in the analysis of the Midea cloud APIs.

How local control works

Once set up, the actual control commands are sent directly from Home Assistant to the PortaSplit:

Home Assistant → lokales Netzwerk → Midea PortaSplit

A switching command does not have to pass through an external Midea server, response times are short, an outage of the Midea cloud does not necessarily interrupt already configured local control, and the device can generally still be controlled without Internet access.

On newer devices using the so-called V3 protocol, however, the PortaSplit does not accept unprotected local commands. Home Assistant requires two device-specific values, a token and a key, which are used to authenticate and encrypt the local connection. During initial setup, the integration retrieves them once through a Midea cloud interface and then stores them locally; no cloud connection is required for subsequent control.

In simplified form, the process looks like this:

1. The PortaSplit is connected to MSmartHome.
2. Home Assistant logs in to a Midea cloud service.
3. Home Assistant receives the device ID, token, and key.
4. The token and key are stored locally.
5. Home Assistant controls the PortaSplit directly on the LAN.

Which integration is right

Midea Smart AC

The GitHubmill1000/midea-ac-py repository focuses on Midea air conditioners and related OEM models and supports the 0xAC and 0xCC device types. It offers local control, graphical setup, automatic discovery, manual setup with a token and key, and automatic querying of device capabilities. The PortaSplit’s “Out Silent Mode” is explicitly supported.

As an indication of compatibility, the project lists the Artic King, Midea Air, NetHome Plus, SmartHome or MSmartHome, Toshiba AC NA, and 美的美居 apps, among others. In Europe, the PortaSplit typically uses MSmartHome and thus fits into this ecosystem.

Midea AC LAN

The GitHubwuwentao/midea_ac_lan repository supports not only air conditioners but also many other Midea device categories: dehumidifiers, fans, air purifiers, washing machines, dryers, dishwashers, water heaters, heat pumps, refrigerators, and more, in some cases under third-party brands such as Carrier or Electrolux. It also offers local communication, automatic device discovery, and additional sensors and, according to the project description, keeps a longer TCP connection open to the device in order to synchronize status changes promptly. It requires at least Home Assistant 2024.4.1.

The biggest drawback at present is the developer’s warning: the cloud token APIs used to add new devices are being phased out. This may make it impossible to add new devices later.

Recommendation

For a PortaSplit-only installation, I would start with Midea Smart AC and keep Midea AC LAN in mind as an alternative. Midea Smart AC is more narrowly focused on air conditioners and explicitly documents the current PortaSplit features.

Running both integrations simultaneously and permanently with the same device is not advisable. Multiple parallel connections cause status issues, unnecessary network traffic, and behavior that is difficult to troubleshoot.

What the integration provides

After setup, the PortaSplit appears as a climate entity in Home Assistant. Depending on firmware and integration, the following functions are available, among others:

• Turn on and off
• Set target temperature
• Read the current room temperature
• Cooling, dehumidification, and fan-only operation
• Set fan speed
• Control the swing function
• Eco and Boost modes
• Read humidity
• Display error codes
• Read energy and power values
• Display compressor values
• Activate the outdoor unit’s quiet mode

Which entities actually appear depends on the model, firmware, protocol used, and respective integration. Midea Smart AC queries the capabilities reported by the device and hides functions that the model does not support. Midea AC LAN also documents extensive climate entities, including temperature, humidity, current power, total energy, compressor frequency, pump status, and various operating modes, and lists dedicated methods for decoding energy data for certain PortaSplit subtypes.

Not every displayed measurement has to be correct. Energy consumption and power in particular are transmitted in different formats across different Midea models. If Home Assistant displays obviously incorrect values, the decoding method in use usually needs to be adjusted rather than the device being defective.

Prerequisites

You need a Midea PortaSplit with Wi-Fi capability, a 2.4 GHz Wi-Fi network, the MSmartHome app, a Midea user account, Home Assistant, HACS, and network access between Home Assistant and the PortaSplit. The PortaSplit should first be connected normally through the MSmartHome app, and only then added to Home Assistant.

Step 1: Connect the PortaSplit to MSmartHome

1. Install the MSmartHome app.
2. Create a Midea account or sign in.
3. Put the PortaSplit into Wi-Fi pairing mode.
4. Connect the device to the 2.4 GHz Wi-Fi network.
5. Check whether the PortaSplit can be controlled through the app.

Many IoT devices still support only 2.4 GHz. If the router uses the same SSID for 2.4 and 5 GHz, setup will usually still work. If there are issues, it helps to temporarily provide a separate 2.4 GHz Wi-Fi network.

Step 2: Install HACS

HACS is the Home Assistant Community Store. It can be used to install community integrations that are not part of Home Assistant Core. After installing HACS, open HACS, go to Integrations, search for Midea Smart AC, download the integration, and restart Home Assistant. Alternatively, search for Midea AC LAN.

HACS simplifies installation and updates. However, it does not make a custom integration an officially reviewed Home Assistant component. This distinction is significant from a security perspective and is discussed below.

Step 3: Add Midea Smart AC

After restarting, go to Settings, Devices & Services, and Add Integration, then search for Midea Smart AC and select Discover devices. The integration can either scan the entire local network or query the PortaSplit’s IP address directly.

If the device is found, the integration requires the region, Midea account, password, and device ID for newer V3 devices, along with the resulting token and key. The cloud region must match the account being used. If there are issues, the project recommends trying the other available regions as well.

Manual setup

If automatic setup fails, the device can be configured manually. Midea Smart AC requires the following information:

Device ID
IP-Adresse
Port
Gerätetyp
Token
Key

The documented default port is:

6444/TCP

For V3 devices, the documentation specifies the token as a 128-character hexadecimal string and the key as a 64-character hexadecimal string. Both values are secrets and must be handled accordingly. Anyone who does not want to retrieve credentials through discovery can obtain them using their own account through the msmart-ng CLI.

Operating the PortaSplit securely

Anyone controlling the PortaSplit locally regains part of the control from the manufacturer cloud, but also shifts responsibility to their own network. The following measures help ensure that a token and key cause little damage even in the event of an incident and that the device remains properly isolated.

Tokens and keys are secrets

Tokens and keys authenticate local communication with the device and must be treated like passwords. For operation, the main point is this: they do not belong in logs, unencrypted backups, or a repository.

No port forwarding to the PortaSplit

The most common avoidable mistake would be making the local device port directly reachable from the Internet. A rule like this would be dangerous:

Internet → TCP 6444 → PortaSplit

There is no good reason to make the PortaSplit directly reachable from the Internet. Home Assistant is already on the local network and serves as the controlling instance. The router should have no port forwarding to the PortaSplit, restrict or disable UPnP where possible, block incoming connections by default, and not use a DMZ rule for the device.

Dedicated IoT VLAN

The best network architecture is a separate IoT network:

VLAN 10: vertrauenswürdige Clients
VLAN 20: Server und Home Assistant
VLAN 30: IoT-Geräte
VLAN 40: Gäste

The PortaSplit is located in the IoT VLAN. Home Assistant is allowed to access the device specifically, but the PortaSplit must not be able to access PCs, NAS devices, and other internal systems without restriction. One possible firewall policy:

Home Assistant → PortaSplit: erlauben
PortaSplit → Home Assistant: etablierte Verbindungen erlauben
PortaSplit → interne Clients: blockieren
PortaSplit → NAS: blockieren
PortaSplit → Management-Netz: blockieren
Internet → PortaSplit: blockieren

During initial setup, the device requires Internet access to the Midea cloud. After local setup has succeeded, you can test whether outbound Internet access can be blocked. Do not put a permanent block in place immediately. First, check whether local control continues to work, whether the device remains reachable after a reboot, whether it survives a router reboot, whether it still responds after several days, whether the MSmartHome app is still needed, and whether firmware updates are still offered. If you want to continue using the cloud and firmware updates, you can temporarily allow outbound Internet access and block it again afterward.

Network segmentation can prevent discovery

Automatic device discovery often relies on broadcast or multicast traffic, which is normally not routed across VLAN boundaries. Home Assistant may therefore not find the PortaSplit automatically, even if regular IP connectivity would be allowed.

In that case, it helps to set up the PortaSplit temporarily in the same VLAN as Home Assistant, enter the device IP manually, use a suitable broadcast relay feature, or define targeted firewall rules after setup. Manual configuration is often even the better option from a security perspective because it does not require allowing additional broadcast traffic between networks.

Static DHCP assignment

The PortaSplit should receive a fixed DHCP assignment on the router:

PortaSplit → 192.168.30.25

A DHCP reservation is usually preferable to a static IP set on the device itself. Home Assistant will find the device reliably, firewall rules can be limited to a fixed address, troubleshooting becomes easier, and the assignment remains stable after router or device restarts. This allows a firewall rule to be written very narrowly:

Home-Assistant-IP → 192.168.30.25:6444/TCP

The port actually required must be verified based on the integration and your own device.

Home Assistant as the central trust anchor

Anyone controlling the PortaSplit locally shifts some trust from the Midea cloud to Home Assistant. If Home Assistant is compromised, an attacker may control not only the air conditioner but the entire smart home.

Home Assistant should therefore be updated regularly, not exposed through unprotected port forwarding, protected with a strong, unique password, use multi-factor authentication, create encrypted backups, contain only necessary add-ons, and not allow unnecessary SSH access from the Internet. For remote access, a VPN, Home Assistant Cloud, or a properly configured reverse proxy are better options than simple port forwarding on port 8123.

HACS and supply-chain risk

Midea Smart AC and Midea AC LAN are custom integrations. They run within Home Assistant and therefore have extensive access to its runtime environment. A malicious or compromised integration could theoretically read configuration data, extract secrets, establish network connections, scan devices on the local network, read the states of other entities, transfer data to external systems, and impair Home Assistant availability.

That does not mean the integrations mentioned are malicious. Both projects are publicly visible, actively developed, and have a visible community. However, open source is not an automatic security guarantee. Before installation, it is worth at least checking whether the repository is actively maintained, whether there are regular releases, how many people contribute code, whether open security issues exist, whether maintainers or repository owners have changed recently, whether HACS points to the expected repository, and whether an update contains unusually large or unexplained changes.

Updates should not be installed blindly immediately after release. Especially for security-critical smart-home systems, it makes sense to wait a few days and review release notes and reported issues.

Secure the cloud account

As long as the Midea cloud is used for setup or app control, the Midea account remains part of the security model. It should have a unique password not shared with other services, use a password manager, use multi-factor authentication if offered, remove old smartphones and sessions, avoid shared accounts, and regularly check which devices are registered in the account.

If the Home Assistant integration asks for a username and password during setup, check whether the credentials are used only for one-time token retrieval or stored permanently. The developers of Midea Smart AC state that devices are not linked to built-in integration accounts after setup and that tokens and keys can also be obtained manually using your own account through the CLI. Where possible, your own account is preferable to third-party or integrated shared accounts.

Block the cloud or not?

After successful setup, the question arises whether the PortaSplit’s Internet access should be blocked completely. Arguments in favor of blocking it include less telemetry, less dependence on external services, a smaller attack path through the manufacturer cloud, the fact that the device cannot contact arbitrary external destinations, and less impact from cloud-side changes.

Arguments against it are that the MSmartHome app may no longer work outside the home network, firmware updates may no longer download, time or cloud functions may fail, logging in again or restoring may become more difficult, and some devices may react unexpectedly after being offline for a long time.

A pragmatic sequence: set up the device normally, test Home Assistant and the app, back up the token and configuration, block Internet access, restart the device and Home Assistant, observe for several days, and, if needed, restore Internet access only temporarily.

Firmware updates: security gain or integration risk?

Firmware updates are a dilemma for IoT devices. They can close known vulnerabilities, improve stability, modernize security mechanisms, and add new features. But they can also change local interfaces, break reverse-engineered integrations, invalidate tokens, disable the local API, and introduce new cloud dependencies.

For example, the PortaSplit firmware released in January 2026 introduced a new quiet mode for the outdoor unit that reduces noise by around 6 decibels. The community integrations first had to reverse-engineer and implement it, documented in a dedicated GitHub issue for the PortaSplit.

The result: do not prevent firmware updates categorically; before an update, check whether other Home Assistant users report problems, back up the configuration and token beforehand, create a Home Assistant backup, and fully test local control after the update. Security does not mean “never update.” Outdated firmware can be more dangerous than a temporarily incompatible integration.

Debug logs contain sensitive data

When issues occur, open-source projects often request debug logs. The documentation for Midea AC LAN shows how to enable logging for the two relevant components:

logger:
  default: warn
  logs:
    custom_components.midea_ac_lan: debug
    midealocal: debug

The logs can then be downloaded through Settings, System, and Logs. Depending on the integration and error condition, such logs can contain local IP addresses, device IDs, serial numbers, model identifiers, cloud responses, account information, tokens or portions of them, network packets, as well as timestamps and usage patterns. They must therefore be reviewed and sensitive values redacted before uploading them to a public GitHub issue.

Once troubleshooting is complete, debug logging should be removed again. Permanently enabled debug logging not only increases storage use, it also increases the amount of sensitive information in backups.

What Midea itself says about security

Midea promotes its SmartHome ecosystem as being aligned with several security and privacy standards, including EN 303 645, UK PSTI, NIST, GDPR-compliant data processing, and the requirements of the EU Radio Equipment Directive. These are positive signals, but they do not say how every individual PortaSplit firmware version, cloud endpoint, and local API is actually implemented. Certification and marketing claims do not replace a technical review of the specific device.

Likewise, it would be wrong to conclude from a community integration’s warning that the PortaSplit is generally insecure. The described issue concerns the architecture of long-lived tokens and their use by unofficial clients.

Risk by scenario

Backing up the configuration

Backing up the token, key, and configuration is the most important one-time step: once the cloud token interfaces are closed, a backup is the only path to setting up the device again. Midea AC LAN stores a JSON configuration file for V3 devices after successful setup. The documented path is:

/config/.storage/midea_ac_lan/

The file uses the device ID as its file name:

<device-id>.json

This file is not an ordinary text note. It may contain the device ID, serial number, IP address, token, key, protocol information, and cloud and device parameters. Accordingly:

• Do not upload it to a public GitHub repository.
• Do not post it in forums.
• Do not share it as an unredacted screenshot.
• Do not send it by unencrypted email.

Even a private Git repository is not automatically the right storage location, because secrets remain in Git history even if they are later removed from the current file. Better options include an encrypted backup, a password manager with a file attachment, an encrypted NAS backup, encrypted offline media, or an encrypted archive with the password stored separately.

To back it up through the Home Assistant terminal:

cd /config/.storage/midea_ac_lan
ls -la

Display the file:

cat <device-id>.json

To copy it, do not transfer the file through a public web service. An encrypted archive that is then moved into an encrypted backup is better:

tar -czf /config/midea-ac-lan-backup.tar.gz \
  /config/.storage/midea_ac_lan

The files in .storage should not be edited manually. The developer explicitly recommends neither deleting nor changing the JSON file directly if there are issues, but instead renaming and backing it up before making changes.

A complete Home Assistant backup also includes these files. A separate copy is still advisable because Home Assistant backups can become corrupted, a restore can overwrite the integration, the file may be specifically needed for a later setup, and a backup should never exist only on the same system.

Remove secrets from a published Git repository

If a JSON file was accidentally published on GitHub, normal deletion and a new commit are not enough. The file remains retrievable in Git history. At minimum, these steps are required:

1. Make the repository private immediately, if possible.
2. Remove the file from the entire Git history.
3. Account for GitHub caches and forks.
4. Treat the token as compromised.
5. Remove the device from the Midea account and reconnect it if this generates new keys.
6. Set up the Home Assistant integration again.
7. Change the Midea account password if credentials were also affected.

Whether pairing again actually generates a new token varies by device and cloud architecture. Do not rely on changing the account password to automatically invalidate the local device token.

Useful automations

After successful integration, the PortaSplit can be operated much more intelligently. Adjust the entity IDs to your own installation.

Cool only when windows are closed:

alias: PortaSplit nur bei geschlossenen Fenstern
triggers:
  - trigger: state
    entity_id: binary_sensor.wohnzimmer_fenster
    to: "on"

actions:
  - action: climate.turn_off
    target:
      entity_id: climate.portasplit

Turn on when the room temperature is high:

alias: PortaSplit bei Hitze einschalten
triggers:
  - trigger: numeric_state
    entity_id: sensor.wohnzimmer_temperatur
    above: 27

conditions:
  - condition: state
    entity_id: binary_sensor.wohnzimmer_fenster
    state: "off"
  - condition: state
    entity_id: person.rafael
    state: "home"

actions:
  - action: climate.set_hvac_mode
    target:
      entity_id: climate.portasplit
    data:
      hvac_mode: cool

  - action: climate.set_temperature
    target:
      entity_id: climate.portasplit
    data:
      temperature: 24

Pre-cool before going to bed:

alias: Schlafzimmer vorkühlen
triggers:
  - trigger: time
    at: "21:00:00"

conditions:
  - condition: numeric_state
    entity_id: sensor.schlafzimmer_temperatur
    above: 25

actions:
  - action: climate.set_temperature
    target:
      entity_id: climate.portasplit
    data:
      temperature: 23

Turn off when nobody is home:

alias: PortaSplit bei Abwesenheit ausschalten
triggers:
  - trigger: state
    entity_id: zone.home
    to: "0"
    for:
      minutes: 10

actions:
  - action: climate.turn_off
    target:
      entity_id: climate.portasplit

Recommended configuration at a glance

1. PortaSplit mit MSmartHome einrichten
2. Midea Smart AC über HACS installieren
3. PortaSplit automatisch oder manuell hinzufügen
4. DHCP-Reservation erstellen
5. Home-Assistant-Backup anfertigen
6. Token- und Konfigurationsdaten verschlüsselt sichern
7. PortaSplit in ein separates IoT-VLAN verschieben
8. Zugriff von Home Assistant zur PortaSplit erlauben
9. Zugriff der PortaSplit auf interne Netze blockieren
10. Internetzugriff testweise blockieren
11. lokale Steuerung nach Neustarts prüfen
12. Firmware- und Integrationsupdates kontrolliert durchführen

The desired communication direction is therefore as follows:

Home Assistant
    │
    │ gezielt erlaubt
    ▼
Midea PortaSplit
    │
    ├── kein Zugriff auf PCs
    ├── kein Zugriff auf NAS
    ├── kein Zugriff auf Management-Netz
    └── Internet nur bei Bedarf

Recommended operating state

The Midea PortaSplit integrates well with Home Assistant. After successful setup, it can be controlled locally and incorporated into automations, eliminating a large part of the cloud dependency for day-to-day operation.

From a security perspective, the integration is reasonable if a few basic rules are followed: no port forwarding, keep tokens and keys secret, encrypt backups, review debug logs before publishing, secure Home Assistant, segment IoT devices, limit outbound Internet access to what is necessary, and do not install firmware or HACS updates blindly. Used this way, the PortaSplit remains a capable air conditioner while also becoming a sensibly integrated part of a locally controlled smart home.