From a9d1ccdac6508d781ade3cf827746ef6bd4f7866 Mon Sep 17 00:00:00 2001
From: Maurice Makaay <mmakaay1@xs4all.net>
Date: Wed, 24 Mar 2021 14:04:18 +0100
Subject: [PATCH] Added some documentation.

---
 README.md        | 41 +++++++++++++++++++++++++++++++++++++++--
 doc/example.yaml | 28 +++++++++++++++++++++++++++-
 2 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 64d6f5b..0a4e31c 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ repo into that folder. For example on the command line:
 
 ```
 # mkdir custom_components
-# cd custom_compnents
+# cd custom_components
 # git clone https://github.com/mmakaay/esphome-yeelight_bs2
 ```
 
@@ -25,5 +25,42 @@ config
 ```
 
 Then add the required configuration to your device's yaml configuration file.
-For an example file, taks a look at `doc/example.yaml` in this repository.
+For an example file, take a look at `doc/example.yaml` in this repository.
+
+## Issue: the device keeps losing its connection to Home Assistant
+
+This is not a problem with the device or the custom firmware, but a problem
+in the upstream library "AsyncTCP". I did identify the issue and have a
+proposed fix for it. The issue was reported at:
+
+https://github.com/me-no-dev/AsyncTCP/issues/116
+
+If you want to try out this change, then create a `libs` folder in the
+folder where your device's yaml configuration file is stored, and clone the
+following repository into that folder:
+
+  https://github.com/mmakaay/AsyncTCP 
+
+For example on the command line:
+
+```
+# mkdir libs
+# cd libs
+# git clone://github.com/mmakaay/AsyncTCP
+```
+
+Then add a pointer to this folder from within your device's yaml
+configuration file, using the `lib_extra_dirs` option. Provide it with the
+absolute path to your `libs` folder. The relevant part of the config change
+looks like this:
+
+```yaml
+esphome:
+  platformio_options:
+    lib_extra_dirs: /config/libs
+```
+
+This way, the repository version of the library will override the version of
+the library that is bundled with ESPHome. Build the device firmware and
+flash the device like you would normally do.
 
diff --git a/doc/example.yaml b/doc/example.yaml
index 3d2e204..5055883 100644
--- a/doc/example.yaml
+++ b/doc/example.yaml
@@ -1,3 +1,28 @@
+substitutions:
+  name: bedside_lamp
+  friendly_name: Bedside Lamp
+  transition_length: 1s
+
+# Use your own preferences for these components.
+wifi:
+captive_portal:
+api:
+ota:
+logger:
+
+# Special platform + package are used for enabling unicore and disabling the
+# efuse mac crc check. These two changes are required for the
+# ESP32-WROOM-32D that is used in the Yeelight bedside lamp 2.
+esphome:
+  name: $name
+  platform: ESP32
+  board: esp32doit-devkit-v1
+  platformio_options:
+    platform: espressif32@1.11.0
+    platform_packages: |-4
+          framework-arduinoespressif32 @ https://github.com/pauln/arduino-esp32.git#solo-no-mac-crc/1.0.4
+
+# The device uses two I2C busses.
 i2c:
   - id: eeprom_i2c
     sda: 17
@@ -8,6 +33,7 @@ i2c:
     scl: 19
     scan: True
 
+# The device uses six GPIO pins for driving the LED circuitry.
 output:
   - platform: gpio
     id: master1
@@ -41,7 +67,7 @@ light:
     white: led_w
     master1: master1
     master2: master2
-    default_transition_length: 1s
+    default_transition_length: ${transition_length}
     effects:
       - random:
           name: "Slow Random"