Add configuration upgrade guide for 2021.10.0

doc/configuration.md

@@ -30,33 +30,16 @@ hardware abstraction layer (HAL) components that are used by the other component
 the GPIO's for the RGBWW leds and one for the I2C communication between the ESP32 and the front
 panel.
 
-I do mention the platform configuration here for completeness sake, but **generally you will not have
-to add the following configuration option to your yaml file**. It is loaded automatically by the
-components that need it, and the GPIO + I2C configurations are fully prepared to work for the
-Bedside Lamp 2 wiring out of the box. Therefore, you will not find this piece of configuration in
-the [`example.yaml`](../example.yaml).
-
-Having said that, here are the configuration options:
+You will not have to add any configuration options for the `xiaomi_bslamp2` to your yaml file.
+The required configuration is fully provided by the configuration package `packages/core.yaml`.
+The GPIO + I2C configurations are prepared to work for the Bedside Lamp 2 wiring out of the box.
 
 ```yaml
 xiaomi_bslamp2:
-  # Options for the RGBWW LEDs HAL.
-  red: "GPIO13"
-  green: "GPIO14"
-  blue: "GPIO5"
-  white: "GPIO12"
-  master_1: "GPIO33"
-  master_2: "GPIO4"
-  
-  # Options for the Front Panel HAL.
-  sda: "GPIO21"
-  scl: "GPIO19"
-  address: 0x2C
-  trigger_pin: "GPIO16"
 ```
 
 The only reason that I can think of for adding this platform configuration to your yaml file, would
-be if you blew one or more or the ESP32 pins, and need to rewire functionality. In other casis,
+be if you blew one or more or the ESP32 pins, and need to rewire functionality. In other cases,
 simply omit the section.
 
 ## Component: light

doc/upgrading_to_2021.10.0.md

@@ -0,0 +1,123 @@
+# Upgrading to version 2021.10.0
+
+Quite a few things have been changed in order to make the Xiaomi Bedside Lamp 2 firmware code compatible with
+ESPHome version 2021.10.0. As a result, configuration changes are needed to make the configuration work with
+the new code.
+
+There are basically two ways in which you can upgrade:
+
+1. Start a new configuration
+2. Upgrade your existing configuration
+
+## 1. Start a new configuration
+
+*This is definitely the simplest way*.
+
+Copy the new `example.yaml` configuration file from the GitHub repository and start a new configuration based
+on that. When this configuration is working, you can extend your configuration to tweak the configuration to
+your needs.
+
+## 2. Upgrade your existing configuration
+
+If you have done extensive customization, it might be easier to upgrade your existing configuration. Below
+you find a list of changse that have to be applied, and that should get your configuration ready for 2021.10.0.
+
+**Setup the following substitutions in your configuration file:**
+
+```yaml
+substitutions:
+  name: bedside-lamp
+  friendly_name: Bedside Lamp
+  light_name: ${friendly_name} RGBWW Light
+  light_mode_text_sensor_name: ${friendly_name} Light Mode
+  default_transition_length: 800ms
+```
+
+Other substitutions are not in use anymore, so you can delete them.
+
+**Modify the existing `external_components:` configuration to:**
+
+```yaml
+external_components:
+  - source:
+      type: git
+      url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
+      ref: release/2021.10.0
+    refresh: 60s
+```
+
+**Add the new core configuration package:**
+
+```yaml
+packages:
+  bslamp2:
+    url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
+    ref: release/2021.10.0
+    files:
+      - packages/core.yaml
+    refresh: 0s
+```
+You can omit the ones that represent the required value already.
+
+**Fully remove the existing `esphome:` configuration section**
+
+Remove the following block from your configuration. The `core.yaml` configuration
+package provides the required configuration, so you don't need it in your
+configuration file anymore.
+
+```yaml
+esphome:
+  name: ${name}
+  ...
+  etc.
+```
+
+**Modfy all instances of id's from a variable to a string value:**
+
+- `${id_light}` -> `my_light`
+- `${id_front_panel_illumination}` -> `my_front_panel_illumination`
+- `${id_light_mode}` -> `my_light_mode`
+- `${id_power_button}` -> `my_power_button`
+- `${id_color_button}` -> `my_color_button`
+- `${id_slider_level}` -> `my_slider_level`
+
+These are the identifiers that I will be using from now on in the configuration
+packages as well. By using these identifiers in all places, it will be easy to
+distribute configuration packages that can be added to your configuration.
+
+**Fully remove the front panel illumination output from the config**
+
+This configuration is already being setup as part of the `core.yaml` configuration package.
+When not removing it, you would get an error about the component being redefined. So simply
+remove this block from your configuration:
+
+```yaml
+output:
+  - platform: xiaomi_bslamp2
+    id: my_front_panel_illumination
+```
+
+**Optionally, modify the the name of the light component**
+
+For the name of the light, you can replace `${friendly_name} RGBWW Light` with
+the new `${light_name}` substitution variable.
+
+```yaml
+light:
+  - platform: xiaomi_bslamp2
+    id: my_light
+    name: ${light_name}
+    ...
+```
+
+** Optionally, modify the name of the text sensor**
+
+Likewise, you can change the text sensor that publishes the current light mode as text.
+The name can be changed from `${fiendly_name} Light Mode` to `${light_mode_text_sensor_name}`.
+
+```yaml
+text_sensor:
+  - platform: xiaomi_bslamp2
+    id: my_light_mode
+    name: ${light_mode_text_sensor_name}
+```