1.. _sensor-read-and-decode:
2
3Read and Decode
4###############
5
6The quickly stabilizing experimental APIs for reading sensor data are:
7
8* :c:func:`sensor_read`
9* :c:func:`sensor_read_async_mempool`
10* :c:func:`sensor_get_decoder`
11* :c:func:`sensor_decode`
12
13
14Benefits over :ref:`sensor-fetch-and-get`
15*********************************************************
16
17These APIs allow for a wider usage of sensors, sensor types, and data flows with
18sensors. These are the future looking APIs in Zephyr and solve many issues
19that have been run into with :ref:`sensor-fetch-and-get`.
20
21:c:func:`sensor_read` and similar functions acquire sensor encoded data into
22a buffer provided by the caller. Decode (:c:func:`sensor_decode`) then
23decodes the sensor specific encoded data into fixed point :c:type:`q31_t` values
24as vectors per channel. This allows further processing using fixed point DSP
25functions that work on vectors of data to be done (e.g. low-pass filters, FFT,
26fusion, etc).
27
28Reading is by default asynchronous in its implementation and takes advantage of
29:ref:`rtio` to enable chaining asynchronous requests, or starting requests
30against many sensors simultaneously from a single call context.
31
32This enables incredibly useful code flows when working with sensors such as:
33
34* Obtaining the raw sensor data, decoding never, later, or on a separate
35  processor (e.g. a phone).
36* Starting a read for sensors directly from an interrupt handler. No dedicated
37  thread needed saving precious stack space. No work queue needed introducing
38  variable latency. Starting a read for multiple sensors simultaneously from a
39  single call context (interrupt/thread/work queue).
40* Requesting multiple reads to the same device for Ping-Pong (double buffering)
41  setups.
42* Creating entire pipelines of data flow from sensors allowing for software
43  defined virtual sensors (:ref:`sensing`) all from a single thread with DAG
44  process ordering.
45* Potentially pre-programming DMAs to trigger on GPIO events, leaving the CPU
46  entirely out of the loop in handling sensor events like FIFO watermarks.
47
48Additionally, other shortcomings of :ref:`sensor-fetch-and-get` related to memory
49and trigger handling are solved.
50
51* Triggers result in enqueued events, not callbacks.
52* Triggers can be setup to automatically fetch data. Potentially
53  enabling pre-programmed DMA transfers on GPIO interrupts.
54* Far less likely triggers are missed due to long held interrupt masks from
55  callbacks and context swapping.
56* Sensor FIFOs supported by wiring up FIFO triggers to read data into
57  mempool allocated buffers.
58* All sensor processing can be done in user mode (memory protected) threads.
59* Multiple sensor channels of the same type are better supported.
60
61.. note::
62   For `Read and Decode`_ benefits to be fully realized requires
63   :ref:`rtio` compliant communication access to the sensor. Typically this means
64   an :ref:`rtio` enabled bus driver for SPI or I2C.
65
66Polling Read
67************
68
69Polling reads with `Read and Decode`_ can be accomplished by instantiating a
70polling I/O device (akin to a file descriptor) for the sensor with the desired
71channels to poll. Requesting either blocking or non-blocking reads, then
72optionally decoding the data into fixed point values.
73
74Polling a temperature sensor and printing its readout is likely the simplest
75sample to show how this all works.
76
77.. literalinclude:: temp_polling.c
78   :language: c
79
80Polling Read with Multiple Sensors
81**********************************
82
83One of the benefits of Read and Decode is the ability to concurrently read many
84sensors with many channels in one thread. Effectively read requests are started
85asynchronously for all sensors and their channels. When each read completes we
86then decode the sensor data. Examples speak loudly and so a sample showing how
87this might work with multiple temperature sensors with multiple temperature
88channels:
89
90.. literalinclude:: multiple_temp_polling.c
91   :language: c
92
93Streaming
94*********
95
96Handling triggers with `Read and Decode`_ works by setting up a stream I/O device
97configuration. A stream specifies the set of triggers to capture and if data
98should be captured with the event.
99
100
101
102.. literalinclude:: accel_stream.c
103   :language: c
104