From 8a0bba689d4b671428aab75db4fc359b5c399ec7 Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:18:24 -0700 Subject: [PATCH 1/7] 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/7] 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/7] 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/7] 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/7] 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/7] 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. From 2d1ae5abafcfdfcfd163c2bcdda96a6b7c40bc45 Mon Sep 17 00:00:00 2001 From: Geoff Davis Date: Wed, 11 Mar 2020 16:59:21 -0700 Subject: [PATCH 7/7] Bump version to 1.0.1 --- espmhp.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/espmhp.h b/espmhp.h index e104743..db5b910 100644 --- a/espmhp.h +++ b/espmhp.h @@ -24,7 +24,7 @@ using namespace esphome; static const char* TAG = "MitsubishiHeatPump"; // Logging tag -static const char* ESPMHP_VERSION = "1.0.0"; +static const char* ESPMHP_VERSION = "1.0.1"; /* If polling interval is greater than 9 seconds, the HeatPump library reconnects, but doesn't then follow up with our data request.*/