From 3cdc870b4a59192fc33928fe92bcfee49b280230 Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:51:01 -0700 Subject: [PATCH] More examples, more references --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1dd4a72..86878d3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ # esphome-mitsubishiheatpump ESPHome Climate Component for Mitsubishi Heatpumps using direct serial connection -Wirelessly control your Mitsubishi Comfort HeatPump with an ESP8266 or ESP32 using the [ESPHome](https://esphome.io) framework. +Wirelessly control your Mitsubishi Comfort HeatPump with an ESP8266 or ESP32 +using the [ESPHome](https://esphome.io) framework. ## Features * Instant feedback of command changes via RF Remote to HomeAssistant or MQTT. * Direct control without the remote. -* Uses the [SwiCago/HeatPump](https://github.com/SwiCago/HeatPump) Arduino libary to talk to the unit directly via the internal CN105 header. - NOTE: REQUIRES SEVERAL FIXES - SEE [PR #155](https://github.com/SwiCago/HeatPump/pull/155) +* Uses the [SwiCago/HeatPump](https://github.com/SwiCago/HeatPump) Arduino + libary to talk to the unit directly via the internal `CN105` connector. + NOTE: REQUIRES SEVERAL FIXES - SEE [PR + #155](https://github.com/SwiCago/HeatPump/pull/155) ## Supported Microcontrollers This library should work on most ESP8266 or ESP32 platforms. It has been tested @@ -17,21 +20,34 @@ with the following MCUs: * Generic ESP32 Dev Kit (ESP32) ## Supported Mitsubishi Climate Units -The underlying HeatPump library works with a number of Mitsubishi HeatPump -units. Basically, if the unit has a CN105 header on the main board, it should +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](https://github.com/SwiCago/HeatPump/wiki/Supported-models) has a more exhaustive list. +The same `CN105` connector is used by the Mitsubishi Kumocloud remotes, which have a +[compatibility list](https://www.mitsubishicomfort.com/kumocloud/compatibility) +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` ## Usage -### Step 1: Build a control circuit as detailed in the SwiCago/HeatPump README. +### Step 1: Build a control circuit. + +Build a control circuit with your MCU as detailed in the [SwiCago/HeatPump + README](https://github.com/SwiCago/HeatPump/blob/master/README.md). You can use either an ESP8266 or an ESP32 for this. +Note that 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](https://github.com/SwiCago/HeatPump/issues/13#issuecomment-457897457) +via CN105. + ### Step 2: Clone this repository into your ESPHome configuration directory This repository needs to live in your ESPHome configuration directory, as it @@ -57,11 +73,40 @@ There's currently no way to guarantee access to a hardware UART nor retrieve the `HardwareSerial` handle within the ESPHome framework. Create an ESPHome YAML configuration with the following sections: - * `esphome: libraries:` - * `climate:` - set up a custom climate, change the Serial port as needed. - * ESP8266 only: `logger: baud_rate: 0` - disables serial port logging on the + * `esphome: libraries: [https://github.com/geoffdavis/HeatPump#init_fix]` + * `esphome: includes: [src/esphome-mitsubishiheatpump]` + * `climate:` - set up a custom climate entry, change the Serial port as needed. + * ESP8266 only: `logger: baud_rate: 0` - disable serial port logging on the sole ESP8266 hardware UART +The custom climate definition should use `platform: custom` and contain a +`lambda` block, where you instanciate an instance of the MitsubishiHeatPump +class, and then register it with ESPHome. It should allso contain a "climates" +entry. On ESP32 you +can change `&Serial` to `&Serial1` or `&Serial2` and re-enable logging to the +main serial port. + +If that's all greek to you, here's an example. Change "My Heat Pump" to +whatever you want. + +```yaml +climate: + - platform: custom + lambda: |- + auto my_heatpump = new MitsubishiHeatPump(&Serial); + App.register_component(my_heatpump); + return {my_heatpump}; + climates: + - name: "My Heat Pump" +``` + +# Example configuration + +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`. + ```yaml esphome: name: denheatpump @@ -148,6 +193,7 @@ climate: # See Also +## Other Implementations The [gysmo38/mitsubishi2MQTT](https://github.com/gysmo38/mitsubishi2MQTT) Arduino sketch also uses the `SwiCago/HeatPump` library, and works with MQTT directly. I found it's WiFi stack to not be @@ -163,3 +209,10 @@ 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. + +## Reference documentation + +The author referred to the following documentation repeatedly: +* https://esphome.io/components/sensor/custom.html +* https://esphome.io/components/climate/custom.html +* Source for ESPHome's Dev branch: https://github.com/esphome/esphome/tree/dev/esphome/components/climate