Clarify terminology

[tobie]

Event name

So there's going to be only one event name and this event is going to be fired either whenever the UA feels like it or at specific intervals depending on the reporting mode. What should we call it?

• onchange
• ondata
• onupdate
• onreading
• onsensorreading

Sensor states

A Sensor instance can be in one of three states. It can be sitting around doing nothing. It can have manifested its intention to get data from its underlying sensor. Or it can be actively be listening to that sensor's output.

What do we call those?

• "idle"|"activating"|"active"
• "inactive"|"activating"|"active"
• "idle"|"registering"|"registered"
• "idle"|"starting"|"started"
• "idle"|"starting"|"running"

Start/Stop

Similarly, Sensor instances can walk through these states by calling one of two methods. The first method moves a sensor object from loitering to actually getting data (starting up the underlying sensor in the process if that one wasn't running already). The second method just signals that the sensor object is no longer interested in hearing about the underlying sensor's data output and that the latter is now free to shut down if there isn't someone else interested in its data.

Of course, this ties in with sensor state names.

Proposals:

• start|stop
• activate|deactivate
• register|deregister
• setup|teardown
• provision|release
• initialize|release
• etc.

[anssiko]

My knee-jerk response would be:
onchange
"idle"|"starting"|"started"
start|stop

[tobie]

Went for:

onchange
"idle"|"activating"|"active"|"errored"
start|stop

Still open to change but closing this as fixed.

[tobie]

@timvolodine had alternate suggestions here.

[mwichmann]

Seems to me the most comfortable name for the third sensor state is the one used in the text introducing that section: "listening". I'd go along with Anssi's choices with that change, so:

onchange
"idle"|"starting"|"listening"
start|stop

[timvolodine]

Regarding the 'onchange' event, generally I am inclined towards something with 'update' in it, e.g. 'onupdate', 'ondataupdate' etc.. That's because 'onchange' is a bit imprecise since a sensor can produce same readings for sequential timestamps.

The state names all make sense. But apart from the naming however I am wondering how this would look like in case there is no sensor available. So upon construction the state would always be "idle" independent of whether the sensor can be activated? Once errored would it remain errored if we call stop()?

// e.g. in normal case
"idle"
| start()
"activating"
|
"active"
| stop()
"idle"

// in no-sensor case
"idle"
| start()
"activating"
|
"errored"
| stop()
?

[tobie]

Calling .stop() with a state of "errored" will throw an InvalidStateError exception (see spec).

This will be turned into promise rejections pending #94.

[tobie]

My understanding is onchange is commonly used across the platform to refer to a change in the object itself (here the reading attribute), not the underlying sensor. Given there will be a new reading object, even if the underlying values stay the same, this doesn't seem that inappropriate. That said, onupdate or even onread would work for me too.

[tobie]

Settled in #104 (comment).