Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-12-30 18:09:26 +01:00
Code Issues Projects Releases Wiki Activity
c7caebd64e
esphome-docs/components/cover/current_based.rst
Jesse Hills 75107305c9
Some docs tidy up (#1895)
2022-02-11 11:10:43 +13:00

263 lines
9.1 KiB
ReStructuredText
Raw Blame History

Current Based Cover
===================
.. seo::
:description: Instructions for setting up current-based covers in ESPHome.
:image: window-open.svg
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
-------------------
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
esp8266:
board: esp01_1m
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`
Reference in New Issue View Git Blame Copy Permalink