Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Create Pump Entity #424

Closed
djtimca opened this issue Aug 16, 2020 · 24 comments
Closed

Create Pump Entity #424

djtimca opened this issue Aug 16, 2020 · 24 comments

Comments

@djtimca
Copy link

djtimca commented Aug 16, 2020

While fixed speed pumps can easily be integrated using switches, with more pool integrations being added to HA it would be nice to have a standard entity for a pump which could be either fixed speed (on/off) or variable speed (0-100%), probably also a low/medium/high state as well for those that have fixed speed settings. Seems a combination of light dimmer, fan speed would work.
@MartinHjelmare
Copy link
Member

Please use the issue template when submitting an issue. Are you going to create an integration with this new entity type?

@djtimca
Copy link
Author

djtimca commented Aug 16, 2020

Sorry the template didn't come up in the mobile Github app. We have already built an integration for the Omnilogic system which this would be very helpful for - is currently in PR for dev.

@MartinHjelmare
Copy link
Member

Please provide a market analysis for different brands and what actuator controls would be needed. See eg this architecture issue:
#375

@djtimca
Copy link
Author

djtimca commented Aug 16, 2020

Ok will do thanks

@BradleyFord
Copy link

BradleyFord commented Aug 16, 2020 via email

@djtimca
Copy link
Author

djtimca commented Aug 16, 2020 via email

@BradleyFord
Copy link

BradleyFord commented Aug 16, 2020 via email

@djtimca
Copy link
Author

djtimca commented Aug 16, 2020 via email

@BradleyFord
Copy link

BradleyFord commented Aug 16, 2020 via email

@djtimca
Copy link
Author

djtimca commented Aug 19, 2020 •
edited by MartinHjelmare

Context

Currently there is no native support for "water pump devices". Typically a water pump would be used for pools, sump pumps, well water, or lake water but they may also be used in temporary situations to pump water out of flooded areas or ponds. A typical example of a common pool pump would be the Hayward VS Omni Variable Speed pump which, when paired with the Hayward OmniLogic control system is used to circulate water in a pool with speeds that can be programmed and configured on a schedule or called through their app or an API integration.

These pumps are commonly integrated either via a cloud connection like the Hayward Omnilogic system or the Jandy iAquaLink system but can also be controlled locally as in the Hayward Prologic system. Other types of smart pumps include smart dump pumps from Zoeller and Liberty Pumps, or fish tank return pumps such as the Syncra SDC 7.0.

I own the Hayward VS Omni pump and OmniLogic controller and we have recently submitted an integration for the OmniLogic control system for inclusion into Home Assistant. There are already integrations for other pool systems such as the Jandy iAquaLink system.

While we could use something like the fan entity or a light entity to accomplish the on/off and variable speed nature of these pumps, it would not be a good representation of the device in the Home Assistant architecture.

Proposal

With a new pump entity we would not need to abuse other types of platforms which would not be an accurate representation of the device, and which would need to be assigned differently depending on the capabilities of the pump.

Based on a market analysis by @BradleyFord, there are some typical configurations for these pumps which could be represented by:

Type (single speed, two speed, multi-speed, variable speed):

  • Single speed (on/off)
  • Two speed (off/low/high)
  • Multi-speed (off, speed1, speed2, ...)
  • Variable speed (0-100%)

Functions could be simple to extend the existing turn_on service to include a speed setting which would be defined in the integration based on the type of pump.

pump:state: on/off
pump:speed: based on grid above

In addition some pumps may return values for power consumption etc.

I see this as an extension to the switch entity which would allow for defined speed attributes and the addition of speed: value to the turn_on service call.

Consequences

While it would be possible to leverage existing entities in Home Assistant to offer variable/multi speed controls on a pump, with more home smart pump applications being added to Home Assistant (pools, aquariums, sumo pumps) it creates a negative user experience (ie knowing to find your variable pool pump by searching for a light entity).

@MartinHjelmare Please let me know if you would like additional details or have additional questions.

@michaelarnauts
Copy link

It looks like this is going towards this issue: #74

@kevstark
Copy link

I can contribute some context here! I live on a rural property and all water is supplied by fixed-speed variable-flow pressure pumps (6 individual pumps for supply and transfer of bore and rainwater across 2 houses...) They have no IoT capability - just plug in power and they'll keep the output side pressurized.

Example pump: https://www.ongapumpsales.com.au/product/jsp120-pressure-pump/

For each pump, I've attached them to a WiFi power meter and switch to provide external monitoring and control. The power is updated every 10s into HA via MQTT and the states I model are:

  1. Idle (<10W draw)
  2. Running (+/- 10% of nominal power draw (eg 1000W pump runs 900-1100W when active)
  3. Stall (+10% of nominal power).
  4. Dry (surging or constant power below -10% of nominal)

Example WiFi power meter: https://templates.blakadder.com/kogan-KASPEMHA.html

A Stall can happen on older pumps as the brushes wear out. On startup it fails to turn and the motor draws a high current for a few seconds until the controller goes into fault mode. This can generally be cleared by cycling the power supply, but if it repeats then you want to throw an alarm.

Dry occurs when the tank runs empty and you get a period of water surging/dribbling into the pump. The power meter fluctuates below the nominal wattage as it has no load then surging up to nominal load. The pump controller itself will protect against run-dry - it monitors low-power and will go into fault mode too after a period of time, however to the external power meter that's indistinguishable from Idle.

I count running cycles and total run time each day. I alarm for extended single runtime (could indicate a pipe blow-out or someone left a tap running). I alarm for extended runtime past sunset (someone left a sprinkler running). I alarm for short & regular running intervals (leaky tap). I alarm for extended periods of no cycles on some pumps (has it gone into fault mode?).

I'm still learning HA and the best way to build this setup into a platform/integration. Each pump is configured as a package in my config at the moment with a lot of duplicated logic - between the MQTT templates, inputs to define nominal/alarm power thresholds, and automations to detect and alarm on states.

@kevstark
Copy link

I have a pool-pump also but under a similar-but-different state model:

  1. Idle/Off (<5W)
  2. Priming (< -10% of nominal power)
  3. Running (+/-10% of nominal power)

The Priming state occurs at startup and when it sucks air through the line. If it spends too much time in this state then I alarm and turn-off the pump to avoid burnout.

The pool pump and water pump are very similar, just with different alarms/monitoring (in my environment). I don't have any variable-speed pumps but this could be modeled as a nominal power set-point and all high/low thresholds relative to that.

@MartinHjelmare
Copy link
Member

There are two sides to the pump or any actuator abstraction:

  1. The controls: on/off, speed
  2. The current state measurement: running, idle, stall

For 1. We need to decide a control interface that will fit all pumps but still be simple to be able to interface with the frontend, voice assistants etc.

The control interfaces seem to be:

a. on/off
b. speed

a. is not a problem.
b. has varying kinds of settings so will need a solution that abstracts that variation. Could we use 0-100 % for all of the variations? Each integration would be responsible for translating to 0-100 %.

For 2. we don't have to include this in the pump entity but can also use separate sensor entities. If we find a common ground that fits the majority of pumps we could include it, but it might be safer to use separate sensors. Please continue recording different states here in this issue, and we'll see. We don't have to decide this before we implement the first version as we can start with separate sensors for the current state.

@BradleyFord
Copy link

BradleyFord commented Aug 20, 2020 via email

@djtimca
Copy link
Author

djtimca commented Aug 20, 2020

The control of speed is really the value to a separate entity. For on/off we are currently using the switch entity which works fine for this purpose. We also have implemented a sensor for the current speed which will handle reporting on the speeds. This setup works fine for fixed speed (on/off) pumps.

Is there a way to simply extend the switch entity to add a set_speed service within the existing entity structure? In that case the integration itself could extend the entity for any variations that are supported:

set_speed_pct: 0-100 (within supported range)
set_speed_level: low/med/high (like a fan)
set_speed_preset: within supported list (like a light effect list)

This would be similar to how the light entity handles dimming (two methods). I could also see the above three methods which each integration would have to handle and apply to the pumps they support which would cover the vast majority of pumps.

The supported range of a pump (many variable speed pumps have a minimum speed) with a min_speed_pct attribute, however that could also be easily handled for variation within each integration.

@djtimca
Copy link
Author

djtimca commented Aug 20, 2020

By the way the Hayward OmniLogic integration that is currently in development/review is at home-assistant/core#38911

@MartinHjelmare
Copy link
Member

Custom entity services can be added by each integration.

The point with a new entity type is to unify the interface and remove the variation between different devices. We should decide on a single speed interface for the new entity.

@djtimca

This comment has been minimized.

Sign in to view
@MartinHjelmare

This comment has been minimized.

Sign in to view
@antonverburg
Copy link

In my CV system I also have some water pumps. They have PWM input to set speed. What I do to control them is to use an analog_output platform (see #347, code is already there in home-assistant/core#33427 but architectural discussion is still pending). If you use an analog_output and add an event to switch power of the pump on if the analog output is switched on you're there.

@djtimca
Copy link
Author

djtimca commented Oct 15, 2020

Thanks @antonverburg will have a look and do some thinking. We are considering three pump types to cover the pump use cases:
-single speed (can be handled by switch)
-dual / fixed speed settings (low/med/high) - no current entity I can find is a fit for this
-variable speed (this analog_output) would work here

It may actually be a case where we just handle the fixed speed pumps as a custom service or extension of one of switch or analog_output.

@Mandrake-Lee
Copy link

Hello,

I'm interested in having a pump entity for variable speed motors. For the record, in my case the device will be linked via modbus.

Is there any repository available with the temptative code?

Cheers!

@antonverburg antonverburg mentioned this issue Nov 25, 2021
Closed
12 tasks
@frenck
Copy link
Member

frenck commented May 11, 2023

This architecture issue is old, stale, and possibly obsolete. Things changed a lot over the years. Additionally, we have been moving to discussions for these architectural discussions.

For that reason, I'm going to close this issue.

../Frenck

@frenck frenck closed this as not planned Won't fix, can't repro, duplicate, stale May 11, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
8 participants
@frenck @BradleyFord @michaelarnauts @kevstark @MartinHjelmare @Mandrake-Lee @antonverburg @djtimca