You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

484 lines
18 KiB

3 years ago
  1. < [Installation guide](installation.md) | [Index](../README.md) | [Flashing guide](flashing.md) >
  2. # Configuration guide
  3. I think, the best starting point for creating your own yaml configuration, is to look at the
  4. [`example.yaml`](../example.yaml) file and the [configuration packages](../packages).
  5. These configuration files were written with the functionality of the original firmware in
  6. mind and it makes use of all available options. This configuration guide can be used to fill
  7. in the blanks.
  8. The `xiaomi_bslamp2` platform provides various components that expose the core functionalities of
  9. the lamp. In the following table, you can find what components are used for exposing what physical
  10. components of the lamp.
  11. | Part | Component(s) |
  12. | -------------------------- |------------------------------------------------------------------|
  13. | ESP32 pinouts | [platform xiaomi_bslamp2](#platform-xiaomi_bslamp2) |
  14. | RGBWW LEDs | [light](#light) |
  15. | Front Panel Power button | [binary_sensor](#component-binary_sensor) |
  16. | Front Panel Color button | [binary_sensor](#component-binary_sensor) |
  17. | Front Panel Slider | [binary_sensor](#component-binary_sensor) (touch/release) |
  18. | | [sensor](#component-sensor) (touched slider level) |
  19. | Front Panel Illumination | [output](#component-output) (on/off + indicator level) |
  20. | Light mode propagation | [text_sensor](#component-text_sensor) |
  21. ## Platform: xiaomi_bslamp2
  22. At the core of the hardware support is the `xiaomi_bslamp2` platform, which provides two hub-style
  23. hardware abstraction layer (HAL) components that are used by the other components: one for driving
  24. the GPIO's for the RGBWW leds and one for the I2C communication between the ESP32 and the front
  25. panel.
  26. I do mention the platform configuration here for completeness sake, but **generally you will not have
  27. to add the following configuration option to your yaml file**. It is loaded automatically by the
  28. components that need it, and the GPIO + I2C configurations are fully prepared to work for the
  29. Bedside Lamp 2 wiring out of the box. Therefore, you will not find this piece of configuration in
  30. the [`example.yaml`](../example.yaml).
  31. Having said that, here are the configuration options:
  32. ```yaml
  33. xiaomi_bslamp2:
  34. # Options for the RGBWW LEDs HAL.
  35. red: "GPIO13"
  36. green: "GPIO14"
  37. blue: "GPIO5"
  38. white: "GPIO12"
  39. master_1: "GPIO33"
  40. master_2: "GPIO4"
  41. # Options for the Front Panel HAL.
  42. sda: "GPIO21"
  43. scl: "GPIO19"
  44. address: 0x2C
  45. trigger_pin: "GPIO16"
  46. ```
  47. The only reason that I can think of for adding this platform configuration to your yaml file, would
  48. be if you blew one or more or the ESP32 pins, and need to rewire functionality. In other casis,
  49. simply omit the section.
  50. ## Component: light
  51. The light component creates an RGBWW light. This means that it can do colored light and cold/warm
  52. white light based on a color temperature.
  53. ```yaml
  54. light:
  55. - platform: xiaomi_bslamp2
  56. name: My Bedside Lamp
  57. id: my_bedside_lamp
  58. default_transition_length: 0.5s
  59. effects:
  60. - random:
  61. name: Randomize
  62. transition_length: 3s
  63. update_interval: 3s
  64. on_brightness:
  65. - then:
  66. - logger.log: The brightness changed!
  67. presets:
  68. my_color_presets:
  69. red: { red: 100%, green: 0%, blue: 0% }
  70. green: { red: 0%, green: 100%, blue: 0% }
  71. blue: { red: 0%, green: 0%, blue: 100% }
  72. yellow: { red: 100%, green: 100%, blue: 0% }
  73. purple: { red: 100%, green: 0%, blue: 100% }
  74. randomize: { effect: Randomize }
  75. my_white_presets:
  76. cold: { color_temperature: 153 mireds }
  77. chilly: { color_temperature: 275 mireds }
  78. luke: { color_temperature: 400 mireds }
  79. warm: { color_temperature: 588 mireds
  80. ```
  81. ### Configuration variables:
  82. * **name** (**Required**, string): The name of the light.
  83. * **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id,
  84. you can reference the light from automation rules (e.g. to turn on the light when the power button
  85. is tapped)
  86. * **default_transition_length** (*Optional*, Time): The transition length to use when no transition
  87. length is set in a light call. Defaults to 1s.
  88. * **effects** (*Optional*, list): A list of
  89. [light effects](https://esphome.io/components/light/index.html#light-effects) to use for this light.
  90. * **presets** (*Optional*, dict): Used to define presets, that can be used from automations. See
  91. [below](#light-presets) for detailed information.
  92. * **on_brightness** (*Optional*, Action): An automation to perform when the brightness of the light
  93. is modified.
  94. * All other options from
  95. [the base Light implementation](https://esphome.io/components/light/index.html#config-light),
  96. except for options that handle color correction options like `gamma_correct` and `color_correct`.
  97. These options are superceded by the fact that the light component has a fully customized light
  98. model, that closely follows the light model of the original lamp's firmware.
  99. ### Light modes
  100. The lamp supports multiple light modes. These are:
  101. * **RGB light** (input: RGB + brightness > 1%)
  102. * **White light** (input: Color Temperature + brightness > 1%)
  103. * **Night light** (input: RGB or White light + brightness at 1%)
  104. In the original firmware + Yeelight Home Assistant integration, the night light feature is
  105. implemented through a switch component. The switch can be turned on to activate the night light
  106. mode. In this ESPHome firmware, setting the brightness to its lowest value triggers the night light
  107. mode. This makes things a lot easier to control.
  108. It is possible to control the night light mode separately. An example of this can be found in the
  109. [example.yaml](../example.yaml), in which holding the power button is bound to activating the night
  110. light.
  111. ### `light.disco_on` Action
  112. This action sets the state of the light immediately (i.e. without waiting for the next main loop
  113. iteration), without saving the state to memory and without publishing the state change.
  114. ```yaml
  115. on_...:
  116. then:
  117. - light.disco_on:
  118. id: my_bedside_lamp
  119. brightness: 80%
  120. red: 70%
  121. green: 0%
  122. blue: 100%
  123. ```
  124. The possible configuration options for this Action are the same as those for the standard
  125. `light.turn_on` Action.
  126. ### `light.disco_off` Action
  127. This action turns off the disco mode by restoring the state of the lamp to the last known state from
  128. before using the disco mode.
  129. ```yaml
  130. on_...:
  131. then:
  132. - light.disco_off:
  133. id: my_bedside_lamp
  134. ```
  135. ### Light presets
  136. The presets functionality was written with the original lamp firemware functionality in mind: the
  137. user has two groups of presets available: one for RGB light presets and one for white light presets
  138. (based on color temperature). The color button (the top one on the front panel) can be tapped to
  139. switch to the next preset within the active preset group. The same button can be held for a little
  140. while, to switch to the other preset group.
  141. In your light configuration, you can mimic this behavior (in fact: it is done so in the
  142. [example.yaml](../example.yaml)) by means of the presets system. This system consists of two parts:
  143. * Defining presets
  144. * Activating presets from automations
  145. **Defining presets**
  146. Presets can be configured in the `presets` option of the `light` configuration.
  147. Presets are arranged in groups. You can define as little or as many groups as you like. The example
  148. configuration uses two groups, but that is only to mimic the original behavior. If you only need one
  149. group, then create one group. If you need ten, go ahead and knock yourself out.
  150. The general structure of the presets configuration is:
  151. ```yaml
  152. light:
  153. presets:
  154. group_1:
  155. preset_1: ...
  156. preset_2: ...
  157. ..
  158. group_2:
  159. preset_1: ...
  160. preset_2: ...
  161. ..
  162. ..
  163. ```
  164. *Note: Duplicate template names are ok, as long as they are within their own group. If you use
  165. duplicate preset names within a single group, then the last preset will override the earlier
  166. one(s).*
  167. A preset can define one of the following:
  168. * **RGB light**
  169. * **red** (**Optional**, percentage): the red component of the RGB value (default = 0%).
  170. * **green** (**Optional**, percentage): the green component of the RGB value (default = 0%).
  171. * **blue** (**Optional**, percentage): the blue component of the RGB value (default = 0%).
  172. * **brightness** (*Optional*, percentage): the brightness to use (default = current brightness).
  173. * **transition_length** (*Optional*, time): the transition length to use.
  174. * **White light**
  175. * **color_temperature** (**Required**, mireds): the color temperature in mireds (range: "153 mireds" - "588 mireds")
  176. * **brightness** (*Optional*, percentage): the brightness to use (default = current brightness).
  177. * **transition_length** (*Optional*, time): the transition length to use.
  178. * **Light effect**
  179. * **effect** (**Required**, string): the name of a light effect to activate.
  180. * **Brightness change only**
  181. * **brightness** (**Required**, percentage): the brightness to use.
  182. **Activating presets from automations**
  183. Once presets have been configured, they can be activated using the `preset.activate` action. The
  184. following options are available for this action:
  185. * Switch to next preset group (and after the last, switch to the first):
  186. ```yaml
  187. preset.activate:
  188. next: group
  189. ```
  190. * Switch to next preset within currentl preset group (and after the last,
  191. switch to the first):
  192. ```yaml
  193. preset.activate:
  194. next: preset
  195. ---
  196. * Activate a specific preset group by specifying the group's name:
  197. ```yaml
  198. preset.activate:
  199. group: rgb
  200. ```
  201. * Activate a specific preset by specifying both the preset's name and group name:
  202. ```yaml
  203. preset.activate:
  204. group: white
  205. preset: warm
  206. ```
  207. Shorthand definitions are available for all these actions:
  208. ```yaml
  209. preset.activate: next_group
  210. preset.activate: next_preset
  211. preset.activate: rgb
  212. preset.activate: white.warm
  213. ```
  214. **Handling of invalid input**
  215. When a group or template is specified that does not exist, or if next group/preset is used while no
  216. presets have been defined at all, then the action will be ignored and an error will be logged.
  217. *Note: This is validation at run time. It would be a lot better to validate the names at compile
  218. time more strictly, so the firmware will not even compile when invalid names are in use.
  219. [Issue #15](https://github.com/mmakaay/esphome-xiaomi_bslamp2/issues/15) was created for
  220. implementing this. However, a new feature in ESPHome is required to be able to do this
  221. implementation. Good news is that this is already well on its way.*
  222. ## Component: binary_sensor
  223. Binary sensors can be added to the configuration for handling touch/release events for the front
  224. panel. On touch, a binary_sensor will publish `True`, on release it will publish `False`. The
  225. configuration of a binary_sensor determines what part of the front panel is involved in the touch
  226. events.
  227. ```yaml
  228. binary_sensor:
  229. - platform: xiaomi_bslamp2
  230. id: my_bedside_lamp_power_button
  231. for: POWER_BUTTON
  232. on_press:
  233. then:
  234. - light.toggle: my_bedside_lamp
  235. ```
  236. For referencing the parts of the front panel, the following part identifiers are available:
  237. * POWER_BUTTON (or its alias: POWER)
  238. * COLOR_BUTTON (or its alias: COLOR)
  239. * SLIDER
  240. If personal taste dictates so, you can use lower case characters and spaces instead of underscores.
  241. This means that for example "Power Button" and "power" would be valid identifiers for the power
  242. button.
  243. ### Configuration variables:
  244. * **name** (*Optional*, string): The name of the binary sensor. Setting a name will expose the
  245. binary sensor as an entity in Home Assistant. If you do not need this, you can omit the name.
  246. * **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id,
  247. you can reference the binary_sensor from automation rules (to retrieve the current state of the
  248. binary_sensor).
  249. * **for** (*Mandatory*, part identifier): This specifies to for part of the front panel the binary
  250. sensor must report touch events.
  251. * All other options from
  252. [Binary Sensor](https://esphome.io/components/binary_sensor/index.html#config-binary-sensor).
  253. ## Component: sensor
  254. The sensor component publishes touch events for the front panel slider. The published value
  255. represents the level at which the slider was touched.
  256. *Note: This sensor only reports the touched slider level. It cannot be used for detecting release
  257. events. If you want to handle touch/release events for the slider, then you can make use of the
  258. [binary_sensor](#component-binary_sensor) instead.*
  259. ```yaml
  260. sensor:
  261. - platform: xiaomi_bslamp2
  262. - id: my_bedside_lamp_slider_level
  263. range_from: 0.2
  264. range_to: 0.9
  265. on_value:
  266. then:
  267. - light.turn_on:
  268. id: my_bedside_lamp
  269. brightness: !lambda return x;
  270. ```
  271. ### Configuration variables:
  272. * **name** (*Optional*, string): The name of the sensor. Setting a name will expose the sensor as an
  273. entity in Home Assistant. If you do not need this, you can omit the name.
  274. * **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id,
  275. you can reference the sensor from automation rules (e.g. to retrieve the current state of the
  276. binary_sensor).
  277. * **range_from** (*Optional*, float): By default, published values vary from the range 0.01 to 1.00,
  278. in 20 steps. This option modifies the lower bound of the range.
  279. * **range_to** (*Optional*, float): This option modifies the upper bound of the range.
  280. * All other options from
  281. [Sensor](https://esphome.io/components/sensor/index.html#config-sensor).
  282. ## Component: output
  283. The (float) output component is linked to the front panel illumination + level indicator. Setting
  284. this output (using the standard `output.set_level` action) to value 0.0 will turn off the frontpanel
  285. illumination. Other values, up to 1.0, will turn on the illumination and will set the level indicator
  286. to the requested level (in 10 steps).
  287. ```yaml
  288. output:
  289. - platform: xiaomi_bslamp2
  290. id: my_bedside_lamp_front_panel_illumination
  291. ```
  292. ### Configuration variables:
  293. * **id** (**Required**, ID): The id to use for this output component.
  294. * All other options from [Output](https://esphome.io/components/output/index.html)
  295. ### Addressing the LEDs of the illumination individually
  296. While the standard `output.set_level` action emulates the front panel illumination behavior
  297. of the original device firmware, it is also possible to control all of the LEDs for this
  298. illumination individually, in case you need some different behavior, e.g. leaving the
  299. power button on at night, so the user can easily find it in the dark.
  300. To address the LEDs, the following identifiers can be used in your YAML configuration:
  301. * `POWER` : The power button illumination.
  302. * `COLOR` : The color button illumination.
  303. * `1`, `2`, .., `10` : The 10 LEDs on the slider, where LED `1` is closest to the
  304. power button and LED `10` is closest to the color button.
  305. * `ALL` : represents all of the available LEDs
  306. * `NONE` : represents none of the available LEDs
  307. #### `front_panel.set_leds` Action
  308. This action turns on the provided LEDs, all other LEDs are turned off.
  309. ```yaml
  310. on_...:
  311. then:
  312. - front_panel.set_leds:
  313. leds:
  314. - POWER
  315. - COLOR
  316. - 1
  317. - 2
  318. - 3
  319. ```
  320. The `leds:` key can also be omitted here, making the following action calls
  321. equivalent to the one above.
  322. ```yaml
  323. on_...:
  324. then:
  325. - front_panel.set_leds:
  326. - POWER
  327. - COLOR
  328. - 1
  329. - 2
  330. - 3
  331. ```
  332. This can also be written as:
  333. ```yaml
  334. on_...:
  335. then:
  336. - front_panel.set_leds: [ POWER, COLOR, 1, 2, 3 ]
  337. ```
  338. If only one LED is specified, you are allowed to omit the list definition:
  339. ```yaml
  340. on_...:
  341. then:
  342. - front_panel.set_leds: POWER
  343. ```
  344. #### `front_panel.turn_on_leds` Action
  345. This action turns on the provided LEDs, and leaves the rest of the LEDs as-is.
  346. The LEDs to affect are specified in the same wat as above for `front_panel.set_leds`.
  347. #### `front_panel.turn_off_leds` Action
  348. This action turns off the provided LEDs, and leaves the rest of the LEDs as-is.
  349. The LEDs to affect are specified in the same wat as above for `front_panel.set_leds`.
  350. #### `front_panel.set_level` Action
  351. This action works like the `output.set_level` action, but it only updates the
  352. LEDs of the slider. The LEDs for the power and color button are left as-is.
  353. ```yaml
  354. on_...:
  355. then:
  356. - front_panel.set_level: 0.5
  357. ```
  358. #### `front_panel.update_leds` Action
  359. The previous actions only modify the required state for the front panel LEDs.
  360. Updating the actual state of the LEDs is done when the main loop for the
  361. output component is run by ESPHome.
  362. If you need the required state to be pushed to the LEDs immediately, regardless
  363. the main loop, then this action can ben used to take care of this.
  364. *Note: In most situations, you will not need to use this action explicitly
  365. to make the LEDs update. Only use it when you are sure that this is required.*
  366. ```yaml
  367. on_...:
  368. then:
  369. - front_panel.set_leds: POWER
  370. - front_panel.update_leds:
  371. ```
  372. ## Component: text_sensor
  373. The text sensor component publishes changes in the active [light mode](#light-modes). Possible
  374. output values for this sensor are: "off", "rgb", "white" and "night".
  375. ### Configuration variables:
  376. * **name** (*Optional*, string): The name of the text sensor. Setting a name will expose the text
  377. sensor as an entity in Home Assistant. If you do not need this, you can omit the name.
  378. * **id** (*Optional*, ID): Manually specify the ID used for code generation. By providing an id,
  379. you can reference the text sensor from automation rules (to retrieve the current state of the
  380. text_sensor).
  381. * All other options from
  382. [Text Sensor](https://esphome.io/components/text_sensor/index.html)
  383. < [Installation guide](installation.md) | [Index](../README.md) | [Flashing guide](flashing.md) >