esphome-xiaomi_bslamp2/doc.chinese/upgrading_to_2021.10.0.md

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:

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:

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:

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.

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:

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.

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}.

text_sensor:
  - platform: xiaomi_bslamp2
    id: my_light_mode
    name: ${light_mode_text_sensor_name}