[RELEASE] Mitsubishi Heat Pump + MQTT Driver

[interrobang]

This driver is designed to work with mitsubishi_heatpump_mqtt_esp8266_esp32 from SwiCago's HeatPump.cpp library. The library runs on an ESP8266 or ESP32 microcontroller connected to the heatpump via connector CN105 (just like the official Kumo Cloud device). For more information about wiring up an ESP8266 / ESP32 to your heat pump, check the links above. (I have a blog post I'll finish soon...)

Features

• Full local control of heatpumps -- bidirectional updates in seconds
• Supports both authenticated and anonymous MQTT connections
• Supports the Hubitat / Google Home integration so you can view and control the heatpumps with Home / Nest devices
• Can detect when the heatpumps are actively heating/cooling and update Hubitat Dashboard
• Reports room temperature back from the heatpump for use in automations
• Supports all heatpump modes and fan speeds (dry mode, quiet fan, etc.)

Requirements

• A Mitsubishi heat pump with a CN105 connector (MSZ models and more, see wiki for full list)
• An ESP8266 / ESP32 microcontroller (I used Lolin S2 Mini which costs about $4) running mitsubishi_heatpump_mqtt_esp8266_esp32
• An MQTT broker running on your network. I use mosquitto on a Raspberry Pi.

Installation

The driver is available on GitHub and includes an importUrl for 1-click import as well as installation instructions.

Why ESP8266 / ESP32?

Kumo Cloud units are very expensive (~$200 USD each) and you need one for each heat pump. ESP32 microcontrollers cost under $5 and can run completely locally so the units can be controlled even without Internet.

If you are lucky enough to have Kumo Cloud, try the driver from @sburke781 instead.

Issues

I am happy to look at bug reports or pull requests on GitHub or here in the forums! I actively use this driver in my home so it will be supported into the future.

[interrobang]

v1.1: added control for vane and wideVane to the allowed commands.

[user2161]

Interrobang, this is amazing thank you!

[michaelahess]

I just grabbed 5 esp devices and installed this software on them. I don't understand MQTT even after reading a bunch about it. Call me old

I got the impression that the MQTT Link app/driver would run the broker on the Hub, is that correct? So I can use this driver without a RPi?

[interrobang]

Unfortunately MQTT Link is a client rather than a broker. You still need to run a broker somewhere-- it could be on a computer, a Pi, or even a NAS if you have one.

The Arduino connects to the broker and issues messages like "currently set to 70 degrees cooling". It also listens for messages like "Set the unit to 72 degrees" or "Turn the unit off".

This driver also connects to the broker. It receives the status updates from the Arduino and syncs those to the Hubitat state so you can see / control the unit in Hubitat.

MQTT Link is ALSO a client (not a broker). It publishes messages like "hubitat/hue-bulb-1: on" so that other devices on your network that don't work directly with Hubitat can see these events.

[michaelahess]

Hey @interrobang I just got my wires from China, soldered up the first unit and plugged in. It's on the network, but I don't get any response via mosquitto. Here's my config:

And here's the topic log, all the commands seen are from Hubitat:

Am I missing something really basic here?

[michaelahess]

Figured it out, everything's working! This is awesome, thank you!

[interrobang]

Great! I was just going to sit down and look at what you had this evening. What was the solution? Will let me know if I need to document anything more thoroughly

It looks like your header file had the topic as "MikesHVAC" but then in Hubitat you defined the topic as "MikesOfficeHVAC", was that it?

[michaelahess]

Got this little guy rocking and rolling. Brief(ish) instructions that worked for me:

Software - Arduino:

1. Download Arduino IDE
2. Install, then go to Tools -> Manage Libraries
3. Search and Install ArduinoJson and PubSubClient
4. Under Preferences, add this link to "Additional boards manager URLs: http://arduino.esp8266.com/stable/package_esp8266com_index.json
5. Open Tools -> Board Manger and search esp8266, install, close the IDE
6. Download, extract, and copy the mitsubishi_heatpump_mqtt_esp8266_esp32 software to your Arduino/libraries and examples user directory (under your local drive, username, Arduino, might have to create examples/libraries folders. I don't recall if I just dumped the whole thing in libraries or not tbh...
7. Open the IDE and you'll see the files, choose the right one:
   

Software - Mosquitto Server

1. Download and install Mosquitto I've done this on MacOS and Windows equally easily
2. Edit the config file (/opt/homebrew/etc/mosquitto/mosquitto.conf) or Win install folder

• Uncomment "Listener" and add port 1883
• Under Security, uncomment "allow_anonymous false" and set to true
• Setup a password file and security via the man pages if you care to

3. Start two terminals, first one, run: mosquitto_sub -t YourDeviceHVAC -h mosquittoserverIP
4. Second one, run: mosquitto_pub -m "test message" -t YourDeviceHVAC -h mosquittoserverIP
5. You should receive the test message in the first terminal. If not, troubleshoot your install/config, also make sure firewalls allow port 1883.

Configuration - Hubitat

1. Install code with @interrobang's importURL
2. Create a new virtual device, assign the driver just installed.
3. Add the mosquitto host IP, port (if changed), and Topic. I use BedroomHVAC, LivingRoomHVAC, etc, save.
4. Restart the first terminal and instead point it to the YourDeviceHVAC/set topic (a folder under the root basically)
5. In the Hubitat driver, click auto/heat/off/etc and see if the terminal updates with the issued commands. If so, you can move on, if not, verify your Topic's are exactly matched. You can use the mosquitto_pub command to issue a message to the root, /set, or anything else you'd like, just make sure the mosquitto_sub is set to the exact same name and folder structure.

Hardware - Simplified

1. Obtain some Mini D1's...
2. Obtain some cables...
3. Combine the two by cutting one end off, don't use the blue wire, strip back a few mm, and cram into the holes. Solder (on 5v side) Red (pin 5) -> TX, Black (pin 4) -> RX, Green (pin 2) -> Gnd, Yellow (pin 3) -> 5v. Pins are seen with connector facing down (wires up) and tab facing you.
4. Plug a D1 into your computer.
5. Open Arduino IDE, double click the mits_heat_mqtt_esp blah blah sketch, select the discovered device from the Board dropdown, search and choose the D1 R2 & Mini:
   
6. Config WiFi and device info:
   
   
7. Click the big circle with -> at the top, this will write the code to the D1.

Validate

1. Use the mosquitto_sub command, and point to YourDeviceHVAC/debug
2. You will see sent/recv'd packets, showing the D1 can talk to your server
3. Plug the Mini D1 into your HVAC unit (power off if you want to be safe, no issues for me though)
4. Issue a command in the Hubitat driver, and you will see a response and result after a few seconds in the terminal.
5. Raise a glass to your success!

[interrobang]

v1.1.1: Improves handling for some failure states when the device hosting your MQTT broker is temporarily unavailable.

As discovered when PSE turned off my power for six hours to replace a telephone pole.

[interrobang]

v1.1.2

• Change the supportedThermostatModes and supportedThermostatFanModes to JSON-encoded arrays for compatibility with Hubitat 2.3.4. (ref)
• Override the default setThermostatMode and setThermostatFanMode commands to show the correct values on the device's edit page. (Dashboards already showed the correct values.) (ref)

Upgrading from an earlier release

Because of the modes change, you need to reconfigure each device using the driver. After saving the updated driver, visit each device's edit page and press Configure. (This will reset the temperature setpoints to defaults.)