From 8a0bba689d4b671428aab75db4fc359b5c399ec7 Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:18:24 -0700 Subject: [PATCH 1/6] Numerous documentation corrections Change J105 to CN105. Fix up formatting. Add list of supported units from SwiCago. --- README.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a01994a..de755df 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,22 @@ Wirelessly control your Mitsubishi Comfort HeatPump with an ESP8266 or ESP32 usi ## 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 J105 header. -* NOTE: REQUIRES SEVERAL FIXES - SEE 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 header. + 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 with the following: +This library should work on most ESP8266 or ESP32 platforms. It has been tested +with the following MCUs: * Generic ESP-01S board (ESP8266) * WeMos D1 Mini (ESP8266) * 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 J105 header on the main board, it should work with this library. +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 +work with this library. The (HeatPump +wiki)[https://github.com/SwiCago/HeatPump/wiki/Supported-models] has a more +exhaustive list. The whole integration with this libary and the underlying HeatPump has been tested by the author on the following units: @@ -24,12 +29,14 @@ tested by the author on the following units: * MFZ-KA09NA ## Usage -### Build a control circuit as detailed in the SwiCago/HeatPump README. +### Step 1: Build a control circuit as detailed in the SwiCago/HeatPump README. You can use either an ESP8266 or an ESP32 for this. -### Clone this repository into your ESPHome configuration directory +### Step 2: Clone this repository into your ESPHome configuration directory -This repository needs to live in your ESPHome configuration directory, as it doesn't work correctly when used as a Platform.IO library, and there doesn't seem to be an analog for that functionality for esphome code. +This repository needs to live in your ESPHome configuration directory, as it +doesn't work correctly when used as a Platform.IO library, and there doesn't +seem to be an analog for that functionality for ESPHome code. On Hass.IO, you'll want to do something like: @@ -38,12 +45,13 @@ On Hass.IO, you'll want to do something like: * `cd src` * `git clone https://github.com/geoffdavis/esphome-mitsubishiheatpump.git` -### Configure your ESPHome device with YAML +### Step 3: Configure your ESPHome device with YAML 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 uses an untypical serial port setting, which are not -implemented in any of the existing software serial libraries. +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 within the ESPHome framework. @@ -147,8 +155,8 @@ particularly robust, but the controls worked fine. Like this ESPHome repository, it 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] -(https://github.com/esphome/esphome/blob/dev/esphome/components/mitsubishi/mitsubishi.h) +There's also the built-in to ESPHome +[Mitsubishi](https://github.com/esphome/esphome/blob/dev/esphome/components/mitsubishi/mitsubishi.h) climate component. It's only in the `dev` branch at the moment (2020-03-11). 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 From d2637ad8e3e5f0e9324159512b4e03879539098f Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:20:50 -0700 Subject: [PATCH 2/6] Fix baud_rate text --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de755df..907b818 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ 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 + * ESP8266 only: `logger: baud_rate: 0` - disables serial port logging on the sole ESP8266 hardware UART ```yaml From e8641f9cb7debfb46d1da2131d7b3d016cfe1dfa Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:25:00 -0700 Subject: [PATCH 3/6] Fix urls --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 907b818..1dd4a72 100644 --- a/README.md +++ b/README.md @@ -19,14 +19,14 @@ with the following MCUs: ## 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 -work with this library. The (HeatPump -wiki)[https://github.com/SwiCago/HeatPump/wiki/Supported-models] has a more +work with this library. The [HeatPump +wiki](https://github.com/SwiCago/HeatPump/wiki/Supported-models) has a more exhaustive list. The whole integration with this libary and the underlying HeatPump has been tested by the author on the following units: -* MSZ-GL06NA -* MFZ-KA09NA +* `MSZ-GL06NA` +* `MFZ-KA09NA` ## Usage ### Step 1: Build a control circuit as detailed in the SwiCago/HeatPump README. From 3cdc870b4a59192fc33928fe92bcfee49b280230 Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:51:01 -0700 Subject: [PATCH 4/6] 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 From 9cc1c4e081a9c4f6bed85f9a44802e121eadffcc Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:54:51 -0700 Subject: [PATCH 5/6] Even more doc tweaks. --- README.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 86878d3..7635f24 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ # 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 HVAC equipment 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. @@ -26,7 +25,8 @@ 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 +The same `CN105` connector is used by the Mitsubishi KumoCloud remotes, which +have a [compatibility list](https://www.mitsubishicomfort.com/kumocloud/compatibility) available. @@ -42,7 +42,7 @@ 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 +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](https://github.com/SwiCago/HeatPump/issues/13#issuecomment-457897457) @@ -63,15 +63,6 @@ On Hass.IO, you'll want to do something like: ### Step 3: Configure your ESPHome device with YAML -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 within the ESPHome framework. - Create an ESPHome YAML configuration with the following sections: * `esphome: libraries: [https://github.com/geoffdavis/HeatPump#init_fix]` * `esphome: includes: [src/esphome-mitsubishiheatpump]` @@ -100,6 +91,14 @@ climate: - name: "My Heat Pump" ``` +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. + # Example configuration Below is an example configuration which will include wireless strength From e79d216cfc9d687bb4ac87214a4d8ea94bf98cbd Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:55:47 -0700 Subject: [PATCH 6/6] Change I to The Author --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7635f24..17e19e2 100644 --- a/README.md +++ b/README.md @@ -195,8 +195,8 @@ climate: ## 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 -particularly robust, but the controls worked fine. Like this ESPHome +library, and works with MQTT directly. The author found it's WiFi stack to not +be particularly robust, but the controls worked fine. Like this ESPHome repository, it will automatically register the device in your HomeAssistant instance if you have HA configured to do so.