From 963fdb824a78c8192905fe3f07e6355474a99f98 Mon Sep 17 00:00:00 2001 From: Maurice Makaay Date: Mon, 18 Oct 2021 01:22:34 +0200 Subject: [PATCH 1/3] Update configuration guide to include packages/core.yaml --- doc/configuration.md | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) diff --git a/doc/configuration.md b/doc/configuration.md index f3d2e0d..67da41c 100644 --- a/doc/configuration.md +++ b/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 From ca85a222885fe0c034f1a4432c94d47f9d24efdf Mon Sep 17 00:00:00 2001 From: Maurice Makaay Date: Mon, 18 Oct 2021 12:15:13 +0200 Subject: [PATCH 2/3] Fix for external component URL in core.yaml Same fix as already applied for release/2021.10.0b1. --- packages/core.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core.yaml b/packages/core.yaml index f6c1983..731cd04 100644 --- a/packages/core.yaml +++ b/packages/core.yaml @@ -30,7 +30,7 @@ esp32: external_components: - source: type: git - url: https://mmakaay/esphome-xiaomi_bslamp2 + url: https://github.com/mmakaay/esphome-xiaomi_bslamp2 ref: dev refresh: 60s From f88834ed805274993cfbe0b84fa4f9c107feaf0c Mon Sep 17 00:00:00 2001 From: Maurice Makaay Date: Mon, 18 Oct 2021 16:52:07 +0200 Subject: [PATCH 3/3] Add configuration upgrade guide for 2021.10.0 --- doc/upgrading_to_2021.10.0.md | 123 ++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 doc/upgrading_to_2021.10.0.md diff --git a/doc/upgrading_to_2021.10.0.md b/doc/upgrading_to_2021.10.0.md new file mode 100644 index 0000000..9ab7960 --- /dev/null +++ b/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} +```