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 `__) and EZO-PMP-L (`datasheet `__) are supported. The :ref:`I²C Bus ` 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 `. .. _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 `. .. _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 `. .. _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 `. .. _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 ` 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 `. .. _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 `. 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 `. .. _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 `. 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 `. .. _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 `. Actions ----------------------------- .. _ezo_pmp-dose_continuously_action: ``ezo_pmp.dose_continuously`` Action ------------------------------------ Use this action in an :ref:`automations ` to have the peristaltic pump dose continuously at the :ref:`Maximum Flow Rate `. 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 ` to have the peristaltic pump dose an specific volume (in milliliters) at the :ref:`Maximum Flow Rate `. 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 `): 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 ` 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 `): The volume to dose in milliliters. If negative, pump will run in reverse. - **duration** (**Required**, int, :ref:`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 ` 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 `): The volume to dose in milliliters every minute. If negative, pump will run in reverse. - **duration** (**Required**, int, :ref:`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 ` 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 `, :ref:`Total Volume Dosed ` and :ref:`Absolute Total Volume Dosed ` 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` 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 `): 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` 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 `): 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 `, 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`