doc: Revamp sensor docs

Docs now start at a high level, discussing sensors, attributes,
channels, and reading data from them.

Followed by more detailed usage guides in how to solve common problems
sensor users may run into.

Additionally renames the sensor_api sphinx tag to sensor

Signed-off-by: Tom Burdick <[email protected]>

Author: teburd

doc/hardware/peripherals/sensor/accel_stream.c

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2024 Intel Corporation
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/sensor.h>
+
+#define ACCEL_TRIGGERS						\
+	{ SENSOR_TRIG_DRDY, SENSOR_STREAM_DATA_INCLUDE },	\
+	{ SENSOR_TRIG_TAP, SENSOR_STREAM_DATA_NOP }
+#define ACCEL_ALIAS(id) DT_ALIAS(CONCAT(accel, id))
+#define ACCEL_IODEV_SYM(id) CONCAT(accel_iodev, id)
+#define ACCEL_IODEV_PTR(id) &ACCEL_IODEV_SYM(id)
+#define ACCEL_DEFINE_IODEV(id)					\
+	SENSOR_DT_STREAM_IODEV(					\
+		ACCEL_IODEV_SYM(id),				\
+		ACCEL_ALIAS(id),				\
+		ACCEL_TRIGGERS					\
+		);
+
+#define NUM_SENSORS 2
+
+LISTIFY(NUM_SENSORS, ACCEL_DEFINE_IODEV, (;));
+
+struct sensor_iodev *iodevs[NUM_SENSORS] = { LISTIFY(NUM_SENSORS, ACCEL_IODEV_PTR, (,)) };
+
+RTIO_DEFINE_WITH_MEMPOOL(accel_ctx, NUM_SENSORS, NUM_SENSORS, NUM_SENSORS, 16, sizeof(void *));
+
+int main(void)
+{
+	int rc;
+	uint32_t accel_frame_iter = 0;
+	struct sensor_three_axis_data accel_data[2] = {0};
+	struct sensor_decoder_api *decoder;
+	struct rtio_cqe *cqe;
+	uint8_t *buf;
+	uint32_t buf_len;
+	struct rtio_sqe *handles[2];
+
+	/* Start the streams */
+	for (int i = 0; i < NUM_SENSORS; i++) {
+		sensor_stream(iodevs[i], &accel_ctx, NULL, &handles[i]);
+	}
+
+	while (1) {
+		cqe = rtio_cqe_consume_block(&accel_ctx);
+
+		if (cqe->result != 0) {
+			printk("async read failed %d\n", cqe->result);
+			return;
+		}
+
+		rc = rtio_cqe_get_mempool_buffer(&accel_ctx, cqe, &buf, &buf_len);
+
+		if (rc != 0) {
+			printk("get mempool buffer failed %d\n", rc);
+			return;
+		}
+
+		struct device *sensor = ((struct sensor_read_config *)
+					 ((struct rtio_iodev *)cqe->userdata)->data)->sensor;
+
+		rtio_cqe_release(&accel_ctx, cqe);
+
+		rc = sensor_get_decoder(sensor, &decoder);
+
+		if (rc != 0) {
+			printk("sensor_get_decoder failed %d\n", rc);
+			return;
+		}
+
+		/* Frame iterator values when data comes from a FIFO */
+		uint32_t accel_fit = 0;
+
+		/* Number of accelerometer data frames */
+		uint32_t frame_count;
+
+		rc = decoder->get_frame_count(buf, {SENSOR_CHAN_ACCEL_XYZ, 0},
+					      &frame_count);
+		if (rc != 0) {
+			printk("sensor_get_decoder failed %d\n", rc);
+			return;
+		}
+
+		/* If a tap has occurred lets print it out */
+		if (decoder->has_trigger(buf, SENSOR_TRIG_TAP)) {
+			printk("Tap! Sensor %s\n", dev->name);
+		}
+
+		/* Decode all available accelerometer sample frames */
+		for (int i = 0; i < frame_count; i++) {
+			decoder->decode(buf, {SENSOR_CHAN_ACCEL_XYZ, 0},
+					accel_fit, 1, &accel_data);
+			printk("Accel data for %s " PRIsensor_three_axis_data "\n",
+			       dev->name,
+			       PRIsensor_three_axis_data_arg(accel_data, 0));
+		}
+
+		rtio_release_buffer(&accel_ctx, buf, buf_len);
+	}
+}

doc/hardware/peripherals/sensor/attributes.rst

@@ -0,0 +1,39 @@
+.. _sensor-attribute:
+
+Sensor Attributes
+#################
+
+:dfn:`Attributes`, enumerated in :c:enum:`sensor_attribute`, are immutable and
+mutable properties of a sensor and its channels.
+
+Attributes allow for obtaining metadata and changing configuration of a sensor.
+Common configuration parameters like channel scale, sampling frequency, adjusting
+channel offsets, signal filtering, power modes, on chip buffers, and event
+handling options are very common. Attributes provide a flexible API for
+inspecting and manipulating such device properties.
+
+Attributes are specified using :c:enum:`sensor_attribute` which can be used with
+:c:func:`sensor_attr_get` and :c:func:`sensor_attr_set` to get and set a sensors
+attributes.
+
+A quick example...
+
+.. code-block:: c
+
+   const struct device *accel_dev = DEVICE_DT_GET(DT_ALIAS(accel0));
+   struct sensor_value accel_sample_rate;
+   int rc;
+
+   rc = sensor_attr_get(accel_dev, SENSOR_CHAN_ACCEL_XYZ, SENSOR_ATTR_SAMPLING_FREQUENCY, &accel_sample_rate);
+   if (rc != 0) {
+                printk("Failed to get sampling frequency\n");
+   }
+
+   printk("Sample rate for accel %p is %d.06%d\n", accel_dev, accel_sample_rate.val1, accel_sample_rate.val2*1000000);
+
+   accel_sample_rate.val1 = 2000;
+
+   rc = sensor_attr_set(accel_dev, SENSOR_CHAN_ACCEL_XYZ, SENSOR_ATTR_SAMPLING_FREQUENCY, accel_sample_rate);
+   if (rc != 0) {
+                printk("Failed to set sampling frequency\n");
+   }

doc/hardware/peripherals/sensor/channels.rst

@@ -0,0 +1,19 @@
+.. _sensor-channel:
+
+Sensor Channels
+###############
+
+:dfn:`Channels`, enumerated in :c:enum:`sensor_channel`, are quantities that
+a sensor device can measure.
+
+Sensors may have multiple channels, either to represent different axes of
+the same physical property (e.g. acceleration); or because they can measure
+different properties altogether (ambient temperature, pressure and
+humidity). Sensors may have multiple channels of the same measurement type to
+enable measuring many readings of perhaps temperature, light intensity, amperage,
+voltage, or capacitance for example.
+
+A channel is specified in Zephyr using a :c:struct:`sensor_chan_spec` which is a
+pair containing both the channel type (:c:enum:`sensor_channel`) and channel index.
+At times only :c:enum:`sensor_channel` is used but this should be considered
+historical since the introduction of :c:struct:`sensor_chan_spec` for Zephyr 3.7.

doc/hardware/peripherals/sensor/device_tree.rst

@@ -0,0 +1,29 @@
+Device Tree
+###########
+
+In the context of sensors device tree provides the initial hardware configuration
+for sensors on a per device level. Each device must specify a device tree binding
+in Zephyr, and ideally, a set of hardware configuration options for things such
+as channel power modes, data rates, filters, decimation, and scales. These can
+then be used in a boards devicetree to configure a sensor to its initial state.
+
+.. code-block:: dts
+
+   #include <zephyr/dt-bindings/icm42688.h>
+
+   &spi0 {
+       /* SPI bus options here, not shown */
+
+       accel_gyro0: icm42688p@0 {
+           compatible = "invensense,icm42688";
+           reg = <0>;
+           int-gpios = <&pioc 6 GPIO_ACTIVE_HIGH>; /* SoC specific pin to select for interrupt line */
+           spi-max-frequency = <DT_FREQ_M(24)>; /* Maximum SPI bus frequency */
+           accel-pwr-mode = <ICM42688_ACCEL_LN>; /* Low noise mode */
+           accel-odr = <ICM42688_ACCEL_ODR_2000>; /* 2000 Hz sampling */
+           accel-fs = <ICM42688_ACCEL_FS_16>; /* 16G scale */
+           gyro-pwr-mode = <ICM42688_GYRO_LN>; /* Low noise mode */
+           gyro-odr = <ICM42688_GYRO_ODR_2000>; /* 2000 Hz sampling */
+           gyro-fs = <ICM42688_GYRO_FS_16>; /* 16G scale */
+       };
+    };

doc/hardware/peripherals/sensor/fetch_and_get.rst

@@ -0,0 +1,75 @@
+.. _sensor-fetch-and-get:
+
+Fetch and Get
+#############
+
+The stable and long existing APIs for reading sensor data and handling triggers
+are:
+
+* :c:func:`sensor_sample_fetch`
+* :c:func:`sensor_sample_fetch_chan`
+* :c:func:`sensor_channel_get`
+* :c:func:`sensor_trigger_set`
+
+These functions work together. The fetch APIs block the calling context which
+must be a thread until the requested :c:enum:`sensor_channel` (or all channels)
+has been obtained and stored into the driver instance's private data.
+
+The channel data most recently fetched can then be obtained as a
+:c:struct:`sensor_value` by calling :c:func:`sensor_channel_get` for each channel
+type.
+
+.. warning::
+   It should be noted that calling fetch and get from multiple contexts without
+   a locking mechanism is undefined and most sensor drivers do not attempt to
+   internally provide exclusive access to the device during or between these
+   calls.
+
+Polling
+*******
+
+Using fetch and get sensor can be read in a polling manner from software threads.
+
+
+.. literalinclude:: ../../../../samples/sensor/magn_polling/src/main.c
+   :language: c
+
+Triggers
+********
+
+Triggers in the stable API require enabling triggers with a device
+specific Kconfig. The device specific Kconfig typically allows selecting the
+context the trigger runs. The application then needs to register a callback with
+a function signature matching :c:type:`sensor_trigger_handler_t` using
+:c:func:`sensor_trigger_set` for the specific triggers (events) to listen for.
+
+.. note::
+   Triggers may not be set from user mode threads, and the callback is not
+   run in a user mode context.
+
+There are typically two options provided for each driver where to run trigger
+handlers. Either the trigger handler is run using the system work queue thread
+(:ref:`workqueues_v2`) or a dedicated thread. A great example can be found in
+the BMI160 driver which has Kconfig options for selecting a trigger mode.
+See :kconfig:option:`CONFIG_BMI160_TRIGGER_NONE`,
+:kconfig:option:`CONFIG_BMI160_TRIGGER_GLOBAL_THREAD` (work queue),
+:kconfig:option:`CONFIG_BMI160_TRIGGER_OWN_THREAD` (dedicated thread).
+
+Some notable attributes of using a driver dedicated thread vs the system work
+queue.
+
+* Driver dedicated threads have dedicated stack (RAM) which only gets used for
+  that single trigger handler function.
+* Driver dedicated threads *do* get their own priority typically which lets you
+  prioritize trigger handling among other threads.
+* Driver dedicated threads will not have head of line blocking if the driver
+  needs time to handle the trigger.
+
+.. note::
+   In all cases it's very likely there will be variable delays from the actual
+   interrupt to your callback function being run. In the work queue
+   (GLOBAL_THREAD) case the work queue itself can be the source of variable
+   latency!
+
+.. literalinclude:: tap_count.c
+   :language: c