Create a new device within ESPHome builder and combine the yaml with one of the examples from the examples directory. Give your unit a name, configure OTA passwords, hotspot, add an API key and install!
simple.yaml: Basic yaml to get started, contains climate and fan direction control.external_sensor.yaml: Contains the basics to configure the room temperature using an external temperature sensor connected to Home Assistant.full.yaml: Contains all (20+!) of the metrics that are possibly in the unit and returns them.simple-energy-management.yaml: Contains the basics to get started with energy measuring (assuming a voltage of 230v to convert A to Wh).
This project is a simple integration of the amazing work absalom-muc has done with his project MHI-AC-Ctrl.
It's supposed to simplify the Home Assistant setup, while giving you OTA and auto-discovery with virtually zero effort and no MQTT needed, powered by ESPHome.
MHI-AC-Ctrl-core.* files were forked directly, with no modification, whereas your WiFi credentials should go into the *.yaml file, and mhi_ac_ctrl.h is the core of the integration.
Most newer MHI units (the ones supporting the WF-RAC WiFi module) support fine grained vane control for Left/Right and Up/Down.
When your log is flooded with mhi_ac_ctrl_core.loop error: -2 errors after updating to the newer code, please change your yaml file to set frame_size: 20.
Currently the MHI code allows for more fine grained fan direction than ESPHome climate supports. for that, additional template parts are added.
There are 8 modes for Left/Right: Left, Left/Center, Center, Center/Right, Right, Wide, Spot and Swing
There are 5 modes for Up/Down: Up, Up/Center, Center/Down, Down and Swing
Setting swing from the ESPHome climate now fully works. It will store the oldvanes mode, and configure swing. After disabling swing (either vertically, horizontally or off), the old settings will be restored. Manually changing modes for Left/Right or Up/Down will update the climate state as well.
Climate Quiet was added to ESPhome, so QUIET was added. Ordering still needs work (ginkage#22 (comment)) Added the solution for the auto mode from: ginkage#22 (comment): CLIMATE_FAN_DIFFUSE in fan speed and status sections and reshuffle the numbers and add CLIMATE_FAN_DIFFUSE to the traits.set_supported_fan_modes
Has now 5 different fan modes but I'm not sure if the auto mode works proper, keep testing.
To allow for lower temperature heating or cooling, set the visual_min_temperature in the climate section of the yaml like so:
climate:
- platform: MhiAcCtrl
name: "MHI Air Conditioner"
temperature_offset: true
visual_min_temperature: 17.0 This will allow for lower temperature heating or cooling.
======= v4.2 (2025-07)
- Allow configuration of pins through yaml
v4.1 (2025-07)
- Changed climate.CLIMATE_SCHEMA to fix deprecation warning in 2025.5.0 and higher ginkage#151
- Make 0.5 degrees setpoint actually work ginkage#88
- Allow low temp heating and cooling (below 18 degrees) ginkage#152
- Allow fan speed from esphome web interface ginkage#136
- Deprecating set set_vertical_vanes and set_horizontal_vanes, will be removed in v4.3 use select functions for fan control
v4.0 (2025-04)
- Compatibility with ESPHOME 2025.2+
- Breaking change: the implementation is ported to the native ESPHome codegen
- The configuration file is significantly simplified
- No need for custom code in the config file
- Sensors are no longer positional
- External sensor support
v3.0 (2024-08)
- Breaking change: moved all files to component and allow for easy install, thanks to @XMaarten and https://github.com/hberntsen/mhi-ac-ctrl-esp32-c3
- When you are upgrading from v2.1 or older, and experience compile errors, please see ginkage#100 (comment) for manual cleanup steps
- Manually downloading the files to your Home Assistant setup is no longer needed
- Legacy or Large framesize files are merged again
v2.1 (2024-03)
- Breaking change: Cleaned up conf files
- Add restart button
- Update Home Assistant naming convention
- Enable energy dashboard usage
v2.0 (2024-01)
- Based on absalom-muc v2.8 (September 2023)
- Breaking change in YAML configuration (need to set frame_size in globals)
- Added legacy support configurable from YAML (removing 3d auto and vanes LR control)
Step 1: Learn Dutch to understand the blogpost (or use some translation service :) Step 2: Go to this extensive blogpost: https://www.twoenter.nl/blog/smarthome/mitsubishi-airco-voorzien-van-wifi-besturing/
[W][component:237]: Component MhiAcCtrl took a long time for an operation (52 ms).
[W][component:238]: Components should block for at most 30 ms.
This is because ESPHome now alerts for slow components. To ignore this warning you can configure logging for components to ERROR, this will suppress the WARNING. See ginkage#61 for more information.
# Enable logging
logger:
level: INFO
baud_rate: 0
logs:
component: ERRORYou probably have an older version of the Airco unit which doesn't support the newer, larger framesize.
You can to change the frame_size in the yaml to 20 to disable newer functionality.
When framsize is set to 20, 3D auto, and vane Left / Right doesn't work, vane Up / Down works limited.
All other features should work fine.
As time progresses, ESPHome and this project evolved, allowing for more features and easier installation and updates in the future. When you are on an older versione (whether that is v3.0, v2.0 or earlier) the best way forward is to get one of the example yaml files from the examples folder and apply this to your current yaml file.
- Make a copy of your current yaml file, and save it somewhere outside of Home Assistant.
- Did you not skip step 1?
- Choose one of the example yaml files from the examples dir
- Carefully copy the basic information from the backup file into the example file. Take things like name, ota password, wifi credentials, ap fallback settings, api settings and key, and frame_size
- Double check your new yaml and paste it in ESPHome builder and deploy
- If you replaced all information carefully, all should build fine. If not, read the message and see what parts are missing or duplicate (most frequently done wrong)
This project is licensed under the MIT License - see the LICENSE file for details.
(TL;DR: Do whatever you want with the code, no warranty given, give credit where it's due.)