More examples, more references

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.
+* Uses the [SwiCago/HeatPump](https://github.com/SwiCago/HeatPump) Arduino
-  NOTE: REQUIRES SEVERAL FIXES - SEE [PR #155](https://github.com/SwiCago/HeatPump/pull/155)
+  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
+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
+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:`
+ * `esphome: libraries: [https://github.com/geoffdavis/HeatPump#init_fix]`
- * `climate:` - set up a custom climate, change the Serial port as needed.
+ * `esphome: includes: [src/esphome-mitsubishiheatpump]`
- * ESP8266 only: `logger: baud_rate: 0` - disables serial port logging on the
+ * `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