Stable release for ESPHome 2024.10.0

Note: This release requires ESPHome 2024.10.0 or newer.

Important Update for ESPHome 2024.10.0 Users

ESPHome 2024.10.0 introduced what turned out to be a breaking change for the type of ESP32 chip that is used in our beloved lamps. See the ESPHome changelog for more information. This release provides the required changes to make the firmware project compatible with ESPHome 2024.10.0.

You already flashed your lamp and it ended up bricked? Then no worries!

If you attempted to upgrade your lamp using ESPHome 2024.10.0 before this release, you may have encountered an issue where the lamp became unavailable in Home Assistant. Fortunately, in all reported cases, it was still possible to restore functionality by flashing a corrected firmware to the bslamp2.

If you're managing multiple lamps and experience issues with flashing, unplug all of them, then reconnect and flash each lamp individually, one at a time.

Thanks for the help spotting and fixing the issue to Andy, @jos, @randybb and @kbx81!

Friendly name included in the esphome: config section

The friendly_name value as defined in the substitution: section of the example.yaml is now used for defining the friendly name in the esphome: configuration section. With this change, the friendly name is also used by Home Assistant for referencing the device and its entities.

Excerpt from the new core.yaml configuration package:

esphome:
  name: ${name}
  friendly_name: ${friendly_name} <-- this definition is new

Thanks to fmauNeko on GitHub for suggesting actually defining the friendly name in here.

Having the friendly name defined now, might have impact on the entity IDs as you see them in Home Assistant.

In the core.yaml, the ${friendly_name} has been removed from the default values for light_name and light_mode_text_sensor_name. The reason for this, is that ESPHome automatically uses the defined friendly name as a prefix in the entity IDs. When keeping the ${friendly_name} in there, this would result in having repeated friendly names (e.g. light.bedside_lamp_bedside_lamp_rgwbb_light).

If you have overridden the above names in your custom device YAML config, then remove ${friendly_name} from them.
You could also get back to the original behavior by adding the following to your device YAML file:

substitutions:
  name: ...
  friendly_name: ...
  light_name: ${friendly_name} RGBWW Light
  light_mode_text_sensor_name: ${friendly_name} Light Mode
  
esphome:
  friendly_name: ""

How to upgrade your device

The basic steps for upgrading are:

1. Upgrade ESPHome to 2024.10.0 or later;
2. Update your device configuration (see below);
3. Compile and upload the new firmware.

If you have used the example.yaml to create your configuration, then update the configuration package ref: to point to release/2024.10.0.

packages:
  bslamp2:
    url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
    ref: release/2024.10.0 <--- update this one
    files:
      ...
      ...

Full changelog

There were some other changes, without end-user impact. For a complete overview of all changes, you can take a look at
the CHANGELOG.md

Stable release for ESPHome 2023.4.0+

Note: This release requires ESPHome 2023.4.0 and Home Assistant 2021.8.0 or newer.

Fixed

• Compile issues with recent ESPHome versions fixed:
  • An error about toolchain-riscv32-esp not being found (the PlatformIO tool manager
    tries to install this one, even though the lamp is an ESP32 device and not riscv).
  • On systems for which the above toolchain could be found, compilation would fail
    with an error about esp_mac.h not being found.

Changed

• ESPHome's compile-time warnings about "GPIO is a Strapping PIN and should
  be avoided" are now being suppressed. These warning are often interpreted
  by users of this firmware as problems. However, the pinouts are dictated by
  the hardware and there are no strapping issues because of how they are used.
• Updated the documentation for the deprecated API password support (which must now
  be an API encryption key instead).

How to upgrade your device

The basic steps for upgrading are:

• Upgrade ESPHome to 2023.4.0 or later;
• Update your device configuration (see below);
• Compile and upload the new firmware.

If you have used the example.yaml to create your configuration, then update the configuration package ref: to point to 2023.4.0.

packages:
  bslamp2:
    url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
    ref: 2023.4.0 <--- update this one
    files:
      ...
      ...

If you use a different configuration method, then make sure that the external_component: and esp32: sections match the ones from the example.yaml for this release.

Stable release for ESPHome 2022.12.0+

Note: This release requires ESPHome 2022.12.0 and Home Assistant 2021.8.0 or newer.

Fixes: failing device when upgrading to ESPHome 2022.12.0

ESPHome 2022.12.0 upgraded the ESP-IDF framework to 4.4.2. Changes were required to make the bslamp2 firmware compatible with this version. Without these changes, the upgrade could render the device non-functional (a.k.a. "bricked").

This release of the firmware fixes this issue, by explicitly reverting the used framework version to 4.3.2 (i.e. the previous version that was working correctly). This is a stop gap work-around at best. I am working on fully supporting the new framework version in my next release.

Do I need to upgrade the lamp?

Basically, no. Based on user reports, there are still ways to break the operations of the lamp, depending on the exact configuration file that you use. There are no security issues, nor new functionality to enjoy, so my general recommendation for now would be to simply keep your lamp at the pre-2022.12.0 firmware.

I am in the process of getting things fixed in a future-proof way, but that depends on cooperation of the Espressif ESP-IDF team. I did a proposal for a change, as from what I see, it is going to be implemented. Once that change is in place, I can implement a new version of the firmware that should be rock solid.

You already flashed your lamp and it ended up bricked? Then no worries!

Unfortunately, simply flashing the device with never firmware over a serial connection does not bring it back into working state. Things can be fixed though with a little flashing dance. Check out the instructions from the related GitHub issue report:
Fix recipe from issue #104

How to upgrade your device

The basic steps for upgrading are:

1. Upgrade ESPHome to 2022.12.0 or later;
2. Update your device configuration (see below);
3. Compile and upload the new firmware.

If you have used the example.yaml to create your configuration, then update the configuration package ref: to point to release/2022.12.0.

packages:
  bslamp2:
    url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
    ref: release/2022.12.0 <--- update this one
    files:
      ...
      ...

If you use a different configuration method, then make sure that the external_component: and esp32: sections match the ones from the example.yaml for this release.

Stable release for ESPHome 2021.10.0+

Note: This release requires ESPHome 2021.10.0 and Home Assistant 2021.8.0 or newer.

This release brings compatibility with ESPHome 2021.10.0.

Configuration file changes
Due to changes in ESPHome, the core configuration for the lamp had to be changed (the esphome base configuration, board configuration and I2C + GPIO hardware configuration). This means that existing configuration files have to be updated accordingly.
To make configuration as easy as possible, the example.yaml configuration now makes use of configuration packages that are stored on GitHub. This reduces the amount of configuration that is required in your own device configuration file, making future configuration changes easier.

No more custom platform packages
ESPHome 2021.10.0 has brought us support for using ESP-IDF instead of the Arduino framework. ESP-IDF is the "Espressif IoT Development Framework", which is the native development framework for ESP32 SoCs. I switched to this framework for building the lamp firmware. This made it possible to get the required ESP32 unicore support and to ignore the MAC CRC using a vanilla build. No more need for hacked up platform packages to get things going! <3

Preparing for ESPHome 2021.10.0

Note: This release requires ESPHome 2021.10.0 and Home Assistant 2021.8.0 or newer.

This release brings compatibility with ESPHome 2021.10.0.

Configuration file changes
Due to changes in ESPHome, the core configuration for the lamp had to be changed (the esphome base configuration, board configuration and I2C + GPIO hardware configuration). This means that existing configuration files have to be updated accordingly.
To make configuration as easy as possible, the example.yaml configuration now makes use of configuration packages that are stored on GitHub. This reduces the amount of configuration that is required in your own device configuration file, making future configuration changes easier.

No more custom platform packages
ESPHome 2021.10.0 has brought us support for using ESP-IDF instead of the Arduino framework. ESP-IDF is the "Espressif IoT Development Framework", which is the native development framework for ESP32 SoCs. I switched to this framework for building the lamp firmware. This made it possible to get the required ESP32 unicore support and to ignore the MAC CRC using a vanilla build. No more need for hacked up platform packages to get things going! <3

Memory leaks are bad, m'kay?

Note: This release requires ESPHome 2021.8.0 and Home Assistant 2021.8.0 or newer.

Changed

• Fixed a memory leak, causing the lamp to disconnect occasionally when doing a lot of
  color transformations (e.g. when running the Random light effect).

To make use of this release, you can use the following in your YAML configuration:

external_components:
  - source:
      type: git
      url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
      ref: 2021.9.1

Getting ready for ESPHome 2021.9.0

At the time of writing, ESPHome 2021.9.0 is in beta. While testing this beta, I found that a compilation error came up in ESPHome. This release fixes that error.

This release can also be used with ESPHome 2021.8.0 and up.

To make use of this release, you can use the following in your YAML configuration:

external_components:
  - source:
      type: git
      url: https://github.com/mmakaay/esphome-xiaomi_bslamp2
      ref: 2021.9.0

A few light transformer fixes

Along with the new custom light transformer code (to make the firmware compatible with the latest and greatest Home Assistant and ESPHome) came some issues in transition handling. This release fixes the following issues:

• Fixed transitioning from the off to on state. Thanks to @marcel1988 for informing me about his non-functional wake-up light script. Before this fix, the light would stay off during the full transformation, only to turn on at the very end.

• The on_brightness trigger is now also called at the start of a transition. This fixes a problem with the brightness slider illumination not following along when you slide your finger over it.

• Suppressing a transition time for transitioning to a night light color is now only instant when starting from a night light setting. Before this change, moving from for example 80% brightness to 1% brightness (i.e. night light), would be instant. Now an actual transformation is done.

A colorful release

Recently, Home Assistant introduced explicit color modes (RGB, Color Temperature, etc.). ESPHome had to follow by adding color modes to its API as well. This did cause some head aches along the way. For users of the Bedside Lamp 2 most noticably the disappearing RGB and Color Temperature tabs in the GUI control panel of Home Assistant. For me as developer, various compatibility issues between my code and the progressing ESPHome code.

But the suffering should now be over 😄 With the release of ESPHome 2021.8.0, the code base has been stabilized and I can release new code that is fully compatible with ESPHome and Home Assistant again.

The changes for this release

• Preset identifiers (group and preset) for the preset.activate action are now validated at compile time.
• Compatibliity with Home Assistant 2021.8.0. and ESPHome 2021.8.0.
• Now ESPHome has switched to Home Assistant's versioning scheme,. this project will follow the versioning scheme as well.
• The example.yaml has been updated to not use underscores in the hostname anymore. Since recently, using an underscore in the name yields a warning during the firmware compilation, because hostnames can only contain letters, numbers and dashes "-".

Support for Home Assistant Color Modes

Home Assistant 2021.8.0 introduced support for Color Modes in the ESPHome integration.
This release implements the required compatibility for this.

The code for this release depends on upcoming changes in ESPHome, which will be available from v1.21.0 on. Because that version is still in development, this release is published as a release candidate, so people with bleeding edge setups can test this.