esphome-docs/components/ezo_pmp.rst

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`