diff --git a/README.md b/README.md index a01994a..17e19e2 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,58 @@ # 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. * 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` 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 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 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 +* `MSZ-GL06NA` +* `MFZ-KA09NA` ## Usage -### 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. -### Clone this repository into your ESPHome configuration directory +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) +via CN105. -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. +### 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. On Hass.IO, you'll want to do something like: @@ -38,21 +61,50 @@ 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 + +Create an ESPHome YAML configuration with the following sections: + * `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" +``` 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 from the +`uart` component within the ESPHome framework. -There's currently no way to guarantee access to a hardware UART nor retrieve -the `HardwareSerial` handle within the ESPHome framework. +# Example configuration -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 - sole ESP8266 hardware UART +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: @@ -140,18 +192,26 @@ 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 -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. -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 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 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.*/