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

Update documentation for external component

Browse Source 
Add configuration variable reference.
Expand upon example configuration.
Add instructions for upgrading to version 2.0.x
This commit is contained in:
Geoff Davis 2021-05-27 13:34:23 -07:00
parent 1aa19b2888
commit c4ea4c14e1
1 changed files with 89 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@ -53,7 +53,8 @@ via CN105.
### Step 2: Use ESPHome 1.18.0 or higher
The code in this repository makes use of a number of features in the 1.18.0
version of ESPHome, including various Fan modes and external components.
version of ESPHome, including various Fan modes and
[external components](https://esphome.io/components/external_components.html).
### Step 3: Add this repository as an external component
@ -64,6 +65,36 @@ external_components:
- source: github://geoffdavis/esphome-mitsubishiheatpump
```
#### Step 3a: Upgrading from 1.x releases
Version 2.0 and greater of this libary use the ESPHome `external_components`
feature, which is a huge step forward in terms of usability. In order to make
things compile correctly, you will need to:
1. Remove the `libraries` section that imports
`https://github.com/SwiCago/HeatPump`, as this is handled by the
`external_component` section of manifest.
2. Remove the `includes` section that imports `src/esphome-mitsubishiheatpump`
3. Delete the old checkout of this repository under
`src/esphome-mitsubishiheatpump`.
4. Clean your old ESPHome build directories out (3-dot menu, "Clean Build
Files")
5. You may also have to delete the _esphomenodename_ directory that
corresponds with your _esphomenodename.yaml_ configuration file
completely. Testing with ESPHome 0.18.x showed this to be necessary to get
the cached copy of src/esphome-mitsubishiheatpump to go away entirely, as
the "Clean Build Files" isn't as thorough as one would like.
*Note:* Failure to delete the old source directory and remove the `includes`
and `libraries` lines will likely result in compilation errors complaining
about duplicate declarations of `MitsubishiHeatPump::traits()`.
##### Example error
```
Linking /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/firmware.elf
/root/.platformio/packages/toolchain-xtensa/bin/../lib/gcc/xtensa-lx106-elf/4.8.2/../../../../xtensa-lx106-elf/bin/ld: /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/src/esphome/components/mitsubishi_heatpump/espmhp.cpp.o: in function `MitsubishiHeatPump::traits()':
espmhp.cpp:(.text._ZN18MitsubishiHeatPump6traitsEv+0x4): multiple definition of `MitsubishiHeatPump::traits()'; /data/bedroom_east_heatpump/.pioenvs/bedroom_east_heatpump/src/esphome-mitsubishiheatpump/espmhp.cpp.o:espmhp.cpp:(.text._ZN18MitsubishiHeatPump6traitsEv+0x80): first defined here
```
### Step 4: Configure the heatpump
Add a `mitsubishi_heatpump` to your ESPHome config:
@ -88,16 +119,16 @@ logger:
baud_rate: 0
```
On ESP32 you can change `hardware_uart` to `UART1` or `UART2` and keep logging
On ESP32 you can change `hardware\_uart` to `UART1` or `UART2` and keep logging
enabled on the main serial port.
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.
*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
@ -122,6 +153,14 @@ wifi:
ssid: "Denheatpump Fallback Hotspot"
password: !secret fallback_password
# Note: if upgrading from 1.x releases of esphome-mitsubishiheatpump, be sure
# to remove any old entries from the `libraries` and `includes` section.
libraries:
# Remove reference to SwiCago/HeatPump
includes:
# Remove reference to src/esphome-mitsubishiheatpump
captive_portal:
# Enable logging
@ -182,11 +221,11 @@ climate:
hardware_uart: UART0
```
# Advanced
# Advanced configuration
Some models of heat pump require different baud rates or don't support all
possible modes of operation. You can configure pretty much everything in YAML
to match what your hardware supports. For example:
possible modes of operation. You can configure mulitple climate "traits" in
YAML to match what your hardware supports. For example:
```yaml
climate:
@ -204,15 +243,44 @@ climate:
temperature_step: 1.0
```
## Configuration variables that affect this library directly
* *hardware\_uart* (_Optional_): the hardware UART instance to use for
communcation with the heatpump. On ESP8266, only `UART0` is usable. On ESP32,
`UART0`, `UART1`, and `UART2` are all valid choices. Default: `UART0`
* *baud\_rate* (_Optional_): Serial BAUD rate used to communicate with the
HeatPump. Most systems use the default value of `4800` baud, but some use
`9600`. Default: `4800`
* *update\_interval* (_Optional_, range: 0ms to 9000ms): How often this
component polls the heatpump hardware, in milliseconds. Maximum usable value
is 9 seconds due to underlying issues with the HeatPump library. Default: 500ms
* *supports* (_Optional_): Supported features for the device. ** *mode*
(_Optional_, list): Supported climate modes for the HeatPump. Default:
`['AUTO', 'COOL', 'HEAT', 'DRY', 'FAN_ONLY']`
** *fan_mode* (_Optional_, list):
Supported fan speeds for the HeatPump. Default: `['AUTO', 'DIFFUSE', 'LOW',
'MEDIUM', 'MIDDLE', 'HIGH']` ** *swing_mode* (_Optional_, list): Supported
fan swing modes. Most Mitsubishi units only support the default. Default:
`['OFF', 'VERTICAL']`
## Other configuration
* *id* (_Optional_): used to identify multiple instances, e.g. "denheatpump"
* *name* (_Required_): The name of the climate component, e.g. "Den Heatpump"
* *visual* (_Optional_): The core `Climate` component has several *visual*
options that can be set. See the [Climate
Component](https://esphome.io/components/climate/index.html) documentation for
details.
# 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. 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.
Arduino sketch also uses the `SwiCago/HeatPump`
library, and works with MQTT directly. The author of this implementation found
`mitsubishi2MQTT`'s WiFi stack to not be particularly robust, but the controls
worked fine. Like this ESPHome repository, `mitsubishi2MQTT` 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)
@ -226,6 +294,7 @@ 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
* [ESPHome Custom Sensors Reference](https://esphome.io/components/sensor/custom.html)
* [ESPHome Custom Climate Components Reference](https://esphome.io/components/climate/custom.html)
* [ESPHome External Components Reference](https://esphome.io/components/external_components.html)
* [Source for ESPHome's Climate Component](https://github.com/esphome/esphome/tree/master/esphome/components/climate)