esphome-docs/components/ezo_pmp.rst
2023-01-24 14:56:46 -03:00

572 lines
17 KiB
ReStructuredText

Atlas Scientific Peristaltic Pump
=================================
.. seo::
:description: Instructions for setting up an Atlas Scientific Peristaltic Pump in ESPHome
:image: ezo-pmp.jpg
:keywords: pump, peristaltic, atlas, ezo
The ``ezo_pmp`` component allows you to use an Atlas Scientific Peristaltic Pump with ESPHome.
Both the EZO-PMP (`datasheet <https://files.atlas-scientific.com/EZO_PMP_Datasheet.pdf>`__)
and EZO-PMP-L (`datasheet <https://files.atlas-scientific.com/EZO_PMP_L_Datasheet.pdf>`__) are supported.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. note::
This component will not be directly controllable in the Home Assistant front-end automatically because
Home Assistant doesn't have support for pumps. In order to control the pump from the frontend you will need to use
templates to offer access to the actions you need. Please see :ref:`ezo-pmp-ha-config`.
.. figure:: images/ezo-pmp.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
ezo_pmp:
id: ezo_pmp
address: 103 # Default Address for the EZO-PMP.
update_interval: 60s
Configuration variables:
- **id** (**Required**, :ref:`config-id`): Specify the ID of the pump so that you can control it.
- **address** (*Optional*, int): Specify the I²C address of the sensor. Defaults to 103.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
Sensors
-----------------------------
Since the EZO-PMP offers a large number of sensors and each sensor needs to be polled individually, the code has been
optimized not to update a sensor that is not defined in the config. If you need very quick updates from the pump (under 3 seconds)
only enable the sensors that you actually need.
.. _ezo_pmp-current_volume_dosed_sensor:
``current_volume_dosed``
-----------------------------
This sensor indicates the volume (in milliliters) that has been dosed in the currently running or last ran dosing command.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
current_volume_dosed:
id: current_volume_dosed
name: Current Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-total_volume_dosed_sensor:
``total_volume_dosed``
-----------------------------
This sensor indicates total volume (in milliliters) that has been dosed since the last time the pump was turned on. Could be a
negative number if the pump has been run in reverse.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
total_volume_dosed:
id: total_volume_dosed
name: Total Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-absolute_total_volume_dosed_sensor:
``absolute_total_volume_dosed``
-------------------------------
This sensor indicates the absolute total volume (in milliliters) that has been dosed since the last time the pump was turned on.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
absolute_total_volume_dosed:
id: absolute_total_volume_dosed
name: Absolute Total Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-last_volume_requested_sensor:
``last_volume_requested``
-----------------------------
Indicates the total volume (in milliliters) that is being dosed (or was if the pump has already finished) by a dose Action. When
using dosing actions that have a duration, the sensor will have the right calculation for total volume.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
last_volume_requested:
id: last_volume_requested
name: Last Volume Requested
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-max_flow_rate_sensor:
``max_flow_rate``
-----------------------------
The pump provides its own calculation of the maximum flow rate it can provide (in ml/minute). Dosing requests that exceed this rate
will fail. When using the :ref:`Dose Continuously <ezo_pmp-dose_continuously_action>` Action, this is the volume the pump will
dose every minute. This value will get updated after the pump is calibrated (see :ref:`ezo_pmp-set_calibration_volume_action`).
.. code-block:: yaml
sensor:
- platform: ezo_pmp
max_flow_rate:
id: max_flow_rate
name: Max Flow Rate
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-pump_voltage_sensor:
``pump_voltage``
-----------------------------
The current voltage of the power supply that powers the pump. Not to be confused with the voltage that powers the electronics on the pump.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
pump_voltage:
id: pump_voltage
name: Pump Voltage
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Binary Sensors
-----------------------------
.. _ezo_pmp-pump_state_binary_sensor:
``pump_state``
-----------------------------
Indicates if the pump is currently running or not.
.. code-block:: yaml
binary_sensor:
- platform: ezo_pmp
pump_state:
id: pump_state
name: Pump State
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _ezo_pmp-is_paused_binary_sensor:
``is_paused``
-----------------------------
Indicates if a dosing action is currently paused.
.. code-block:: yaml
binary_sensor:
- platform: ezo_pmp
is_paused:
id: is_paused
name: Is Paused
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
Text Sensors
-----------------------------
.. _ezo_pmp-dosing_mode_text_sensor:
``dosing_mode``
-----------------------------
Indicates the dosing mode the pump is currently running as. Can be any of `Volume`, `Volume/Time`, `Constant Flow Rate`, `Continuous`, `None`.
.. code-block:: yaml
text_sensor:
- platform: ezo_pmp
dosing_mode:
id: dosing_mode
name: Dosing Mode
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
.. _ezo_pmp-calibration_status_text_sensor:
``calibration_status``
-----------------------------
Indicates calibration status of the pump. Can be any of `Fixed Volume`, `Volume/Time`, `Fixed Volume & Volume/Time` or `Uncalibrated`.
.. code-block:: yaml
text_sensor:
- platform: ezo_pmp
calibration_status:
id: calibration_status
name: Calibration Status
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
Actions
-----------------------------
.. _ezo_pmp-dose_continuously_action:
``ezo_pmp.dose_continuously`` Action
------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose continuously
at the :ref:`Maximum Flow Rate <ezo_pmp-max_flow_rate_sensor>`. The pump will automatically stop after 20 days
of running in continuous mode.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.find:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-dose_volume_action:
``ezo_pmp.dose_volume`` Action
------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific volume (in milliliters)
at the :ref:`Maximum Flow Rate <ezo_pmp-max_flow_rate_sensor>`. If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_volume:
id: ezo_pmp
volume: 10
# Templated
- ezo_pmp.dose_volume:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters. If negative, pump will run in reverse.
.. _ezo_pmp-dose_volume_over_time_action:
``ezo_pmp.dose_volume_over_time`` Action
----------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific ``volume`` (in milliliters)
over the provided ``duration`` (in minutes). At the end of the time period the pump will have dosed the specified ``volume``.
If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_volume_over_time:
id: ezo_pmp
volume: 23.4
duration: 2
# Templated
- ezo_pmp.dose_volume_over_time:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
duration: !lambda |-
return id(some_duration_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters. If negative, pump will run in reverse.
- **duration** (**Required**, int, :ref:`templatable <config-templatable>`): The time (in minutes) the pump will take to dose the volume requested.
.. _ezo_pmp-dose_with_constant_flow_rate_action:
``ezo_pmp.dose_with_constant_flow_rate`` Action
-----------------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific ``volume`` (in milliliters) every minute
for the provided ``duration`` (in minutes). At the end of the time period the pump will have dosed the specified ``volume`` times the ``duration``.
If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_with_constant_flow_rate:
id: ezo_pmp
volume_per_minute: 10.2
duration: 2
# Templated
- ezo_pmp.dose_with_constant_flow_rate:
id: ezo_pmp
volume_per_minute: !lambda |-
return id(some_volume_sensor).state;
duration: !lambda |-
return id(some_duration_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume_per_minute** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters every minute. If negative, pump will run in reverse.
- **duration** (**Required**, int, :ref:`templatable <config-templatable>`): The time (in minutes) the pump will dose the volume requested every minute.
.. _ezo_pmp-pause_dosing_action:
``ezo_pmp.pause_dosing`` Action
-------------------------------
Use this action to pause a Dosing command that was previously issued. To determine if the dosing is paused or not, you can use the :ref:`Is Paused <ezo_pmp-is_paused_binary_sensor>` sensor.
If the pump is currently paused, issuing this action again will unpause it.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.pause_dosing:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-stop_dosing_action:
``ezo_pmp.stop_dosing`` Action
------------------------------
Use this action to stop the current Dosing command.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.stop_dosing:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-clear_total_volume_dosed_action:
``ezo_pmp.clear_total_volume_dosed`` Action
-------------------------------------------
Clear the values of the :ref:`Current Volume Dosed <ezo_pmp-current_volume_dosed_sensor>`, :ref:`Total Volume Dosed <ezo_pmp-total_volume_dosed_sensor>`
and :ref:`Absolute Total Volume Dosed <ezo_pmp-absolute_total_volume_dosed_sensor>` sensors.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.clear_total_volume_dosed:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-set_calibration_volume_action:
``ezo_pmp.set_calibration_volume`` Action
-----------------------------------------
Use this action to calibrate the peristaltic pump. The EZO-PMP needs two forms of calibration: absolute volume and volume over time. You can check
the calibration status by using the :ref:`Calibration Status<ezo_pmp-calibration_status_text_sensor>` sensor. For the procedure on calibrating the pump
check the datasheet.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.set_calibration_volume:
id: ezo_pmp
volume: 10.01
# Templated
- ezo_pmp.set_calibration_volume:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume measured as part of the calibration process.
.. _ezo_pmp-clear_calibration_action:
``ezo_pmp.clear_calibration`` Action
------------------------------------
Clear the calibration values stored in the pump. You can check the calibration status by using the
:ref:`Calibration Status<ezo_pmp-calibration_status_text_sensor>` sensor.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.clear_calibration:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-find_action:
``ezo_pmp.find`` Action
-----------------------
Use this action to make the LED on the Pump control board to blink for a minute. The pump will not respond to any other action while the LED is blinking.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.find:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-change_i2c_address_action:
``ezo_pmp.change_i2c_address`` Action
-------------------------------------------
Changes the i2c address of the pump to the provided value. After the address is changed you must upload a new version of the ESPHome firmware with the updated I2C
address for the pump to work.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.change_i2c_address:
id: ezo_pmp
address: 100
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **address** (**Required**, int, :ref:`templatable <config-templatable>`): The new I2C address for the pump.
.. _ezo-pmp-ha-config:
Home Assistant Configuration
----------------------------
In order to provide control of the pump from the home assistant frontend it is important to expose the actions
as components that have UI rendering. This could be done using templates in ESPHome. Here is an example using a
`Template Button` and `Template Number` to dose a certain volume over time.
.. code-block:: yaml
i2c:
ezo_pmp:
id: ezo_pmp
number:
- platform: template
id: volume
name: "Volume"
optimistic: true
min_value: 0
max_value: 100
step: 0.01
- platform: template
id: duration
name: "Duration"
optimistic: true
min_value: 0
max_value: 100
step: 1
button:
- platform: template
name: "Dose Over Time"
on_press:
- ezo_pmp.dose_volume_over_time:
id: ezo_pump
volume: !lambda |-
return id(volume).state;
duration: !lambda |-
return id(duration).state;
.. _ezo_pmp-lambda_calls:
lambda calls
------------
From :ref:`lambdas <config-lambda>`, you can also access the actions on the peristaltic pump to do some
advanced stuff (see the full API Reference for more info). The name of the functions is the same as the name
of the actions in YAML config.
See Also
--------
- :apiref:`ezo_pmp/ezo_pmp.h`
- :ghedit:`Edit`