ESPHome Climate Component for Mitsubishi Heatpumps using direct serial connection
Wirelessly control your Mitsubishi Comfort HVAC equipment with an ESP8266 or ESP32 using the ESPHome framework.
CN105
connector.This library should work on most ESP8266 or ESP32 platforms. It has been tested with the following MCUs:
The underlying HeatPump library works with a number of Mitsubishi HVAC
units. Basically, if the unit has a CN105
header on the main board, it should
work with this library. The HeatPump
wiki has a more
exhaustive list.
The same CN105
connector is used by the Mitsubishi KumoCloud remotes, which
have a
compatibility list
available.
The whole integration with this libary and the underlying HeatPump has been tested by the author on the following units:
MSZ-GL06NA
MFZ-KA09NA
Build a control circuit with your MCU as detailed in the SwiCago/HeatPump README. You can use either an ESP8266 or an ESP32 for this.
Note: several users have reported that they've been able to get away with not using the pull-up resistors, and just directly connecting a Wemos D1 mini to the control board via CN105.
The code in this repository makes use of a number of features in the 1.18.0 version of ESPHome, including various Fan modes and external components.
Add this repository to your ESPHome config:
external_components:
- source: github://geoffdavis/esphome-mitsubishiheatpump
Version 2.0 and greater of this libary use the ESPHome external_components
feature, which is a huge step forward in terms of usability. In order to make
things compile correctly, you will need to:
libraries
section that imports
https://github.com/SwiCago/HeatPump
, as this is handled by the
external_component
section of manifest.includes
section that imports src/esphome-mitsubishiheatpump
src/esphome-mitsubishiheatpump
.config/.esphome/build
. Testing with ESPHome 0.18.x showed this
to be necessary to get the cached copy of src/esphome-mitsubishiheatpump to
go away entirely, as the "Clean Build Files" isn't as thorough as one would like.Note: Failure to delete the old source directory and remove the includes
and libraries
lines will likely result in compilation errors complaining
about duplicate declarations of MitsubishiHeatPump::traits()
.
Linking /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/firmware.elf
/root/.platformio/packages/toolchain-xtensa/bin/../lib/gcc/xtensa-lx106-elf/4.8.2/../../../../xtensa-lx106-elf/bin/ld: /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/src/esphome/components/mitsubishi_heatpump/espmhp.cpp.o: in function `MitsubishiHeatPump::traits()':
espmhp.cpp:(.text._ZN18MitsubishiHeatPump6traitsEv+0x4): multiple definition of `MitsubishiHeatPump::traits()'; /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/src/esphome-mitsubishiheatpump/espmhp.cpp.o:espmhp.cpp:(.text._ZN18MitsubishiHeatPump6traitsEv+0x80): first defined here
Add a mitsubishi_heatpump
to your ESPHome config:
climate:
- platform: mitsubishi_heatpump
name: "My Heat Pump"
# Optional
hardware_uart: UART0
# Optional
update_interval: 500ms
On ESP8266 you'll need to disable logging to serial because it conflicts with the heatpump UART:
logger:
baud_rate: 0
On ESP32 you can change hardware_uart
to UART1
or UART2
and keep logging
enabled on the main serial port.
Note: this component DOES NOT use the ESPHome uart
component, as it
requires direct access to a hardware UART via the Arduino HardwareSerial
class. The Mitsubishi Heatpump units use an atypical serial port setting ("even
parity"). Parity bit support is not implemented in any of the existing
software serial libraries, including the one in ESPHome. There's currently no
way to guarantee access to a hardware UART nor retrieve the HardwareSerial
handle from the uart
component within the ESPHome framework.
Below is an example configuration which will include wireless strength
indicators and permit over the air updates. You'll need to create a
secrets.yaml
file inside of your esphome
directory with entries for the
various items prefixed with !secret
.
substitutions:
name: hptest
friendly_name: Test Heatpump
esphome:
name: ${name}
platform: ESP8266
board: esp01_1m
# Boards tested: ESP-01S (ESP8266), Wemos D1 Mini (ESP8266); ESP32 Wifi-DevKit2
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Enable fallback hotspot (captive portal) in case wifi connection fails
ap:
ssid: "${friendly_name} Fallback Hotspot"
password: !secret fallback_password
# Note: if upgrading from 1.x releases of esphome-mitsubishiheatpump, be sure
# to remove any old entries from the `libraries` and `includes` section.
#libraries:
# Remove reference to SwiCago/HeatPump
#includes:
# Remove reference to src/esphome-mitsubishiheatpump
captive_portal:
# Enable logging
logger:
# ESP8266 only - disable serial port logging, as the HeatPump component
# needs the sole hardware UART on the ESP8266
baud_rate: 0
# Enable Home Assistant API
api:
ota:
# Enable Web server.
web_server:
port: 80
# Sync time with Home Assistant.
time:
- platform: homeassistant
id: homeassistant_time
# Text sensors with general information.
text_sensor:
# Expose ESPHome version as sensor.
- platform: version
name: ${name} ESPHome Version
# Expose WiFi information as sensors.
- platform: wifi_info
ip_address:
name: ${name} IP
ssid:
name: ${name} SSID
bssid:
name: ${name} BSSID
# Sensors with general information.
sensor:
# Uptime sensor.
- platform: uptime
name: ${name} Uptime
# WiFi Signal sensor.
- platform: wifi_signal
name: ${name} WiFi Signal
update_interval: 60s
external_components:
- source: github://geoffdavis/esphome-mitsubishiheatpump
climate:
- platform: mitsubishi_heatpump
name: "${friendly_name}"
# ESP32 only - change UART0 to UART1 or UART2 and remove the
# logging:baud_rate above to allow the built-in UART0 to function for
# logging.
hardware_uart: UART0
Some models of heat pump require different baud rates or don't support all possible modes of operation. You can configure mulitple climate "traits" in YAML to match what your hardware supports. For example:
climate:
- platform: mitsubishi_heatpump
name: "My heat pump"
hardware_uart: UART2
baud_rate: 9600
supports:
mode: [HEAT_COOL, COOL, HEAT, FAN_ONLY]
fan_mode: [AUTO, LOW, MEDIUM, HIGH]
swing_mode: [OFF, VERTICAL]
visual:
min_temperature: 16
max_temperature: 31
temperature_step: 1.0
UART0
is usable. On ESP32,
UART0
, UART1
, and UART2
are all valid choices. Default: UART0
4800
baud, but some use
9600
. Default: 4800
['HEAT_COOL', 'COOL', 'HEAT', 'DRY', 'FAN_ONLY']
** fan_mode (Optional, list):
Supported fan speeds for the HeatPump. Default: ['AUTO', 'DIFFUSE', 'LOW', 'MEDIUM', 'MIDDLE', 'HIGH']
** swing_mode (Optional, list): Supported
fan swing modes. Most Mitsubishi units only support the default. Default:
['OFF', 'VERTICAL']
Climate
component has several visual
options that can be set. See the Climate
Component documentation for
details.It is possible to use an external temperature sensor to tell the heat pump what
the room temperature is, rather than relying on its internal temperature
sensor. You can do this by calling set_remote_temperature(float temp)
on the
mitsubishi_heatpump
object in a lambda. Note that you can call
set_remote_temperature(0)
to switch back to the internal temperature sensor.
There are several ways you could make use of this functionality. One is to use a sensor automation:
climate:
- platform: mitsubishi_heatpump
name: "Lounge heat pump"
id: hp
sensor:
# You could use a Bluetooth temperature sensor
- platform: atc_mithermometer
mac_address: "XX:XX:XX:XX:XX:XX"
temperature:
name: "Lounge temperature"
on_value:
then:
- lambda: 'id(hp).set_remote_temperature(x);'
# Or you could use a HomeAssistant sensor
- platform: homeassistant
name: "Temperature Sensor From Home Assistant"
entity_id: sensor.temperature_sensor
on_value:
then:
- lambda: 'id(hp).set_remote_temperature(x);'
Alternatively you could define a service that HomeAssistant can call:
api:
services:
- service: set_remote_temperature
variables:
temperature: float
then:
- lambda: 'id(hp).set_remote_temperature(temperature);'
- service: use_internal_temperature
then:
- lambda: 'id(hp).set_remote_temperature(0);'
The gysmo38/mitsubishi2MQTT
Arduino sketch also uses the SwiCago/HeatPump
library, and works with MQTT directly. The author of this implementation found
mitsubishi2MQTT
's WiFi stack to not be particularly robust, but the controls
worked fine. Like this ESPHome repository, mitsubishi2MQTT
will automatically
register the device in your HomeAssistant instance if you have HA configured to do so.
There's also the built-in to ESPHome
Mitsubishi
climate component.
The big drawback with the built-in component is that it uses Infrared Remote
commands to talk to the Heat Pump. By contrast, the approach used by this
repository and it's underlying HeatPump
library allows bi-directional
communication with the Mitsubishi system, and can detect when someone changes
the settings via an IR remote.
The author referred to the following documentation repeatedly: