Behavior of `distance` attribute when sensor cannot provide distance measurements?

[andycarle]

Greetings!

I am a member of Ecma TC53, working on the draft specification of ECMAScript Modules for Embedded Systems.

As part of our work on Sensor Class Patterns, we are specifying APIs for common sensor types. Where possible, we are making these APIs compatible with the related W3C Sensor specifications. For example, this is the definition in our current draft for the Proximity class.

With that as background, I had a quick question on the intended implementation of the distance attribute of the ProximitySensor Interface.

I understand that distance is the sensed distance between the device and the closest sensed object and that distance should be null if no object is detected. But, the Introduction notes:

"Moreover some proximity sensors might be only able to provide just a boolean to indicate if there is a physical object which is near, more like presence detection, than an absolute value for the distance."

What is the intended behavior of distance in this situation, where the sensor is only capable of a Boolean determination of object presence? Should distance be absent from the sensor instance? Or should it return a Boolean value (presumably the same value returned by near)? Or something else?

Thank you!  - Andy

[reillyeon]

I believe the intent is that the min and max attributes should indicate the sensing range of the device and distance may be set to an arbitrary value in between.

I should note that no browser has shipped an implementation of the ProximitySensor interface and so there is little implementation experience from which to deduce that this is the correct API for such sensors. It may be more appropriate for that experience to flow from TC53's work on its own draft specification rather than the other way around.

[anssiko]

@andycarle, thanks for raising this issue. As @reillyeon noted, feedback on your preferred approach would help us tighten normative language around this attribute's behavior.

The introduction section is informative and as such does not impose implementation requirements. We'd need to craft additional normative text to address your issue, which I propose we try to do if there's a significant population of proximity sensors that can only report boolean presence.

I believe we should augment the following normative statement for distance:

If the physical object is outside the sensing range, the attribute must return null.

I think it is probably more aligned with the platform conventions to have that attribute around and specify a special value to indicate this case.

Some ideas:

We could return null for both "outside the sensing range" and "implementation is unable to provide" cases:

If the physical object is outside the sensing range, the attribute must return null.

If the implementation is unable to provide the distance value, the attribute must return null.

If we'd want to differentiate between the two cases change the attribute's type to e.g. unrestricted double to be able to return positive Infinity to indicate the former case, e.g.:

If the physical object is outside the sensing range, the attribute must return positive Infinity.

If the implementation is unable to provide the distance value, the attribute must return null.

The tradeoff here is we'd loose the symmetrical behavior between distance and near when outside the sensing range, so I guess suggestions are welcome :-)

Luckily there's flexibility for us to adjust the API behavior given the API hasn't yet shipped.

Please let us know your thoughts and we'll clarify the spec. It is exciting to see the TC53 work unfold :-)

[anssiko]

@andycarle, curious which way you'd prefer to take the design for the TC53 Proximity class? Let us know and we'll figure out the W3C spec bits.

[andycarle]

@reillyeon @anssiko, thank you both for the informative responses; I really appreciate it.

It's encouraging to hear that there's some room to work together here and align our Proximity specs. We've been impressed with the work of the W3C Devices and Sensors group and we're glad to be promoting a more coherent ecosystem for working with sensors in JavaScript.

We have our next TC53 meeting next Wednesday. The couple of people who are likely to have strong opinions on this will be on that call. So, I propose that I raise this issue at that meeting for discussion and then report back here.

[andycarle]

Greetings!

As it turned out, this topic launched a lengthy discussion on the TC53 mailing list and at our March meeting. I'll attempt to summarize that discussion here, though I'll also welcome my colleagues from TC53 to chime in.

The high-level conclusion that we reached was that we prefer using undefined for both situations outlined above: when the sensor is not capable of measuring a specific distance and when the sensor is capable of that reading but does not currently sense an object.

The rationale basically came down to these points:

• There is a strong preference among the TC39 contingent on the committee to avoid null as an indicator of an absent value, believing that undefined is more consistent with the language design.
• There was a desire to avoid special values that still satisfy the condition typeof value === 'number', out of concern that anything that is a number might be interpreted as a valid distance reading. This lead our discussion away from using positive infinity as a special signal value.
• In the TC53 context, it is usually true that the script knows exactly what hardware it is communicating with. We would expect the documentation for individual Proximity Sensor implementations to indicate whether or not the distance property of the sample will ever be anything other than undefined.

We're also exploring parallel ways of signaling the condition where a sensor is generally capable of measuring exact distances but currently cannot for some reason. For that type of situation, we have an additional mechanism for sensor drivers to use to signal faults. But we are holding off on refining that notion for individual sensor types until a future revision.

So, that's where we landed. I'd be happy to make the connections between committees if further discussion between the groups would be helpful!

[anssiko]

Thanks @andycarle! This issue will be discussed in our upcoming meeting in the "Sensors" session: https://www.w3.org/groups/wg/das/calendar

[marcoscaceres]

@domenic, wondering if maybe you could provide us with some guidance here? Is there precedence for returning undefined from an IDL attribute in the manner described above? It might be something we then send up to the API design guidelines.

[reillyeon]

What is the disadvantage of setting distance to null in the case of either no detectable object or no distance sensing capability and use the state of near to disambiguate?

[reillyeon]

In discussion of this issue at our F2F meeting on April 8th a concern was raised that developers may ignore the near attribute if they only test their code on devices which are capable of providing the distance attribute. I suggested that to mitigate this the ProximitySensor constructor be modified to take a threshold (or even a pair of rising and falling thresholds) that is used to calibrate the definition of "near" for the sensor. Applications would thus be encouraged to use the near attribute unless they have a particular need for the more complex distance attribute, in which case they likely would either not support or need separate fallback logic for the case where they were running on a device without support for distance measurement.,

[larsgk]

Web developers with devices capable of measuring distance might only rely on the value, breaking the app when used on devices with only near/far boolean. Could it make sense to introduce an enum, e.g MIN, NEAR, MIDDLE, ... FAR, UNDEFINED, encouraging developers to use values not causing unintended behavior?

[kenchris]

@larsgk maybe an observer pattern would work better then. Give the conditions and get notified if they occur

[domenic]

@domenic, wondering if maybe you could provide us with some guidance here? Is there precedence for returning undefined from an IDL attribute in the manner described above? It might be something we then send up to the API design guidelines.

No, there's no such precedent. Web platform APIs should use null, not undefined, for this. (Or a similar sentinel value such as positive infinity.)