diff --git a/doc/configuration.md b/doc/configuration.md index f37303b..76bc006 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -2,14 +2,15 @@ # Configuration guide -I think, the best starting point for creating your own yaml configuration, is to -look at the [example.yaml](example.yaml) file from the project documentation. -This configuration was written with the functionality of the original firmware in mind -and it makes use of all available options. This configuration guide can be used to -fill in the blanks. +I think, the best starting point for creating your own yaml configuration, +is to look at the [example.yaml](example.yaml) file from the project +documentation. This configuration was written with the functionality of the +original firmware in mind and it makes use of all available options. This +configuration guide can be used to 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. +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 physical components of the lamp. | Part | Component(s) | | -------------------------- |------------------------------------------------------------------| @@ -24,16 +25,17 @@ In the following table, you can find what components are used for exposing what ## Platform: xiaomi_bslamp2 -At the core of the hardware support is the `xiaomi_bslamp2` platform, which provides two -hub-style hardware abstraction layer (HAL) components that are used by the other components: -one for driving the GPIO's for the RGBWW leds and one for the I2C communication between -the ESP32 and the front panel. +At the core of the hardware support is the `xiaomi_bslamp2` platform, which +provides two hub-style hardware abstraction layer (HAL) components that are +used by the other components: one for driving the GPIO's for the RGBWW leds +and one for the I2C communication between the ESP32 and the front panel. -I do mention it 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). +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: @@ -54,14 +56,14 @@ xiaomi_bslamp2: 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 functions -to different pins. +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, simply omit the section. ## Component: light -The light component creates an RGBWW light. This means that it can do colored light and -cold/warm white light based on a color temperature. +The light component creates an RGBWW light. This means that it can do +colored light and cold/warm white light based on a color temperature. ```yaml light: @@ -95,60 +97,68 @@ light: ### Configuration variables: * **name** (**Required**, string): The name of the light. -* **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id, - you can reference the light from automation rules (e.g. to turn on the light when the power - button is tapped) -* **default_transition_length** (*Optional*, Time): The transition length to use when - no transition length is set in a light call. Defaults to 1s. -* **effects** (*Optional*, list): A list of [light effects](https://esphome.io/components/light/index.html#light-effects) +* **id** (*Optional*, ID): Manually specify the ID used for code generation. + By providing an id, you can reference the light from automation rules + (e.g. to turn on the light when the power button is tapped) +* **default_transition_length** (*Optional*, Time): The transition length to + use when no transition length is set in a light call. Defaults to 1s. +* **effects** (*Optional*, list): A list of + [light effects](https://esphome.io/components/light/index.html#light-effects) to use for this light. -* **presets** (*Optional*, dict): Used to define presets, that can be used from automations. - See [below](#light-presets) for detailed information. -* **on_brightness** (*Optional*, Action): An automation to perform when the brightness of the light is modified. -* All other options from [the base Light implementation](https://esphome.io/components/light/index.html#config-light), - except for options that handle color correction options like `gamma_correct` and `color_correct`. - 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. +* **presets** (*Optional*, dict): Used to define presets, that can be used + from automations. See [below](#light-presets) for detailed information. +* **on_brightness** (*Optional*, Action): An automation to perform when the + brightness of the light is modified. +* All other options from [the base Light + implementation](https://esphome.io/components/light/index.html#config-light), + except for options that handle color correction options like + `gamma_correct` and `color_correct`. 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%) +* **RGB light** (input: RGB + brightness > 1%) +* **White light** (input: Color Temperature + brightness > 1%) +* **Night light** (input: RGB or White light + 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. +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. +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: -the user has two groups of presets available: one for RGB light presets and one for white light -presets (based on color temperature). The color button (the top one on the front panel) can be -tapped to switch to the next preset within the active preset group. The same button can be -held for a little while, to switch to the other preset group. +The presets functionality was written with the original lamp firemware +functionality in mind: the user has two groups of presets available: one for +RGB light presets and one for white light presets (based on color +temperature). The color button (the top one on the front panel) can be +tapped to switch to the next preset within the active preset group. The same +button can be held for a little while, to switch to the other preset group. -In your light configuration, you can mimic this behavior (in fact: it is done so in the -[example.yaml](example.yaml)) by means of the presets system. This system consists of two -parts: +In your light configuration, you can mimic this behavior (in fact: it is +done so in the [example.yaml](example.yaml)) by means of the presets system. +This system consists of two parts: * Defining presets * Activating presets from automations **Defining presets** -Presets can be configured in the `presets` option of the `light` configuration. +Presets can be configured in the `presets` option of the `light` +configuration. -Presets are arranged in groups. You can define as little or as many groups as you like. -The example configuration uses two groups, but that is only to mimic the original behavior. -If you only need one group, then create one group. If you need ten, go ahead and knock yourself out. +Presets are arranged in groups. You can define as little or as many groups +as you like. The example configuration uses two groups, but that is only to +mimic the original behavior. If you only need one group, then create one +group. If you need ten, go ahead and knock yourself out. The general structure of the presets configuration is: @@ -166,9 +176,9 @@ light: .. ``` -*Note: duplicate template names are ok, as long as they are within their own group. -If you use duplicate preset names within a single group, then the last preset will override the -earlier one(s).* +*Note: duplicate template names are ok, as long as they are within their own +group. If you use duplicate preset names within a single group, then the +last preset will override the earlier one(s).* A preset can define one of the following: @@ -189,8 +199,9 @@ A preset can define one of the following: **Activating presets from automations** -Once presets have been configured, they can be activated using the `preset.activate` action. -The following options are available for this action: +Once presets have been configured, they can be activated using the +`preset.activate` action. The following options are available for this +action: * Switch to next preset group (and after the last, switch to the first): ```yaml @@ -198,7 +209,8 @@ preset.activate: next: group ``` -* Switch to next preset within currentl preset group (and after the last, switch to the first): +* Switch to next preset within currentl preset group (and after the last, + switch to the first): ```yaml preset.activate: next: preset @@ -228,33 +240,44 @@ preset.activate: white.warm **Handling of invalid input** -When a group or template is specified that does not exist, or if next group/preset -is used while no presets have been defined at all, then the action will be ignored -and an error will be logged. +When a group or template is specified that does not exist, or if next +group/preset is used while no presets have been defined at all, then the +action will be ignored and an error will be logged. + +*Note: This is validation at run time. It would be a lot better to +validate the names at compile time more strictly, so the firmware will not +even compile when invalid names are in use. +[Issue #15](https://github.com/mmakaay/esphome-xiaomi_bslamp2/issues/15) +was created for implementing this. However, a new feature in ESPHome is +required to be able to do this implementation. Good news is that this +is already well on its way.* -This is of course validation at run time. It would be better to validate the -names at compile time more strictly, so the firmware won't compile when invalid -names are in use. [Issue #15 was created for implementing this](https://github.com/mmakaay/esphome-xiaomi_bslamp2/issues/15). ## Component: binary_sensor -Binary sensors can be added to the configuration for handling touch/release events -for the front panel. On touch, a binary_sensor will publish `True`, on release it -will publish `False`. The configuration of a binary_sensor determines what part -or parts of the front panel are involved in the touch events. +Binary sensors can be added to the configuration for handling touch/release +events for the front panel. On touch, a binary_sensor will publish `True`, +on release it will publish `False`. The configuration of a binary_sensor +determines what part or parts of the front panel are involved in the touch +events. -For referencing the parts of the front panel, the following identifiers are available: +For referencing the parts of the front panel, the following identifiers are +available: -* POWER_BUTTON (or its alias: POWER) +* POWER_BUTTON (or POWER) * COLOR_BUTTON (or its alias: COLOR) * SLIDER +If personal taste dictates so, you can use lower case characters and spaces +instead of underscores. This means that for example "Power Button" would also +be a valid identifier. + ```yaml binary_sensor: - platform: xiaomi_bslamp2 id: my_bedside_lamp_power_button for: POWER_BUTTON - on_press: + on_release: then: - light.toggle: my_bedside_lamp @@ -272,24 +295,77 @@ binary_sensor: ### Configuration variables: -* **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 (to retrieve the current state - of the binary_sensor). -* **for** (*Mandatory*, part identifier or list): This specifies what part or parts of the - front panel the binary sensor must look at. When multiple parts are specified here, the - binary_sensor will handle multi-touch events using those parts. -* All other options from [Binary Sensor](https://esphome.io/components/binary_sensor/index.html#config-binary-sensor). +* **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 (to retrieve the current state of the binary_sensor). +* **for** (*Mandatory*, single identifier or a list): This specifies what part + or parts of the front panel the binary sensor must look at. When multiple + parts are specified here, the binary_sensor will handle multi-touch events + using those parts. +* All other options from + [Binary Sensor](https://esphome.io/components/binary_sensor/index.html#config-binary-sensor). + +### Multi-touch support + +When using a multi-touch binary-sensor, beware to use non-conflicting +triggers for any related binary sensors. For example, when you implement a +multi-touch binary sensor for the power + color button, then you probably +should not also be using `on_press` triggers for the two individual buttons. + +First a few definitions: + +* **multi-touch binary sensor**: when two or more parts of the front panel + can be touched concurrently to trigger an automation. A binary sensor can + be defined as multi-touch by configuring two or more parts in the `for:` + parameter. +* **lower order binary sensors**: binary sensors that use a subset of the + parts of a multi-touch binary sensor. For example a binary sensor for the + power button is a lower order binary sensor for a multi-touch binary + sensor for the power + color button. + +Why not use `on_press` for every binary sensor: + +The user of your lamp will very likely not touch the power and color buttons +at the *exact same time*. Therefore, you would first get an `on_press` +trigger for one of these buttons, followed by the `on_press` trigger for the +multi-touch binary sensor. Thus, if you have defined `on_press` for every +binary sensor, then two automations would be triggered. Most likely, this +would be unwanted behavior. + +Interlocking to the rescue: + +Multi-touch binary sensors provide a form of interlocking behavior, to +facilitate their use. + +* When multi-touch binary sensors trigger `on_press`, they will block all + further triggers for their lower order binary sensors. +* These blocks will be released after all involved parts have been released. + +Because of interlocking, in the above example you might first have gotten +an `on_press` trigger for the power button, followed by an `on_press` +trigger for the multi-touch power + color buttons. When after this the +buttons are released, then only the multi-touch binary sensor will trigger +`on_release`. + +TL;DR: + +* If a sensor is a lower order sensor for a multi-touch sensor, then it is + best to only use an `on_release` trigger. +* A multi-touch sensor can also act on other triggers. + ## 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. +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.* +*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: @@ -306,22 +382,27 @@ sensor: ### 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). +* **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 -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). +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: @@ -336,16 +417,19 @@ output: ## 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". +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) +* **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) >