Mirrored_Repos/esphome-mitsubishiheatpump
1
0
Fork 0
mirror of https://github.com/geoffdavis/esphome-mitsubishiheatpump synced 2024-08-30 18:12:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/docfix' into develop

Browse Source
This commit is contained in:
Geoff Davis 2020-03-11 16:58:02 -07:00
commit 13ab46b421
1 changed files with 85 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
README.md
View File

@ -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