572 lines
17 KiB
ReStructuredText
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`
|