diff --git a/components/ezo_pmp.rst b/components/ezo_pmp.rst new file mode 100644 index 000000000..d373e7e71 --- /dev/null +++ b/components/ezo_pmp.rst @@ -0,0 +1,571 @@ +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` diff --git a/components/images/ezo-pmp.jpg b/components/images/ezo-pmp.jpg new file mode 100644 index 000000000..de1f85ea0 Binary files /dev/null and b/components/images/ezo-pmp.jpg differ diff --git a/images/ezo-pmp.jpg b/images/ezo-pmp.jpg new file mode 100644 index 000000000..de1f85ea0 Binary files /dev/null and b/images/ezo-pmp.jpg differ