[sensors] Future proofing terminology

tobie has just created a new issue for https://github.com/w3c/sensors:

== Future proofing terminology ==
So following up on the terminology change of #290. Let me recap a couple of things. What you end up doing with: `new FooSensor({ frequency: 100 });` is, I think we all agree, essentially two things:

1. Set the frequency at which `onreading` is called (the reporting frequency), and
2. indirectly, set the sampling frequency of the associated platform sensor. You're not setting it directly to 100 Hz, but you are modifying its settings so the UA is able to deliver on (1) to the best of the platform's capabilities.

Now let's say that we have a sensor that can be sampled at 1KHz. But collecting that data 1000 per seconds is not desired. Perhaps you only want to collect them in batch of 10 (obviously a level 2 feature, but please bear with me). Your API would look something like this:

```js
new FooSensor({ frequency: 1000, groupBy: 10 });
```

And thus `[desiredSamplingFrequency]` would be `1000` and `[reportingFrequency]` would be 100, right? This seems to indicate that the frequency option is actually setting the `[desiredSamplingFrequency]` and not the `[reportingFrequency]`, no?

Similarly, if you're doing:

```js
let foo = new FooSensor({ frequency: 1000 });
requestAnimationFrame(function render() {
    draw(foo.value);
    requestAnimationFrame(render);
});
```

…as is common to improve latency (as demonstrated [here](https://s3.amazonaws.com/pr-preview/tobie/sensors/diagram.html#model)). Then from a developer's perspective, you're not setting the reporting frequency (you're don't even have an event listener). No, here again you're setting the desired sampling frequency.

And going further, let's say your HW sensor doesn't support frequencies above 100 Hz, what will the reporting frequency be if the `frequency` option was set to 200Hz? Well the spec is [pretty clear about this too](https://w3c.github.io/sensors/#ref-for-update-latest-reading):

> "Any time a new sensor reading for a platform sensor is obtained and if the user agent can expose sensor readings, update latest reading is invoked with the platform sensor and the sensor reading as arguments."

If this really was "the frequency at which onreading is called", why would it be impacted by the underlying hardware?

All that to say that **the reporting frequency is a function of the sampling frequency** and not the opposite.

So while you may well get away with this terminology change right now (as the API is still very simple) it'll come back to haunt you the second you want to add features to the API. Sure, you can always revert to the previous terminology at that point, but that will create confusion with terminology in implementations, developer documentation, articles, etc.

Your best strategy here would be to refer to the `frequency` option as the way to set the desiredSamplingFrequency (with all of the caveats known—HW and platform limitations, etc). And have the reporting frequency be a function of that. As initially designed.

Please view or discuss this issue at https://github.com/w3c/sensors/issues/294 using your GitHub account

Received on Friday, 29 September 2017 09:08:48 UTC