Capability Valve: Attribute "contact" seems mis-named

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #1

(Perhaps this doesn’t belong “literally” in the New Capability Types Category … though maybe this Category can be renamed to handle definition issues related to existing Capabilities as well?)

I am concerned that Capability “Valve” has it’s main attribute called: contact ["closed", "open"].

A Valve is not a “contact sensor”. (NB: Is this just a Documentation error, @Jim ?).

Per the Capability Guidelines (in draft by yours truly…), I recommend that the Primary Attribute of a Capability be named similarly to the Capability:

i.e., valve ["closed", "open"]

(For grammar reasons, to avoid using the word "open-ed ", I would prefer: valve ["shut", "open"] … Whatever, I’m Canadian :maple_leaf: :grimacing:).


My Guidelines also suggest a Best Practice to avoid using Command Names that may overlap with other Capabilities. I suppose this is impractical in the long term, unless a prefix is used. This Best Practice exists because a single SmartDevice Type is permitted to implement multiple Capabilities; therefore, if the Command Names overlap among those served Capabilities, then we have a serious problem unless the Command always has the exact same meaning on the composite-Device.

It is hard to imagine that a Device which is a Valve would also be a Door Control, but should that occur, we would be unable to implement the Commands “open()” & “close()” as there is a namespace conflict.

It may be “too late” for Valve, but, in general, IMHO, there is some value to making up creative Capability tailored Attribute and Command names (and, even, Values). For Valve, I might suggest Commands: "flow(), stopFlow()". I concede that this can get awkward really fast, so this practice need only be seriously considered when there is a high probability of a Command name conflict (i.e., when Capabilities are likely to be implemented in a single device).

Moisture Sensor to trigger outlet? -Help needed
Documentation error for Valve or platform bug

Actually many older, cheaper smart valves are contact sensors. That’s how you know whether the valve is open or closed.

More expensive types measure pressure instead, but they cost more. And newer, smarter ones have non contact proximity sensors.

So there may be capabilities missing, but I’d certainly expect contact to be a capability of a generic valve device type.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #3

OK … Thanks for the clarification, and I’ll grant you that for sure.

However, for the purpose of Abstraction, isn’t it valid (and, perhaps even, helpful) to name the single status Attribute something that is very generic instead of adding more Attributes?

i.e., If the Attribute is: valve ["closed", "open"], then we have abstracted from the hardware implementation which could be a contact sensor, pressure sensor, or non-contact proximity sensor, or some other flow sensor.

If, indeed, it has a pressure or flow sensor, then these would be additional Capabilities (Capability Pressure Sensor and/or Capability Pressure Measurement; Capability Flow Sensor or Capability Flow Measurement).

Emphasis here: Additional distinct optional Capabilities, not just Attributes or Commands, since Attributes and Commands are mandatory for any claimed Capability implmented by the Device Type.


Sure, for isolation valves. I suspect the original physical device prompting the device type may have been an irrigation system or pool pump control, since these generally need to be cheap and don’t usually care much about rate of flow. Just if the water level is low, open the valve, when the water level rises, close it again. Simple isolation valve with a Binary state.

But many control valves do open partially to regulate rate of flow, a whole different issue. Then you need both a set point and a process variable, and a lot of systems care vary much about the rate of flow in between those two, usually for safety reasons of one kind or another. Or in sprinkler systems to control dispersion radius.

If it was me, I’d have one device type for isolation valves and another for control valves. But you know me–I like to limit the times I have to send null value parameters over a mesh network.

Fortrezz uses “binary switch” as the device class for their zwave water valve, but it’s an isolation valve used for flow cutoff, not variable regulation.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #5

So I think this currently maps to a generic Z-Wave Switch in SmartThings, then, right?

While the underlying Attributes and Commands of Switch have reasonable application to this device, using this Capability Name is unfortunately not helpful to the Preferences input filter (ie, this valve will show up when we mostly are looking for light switches, and will not show up when we really desire a Valve for water or gas cutoff).

The problem is, again, the limitations of the input filter which I don’t know an easy solution to except to add boolean AND feature to it.

Meanwhile, from an overall understanding and abstraction perspective, would it be better if SmartThings gave it a simple Capability Valve DeviceType (using deeper signature / model check)?


I’m in double vision mode again (happens) so I’ll just say quickly that an isolation valve maps pretty well to a binary switch and a control valve maps moderately well to a thermostat. (You need the target set point vs current value concept.) But I have no idea what ST has done with them in the past.