Suggested binarySensor changes about api

[benfrancis]

I'm not sure "on" is the best name for the binary state of a binary sensor, but I don't think I agree with these proposals either.

1 - Change 'on' to 'value'. value doesn't have any extra semantics.

I think "value" is too generic a name for a property. Every property of a thing has a value and a thing can have multiple properties. For example, the SmartThings Multi Sensor includes an open/closed (binary sensor), vibration, orientation, and temperature sensor all in one. In this case it wouldn't be clear which value the "value" property applied to.

An alternative to "on" might be "active", given this is how we currently represent a binary state in the UI.

2 - Change true/false to be 1/0. This would then make a binary sensor more like a special case of a multiLevelSensor

Why represent a binary state with a 64-bit number when you could use a boolean? I don't see how 1/0 is any less semantic than true/false, in JavaScript 1 is truthy and 0 is falsy. It would just mean dealing with more exceptions like the value being negative or greater than 1.

The UI design currently represents the binary property of a binarySensor as "active" or "inactive".

3 - Add a property which inverts the sense of the signal reported. On the raspberry pi, the GPIO pins have an 'activeLow' attribute, so that the pin reports 0 when the voltage is high and reports 1 when the voltage is low.

I agree this is a problem, but I'm not convinced adding a property of a property to the thing description is the best approach. Changing the "sense" of a binary value doesn't change a physical attribute of the thing, it's just a rule for how to interpret the value of the thing's property. It feels more like a gateway setting for how to represent the thing's value than a property of the thing itself.

Maybe we should have settings for things where you can do things like choose a custom icon for the thing and switch which way around a binary property is considered to be "active"?

[benfrancis]

BTW I know that GPIO pins can be set to be active low or active high, but we can't be sure that all binary sensors will have this feature (most, like door sensors, probably don't). So we have to leave it up to the gateway software to decide how to interpret the value.

[dhylands]

I'm not sure "on" is the best name for the binary state of a binary sensor, but I don't think I agree with these proposals either.

1 - Change 'on' to 'value'. value doesn't have any extra semantics.

I think "value" is too generic a name for a property. Every property of a thing has a value and a thing can have multiple properties. For example, the SmartThings Multi Sensor includes an open/closed (binary sensor), vibration, orientation, and temperature sensor all in one. In this case it wouldn't be clear which value the "value" property applied to.

I don't think that a SmartThings MultiSensor qualifies as a binary sensor. It has a collection of sensors, which makes it a totally different beast.

An alternative to "on" might be "active", given this is how we currently represent a binary state in the UI.

I could also live with active, although I still prefer value. To me active (used how most people use it) still implies semantics of it doing something. Active in the electronics sense is a good fit here, but most people probably don't interpret the word that way.

2 - Change true/false to be 1/0. This would then make a binary sensor more like a special case of a multiLevelSensor

Why represent a binary state with a 64-bit number when you could use a boolean? I don't see how 1/0 is any less semantic than true/false, in JavaScript 1 is truthy and 0 is falsy. It would just mean dealing with more exceptions like the value being negative or greater than 1.

The UI design currently represents the binary property of a binarySensor as "active" or "inactive".

3 - Add a property which inverts the sense of the signal reported. On the raspberry pi, the GPIO pins have an 'activeLow' attribute, so that the pin reports 0 when the voltage is high and reports 1 when the voltage is low.

I agree this is a problem, but I'm not convinced adding a property of a property to the thing description is the best approach. Changing the "sense" of a binary value doesn't change a physical attribute of the thing, it's just a rule for how to interpret the value of the thing's property. It feels more like a gateway setting for how to represent the thing's value than a property of the thing itself.

Maybe we should have settings for things where you can do things like choose a custom icon for the thing and switch which way around a binary property is considered to be "active"?

Seems like you've created a bunch of work for the UI when the device/adapter might now whether its active low or active high. And without the active low/high setting then the word active from the electronics sense doesn't make sense.

To me the adapter layer feels like the right place to transform the physical signal being high or low to its logically being active or inactive.

[benfrancis]

I don't think that a SmartThings MultiSensor qualifies as a binary sensor. It has a collection of sensors, which makes it a totally different beast.

I agree, it doesn't. But wouldn't it be neater to re-use the same property name for the same property across different thing types (like we currently do with "on" and "level")? Another reason I don't like the name "value" is that you're calling the key in a key-value pair in the Thing Description "value". You also GET the "value" property URL to get the value of "value". It's just confusing!

I could also live with active, although I still prefer value. To me active (used how most people use it) still implies semantics of it doing something. Active in the electronics sense is a good fit here, but most people probably don't interpret the word that way.

Fair point. Which probably means it's better to use a thing type with more specificity when possible (e.g. "doorSensor" or "motionSensor").

To me the adapter layer feels like the right place to transform the physical signal being high or low to its logically being active or inactive.

That makes a lot of sense if it's possible. I'd again argue that's a configuration of the adapter, not a property of the thing itself which should be exposed to the web layer.

I wonder how we'll see things like this differently if we standardise at the capability level (property, action, event) rather than the thing level. Can we infer semantic meaning from a property name and/or type, or will it require semantic markup using JSON-LD to attach semantic meaning to each property?

[dhylands]

I don't know if you can tell the difference between a door sensor and a motion sensor at the adapter level. At the more generic level, you certainly can't tell the type of sensor connected to a gpio. You could know that its a gpio. Maybe you want a special type for gpio input?

[benfrancis]

Maybe you want a special type for gpio input?

Beyond the simplest possible example of turning an LED on and off, I don't think a GPIO pin is a type of "thing" at all. GPIO pins are digital control lines in the low level implementation of a thing, one or more of which may be used to monitor and control a thing's property, carry out an action, or trigger an event. If an individual GPIO pin maps directly onto anything in the Web Thing Description, I'd suggest it would be a binary property, where the adapter deals with whether it's active low or active high.

In general I think the web layer should exist at a higher level of abstraction which just needs to know it's a binary property that can be true or false. Below the web layer that could be implemented as a GPIO pin, a message over a wireless connection, or a tiny elf pulling a lever.

The binarySensor Web Thing Type is an exceptional example because it only has a single property, no actions and no events. I imagine most Web Thing Types will be much more complex and have a more specific purpose. For native web things this higher level purpose (e.g. a wifi camera, a fridge or a vacuum cleaner) can be defined by the developer at the time of its creation. For adapting existing IoT protocols to the Web of Things we have the challenge of trying to classify things based on the information that is exposed via that protocol. In the worst case scenario we may have to get the end user to choose whether a thing with a binary property is a door sensor or a motion sensor, if the device itself doesn't advertise that information.

[mrstegeman]

I'm going to close this. Since we switched to using schemas, the property can be named anything, so long as the @type is still BooleanProperty.