1.. _sensor:
2
3Sensors
4#######
5
6The sensor driver API provides functionality to uniformly read, configure,
7and setup event handling for devices that take real world measurements in
8meaningful units.
9
10Sensors range from very simple temperature-reading devices that must be polled
11with a fixed scale to complex devices taking in readings from multitudes of
12sensors and themselves producing new inferred sensor data such as step counts,
13presence detection, orientation, and more.
14
15Supporting this wide breadth of devices is a demanding task and the sensor API
16attempts to provide a uniform interface to them.
17
18
19.. _sensor-using:
20
21Using Sensors
22*************
23
24Using sensors from an application there are some APIs and terms that are helpful
25to understand. Sensors in Zephyr are composed of :ref:`sensor-channel`,
26:ref:`sensor-attribute`, and :ref:`sensor-trigger`. Attributes and triggers may
27be device or channel specific.
28
29.. note::
30   Getting samples from sensors using the sensor API today can be done in one of
31   two ways. A stable and long-lived API :ref:`sensor-fetch-and-get`, or a newer
32   but rapidly stabilizing API :ref:`sensor-read-and-decode`. It's expected that
33   in the near future :ref:`sensor-fetch-and-get` will be deprecated in favor of
34   :ref:`sensor-read-and-decode`. Triggers are handled entirely differently for
35   :ref:`sensor-fetch-and-get` or :ref:`sensor-read-and-decode` and the
36   differences are noted in each of those sections.
37
38.. toctree::
39   :maxdepth: 1
40
41   attributes.rst
42   channels.rst
43   triggers.rst
44   power_management.rst
45   device_tree.rst
46   fetch_and_get.rst
47   read_and_decode.rst
48
49
50.. _sensor-implementing:
51
52Implementing Sensor Drivers
53***************************
54
55.. note::
56   Implementing the driver side of the sensor API requires an understanding how
57   the sensor APIs are used. Please read through :ref:`sensor-using` first!
58
59Implementing Attributes
60=======================
61
62* SHOULD implement attribute setting in a blocking manner.
63* SHOULD provide the ability to get and set channel scale if supported by the
64  device.
65* SHOULD provide the ability to get and set channel sampling rate if supported
66  by the device.
67
68Implementing Fetch and Get
69==========================
70
71* SHOULD implement :c:type:`sensor_sample_fetch_t` as a blocking call that
72  stashes the specified channels (or all sensor channels) as driver instance
73  data.
74* SHOULD implement :c:type:`sensor_channel_get_t` without side effects
75  manipulating driver state returning stashed sensor readings.
76* SHOULD implement :c:type:`sensor_trigger_set_t` storing the address of the
77  :c:struct:`sensor_trigger` rather than copying the contents. This is so
78  :c:macro:`CONTAINER_OF` may be used for trigger callback context.
79
80Implementing Read and Decode
81============================
82
83* MUST implement :c:type:`sensor_submit_t` as a non-blocking call.
84* SHOULD implement :c:type:`sensor_submit_t` using :ref:`rtio` to do non-blocking bus transfers if possible.
85* MAY implement :c:type:`sensor_submit_t` using a work queue if
86  :ref:`rtio` is unsupported by the bus.
87* SHOULD implement :c:type:`sensor_submit_t` checking the :c:struct:`rtio_sqe`
88  is of type :c:enum:`RTIO_SQE_RX` (read request).
89* SHOULD implement :c:type:`sensor_submit_t` checking all requested channels
90  supported or respond with an error if not.
91* SHOULD implement :c:type:`sensor_submit_t` checking the provided buffer
92  is large enough for the requested channels.
93* SHOULD implement :c:type:`sensor_submit_t` in a way that directly reads into
94  the provided buffer avoiding copying of any kind, with few exceptions.
95* MUST implement :c:struct:`sensor_decoder_api` with pure stateless functions. All state needed to convert the raw sensor readings into
96  fixed point SI united values must be in the provided buffer.
97* MUST implement :c:type:`sensor_get_decoder_t` returning the
98  :c:struct:`sensor_decoder_api` for that device type.
99
100.. _sensor-api-reference:
101
102API Reference
103***************
104
105.. doxygengroup:: sensor_interface
106.. doxygengroup:: sensor_emulator_backend
107