RFC for a sensor abstraction layer

[ROMemories]

RFC for a sensor abstraction layer

Definitions

For the purpose of this RFC, we introduce the following definitions:

• A sensor device is a device measuring one or multiple physical quantities and reporting them as one or more digital values.
• Sensor devices measuring the same physical quantity are said to be part of the same sensor class.
• A reading is the result returned by a sensor device of measuring a physical quantity.
• A sensor driver refers to a sensor device exposed by the sensor abstraction layer.
• Consumers refer to consumers of the abstraction.
• Users refer to users of the hardware product.

Goals

• Provide an abstraction over sensors, exposing readings in a way that consumers do not need to know about implementation details of specific sensor devices within a sensor class.
• Allow sensor drivers to expose metadata relevant for formatting measurements in a physically correct and consistent fashion.
• Allow to list connected sensor devices, with names understandable by users.
• Allow sensor drivers to notify consumers of relevant changes, in an energy-efficient manner.

Requirements for riot-rs-sensors

Sensor driver management

• A sensor driver MUST be discoverable for listing by a central entity.
• It MUST be possible to disable and re-enable sensor drivers—e.g., in case of failure and for energy efficiency.
• A sensor driver MUST provide the sensor device's part number, when known.
• A sensor driver MUST provide its version number.
• A sensor driver SHOULD provide a user-friendly display name.

Measurements

• A sensor driver MUST provide a polling interface and/or a notification-based interface.
• Within the notification-based interface, consumers SHOULD be able to request sensor drivers to provide notifications when:
  • a new reading value is available, with a configurable debouncing frequency,
  • the reading value has crossed a configured threshold,
  • the first-order time derivative of the reading value has crossed a configured threshold.
• A sensor driver MUST be able to report multiple values at once, as data tuples, with a common prescaler. The cardinality of such data tuples and the prescaler are fixed per sensor driver.
• A sensor driver MUST be able to report the unit of measurement of its readings. The unit of measurement is fixed per sensor driver.
• A sensor driver SHOULD be able to report its measurement accuracy/error, for individual readings.
• A sensor driver SHOULD be able to report its measurement precision.

Open questions

• Should sensor drivers be able to tie readings to a timestamp of the time of measurement?

References

RIOT-c's SAUL BTHome SenML

[ROMemories]

I'v drafted a first version of an RFC for our sensor abstraction. I'm sure I must have forgotten some things and many points could be clarified. Wdyt?

cc @chrysn @bergzand @maribu @kaspar030

[bergzand]

A sensor driver MUST provide its version number.

To which exact component does 'its version number' refer here? The version of the sensor device or the version of the sensor driver?

There are drivers that can perform measurements automatically at configurable intervals and throw an event when the next measurement is available. Is that something we want to support? I suppose it would be trivial to add a small wrapper around devices that do not support this and handle the periodic measurements in software.

[ROMemories]

To which exact component does 'its version number' refer here? The version of the sensor device or the version of the sensor driver?

This refers to the sensor driver's version number; I don't think there's really such a concept for sensor devices, as new versions would be indicated by a different part number.

There are drivers that can perform measurements automatically at configurable intervals and throw an event when the next measurement is available. Is that something we want to support?

This capability should definitively be added; even it the sensor device does not support this, we clearly do not always want sensor drivers to send a notification when a new reading value is ready. In other words, "reading debouncing" should be part of sensor drivers. I'll add this to the RFC, thanks a lot!

[maribu]

There is also one particular issue with SAUL that I would like to avoid: SAUL is unpredictable in the unit, scale and dimensions from an API point of view. Specifically, the API would allow a temperature sensor that you looked up to:

1. Report the temperature in Kelvin, Celsius and Fahrenheit, round robin
2. Report the current temperature and up to the last two readings as 3-dimensional array. So that the first call would result in a 1-d value, the second call in a 2-d value, and all subsequent in 3-d values
3. The scale could differ between two subsequent calls when the first read fits the range of int16_t, while the second read doesn't.

IMO it would be much more convenient to have a fixed description of what data a sensors provides and how it is presented. Knowing the dimensions of the reading in advance would also allow an API where the caller allocates enough space. E.g. the SAUL API often wastes memory when less than 3 dimensions are used, but also prevents using more dimensions than 3. However, using more "dimensions" than three could be useful e.g. for a particulate matter sensor, where the sensor typically reads a tuple with the number of particles by size.

(And maybe we should not call it "dimension", but rather data tuples?)

[ROMemories]

Thanks @maribu for your feedback! Some of these points have also been raised by @chrysn in #188. I have updated the RFC to clarify that what you propose is indeed part of the current design proposal.