diff --git a/doc/configuration.md b/doc/configuration.md index aa093c8..8a8e855 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -11,16 +11,16 @@ fill in the blanks. The `xiaomi_bslamp2` platform provides various components that expose the core functionalities of the lamp. In the following table, you can find what components are used for exposing what parts of the lamp. - | Part | Component(s) | - | -------------------------- |--------------------------------------------------------| - | ESP32 pinouts | [platform xiaomi_bslamp2](#platform-xiaomi_bslamp2) | - | RGBWW LEDs | [light](#light) | - | Front Panel Power button | [binary_sensor](#binary_sensor) | - | Front Panel Color button | [binary_sensor](#binary_sensor) | - | Front Panel Slider | [binary_sensor](#binary_sensor) (touch/release) | - | | [sensor](#sensor) (touched slider level) | - | Front Panel Illumination | [output](#output) (on/off + indicator level) | - | Light mode propagation | [text_sensor](#text_sensor) | + | Part | Component(s) | + | -------------------------- |------------------------------------------------------------------| + | ESP32 pinouts | [platform xiaomi_bslamp2](#platform-xiaomi_bslamp2) | + | RGBWW LEDs | [light](#light) | + | Front Panel Power button | [binary_sensor](#component-binary_sensor) | + | Front Panel Color button | [binary_sensor](#component-binary_sensor) | + | Front Panel Slider | [binary_sensor](#component-binary_sensor) (touch/release) | + | | [sensor](#component-sensor) (touched slider level) | + | Front Panel Illumination | [output](#component-output) (on/off + indicator level) | + | Light mode propagation | [text_sensor](#component-text_sensor) | ## Platform: xiaomi_bslamp2 @@ -110,6 +110,23 @@ light: These options are superceded by the fact that the light component has a fully customized light model, that closely follows the light model of the original lamp's firmware. +### Light modes + +The lamp supports multiple light modes. These are: + +* **RGB light** (input: RGB + brightness) +* **White light** (input: Color Temperature + brightness) +* **Night light** (input: either RGB or Color Temperature + brightness at 1%) + +In the original firmware + Yeelight Home Assistant integration, the night light feature is +implemented through a switch component. The switch can be turned on to activate the night +light mode. In this ESPHome firmware, setting the brightness to its lowest value triggers +the night light mode. This makes things a lot easier to control. + +It is possible to control the night light mode separately. An example of this can be +found in the [example.yaml](example.yaml), in which holding the power button is bound +to activating the night light. + ### Light presets The presets functionality was written with the original lamp firemware functionality in mind: @@ -227,6 +244,7 @@ or parts of the front panel are involved in the touch events. ```yaml binary_sensor: - platform: xiaomi_bslamp2 + id: my_bedside_lamp_power_button part: POWER_BUTTON on_press: then: @@ -245,7 +263,7 @@ the following identifiers are available: * **name** (*Optional*, string): The name of the binary sensor. Setting a name will expose the binary sensor as an entity in Home Assistant. If you do not need this, you can omit the name. * **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id, - you can reference the binary_sensor from automation rules (e.g. to retrieve the current state + you can reference the binary_sensor from automation rules (to retrieve the current state of the binary_sensor). * **part** (*Optional*, part identifier): This specifies what part of the front panel the binary sensor must look at. Valid options are: "any" (the default) or one of the abovementioned part identifiers. @@ -253,9 +271,68 @@ the following identifiers are available: ## Component: sensor +The sensor component publishes touch events for the front panel slider. The published value +represents the level at which the slider was touched. + +*Note: This sensor only reports the touched slider level. It cannot be used for detecting release +events. If you want to handle touch/release events for the slider, then you can make use of +the [binary_sensor](#component-binary_sensor) instead.* + +```yaml +sensor: + - platform: xiaomi_bslamp2 + - id: my_bedside_lamp_slider_level + range_from: 0.2 + range_to: 0.9 + on_value: + then: + - light.turn_on: + id: my_bedside_lamp + brightness: !lambda return x; +``` + +### Configuration variables: + +* **name** (*Optional*, string): The name of the sensor. Setting a name will expose the + sensor as an entity in Home Assistant. If you do not need this, you can omit the name. +* **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id, + you can reference the sensor from automation rules (e.g. to retrieve the current state + of the binary_sensor). +* **range_from** (*Optional*, float): By default, published values vary from the range 0.01 to 1.00, + in 20 steps. This option modifies the lower bound of the range. +* **range_to** (*Optional*, float): This option modifies the upper bound of the range. +* All other options from [Sensor](https://esphome.io/components/sensor/index.html#config-sensor). + ## Component: output -## Component: text_output +The (float) output component is linked to the front panel illumination + level indicator. +Setting this output to value 0.0 will turn off the frontpanel illumination. Other values, +up to 1.0, will turn on the illumination and will set the level indicator to the requested +level (in 10 steps). + +```yaml +output: + - platform: xiaomi_bslamp2 + id: my_bedside_lamp_front_panel_illumination +``` + +### Configuration variables: + +* **id** (**Required**, ID): The id to use for this output component. +* All other options from [Output](https://esphome.io/components/output/index.html) + +## Component: text_sensor + +The text sensor component publishes changes in the active [light mode](#light-modes). +Possible output values for this sensor are: "off", "rgb", "white" and "night". +### Configuration variables: + +* **name** (*Optional*, string): The name of the text sensor. Setting a name will expose the + text sensor as an entity in Home Assistant. If you do not need this, you can omit the name. +* **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id, + you can reference the text sensor from automation rules (to retrieve the current state + of the text_sensor). +* All other options from [Text Sensor](https://esphome.io/components/text_sensor/index.html) < [Installation guide](installation.md) | [Index](../README.md) | [Flashing guide](flashing.md) > diff --git a/doc/flashing.md b/doc/flashing.md index 9222bbd..a0efad5 100644 --- a/doc/flashing.md +++ b/doc/flashing.md @@ -1,3 +1,5 @@ +< [Configuration guide](configuration.md) | [Index](../README.md) | [Known issues](known_issues.md) > + # Flashing guide ## Tools needed @@ -195,3 +197,5 @@ https://github.com/arendst/Tasmota/tree/firmware/firmware/tasmota32/ESP32_needed (remember that the [esphome-flasher](https://github.com/esphome/esphome-flasher) will give you a bit less of a hard-core experience during flashing) + +< [Configuration guide](configuration.md) | [Index](../README.md) | [Known issues](known_issues.md) > diff --git a/doc/installation.md b/doc/installation.md index 57d725c..c29df3a 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,3 +1,5 @@ +< [Why custom firmware?](why_custom_firmware.md) | [Index](../README.md) | [Configuration guide](configuration.md) > + # Installation guide The code must be compiled using ESPHome. Therefore, a prerequisite is that @@ -57,3 +59,5 @@ can flash new versions of the firmware using the OTA (Over The Air) method. See [doc/flashing.md](the flashing guide) for hints on opening up the device and flashing its firmware using its serial interface. + +< [Why custom firmware?](why_custom_firmware.md) | [Index](../README.md) | [Configuration guide](configuration.md) > diff --git a/doc/known_issues.md b/doc/known_issues.md index 21dbe31..769fb0e 100644 --- a/doc/known_issues.md +++ b/doc/known_issues.md @@ -1,3 +1,5 @@ +< [Flashing guide](flashing.md) | [Index](../README.md) | [Sponsoring](sponsoring.md) > + # Known issues ## The device keeps losing its connection to Home Assistant @@ -81,3 +83,4 @@ the ESP32. For this reason, I advise to completely omit logging or use a very low log level for production purposes. +< [Flashing guide](flashing.md) | [Index](../README.md) | [Sponsoring](sponsoring.md) > diff --git a/doc/sponsoring.md b/doc/sponsoring.md index d9076e8..86d9889 100644 --- a/doc/sponsoring.md +++ b/doc/sponsoring.md @@ -1,3 +1,5 @@ +< [Known issues](known_issues.md) | [Index](../README.md) + # Sponsoring the project All development on this firmware is done for the greater good of mankind. @@ -15,3 +17,5 @@ this project were: * a simple 8 port logic analyzer that helped me with reverse engineering the I2C protocol of the front panel. * Various wires and buttons. + +< [Known issues](known_issues.md) | [Index](../README.md) diff --git a/doc/why_custom_firmware.md b/doc/why_custom_firmware.md index b9175fb..c2b4249 100644 --- a/doc/why_custom_firmware.md +++ b/doc/why_custom_firmware.md @@ -1,3 +1,5 @@ +[Index](../README.md) | [Installation guide](installation.md) > + # Why custom ESPHome firmware? This lamp could always be added to Home Assistant using the Yeelight @@ -35,3 +37,4 @@ separate GitHub repository: https://github.com/mmakaay/esphome-yeelight_bs2-revengineering +[Index](../README.md) | [Installation guide](installation.md) >