TL;DR: Control a Mitsubishi mini-split heat pump over the Web using a Raspberry Pi Zero W.

Background

prototype in Lego enclosure photo
First prototype

After installing a photovoltaic (solar) system with battery backup, managing home loads during grid outages became important. Mini-Split heat pumps use a lot of energy when it is really cold out and are the one home device we have that may continue to run unnoticed during an outage, such as when we are asleep or out of the house, causing the batteries to drain down rapidly. So, finding a way to automatically shut them off at the start of an outage became the goal of this project, and in the process ended up with full web control of the mini-splits. Yes, they could have been put on a separate panel that is not powered during an outage, however what's the fun in that we still wanted the ability to run them for A/C during the summer when they don't use up much energy (hey, this is around 44° north). For those concerned about us freezing, there is backup non-electric heat set to a few degrees below the mini-split temps; thanks for caring.

There are products available, including by Mitsubishi, for controlling mini-splits using a WiFi thermostat or a phone app. These cost around US$200 and still wouldn't auto shut-off the mini-splits as they have no knowledge of a grid outage. The solution below provides a more capable device for around US$20 in electronic parts for each indoor mini-split unit.

With 5 mini-split heads indoors, the project was broken up into a Raspberry Pi for each unit and an already existing home web server for controlling all the Pis that was also logging PV/battery data and monitoring for grid outages. If there was just one mini-split or no home server, a Pi could instead have served as the main controller.

WARNING: If you choose to read on and actually try to replicate any of the steps below, you assume full responsibility for any damage or harm you may cause yourself, others, mini-splits, the building they are housed in, or pretty much anything else a clever lawyer may come up with. The possibility of electrocution is real, as is frying the Raspberry Pi, mini-split, or your hair. At a minimum, you may void your warranty.

Hardware

CN105 connector on mini-split
CN105 connector on mini-split

Many Mitsubishi Mini-Split Heat Pumps have a CN105 connector (see photo at right) for interfacing the aforementioned Mitsubishi WiFi controller. The mini-split units used in this project were MSZ-GE##NA, although others are reported to work as well. If you can't figure out how to open up the mini-split, then you should probably not be taking this project on ;)

The CN105 connector pins provide 12V, Ground, 5V, TX, and RX. Communications are through the serial UART (TX/RX). Although the 5V could possibly be used to power the Pi, in an abundance of caution the 12V was used instead along with a buck converter to step down the voltage to the Pi required 5V. Similarly, the CN105 TX/RX are 5V whereas the Pi requires 3V, so a bi-directional logic level converter was used. For the MSZ-GE/NA, what you see in the photo as the black wire coming out of the CN105 connector is the 12V pin. Regardless of the model, it is recommended that the CN105 pins be tested with a multimeter to ensure proper connector alignment.

In case the Pi becomes unreachable through WiFi, a momentary-touch button (switch) was also added to allow the Pi to be cleanly shutdown if needed. The button also allows the Pi to be started back up if it is in a halt state, without requiring a power reset.

Another feature is a red LED so at-a-glance we can tell if the grid is out. With seamless switching batteries, it is not always evident that there is a grid outage in progress. Depending on the LED used, a different resistance than shown in the schematic may work better. A subsequent prototype also included a PIR (motion sensor) activated OLED (display) showing mini-split settings, grid status, and weather. This was done as the mini-split remote control would no longer show correct information with the mini-split separately controlled over the web. These enhancements are not discussed here, although if you include the LED, the API supports turning it on and off.

The biggest challenge was finding a visually-appealing enclosure of the right size and color to contain the electronics and attach to the mini-split. The solution ended up building one out of Lego™. This had the advantage of being as small as possible while easily allowing experimentation for the best layout. The final enclosure is 6 x 12 x 3-2/3 studs with a clear brick by the LEDs and a 1x2x2 wall element with window for the large button. Attaching the Lego enclosure to the mini-split was accomplished using poster strips which allows it to be cleanly taken off in the future.

Below is the schematic and photos of electronic components:

first prototype photo
First prototype

photo of second prototype with button and LED
Second prototype with button in LEGO housing and LED

schematic

Software

OS & Configuration

As the Pi is only used remotely after initial setup, Raspbian Lite1 is a good option. Once installed and signed into the default pi account (password: raspberry), the following configuration steps were taken while connected to a monitor, keyboard, and USB power:

A few gotchas to be aware of:

IMPORTANT: Assign a static IP to the Pi through the WiFi router (or in Raspbian) because the MiniSplitPi install script (see below) will generate a secure key and certificate tied to the IP address. What you are building is an Internet of Things (IoT) device which is why connections are only via TLS (httpS://) and, as you will see, a UUID is used for Web API access. This device should ideally only be accessible to the local network or a trusted controlling device and not exposed to the Internet.

OS Update & Required Library Installation

Let's make sure the OS is up to date:

As of this writeup, Raspbian still defaults to the obsoleted Python 2. So, let's upgrade to Python 3, set it as the default, and install required libraries (gpiozero, pyserial):

It is strongly recommended that Raspbian be kept up to date and/or unattended-upgrades be installed.

MiniSplitPi Software & Installation

The Mini-Split Raspberry Pi Web Controller software is available on GitHub.2 It is assumed the software files are installed in /home/pi/MiniSplitPi/. Once installed, set the .py and .sh files to be executable:

Once the above commands are executed, run the install script:

This will:


Below-mounted MiniSplitPi

At this point, everything is ready. Pressing the button while the Pi is on should cause the Pi to shutdown. If the Pi is in a halt state, it should boot up. This is accomplished by having the button connected to GPIO3 (pin 15). See below for how to make Web API requests.

Testing out the web API prior to putting everything in an enclosure and connecting it to the mini-split is suggested. Although you will not be able to control the mini-split untill connected, you can try issuing a Pi shutdown or reboot command, and test the LED (see next section).

Web API Requests

Requests to MiniSplitPi are sent through the web using GET requests. The syntax is as follows:

Below is a sample request to turn on the mini-split and set it to heat mode with the temperature at 24°C, fan on auto, and vane pointed down:

When a valid action request is received, the following is returned:

If the UUID is invalid, the following is returned:

When requesting the status (i.e., no action GET parameter), the following is returned as an example:

The additional values returned are:

NOTE:

Web Control

If you don't want to craft custom URLs each time you check or update the mini-split, create your own application using the MiniSplitPi API. This is left as an exercise for the reader.

Below is a screenshot of the web application in use for controlling our 5 mini-splits. Clicking the left-side of a unit toggles power on/off. Clicking on the right-side of a unit allows changing the mode, temperature, vane direction, and fan.

web interface showing mini-splits

Acknowledgements

A shout out to Hadley Rich3 who decoded the mini-split signals and developed a python library4 for controlling it. Two of Hadley's library files are included in this project and have been updated to Python 3. If you are working with Arduino or ESP8266, be sure to check out the references to related projects below.5,6,7

References

  1. https://www.raspberrypi.org/learning/software-guide/
  2. https://github.com/hobbez/MiniSplitPi
  3. https://nicegear.nz/blog/hacking-a-mitsubishi-heat-pump-air-conditioner/ (Web Archive link)
  4. https://github.com/hadleyrich/MQMitsi
  5. https://chrdavis.github.io/hacking-a-mitsubishi-heat-pump-Part-1/
  6. https://github.com/SwiCago/HeatPump
  7. https://github.com/JMan7777/Mitsubishi-Aircon-SmartThings

Parts List

Raspberry Pi Pinout


Source: pinout.xyz