From d93d706fe99727a1dbfc1b2f3e4ce373ed536a4c Mon Sep 17 00:00:00 2001 From: Oleg Tarasov Date: Fri, 15 Nov 2024 18:57:26 +0300 Subject: [PATCH 1/4] Added documentation on Shelly Dimmer calibration capability --- components/light/shelly_dimmer.rst | 60 ++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst index 7b5899067a..ae7f5ed6b0 100644 --- a/components/light/shelly_dimmer.rst +++ b/components/light/shelly_dimmer.rst @@ -93,6 +93,66 @@ Configuration variables: - All other options from :ref:`Light `. +Automatic calibration +--------------------- + +Many dimmable light bulbs have non-linear characteristic. This means that changing brightness from 100% to 80% can +have no visible change, but a change from 50% to 40% can decrease visible output by a third. You can partially overcome +this by hand-picking ``min_brightness`` and ``max_brightness`` values, but this only helps in aligning 0% and 100% +levels to the actual output. The curve between these values is still likely to be non-linear. Original Shelly firmware +supports automatic calibration that helps make this curve more linear resulting in smoother control across the whole +spectrum. + +An attempt was made to replicate this process in Shelly Dimmer component for ESPHome. In order to be able to calibrate +your dimmer, you need to take several steps: + +1. Optionally remove ``min_brightness`` and ``max_brightness`` from your Shelly ``light`` section. Calibration process + will respect these values if they are set, but they are not needed unless you intentionally wish to limit your + brightness levels. +2. Add ``update_interval: 1s`` to your Shelly ``light`` section. This is not strictly required, but will greatly + increase the speed of calibration process. ``update_interval`` can be removed after calibration. This + change will result in power, voltage and current sensors being reported to HA every second instead of every 10 + seconds. +3. Add a template button that starts calibration process. You might notice the hardcoded dimmer id — that's because + ``id`` property that you specify in config is used for ``LightState``, not the parent dimmer component. + +.. code-block:: yaml + + button: + - platform: template + id: calibrate_button + name: "Calibrate" + entity_category: config + on_press: + then: + - lambda: |- + shelly_dimmer_shellydimmer_id->start_calibration(); + +4. You can also create another button to clear calibration data and revert your dimmer to its original behavior: + +.. code-block:: yaml + + button: + - platform: template + id: clear_calibration_button + name: "Clear calibration" + entity_category: config + on_press: + then: + - lambda: |- + shelly_dimmer_shellydimmer_id->clear_calibration(); + +5. Set logger level to ``DEBUG`` if you want to observe the calibration process in detail. + +Upload firmware as usual and press the "Calibrate" button that appears in Home Assistant. The following will happen: + +1. Light will be turned on and set to full brightness. +2. Nothing will happen for a warmup period of 20 steps. If you set ``update_interval: 1s``, one step takes one second. +3. Every 3 steps brightness will decrease by 5%. Power drawn by the light bulb will be measured on each step, producing + a single measurement averaged over 3 steps. Calibration process takes 60 steps in total. +4. Calibration results will be saved to device memory and brightness level will be brought back to 100%. +5. Calibration is complete! You can change brightness value and observe whether it became more linear. + See Also -------- From 8bd3fec48cf11c13422eb0d2b7ec3a927d3ce949 Mon Sep 17 00:00:00 2001 From: Oleg Tarasov Date: Sat, 23 Nov 2024 16:55:24 +0300 Subject: [PATCH 2/4] Removed the requirement to set update_interval, used proper id to start calibration --- components/light/shelly_dimmer.rst | 52 ++++++++++++++++-------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst index ae7f5ed6b0..c5cbde7d0f 100644 --- a/components/light/shelly_dimmer.rst +++ b/components/light/shelly_dimmer.rst @@ -109,47 +109,49 @@ your dimmer, you need to take several steps: 1. Optionally remove ``min_brightness`` and ``max_brightness`` from your Shelly ``light`` section. Calibration process will respect these values if they are set, but they are not needed unless you intentionally wish to limit your brightness levels. -2. Add ``update_interval: 1s`` to your Shelly ``light`` section. This is not strictly required, but will greatly - increase the speed of calibration process. ``update_interval`` can be removed after calibration. This - change will result in power, voltage and current sensors being reported to HA every second instead of every 10 - seconds. -3. Add a template button that starts calibration process. You might notice the hardcoded dimmer id — that's because - ``id`` property that you specify in config is used for ``LightState``, not the parent dimmer component. +2. Add ``output_id`` to your ``light`` configuration. This id will be used to access calibration functions from lambdas. +3. Add a template button that calls ``start_calibration`` function to begin calibration process. .. code-block:: yaml + light: + - platform: shelly_dimmer + id: dimmer + output_id: shelly + + button: - - platform: template - id: calibrate_button - name: "Calibrate" - entity_category: config - on_press: - then: - - lambda: |- - shelly_dimmer_shellydimmer_id->start_calibration(); + - platform: template + id: calibrate_button + name: "Calibrate" + entity_category: config + on_press: + then: + - lambda: |- + id(shelly)->start_calibration(); 4. You can also create another button to clear calibration data and revert your dimmer to its original behavior: .. code-block:: yaml button: - - platform: template - id: clear_calibration_button - name: "Clear calibration" - entity_category: config - on_press: - then: - - lambda: |- - shelly_dimmer_shellydimmer_id->clear_calibration(); + - platform: template + id: clear_calibration_button + name: "Clear calibration" + entity_category: config + on_press: + then: + - lambda: |- + id(shelly)->clear_calibration(); 5. Set logger level to ``DEBUG`` if you want to observe the calibration process in detail. Upload firmware as usual and press the "Calibrate" button that appears in Home Assistant. The following will happen: 1. Light will be turned on and set to full brightness. -2. Nothing will happen for a warmup period of 20 steps. If you set ``update_interval: 1s``, one step takes one second. -3. Every 3 steps brightness will decrease by 5%. Power drawn by the light bulb will be measured on each step, producing - a single measurement averaged over 3 steps. Calibration process takes 60 steps in total. +2. Nothing will happen for a warmup period of 20 seconds. +3. Every 3 seconds brightness will decrease by 5%. Power drawn by the light bulb will be measured each second, producing + a single measurement averaged over 3 steps. Calibration process takes 60 seconds in total. 4. Calibration results will be saved to device memory and brightness level will be brought back to 100%. 5. Calibration is complete! You can change brightness value and observe whether it became more linear. From 2bba8d8c196cd77a213924f410b79774784c4edf Mon Sep 17 00:00:00 2001 From: Oleg Tarasov Date: Sat, 23 Nov 2024 17:00:35 +0300 Subject: [PATCH 3/4] Fixed spacing in examples --- components/light/shelly_dimmer.rst | 38 +++++++++++++++--------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst index c5cbde7d0f..727f4d16f2 100644 --- a/components/light/shelly_dimmer.rst +++ b/components/light/shelly_dimmer.rst @@ -115,34 +115,34 @@ your dimmer, you need to take several steps: .. code-block:: yaml light: - - platform: shelly_dimmer - id: dimmer - output_id: shelly + - platform: shelly_dimmer + id: dimmer + output_id: shelly button: - - platform: template - id: calibrate_button - name: "Calibrate" - entity_category: config - on_press: - then: - - lambda: |- - id(shelly)->start_calibration(); + - platform: template + id: calibrate_button + name: "Calibrate" + entity_category: config + on_press: + then: + - lambda: |- + id(shelly)->start_calibration(); 4. You can also create another button to clear calibration data and revert your dimmer to its original behavior: .. code-block:: yaml button: - - platform: template - id: clear_calibration_button - name: "Clear calibration" - entity_category: config - on_press: - then: - - lambda: |- - id(shelly)->clear_calibration(); + - platform: template + id: clear_calibration_button + name: "Clear calibration" + entity_category: config + on_press: + then: + - lambda: |- + id(shelly)->clear_calibration(); 5. Set logger level to ``DEBUG`` if you want to observe the calibration process in detail. From c4ec020398997da27b61958c00117c8082b2265b Mon Sep 17 00:00:00 2001 From: Oleg Tarasov Date: Sat, 23 Nov 2024 17:04:54 +0300 Subject: [PATCH 4/4] More spacing fixes --- components/light/shelly_dimmer.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst index 727f4d16f2..09c0a5cbcf 100644 --- a/components/light/shelly_dimmer.rst +++ b/components/light/shelly_dimmer.rst @@ -122,13 +122,13 @@ your dimmer, you need to take several steps: button: - platform: template - id: calibrate_button - name: "Calibrate" - entity_category: config - on_press: + id: calibrate_button + name: "Calibrate" + entity_category: config + on_press: then: - - lambda: |- - id(shelly)->start_calibration(); + - lambda: |- + id(shelly)->start_calibration(); 4. You can also create another button to clear calibration data and revert your dimmer to its original behavior: