Current based cover (#905)
* Current base cover documentation * Minor doc fixes * Improving doc. Adding shelly 2.5 image. Add component to index * adding malfunction detection * Adding missing image to index * Apply suggestions from code review Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl> Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
This commit is contained in:
parent
33ba298b13
commit
b40fe3ca16
|
@ -0,0 +1,265 @@
|
|||
Current Based Cover
|
||||
===================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up current-based covers in ESPHome.
|
||||
:image: window-open.jpg
|
||||
|
||||
The ``current_based`` cover platform allows you to create covers with position control by using current
|
||||
sensors to detect the fully-open and fully-closed states. This is pretty useful when using motors with
|
||||
integrated mechanical endstops. During cover operation, the component monitors the current consumption
|
||||
to detect when the motor has stopped.
|
||||
|
||||
When fully open or close is requested, the corresponding relay will stay on until the current the motor is
|
||||
consuming goes below a certain amount. The amount of current needs to be specified in the configuration.
|
||||
|
||||
Open and close durations can be specified to allow ESPHome to approximate the current position of the cover.
|
||||
|
||||
.. figure:: images/more-info-ui.png
|
||||
:align: center
|
||||
:width: 75.0%
|
||||
|
||||
This type of cover also provides safety features like current-based obstacle detection with automatic configurable
|
||||
rollback as well as relay malfunction detection: operation cancels if there's a current flowing in the opposite
|
||||
operation circuit (typically caused by welded relays).
|
||||
|
||||
.. warning::
|
||||
|
||||
Depending on the cover and motor type, obstacles can physically damage the cover before being detectable.
|
||||
Verify your setup to ensure the current consumption will increase enough to be detectable before causing
|
||||
any physical damage. Use it at your own risk.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
cover:
|
||||
- platform: current_based
|
||||
name: "Current Based Cover"
|
||||
|
||||
open_sensor: open_current_sensor
|
||||
open_moving_current_threshold: 0.5
|
||||
open_obstacle_current_threshold: 0.8
|
||||
open_duration: 12s
|
||||
open_action:
|
||||
- switch.turn_on: open_cover_switch
|
||||
|
||||
close_sensor: close_current_sensor
|
||||
close_moving_current_threshold: 0.5
|
||||
close_obstacle_current_threshold: 0.8
|
||||
close_duration: 10s
|
||||
close_action:
|
||||
- switch.turn_on: close_cover_switch
|
||||
|
||||
stop_action:
|
||||
- switch.turn_off: close_cover_switch
|
||||
- switch.turn_off: open_cover_switch
|
||||
|
||||
obstacle_rollback: 30%
|
||||
start_sensing_delay: 0.8s
|
||||
|
||||
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **name** (**Required**, string): The name of the cover.
|
||||
- **open_sensor** (**Required**, :ref:`config-id`): The open current sensor.
|
||||
- **open_action** (**Required**, :ref:`Action <config-action>`): The action that should
|
||||
be performed when the remote requests the cover to be opened.
|
||||
- **open_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
|
||||
to open up from the fully-closed state.
|
||||
- **open_moving_current_threshold** (**Required**, float): The amount of current in Amps the motor
|
||||
should drain to consider the cover is opening.
|
||||
- **open_obstacle_current_threshold** (**Required**, float): The amount of current in Amps the motor
|
||||
should drain to consider the cover is blocked during opening.
|
||||
- **close_sensor** (**Required**, :ref:`config-id`): The close current sensor.
|
||||
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should
|
||||
be performed when the remote requests the cover to be closed.
|
||||
- **close_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
|
||||
to close from the fully-open state.
|
||||
- **close_moving_current_threshold** (**Required**, float): The amount of current in Amps the motor
|
||||
should drain to consider the cover is closing.
|
||||
- **close_obstacle_current_threshold** (**Required**, float): The amount of current in Amps the motor
|
||||
should drain to consider the cover is blocked during closing.
|
||||
- **stop_action** (**Required**, :ref:`Action <config-action>`): The action that should
|
||||
be performed to stop the cover.
|
||||
- **max_duration** (*Optional*, :ref:`config-time`): The maximum duration the cover should be opening
|
||||
or closing. Useful for protecting from dysfunctional motor integrated endstops.
|
||||
- **start_sensing_delay** (*Optional*, :ref:`config-time`): The amount of time the current sensing will be
|
||||
disabled when the movement starts. Motors can take some time before reaching their average consumption.
|
||||
Low values can cause an immediate stop because of the first current reading happening in the current-rising period.
|
||||
Defaults to ``500ms``.
|
||||
- **obstacle_rollback** (*Optional*, percentage): The percentage of rollback the cover will perform in case of
|
||||
obstacle detection. Defaults to ``10%``.
|
||||
- **malfunction_detection** (*Optional*, boolean): Enable to detect malfunction detection (Tipically welded realys). Defaults to ``True``.
|
||||
- **malfunction_action** (*Optional*, :ref:`Action <config-action>`): The action that should
|
||||
be performed when relay malfunction is detected. Malfunction may require device servicing. You can use this action
|
||||
to notify other systems about this situation
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||
- All other options from :ref:`Cover <config-cover>`.
|
||||
|
||||
Use with Shelly 2.5
|
||||
-------------------
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up current-based covers in ESPHome using a Shelly 2.5.
|
||||
:image: shelly2.5.png
|
||||
|
||||
The Shelly 2.5 is the perfect hardware for this platform. It features two outputs with current monitoring
|
||||
(thanks to an embedded :doc:`ADE7953 </components/sensor/ade7953>`) in a very small form factor (39mm x 36mm x 17 mm).
|
||||
It also features an :doc:`NTC temperature sensor </components/sensor/ntc>`.
|
||||
|
||||
.. figure:: images/shelly2.5.png
|
||||
:align: center
|
||||
:width: 30.0%
|
||||
|
||||
These devices typically run hot (~55Cº at 20ºC room temperature). Long-term heavy loads (near to its rated limit) can overheat the device.
|
||||
It is strongly recommended to monitor the device temperature using the NTC temperature sensor, shutting down the device if it exceeds 90ºC.
|
||||
This safety feature is also present in the original firmware.
|
||||
|
||||
.. warning::
|
||||
|
||||
The ADE7953 IRQ line is connected to the GPIO16. The ``irq_pin`` parameter for the :doc:`ADE7953 </components/sensor/ade7953>` MUST be
|
||||
set to GPIO16 to prevent device overheat (>70ºC idling).
|
||||
|
||||
Configuration example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
esphome:
|
||||
name: Shelly 2.5
|
||||
platform: ESP8266
|
||||
board: esp01_1m
|
||||
esp8266_restore_from_flash: true
|
||||
|
||||
i2c:
|
||||
sda: GPIO12
|
||||
scl: GPIO14
|
||||
|
||||
sensor:
|
||||
- platform: ade7953
|
||||
irq_pin: GPIO16
|
||||
voltage:
|
||||
name: Shelly 2.5 Mains Voltage
|
||||
internal: true
|
||||
filters:
|
||||
- throttle: 5s
|
||||
current_a:
|
||||
name: Shelly 2.5 Open Current
|
||||
id: open_current
|
||||
internal: true
|
||||
current_b:
|
||||
name: Shelly 2.5 Close Current
|
||||
id: close_current
|
||||
internal: true
|
||||
update_interval: 0.5s
|
||||
|
||||
# NTC Temperature
|
||||
- platform: ntc
|
||||
sensor: temp_resistance_reading
|
||||
name: Shelly 2.5 Temperature
|
||||
unit_of_measurement: "°C"
|
||||
accuracy_decimals: 1
|
||||
calibration:
|
||||
b_constant: 3350
|
||||
reference_resistance: 10kOhm
|
||||
reference_temperature: 298.15K
|
||||
on_value_range:
|
||||
above: 90
|
||||
then: # Security shutdown by overheating
|
||||
- switch.turn_on: _shutdown
|
||||
|
||||
- platform: resistance
|
||||
id: temp_resistance_reading
|
||||
sensor: temp_analog_reading
|
||||
configuration: DOWNSTREAM
|
||||
resistor: 32kOhm
|
||||
internal: true
|
||||
- platform: adc
|
||||
id: temp_analog_reading
|
||||
pin: A0
|
||||
update_interval: 30s
|
||||
internal: true
|
||||
|
||||
binary_sensor:
|
||||
- platform: gpio
|
||||
pin:
|
||||
number: GPIO13
|
||||
name: Shelly 2.5 Open Button
|
||||
on_press:
|
||||
then:
|
||||
cover.open: blind
|
||||
|
||||
- platform: gpio
|
||||
pin:
|
||||
number: GPIO5
|
||||
name: Shelly 2.5 Close Button
|
||||
on_press:
|
||||
then:
|
||||
cover.close: blind
|
||||
|
||||
switch:
|
||||
- platform: shutdown
|
||||
id: _shutdown
|
||||
name: Shelly 2.5 Shutdown
|
||||
|
||||
- platform: gpio
|
||||
id: open_relay
|
||||
name: Shelly 2.5 Open Relay
|
||||
pin: GPIO15
|
||||
restore_mode: RESTORE_DEFAULT_OFF
|
||||
interlock: &interlock [open_relay, close_relay]
|
||||
interlock_wait_time: 200ms
|
||||
|
||||
- platform: gpio
|
||||
id: close_relay
|
||||
name: Shelly 2.5 Close Relay
|
||||
pin: GPIO4
|
||||
restore_mode: RESTORE_DEFAULT_OFF
|
||||
interlock: *interlock
|
||||
interlock_wait_time: 200ms
|
||||
|
||||
# Example configuration entry
|
||||
cover:
|
||||
- platform: current_based
|
||||
name: Blind
|
||||
id: blind
|
||||
|
||||
open_sensor: open_current
|
||||
open_moving_current_threshold: 0.5
|
||||
open_duration: 12s
|
||||
open_action:
|
||||
- switch.turn_on: open_relay
|
||||
close_sensor: close_current
|
||||
close_moving_current_threshold: 0.5
|
||||
close_duration: 10s
|
||||
close_action:
|
||||
- switch.turn_on: close_relay
|
||||
stop_action:
|
||||
- switch.turn_off: close_relay
|
||||
- switch.turn_off: open_relay
|
||||
obstacle_rollback: 30%
|
||||
start_sensing_delay: 0.8s
|
||||
malfunction_detection: true
|
||||
malfunction_action:
|
||||
then:
|
||||
- logger.log: "Malfunction detected. Relay welded."
|
||||
|
||||
|
||||
|
||||
status_led:
|
||||
pin:
|
||||
number: GPIO0
|
||||
inverted: yes
|
||||
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :doc:`/components/cover/template`
|
||||
- :doc:`/components/sensor/ade7953`
|
||||
- :ref:`automation`
|
||||
- :apiref:`current_based/current_based_cover.h`
|
||||
- :ghedit:`Edit`
|
Binary file not shown.
After Width: | Height: | Size: 95 KiB |
|
@ -496,6 +496,7 @@ Cover Components
|
|||
Cover Core, components/cover/index, folder-open.svg
|
||||
Template Cover, components/cover/template, description.svg
|
||||
Endstop Cover, components/cover/endstop, electric-switch.svg
|
||||
Current-Based Cover, components/cover/current_based, flash.svg
|
||||
Time-Based Cover, components/cover/time_based, timer.svg
|
||||
Custom Cover, components/cover/custom, language-cpp.svg
|
||||
AM43 Cover, components/cover/am43, am43.jpg
|
||||
|
|
Loading…
Reference in New Issue