.. _sensor:

Sensors #######

The sensor driver API provides functionality to uniformly read, configure, and setup event handling for devices that take real world measurements in meaningful units.

Sensors range from very simple temperature-reading devices that must be polled with a fixed scale to complex devices taking in readings from multitudes of sensors and themselves producing new inferred sensor data such as step counts, presence detection, orientation, and more.

Supporting this wide breadth of devices is a demanding task and the sensor API attempts to provide a uniform interface to them.

.. _sensor-using:

Using Sensors

Using sensors from an application there are some APIs and terms that are helpful to understand. Sensors in Zephyr are composed of :ref:sensor-channel, :ref:sensor-attribute, and :ref:sensor-trigger. Attributes and triggers may be device or channel specific.

.. note:: Getting samples from sensors using the sensor API today can be done in one of two ways. A stable and long-lived API :ref:sensor-fetch-and-get, or a newer but rapidly stabilizing API :ref:sensor-read-and-decode. It's expected that in the near future :ref:sensor-fetch-and-get will be deprecated in favor of :ref:sensor-read-and-decode. Triggers are handled entirely differently for :ref:sensor-fetch-and-get or :ref:sensor-read-and-decode and the differences are noted in each of those sections.

.. toctree:: :maxdepth: 1

attributes.rst channels.rst triggers.rst power_management.rst device_tree.rst fetch_and_get.rst read_and_decode.rst

.. _sensor-implementing:

Implementing Sensor Drivers

.. note:: Implementing the driver side of the sensor API requires an understanding how the sensor APIs are used. Please read through :ref:sensor-using first!

Implementing Attributes

SHOULD implement attribute setting in a blocking manner.
SHOULD provide the ability to get and set channel scale if supported by the device.
SHOULD provide the ability to get and set channel sampling rate if supported by the device.

Implementing Fetch and Get

SHOULD implement :c:type:sensor_sample_fetch_t as a blocking call that stashes the specified channels (or all sensor channels) as driver instance data.
SHOULD implement :c:type:sensor_channel_get_t without side effects manipulating driver state returning stashed sensor readings.
SHOULD implement :c:type:sensor_trigger_set_t storing the address of the :c:struct:sensor_trigger rather than copying the contents. This is so :c:macro:CONTAINER_OF may be used for trigger callback context.

Implementing Read and Decode

MUST implement :c:type:sensor_submit_t as a non-blocking call.
SHOULD implement :c:type:sensor_submit_t using :ref:rtio to do non-blocking bus transfers if possible.
MAY implement :c:type:sensor_submit_t using a work queue if :ref:rtio is unsupported by the bus.
SHOULD implement :c:type:sensor_submit_t checking the :c:struct:rtio_sqe is of type :c:enum:RTIO_SQE_RX (read request).
SHOULD implement :c:type:sensor_submit_t checking all requested channels supported or respond with an error if not.
SHOULD implement :c:type:sensor_submit_t checking the provided buffer is large enough for the requested channels.
SHOULD implement :c:type:sensor_submit_t in a way that directly reads into the provided buffer avoiding copying of any kind, with few exceptions.
MUST implement :c:struct:sensor_decoder_api with pure stateless functions. All state needed to convert the raw sensor readings into fixed point SI united values must be in the provided buffer.
MUST implement :c:type:sensor_get_decoder_t returning the :c:struct:sensor_decoder_api for that device type.

.. _sensor-api-reference:

API Reference

.. doxygengroup:: sensor_interface .. doxygengroup:: sensor_emulator_backend