MitsubishiCN105ESPHome

Mitsubishi CN105 ESPHome

This project is a firmware for ESP32 microcontrollers supporting UART communication via the CN105 Mitsubishi connector. Its purpose is to enable complete control of a compatible Mitsubishi heat pump through Home Assistant, a web interface, or any MQTT client.

It uses the ESPHome framework and is compatible with the Arduino framework and ESP-IDF.

This component version is an adaptation of geoffdavis's esphome-mitsubishiheatpump. Its purpose is to integrate the Mitsubishi heat pump protocol (enabled by the SwiCago library) directly into the ESPHome component classes for a more seamless integration.

The intended use case is for owners of a Mitsubishi Electric heat pump or air conditioner that includes a CN105 communication port to directly control their air handler or indoor unit using local communication through a web browser, or most commonly, the HomeAssistant home automation platform. Installation requires a WiFi capable ESP32 or ESP8266 device, a bidirectional logic level shifter, and a 5-pin plug to connect to the heat pump indoor unit. ESPHome is used to load the custom firmware onto the device, and the web browser or HomeAssistant software is used to send temperature setpoints, external temperature references, and settings to the heat pump. Installation requires basic soldering skills, and basic skills in flashing a firmware to a microcontroller (though ESPHome makes this as painless as possible).

The benefits include fully local control over your heat pump system, without reliance on a vendor network. Additional visibility, finer control, and even improved energy efficiency and comfort are possible when utilizing the remote temperature features.

[!CAUTION] Use at your own risk. This is an unofficial implementation of the reverse-engineered Mitsubishi protocol based on the Swicago library. The authors and contributors have extensively tested this firmware across several similar implementations and forks. However, it's important to note that not all units support every feature. While free to use, it is at your own risk. If you are seeking an officially supported method to remotely control your Mitsubishi device via WiFi, a commercial solution is available here.

New Features

• Support Fahrenheit users better by mapping unit conversions to Mitsubishi's "creative" math, ensuring that HomeAssistant and external thermostats stay in sync. Thanks @ams2990 and @dsstewa!
• Support the MSZ-A24NA setpoint table using a unique bytecode-to-Celsius mapping. Enable with msz_a24na_setpoint_table: true. Thanks @GraphicHealer!
• Additional components for supported units: vane orientation (fully supporting the Swicago map), compressor frequency for energy monitoring, and i-see sensor.
• Additional diagnostic sensors for understanding the behavior of the indoor units while in AUTO mode.
• Additional sensors for power usage and outdoor temperature (not supported by all units).
• Code is divided into distinct concerns for better readability.
• Extensive logging for easier troubleshooting and development.
• Ongoing refactoring to further improve the code quality.
• Enhanced UART communication with the Heatpump to eliminate delays in the ESPHome loop(), which was a limitation of the original SwiCago library.
• Byte-by-byte reading within the loop() function ensures no data loss or lag, as the component continuously reads without blocking ESPHome.
• UART writes are followed by non-blocking reads. The responses are accumulated byte-by-byte in the loop() method and processed when complete, allowing command stacking without delays for a more responsive UI.

Retained Features

This project maintains all functionalities of the original geoffdavis project, including:

• Wireless Mitsubishi Comfort HVAC equipment control via ESP8266 or ESP32, using the ESPHome framework.
• Instant feedback of command changes via RF Remote to HomeAssistant or MQTT.
• Direct control independent of the remote.
• A slightly modified version of the SwiCago/HeatPump Arduino library for direct communication via the internal CN105 connector.
• Full mode and vane orientation support (added as an extra component within the Core Climate Component).
• Thermostat in HomeAssistant with compressor frequency monitoring (an extra component within the Core Climate Component).

Requirements

• ESPHome — 2025.7 or later. ESPHome 2025.11+ is recommended (native ClimateTraits feature flags and FixedVector select options). 2025.7–2025.10 remain buildable via compile-time API shims (see issue #733). Install independently or as a Home Assistant add-on.

Supported Microcontrollers

[!IMPORTANT] ESP8266 boards such as the WeMos D1 Mini clones (LOLIN in particular) tend to be unreliable in this application, and may require an external voltage regulator to work. While some users have successfully used ESP8266 based devices, if you are purchasing new hardware for use with this project, it is recommended to focus on the more modern and powerful ESP32-S3 based devices.

• Generic ESP32 Dev Kit (ESP32): tested
• M5Stack ATOM Lite : tested
• M5Stack ATOM S3 Lite: tested w/ modifications
• M5Stack NanoC6: tested over both wifi and thread
• M5Stack StampS3
• Seeed Studios Xiao ESP32S3: tested
• WeMos D1 Mini Pro (ESP8266): tested (but not currently recommended, see above)

Supported Mitsubishi Climate Units

Generally, indoor units with a CN105 header are compatible. Refer to the HeatPump wiki for a comprehensive list. Additionally, Mitsubishi units listed as compatible with the Mitsubishi PAC-USWHS002-WF-2 Kumo Cloud interface will likely be compatible with this project, as they use the same CN105 connector and serial protocol.

Units tested by project contributors include:

• MFZ-KA09NA
• MLZ-KP12NA
• MSXY-FN10VE (https://github.com/echavet/MitsubishiCN105ESPHome/discussions/368)
• 'MSXY-FN10VE R2', 'MSXY-FN13VE R2','MSXY-FN24VE R2'
• MSZ-AP20VGK, MSZ-AP25VGK, MSZ-AP35VGK, MSZ-AP42VGK, MSZ-AP50VGK
• MSZ-AP35VGD2 (https://github.com/echavet/MitsubishiCN105ESPHome/discussions/254)
• MSZ-AY series (e.g. MSZ-AY20, MSZ-AY25, MSZ-AY35, MSZ-AY42, MSZ-AY50)
• MSZ-EF series (e.g. MSZ-EF09NA, MSZ-EF15NA, MSZ-EF42VE, MSZ-EF50VE)
• MSZ-FHxxNA
• MSZ-FSxxNA
• MSZ-FT50VG2
• MSZ-GE24NA
• MSZ-GL series (e.g. MSZ-GL06NA, MSZ-GL09NA, MSZ-GL12NA, MSZ-GL15NA, MSZ-GL18NA, MSZ-GL24NA)
• MSZ-GS12NA
• MSZ-HR series (e.g. MSZ-HR25VF, MSZ-HR35VF, MSZ-HR45VF, MSZ-HR50VF)
• MSZ-LN35VGW
• MSZ-SF35VE3, MSZ-SF50VE3
• PEFY-P32VMA-E2
• SEZ-KD25VAQ
• SEZ-M50DAL
• MSZ-A24NA (See msz_a24na_setpoint_table and fahrenheit_compatibility)

Usage

Step 1: Building the Control Circuit

The CN105 port is a 5V TTL UART (2400 baud). ESP32 (and ESP8266) GPIO pins are 3.3V. The proper way to hook them up is a bidirectional logic level shifter on the TX and RX lines. Do not wire the heat pump UART directly to the ESP32 GPIO pins because the ESP32 GPIO pins are not 5V tolerant.

The indoor unit also supplies 5V on CN105. The ESP32 can be powered from that 5V rail via the board's 5V pin, so a separate USB supply is not required once the device is installed.

Circuit diagram

The diagram below shows a Seeed Studio XIAO ESP32-C6 with a 4-channel bidirectional level shifter. The same wiring applies to other ESP32 boards: use that board's 5V, GND, 3V3, UART TX, and UART RX pins (and match tx_pin / rx_pin in your ESPHome YAML).

Wiring

TX and RX must be crossed: ESP32 TX → heat pump RX, ESP32 RX ← heat pump TX. Unused shifter channels (HV3/LV3, HV4/LV4) can be left open.

CN105 pinout

The indoor-unit connector is a JST PA 5-pin header (housing PAP-05V-S). Pin 1 is typically nearest the board silkscreen 1 / the keyed edge of the housing.

[!NOTE] Some indoor units provide only limited current on the CN105 5V pin. Compact boards such as the XIAO series typically draw little enough to run from that rail. If the ESP32 brownouts, resets, or Wi-Fi is unstable, power it from the CN105 12V pin through a 5V regulator instead, and keep 12V off the ESP32 5V pin and GPIO.

Connector part numbers and pre-crimped pigtails are listed in the SwiCago/HeatPump README.

Step 2: Using ESPHome

Add a new device in your ESPHome dashboard. Create a yaml configuration file for the new device using the templates below, and flash to your device. Refer to the ESPHome documentation for guides on how to install ESPHome, add new devices, and flash the initial firmware.

• Getting Started with ESPHome and HomeAssistant
• Installing ESPHome Locally

[!NOTE] This code uses the ESPHome external components integration feature. This means the project is not part of the ESPHome framework, it is an external component not managed by the core ESPHome project.

Step 3: Configure the board and UART settings

Your ESPHome device configuration file starts with common defaults for ESPHome. To these defaults, add these minimum sections:

For ESP32-based Devices

esp32:
  board: esp32doit-devkit-v1 #or esp32-s3-devkitc-1
  framework:
    type: esp-idf

uart:
  id: HP_UART
  baud_rate: 2400
  tx_pin: GPIO17
  rx_pin: GPIO16

For ESP8266-based Devices

esp8266:
  board: d1_mini

uart:
  id: HP_UART
  baud_rate: 2400
  tx_pin: 1
  rx_pin: 3

[!IMPORTANT] Logger UART vs CN105 UART. ESPHome's logger: uses UART0 by default. If CN105 is wired to the same pins (typical ESP8266 GPIO1/GPIO3, and several ESP32 boards such as the M5Stack ATOM Lite), serial logs collide with heat-pump traffic and the unit looks “wired correctly but dead”. Move the logger off UART0:

yaml复制

logger:
  hardware_uart: UART1  # ESP8266 *and* ESP32 when UART0 is used by CN105
  level: INFO

On ESP32-S3 boards that log over USB, `hard