262 lines
9.2 KiB
ReStructuredText
262 lines
9.2 KiB
ReStructuredText
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
|
|
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`
|