Sensor Interface

Sensor Interface. More...

Modules
	Invensense (TDK) ICM42688 DT Options
	Memsic DT Options

Data Structures
struct	sensor_value
	Representation of a sensor readout value. More...
struct	sensor_trigger
	Sensor trigger spec. More...
struct	sensor_chan_spec
	Sensor Channel Specification. More...
struct	sensor_decoder_api
	Decodes a single raw data buffer. More...
struct	sensor_decode_context
	Used for iterating over the data frames via the sensor_decoder_api. More...
struct	sensor_stream_trigger
struct	sensor_read_config
struct	sensor_driver_api
struct	sensor_data_generic_header

Macros
#define	SENSOR_DECODE_CONTEXT_INIT(decoder_, buffer_, channel_type_, channel_index_)
	Initialize a sensor_decode_context.
#define	SENSOR_STREAM_TRIGGER_PREP(_trigger, _opt)
#define	SENSOR_DT_READ_IODEV(name, dt_node, ...)
	Define a reading instance of a sensor.
#define	SENSOR_DT_STREAM_IODEV(name, dt_node, ...)
	Define a stream instance of a sensor.
#define	SENSOR_CHANNEL_3_AXIS(chan)
	checks if a given channel is a 3-axis channel
#define	SENSOR_G   9806650LL
	The value of gravitational constant in micro m/s^2.
#define	SENSOR_PI   3141592LL
	The value of constant PI in micros.
#define	SENSOR_INFO_DEFINE(name, ...)
#define	SENSOR_INFO_DT_DEFINE(node_id)
#define	SENSOR_DEVICE_DT_DEFINE(node_id, init_fn, pm_device, data_ptr, cfg_ptr, level, prio, api_ptr, ...)
	Like DEVICE_DT_DEFINE() with sensor specifics.
#define	SENSOR_DEVICE_DT_INST_DEFINE(inst, ...)    SENSOR_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like SENSOR_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.

Typedefs
typedef void(*	sensor_trigger_handler_t) (const struct device *dev, const struct sensor_trigger *trigger)
	Callback API upon firing of a trigger.
typedef int(*	sensor_attr_set_t) (const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, const struct sensor_value *val)
	Callback API upon setting a sensor's attributes.
typedef int(*	sensor_attr_get_t) (const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, struct sensor_value *val)
	Callback API upon getting a sensor's attributes.
typedef int(*	sensor_trigger_set_t) (const struct device *dev, const struct sensor_trigger *trig, sensor_trigger_handler_t handler)
	Callback API for setting a sensor's trigger and handler.
typedef int(*	sensor_sample_fetch_t) (const struct device *dev, enum sensor_channel chan)
	Callback API for fetching data from a sensor.
typedef int(*	sensor_channel_get_t) (const struct device *dev, enum sensor_channel chan, struct sensor_value *val)
	Callback API for getting a reading from a sensor.
typedef int(*	sensor_get_decoder_t) (const struct device *dev, const struct sensor_decoder_api **api)
	Get the decoder associate with the given device.
typedef void(*	sensor_submit_t) (const struct device *sensor, struct rtio_iodev_sqe *sqe)
typedef void(*	sensor_processing_callback_t) (int result, uint8_t *buf, uint32_t buf_len, void *userdata)
	Callback function used with the helper processing function.

Enumerations
enum	sensor_channel {   SENSOR_CHAN_ACCEL_X , SENSOR_CHAN_ACCEL_Y , SENSOR_CHAN_ACCEL_Z , SENSOR_CHAN_ACCEL_XYZ ,   SENSOR_CHAN_GYRO_X , SENSOR_CHAN_GYRO_Y , SENSOR_CHAN_GYRO_Z , SENSOR_CHAN_GYRO_XYZ ,   SENSOR_CHAN_MAGN_X , SENSOR_CHAN_MAGN_Y , SENSOR_CHAN_MAGN_Z , SENSOR_CHAN_MAGN_XYZ ,   SENSOR_CHAN_DIE_TEMP , SENSOR_CHAN_AMBIENT_TEMP , SENSOR_CHAN_PRESS , SENSOR_CHAN_PROX ,   SENSOR_CHAN_HUMIDITY , SENSOR_CHAN_LIGHT , SENSOR_CHAN_IR , SENSOR_CHAN_RED ,   SENSOR_CHAN_GREEN , SENSOR_CHAN_BLUE , SENSOR_CHAN_ALTITUDE , SENSOR_CHAN_PM_1_0 ,   SENSOR_CHAN_PM_2_5 , SENSOR_CHAN_PM_10 , SENSOR_CHAN_DISTANCE , SENSOR_CHAN_CO2 ,   SENSOR_CHAN_O2 , SENSOR_CHAN_VOC , SENSOR_CHAN_GAS_RES , SENSOR_CHAN_VOLTAGE ,   SENSOR_CHAN_VSHUNT , SENSOR_CHAN_CURRENT , SENSOR_CHAN_POWER , SENSOR_CHAN_RESISTANCE ,   SENSOR_CHAN_ROTATION , SENSOR_CHAN_POS_DX , SENSOR_CHAN_POS_DY , SENSOR_CHAN_POS_DZ ,   SENSOR_CHAN_POS_DXYZ , SENSOR_CHAN_RPM , SENSOR_CHAN_GAUGE_VOLTAGE , SENSOR_CHAN_GAUGE_AVG_CURRENT ,   SENSOR_CHAN_GAUGE_STDBY_CURRENT , SENSOR_CHAN_GAUGE_MAX_LOAD_CURRENT , SENSOR_CHAN_GAUGE_TEMP , SENSOR_CHAN_GAUGE_STATE_OF_CHARGE ,   SENSOR_CHAN_GAUGE_FULL_CHARGE_CAPACITY , SENSOR_CHAN_GAUGE_REMAINING_CHARGE_CAPACITY , SENSOR_CHAN_GAUGE_NOM_AVAIL_CAPACITY , SENSOR_CHAN_GAUGE_FULL_AVAIL_CAPACITY ,   SENSOR_CHAN_GAUGE_AVG_POWER , SENSOR_CHAN_GAUGE_STATE_OF_HEALTH , SENSOR_CHAN_GAUGE_TIME_TO_EMPTY , SENSOR_CHAN_GAUGE_TIME_TO_FULL ,   SENSOR_CHAN_GAUGE_CYCLE_COUNT , SENSOR_CHAN_GAUGE_DESIGN_VOLTAGE , SENSOR_CHAN_GAUGE_DESIRED_VOLTAGE , SENSOR_CHAN_GAUGE_DESIRED_CHARGING_CURRENT ,   SENSOR_CHAN_ALL , SENSOR_CHAN_COMMON_COUNT , SENSOR_CHAN_PRIV_START = SENSOR_CHAN_COMMON_COUNT , SENSOR_CHAN_MAX = INT16_MAX }
	Sensor channels. More...
enum	sensor_trigger_type {   SENSOR_TRIG_TIMER , SENSOR_TRIG_DATA_READY , SENSOR_TRIG_DELTA , SENSOR_TRIG_NEAR_FAR ,   SENSOR_TRIG_THRESHOLD , SENSOR_TRIG_TAP , SENSOR_TRIG_DOUBLE_TAP , SENSOR_TRIG_FREEFALL ,   SENSOR_TRIG_MOTION , SENSOR_TRIG_STATIONARY , SENSOR_TRIG_FIFO_WATERMARK , SENSOR_TRIG_FIFO_FULL ,   SENSOR_TRIG_COMMON_COUNT , SENSOR_TRIG_PRIV_START = SENSOR_TRIG_COMMON_COUNT , SENSOR_TRIG_MAX = INT16_MAX }
	Sensor trigger types. More...
enum	sensor_attribute {   SENSOR_ATTR_SAMPLING_FREQUENCY , SENSOR_ATTR_LOWER_THRESH , SENSOR_ATTR_UPPER_THRESH , SENSOR_ATTR_SLOPE_TH ,   SENSOR_ATTR_SLOPE_DUR , SENSOR_ATTR_HYSTERESIS , SENSOR_ATTR_OVERSAMPLING , SENSOR_ATTR_FULL_SCALE ,   SENSOR_ATTR_OFFSET , SENSOR_ATTR_CALIB_TARGET , SENSOR_ATTR_CONFIGURATION , SENSOR_ATTR_CALIBRATION ,   SENSOR_ATTR_FEATURE_MASK , SENSOR_ATTR_ALERT , SENSOR_ATTR_FF_DUR , SENSOR_ATTR_BATCH_DURATION ,   SENSOR_ATTR_GAIN , SENSOR_ATTR_RESOLUTION , SENSOR_ATTR_COMMON_COUNT , SENSOR_ATTR_PRIV_START = SENSOR_ATTR_COMMON_COUNT ,   SENSOR_ATTR_MAX = INT16_MAX }
	Sensor attribute types. More...
enum	sensor_stream_data_opt { SENSOR_STREAM_DATA_INCLUDE = 0 , SENSOR_STREAM_DATA_NOP = 1 , SENSOR_STREAM_DATA_DROP = 2 }
	Options for what to do with the associated data when a trigger is consumed. More...

Functions
static bool	sensor_chan_spec_eq (struct sensor_chan_spec chan_spec0, struct sensor_chan_spec chan_spec1)
	Check if channel specs are equivalent.
static int	sensor_decode (struct sensor_decode_context *ctx, void *out, uint16_t max_count)
	Decode N frames using a sensor_decode_context.
int	sensor_natively_supported_channel_size_info (struct sensor_chan_spec channel, size_t *base_size, size_t *frame_size)
int	sensor_attr_set (const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, const struct sensor_value *val)
	Set an attribute for a sensor.
int	sensor_attr_get (const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, struct sensor_value *val)
	Get an attribute for a sensor.
static int	sensor_trigger_set (const struct device *dev, const struct sensor_trigger *trig, sensor_trigger_handler_t handler)
	Activate a sensor's trigger and set the trigger handler.
int	sensor_sample_fetch (const struct device *dev)
	Fetch a sample from the sensor and store it in an internal driver buffer.
int	sensor_sample_fetch_chan (const struct device *dev, enum sensor_channel type)
	Fetch a sample from the sensor and store it in an internal driver buffer.
int	sensor_channel_get (const struct device *dev, enum sensor_channel chan, struct sensor_value *val)
	Get a reading from a sensor device.
int	sensor_get_decoder (const struct device *dev, const struct sensor_decoder_api **decoder)
	Get the sensor's decoder API.
int	sensor_reconfigure_read_iodev (struct rtio_iodev *iodev, const struct device *sensor, const struct sensor_chan_spec *channels, size_t num_channels)
	Reconfigure a reading iodev.
static int	sensor_stream (struct rtio_iodev *iodev, struct rtio *ctx, void *userdata, struct rtio_sqe **handle)
static int	sensor_read (struct rtio_iodev *iodev, struct rtio *ctx, uint8_t *buf, size_t buf_len)
	Blocking one shot read of samples from a sensor into a buffer.
static int	sensor_read_async_mempool (struct rtio_iodev *iodev, struct rtio *ctx, void *userdata)
	One shot non-blocking read with pool allocated buffer.
void	sensor_processing_with_callback (struct rtio *ctx, sensor_processing_callback_t cb)
	Helper function for common processing of sensor data.
static int32_t	sensor_ms2_to_g (const struct sensor_value *ms2)
	Helper function to convert acceleration from m/s^2 to Gs.
static void	sensor_g_to_ms2 (int32_t g, struct sensor_value *ms2)
	Helper function to convert acceleration from Gs to m/s^2.
static int32_t	sensor_ms2_to_ug (const struct sensor_value *ms2)
	Helper function to convert acceleration from m/s^2 to micro Gs.
static void	sensor_ug_to_ms2 (int32_t ug, struct sensor_value *ms2)
	Helper function to convert acceleration from micro Gs to m/s^2.
static int32_t	sensor_rad_to_degrees (const struct sensor_value *rad)
	Helper function for converting radians to degrees.
static void	sensor_degrees_to_rad (int32_t d, struct sensor_value *rad)
	Helper function for converting degrees to radians.
static int32_t	sensor_rad_to_10udegrees (const struct sensor_value *rad)
	Helper function for converting radians to 10 micro degrees.
static void	sensor_10udegrees_to_rad (int32_t d, struct sensor_value *rad)
	Helper function for converting 10 micro degrees to radians.
static double	sensor_value_to_double (const struct sensor_value *val)
	Helper function for converting struct sensor_value to double.
static float	sensor_value_to_float (const struct sensor_value *val)
	Helper function for converting struct sensor_value to float.
static int	sensor_value_from_double (struct sensor_value *val, double inp)
	Helper function for converting double to struct sensor_value.
static int	sensor_value_from_float (struct sensor_value *val, float inp)
	Helper function for converting float to struct sensor_value.
static int64_t	sensor_value_to_milli (const struct sensor_value *val)
	Helper function for converting struct sensor_value to integer milli units.
static int64_t	sensor_value_to_micro (const struct sensor_value *val)
	Helper function for converting struct sensor_value to integer micro units.
static int	sensor_value_from_milli (struct sensor_value *val, int64_t milli)
	Helper function for converting integer milli units to struct sensor_value.
static int	sensor_value_from_micro (struct sensor_value *val, int64_t micro)
	Helper function for converting integer micro units to struct sensor_value.

Detailed Description

Sensor Interface.

Since

1.2

Version

1.0.0

Macro Definition Documentation

SENSOR_CHANNEL_3_AXIS

#define SENSOR_CHANNEL_3_AXIS

(

chan

)

#include <include/zephyr/drivers/sensor.h>

Value:

        ((chan) == SENSOR_CHAN_ACCEL_XYZ || (chan) == SENSOR_CHAN_GYRO_XYZ ||                      \
         (chan) == SENSOR_CHAN_MAGN_XYZ || (chan) == SENSOR_CHAN_POS_DXYZ)

checks if a given channel is a 3-axis channel

Parameters

[in]

chan

The channel to check

Return values

true	if chan is any of SENSOR_CHAN_ACCEL_XYZ, SENSOR_CHAN_GYRO_XYZ, or SENSOR_CHAN_MAGN_XYZ, or SENSOR_CHAN_POS_DXYZ
false	otherwise

SENSOR_DECODE_CONTEXT_INIT

#define SENSOR_DECODE_CONTEXT_INIT	(		decoder_,
			buffer_,
			channel_type_,
			channel_index_
	)

#include <include/zephyr/drivers/sensor.h>

Value:

        {                                                                                          \
                .decoder = (decoder_),                                                             \
                .buffer = (buffer_),                                                               \
                .channel = {.chan_type = (channel_type_), .chan_idx = (channel_index_)},           \
                .fit = 0,                                                                          \
        }

Initialize a sensor_decode_context.

SENSOR_DEVICE_DT_DEFINE

#define SENSOR_DEVICE_DT_DEFINE	(		node_id,
			init_fn,
			pm_device,
			data_ptr,
			cfg_ptr,
			level,
			prio,
			api_ptr,
			...
	)

#include <include/zephyr/drivers/sensor.h>

Value:

        DEVICE_DT_DEFINE(node_id, init_fn, pm_device,                   \
                         data_ptr, cfg_ptr, level, prio,                \
                         api_ptr, __VA_ARGS__);                         \
                                                                        \
        SENSOR_INFO_DT_DEFINE(node_id);

Like DEVICE_DT_DEFINE() with sensor specifics.

Defines a device which implements the sensor API. May define an element in the sensor info iterable section used to enumerate all sensor devices.

Parameters

node_id	The devicetree node identifier.
init_fn	Name of the init function of the driver.
pm_device	PM device resources reference (NULL if device does not use PM).
data_ptr	Pointer to the device's private data.
cfg_ptr	The address to the structure containing the configuration information for this instance of the driver.
level	The initialization level. See SYS_INIT() for details.
prio	Priority within the selected initialization level. See SYS_INIT() for details.
api_ptr	Provides an initial pointer to the API function struct used by the driver. Can be NULL.

SENSOR_DEVICE_DT_INST_DEFINE

#define SENSOR_DEVICE_DT_INST_DEFINE	(		inst,
			...
	)		SENSOR_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

#include <include/zephyr/drivers/sensor.h>

Like SENSOR_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.

Parameters

inst	instance number. This is replaced by DT_DRV_COMPAT(inst) in the call to SENSOR_DEVICE_DT_DEFINE().
...	other parameters as expected by SENSOR_DEVICE_DT_DEFINE().

SENSOR_DT_READ_IODEV

#define SENSOR_DT_READ_IODEV	(		name,
			dt_node,
			...
	)

#include <include/zephyr/drivers/sensor.h>

Value:

        static struct sensor_chan_spec _CONCAT(__channel_array_, name)[] = {__VA_ARGS__};          \
        static struct sensor_read_config _CONCAT(__sensor_read_config_, name) = {                  \
                .sensor = DEVICE_DT_GET(dt_node),                                                  \
                .is_streaming = false,                                                             \
                .channels = _CONCAT(__channel_array_, name),                                       \
                .count = ARRAY_SIZE(_CONCAT(__channel_array_, name)),                              \
                .max = ARRAY_SIZE(_CONCAT(__channel_array_, name)),                                \
        };                                                                                         \
        RTIO_IODEV_DEFINE(name, &__sensor_iodev_api, _CONCAT(&__sensor_read_config_, name))

Define a reading instance of a sensor.

Use this macro to generate a rtio_iodev for reading specific channels. Example:

 (.c)
SENSOR_DT_READ_IODEV(icm42688_accelgyro, DT_NODELABEL(icm42688),
    { SENSOR_CHAN_ACCEL_XYZ, 0 },
    { SENSOR_CHAN_GYRO_XYZ, 0 });
 
int main(void) {
  sensor_read_async_mempool(&icm42688_accelgyro, &rtio);
}

SENSOR_DT_STREAM_IODEV

#define SENSOR_DT_STREAM_IODEV	(		name,
			dt_node,
			...
	)

#include <include/zephyr/drivers/sensor.h>

Value:

        static struct sensor_stream_trigger _CONCAT(__trigger_array_, name)[] = {__VA_ARGS__};     \
        static struct sensor_read_config _CONCAT(__sensor_read_config_, name) = {                  \
                .sensor = DEVICE_DT_GET(dt_node),                                                  \
                .is_streaming = true,                                                              \
                .triggers = _CONCAT(__trigger_array_, name),                                       \
                .count = ARRAY_SIZE(_CONCAT(__trigger_array_, name)),                              \
                .max = ARRAY_SIZE(_CONCAT(__trigger_array_, name)),                                \
        };                                                                                         \
        RTIO_IODEV_DEFINE(name, &__sensor_iodev_api, &_CONCAT(__sensor_read_config_, name))

Define a stream instance of a sensor.

Use this macro to generate a rtio_iodev for starting a stream that's triggered by specific interrupts. Example:

 (.c)
SENSOR_DT_STREAM_IODEV(imu_stream, DT_ALIAS(imu),
    {SENSOR_TRIG_FIFO_WATERMARK, SENSOR_STREAM_DATA_INCLUDE},
    {SENSOR_TRIG_FIFO_FULL, SENSOR_STREAM_DATA_NOP});
 
int main(void) {
  struct rtio_sqe *handle;
  sensor_stream(&imu_stream, &rtio, NULL, &handle);
  k_msleep(1000);
  rtio_sqe_cancel(handle);
}

SENSOR_G

#define SENSOR_G   9806650LL

#include <include/zephyr/drivers/sensor.h>

The value of gravitational constant in micro m/s^2.

SENSOR_INFO_DEFINE

#define SENSOR_INFO_DEFINE	(		name,
			...
	)

#include <include/zephyr/drivers/sensor.h>

SENSOR_INFO_DT_DEFINE

#define SENSOR_INFO_DT_DEFINE

(

node_id

)

#include <include/zephyr/drivers/sensor.h>

SENSOR_PI

#define SENSOR_PI   3141592LL

#include <include/zephyr/drivers/sensor.h>

The value of constant PI in micros.

SENSOR_STREAM_TRIGGER_PREP

#define SENSOR_STREAM_TRIGGER_PREP	(		_trigger,
			_opt
	)

#include <include/zephyr/drivers/sensor.h>

Value:

        {                                                                                          \
                .trigger = (_trigger), .opt = (_opt),                                              \
        }

Typedef Documentation

sensor_attr_get_t

sensor_attr_get_t

#include <include/zephyr/drivers/sensor.h>

Callback API upon getting a sensor's attributes.

See sensor_attr_get() for argument description

sensor_attr_set_t

sensor_attr_set_t

#include <include/zephyr/drivers/sensor.h>

Callback API upon setting a sensor's attributes.

See sensor_attr_set() for argument description

sensor_channel_get_t

sensor_channel_get_t

#include <include/zephyr/drivers/sensor.h>

Callback API for getting a reading from a sensor.

See sensor_channel_get() for argument description

sensor_get_decoder_t

sensor_get_decoder_t

#include <include/zephyr/drivers/sensor.h>

Get the decoder associate with the given device.

See also

sensor_get_decoder for more details

sensor_processing_callback_t

sensor_processing_callback_t

#include <include/zephyr/drivers/sensor.h>

Callback function used with the helper processing function.

See also

sensor_processing_with_callback

Parameters

[in]	result	The result code of the read (0 being success)
[in]	buf	The data buffer holding the sensor data
[in]	buf_len	The length (in bytes) of the buf
[in]	userdata	The optional userdata passed to sensor_read_async_mempool()

sensor_sample_fetch_t

sensor_sample_fetch_t

#include <include/zephyr/drivers/sensor.h>

Callback API for fetching data from a sensor.

See sensor_sample_fetch() for argument description

sensor_submit_t

typedef void(* sensor_submit_t) (const struct device *sensor, struct rtio_iodev_sqe *sqe)

#include <include/zephyr/drivers/sensor.h>

sensor_trigger_handler_t

sensor_trigger_handler_t

#include <include/zephyr/drivers/sensor.h>

Callback API upon firing of a trigger.

Parameters

dev	Pointer to the sensor device
trigger	The trigger

sensor_trigger_set_t

sensor_trigger_set_t

#include <include/zephyr/drivers/sensor.h>

Callback API for setting a sensor's trigger and handler.

See sensor_trigger_set() for argument description

Enumeration Type Documentation

sensor_attribute

enum sensor_attribute

#include <include/zephyr/drivers/sensor.h>

Sensor attribute types.

Enumerator
SENSOR_ATTR_SAMPLING_FREQUENCY	Sensor sampling frequency, i.e. how many times a second the sensor takes a measurement.
SENSOR_ATTR_LOWER_THRESH	Lower threshold for trigger.
SENSOR_ATTR_UPPER_THRESH	Upper threshold for trigger.
SENSOR_ATTR_SLOPE_TH	Threshold for any-motion (slope) trigger.
SENSOR_ATTR_SLOPE_DUR	Duration for which the slope values needs to be outside the threshold for the trigger to fire.
SENSOR_ATTR_HYSTERESIS
SENSOR_ATTR_OVERSAMPLING	Oversampling factor.
SENSOR_ATTR_FULL_SCALE	Sensor range, in SI units.
SENSOR_ATTR_OFFSET	The sensor value returned will be altered by the amount indicated by offset: final_value = sensor_value + offset.
SENSOR_ATTR_CALIB_TARGET	Calibration target. This will be used by the internal chip's algorithms to calibrate itself on a certain axis, or all of them.
SENSOR_ATTR_CONFIGURATION	Configure the operating modes of a sensor.
SENSOR_ATTR_CALIBRATION	Set a calibration value needed by a sensor.
SENSOR_ATTR_FEATURE_MASK	Enable/disable sensor features.
SENSOR_ATTR_ALERT	Alert threshold or alert enable/disable.
SENSOR_ATTR_FF_DUR	Free-fall duration represented in milliseconds. If the sampling frequency is changed during runtime, this attribute should be set to adjust freefall duration to the new sampling frequency.
SENSOR_ATTR_BATCH_DURATION	Hardware batch duration in ticks.
SENSOR_ATTR_GAIN
SENSOR_ATTR_RESOLUTION
SENSOR_ATTR_COMMON_COUNT	Number of all common sensor attributes.
SENSOR_ATTR_PRIV_START	This and higher values are sensor specific. Refer to the sensor header file.
SENSOR_ATTR_MAX	Maximum value describing a sensor attribute type.

sensor_channel

enum sensor_channel

#include <include/zephyr/drivers/sensor.h>

Sensor channels.

Enumerator
SENSOR_CHAN_ACCEL_X	Acceleration on the X axis, in m/s^2.
SENSOR_CHAN_ACCEL_Y	Acceleration on the Y axis, in m/s^2.
SENSOR_CHAN_ACCEL_Z	Acceleration on the Z axis, in m/s^2.
SENSOR_CHAN_ACCEL_XYZ	Acceleration on the X, Y and Z axes.
SENSOR_CHAN_GYRO_X	Angular velocity around the X axis, in radians/s.
SENSOR_CHAN_GYRO_Y	Angular velocity around the Y axis, in radians/s.
SENSOR_CHAN_GYRO_Z	Angular velocity around the Z axis, in radians/s.
SENSOR_CHAN_GYRO_XYZ	Angular velocity around the X, Y and Z axes.
SENSOR_CHAN_MAGN_X	Magnetic field on the X axis, in Gauss.
SENSOR_CHAN_MAGN_Y	Magnetic field on the Y axis, in Gauss.
SENSOR_CHAN_MAGN_Z	Magnetic field on the Z axis, in Gauss.
SENSOR_CHAN_MAGN_XYZ	Magnetic field on the X, Y and Z axes.
SENSOR_CHAN_DIE_TEMP	Device die temperature in degrees Celsius.
SENSOR_CHAN_AMBIENT_TEMP	Ambient temperature in degrees Celsius.
SENSOR_CHAN_PRESS	Pressure in kilopascal.
SENSOR_CHAN_PROX	Proximity. Adimensional. A value of 1 indicates that an object is close.
SENSOR_CHAN_HUMIDITY	Humidity, in percent.
SENSOR_CHAN_LIGHT	Illuminance in visible spectrum, in lux.
SENSOR_CHAN_IR	Illuminance in infra-red spectrum, in lux.
SENSOR_CHAN_RED	Illuminance in red spectrum, in lux.
SENSOR_CHAN_GREEN	Illuminance in green spectrum, in lux.
SENSOR_CHAN_BLUE	Illuminance in blue spectrum, in lux.
SENSOR_CHAN_ALTITUDE	Altitude, in meters.
SENSOR_CHAN_PM_1_0	1.0 micro-meters Particulate Matter, in ug/m^3
SENSOR_CHAN_PM_2_5	2.5 micro-meters Particulate Matter, in ug/m^3
SENSOR_CHAN_PM_10	10 micro-meters Particulate Matter, in ug/m^3
SENSOR_CHAN_DISTANCE	Distance. From sensor to target, in meters
SENSOR_CHAN_CO2	CO2 level, in parts per million (ppm)
SENSOR_CHAN_O2	O2 level, in parts per million (ppm)
SENSOR_CHAN_VOC	VOC level, in parts per billion (ppb)
SENSOR_CHAN_GAS_RES	Gas sensor resistance in ohms.
SENSOR_CHAN_VOLTAGE	Voltage, in volts.
SENSOR_CHAN_VSHUNT	Current Shunt Voltage in milli-volts.
SENSOR_CHAN_CURRENT	Current, in amps.
SENSOR_CHAN_POWER	Power in watts.
SENSOR_CHAN_RESISTANCE	Resistance , in Ohm.
SENSOR_CHAN_ROTATION	Angular rotation, in degrees.
SENSOR_CHAN_POS_DX	Position change on the X axis, in points.
SENSOR_CHAN_POS_DY	Position change on the Y axis, in points.
SENSOR_CHAN_POS_DZ	Position change on the Z axis, in points.
SENSOR_CHAN_POS_DXYZ	Position change on the X, Y and Z axis, in points.
SENSOR_CHAN_RPM	Revolutions per minute, in RPM.
SENSOR_CHAN_GAUGE_VOLTAGE	Voltage, in volts.
SENSOR_CHAN_GAUGE_AVG_CURRENT	Average current, in amps.
SENSOR_CHAN_GAUGE_STDBY_CURRENT	Standby current, in amps.
SENSOR_CHAN_GAUGE_MAX_LOAD_CURRENT	Max load current, in amps.
SENSOR_CHAN_GAUGE_TEMP	Gauge temperature
SENSOR_CHAN_GAUGE_STATE_OF_CHARGE	State of charge measurement in %.
SENSOR_CHAN_GAUGE_FULL_CHARGE_CAPACITY	Full Charge Capacity in mAh.
SENSOR_CHAN_GAUGE_REMAINING_CHARGE_CAPACITY	Remaining Charge Capacity in mAh.
SENSOR_CHAN_GAUGE_NOM_AVAIL_CAPACITY	Nominal Available Capacity in mAh.
SENSOR_CHAN_GAUGE_FULL_AVAIL_CAPACITY	Full Available Capacity in mAh.
SENSOR_CHAN_GAUGE_AVG_POWER	Average power in mW.
SENSOR_CHAN_GAUGE_STATE_OF_HEALTH	State of health measurement in %.
SENSOR_CHAN_GAUGE_TIME_TO_EMPTY	Time to empty in minutes.
SENSOR_CHAN_GAUGE_TIME_TO_FULL	Time to full in minutes.
SENSOR_CHAN_GAUGE_CYCLE_COUNT	Cycle count (total number of charge/discharge cycles)
SENSOR_CHAN_GAUGE_DESIGN_VOLTAGE	Design voltage of cell in V (max voltage)
SENSOR_CHAN_GAUGE_DESIRED_VOLTAGE	Desired voltage of cell in V (nominal voltage)
SENSOR_CHAN_GAUGE_DESIRED_CHARGING_CURRENT	Desired charging current in mA.
SENSOR_CHAN_ALL	All channels.
SENSOR_CHAN_COMMON_COUNT	Number of all common sensor channels.
SENSOR_CHAN_PRIV_START	This and higher values are sensor specific. Refer to the sensor header file.
SENSOR_CHAN_MAX	Maximum value describing a sensor channel type.

sensor_stream_data_opt

enum sensor_stream_data_opt

#include <include/zephyr/drivers/sensor.h>

Options for what to do with the associated data when a trigger is consumed.

Enumerator
SENSOR_STREAM_DATA_INCLUDE	Include whatever data is associated with the trigger.
SENSOR_STREAM_DATA_NOP	Do nothing with the associated trigger data, it may be consumed later.
SENSOR_STREAM_DATA_DROP	Flush/clear whatever data is associated with the trigger.

sensor_trigger_type

enum sensor_trigger_type

#include <include/zephyr/drivers/sensor.h>

Sensor trigger types.

Enumerator
SENSOR_TRIG_TIMER	Timer-based trigger, useful when the sensor does not have an interrupt line.
SENSOR_TRIG_DATA_READY	Trigger fires whenever new data is ready.
SENSOR_TRIG_DELTA	Trigger fires when the selected channel varies significantly. This includes any-motion detection when the channel is acceleration or gyro. If detection is based on slope between successive channel readings, the slope threshold is configured via the SENSOR_ATTR_SLOPE_TH and SENSOR_ATTR_SLOPE_DUR attributes.
SENSOR_TRIG_NEAR_FAR	Trigger fires when a near/far event is detected.
SENSOR_TRIG_THRESHOLD	Trigger fires when channel reading transitions configured thresholds. The thresholds are configured via the SENSOR_ATTR_LOWER_THRESH, SENSOR_ATTR_UPPER_THRESH, and SENSOR_ATTR_HYSTERESIS attributes.
SENSOR_TRIG_TAP	Trigger fires when a single tap is detected.
SENSOR_TRIG_DOUBLE_TAP	Trigger fires when a double tap is detected.
SENSOR_TRIG_FREEFALL	Trigger fires when a free fall is detected.
SENSOR_TRIG_MOTION	Trigger fires when motion is detected.
SENSOR_TRIG_STATIONARY	Trigger fires when no motion has been detected for a while.
SENSOR_TRIG_FIFO_WATERMARK	Trigger fires when the FIFO watermark has been reached.
SENSOR_TRIG_FIFO_FULL	Trigger fires when the FIFO becomes full.
SENSOR_TRIG_COMMON_COUNT	Number of all common sensor triggers.
SENSOR_TRIG_PRIV_START	This and higher values are sensor specific. Refer to the sensor header file.
SENSOR_TRIG_MAX	Maximum value describing a sensor trigger type.

Function Documentation

sensor_10udegrees_to_rad()

static void sensor_10udegrees_to_rad ( int32_t  d, struct sensor_value *  rad  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting 10 micro degrees to radians.

Parameters

d	The value (in 10 micro degrees) to be converted.
rad	A pointer to a sensor_value struct, where the result is stored.

sensor_attr_get()

int sensor_attr_get	(	const struct device *	dev,
		enum sensor_channel	chan,
		enum sensor_attribute	attr,
		struct sensor_value *	val
	)

#include <include/zephyr/drivers/sensor.h>

Get an attribute for a sensor.

Parameters

dev	Pointer to the sensor device
chan	The channel the attribute belongs to, if any. Some attributes may only be set for all channels of a device, depending on device capabilities.
attr	The attribute to get
val	Pointer to where to store the attribute

Returns

0 if successful, negative errno code if failure.

sensor_attr_set()

int sensor_attr_set	(	const struct device *	dev,
		enum sensor_channel	chan,
		enum sensor_attribute	attr,
		const struct sensor_value *	val
	)

#include <include/zephyr/drivers/sensor.h>

Set an attribute for a sensor.

Parameters

dev	Pointer to the sensor device
chan	The channel the attribute belongs to, if any. Some attributes may only be set for all channels of a device, depending on device capabilities.
attr	The attribute to set
val	The value to set the attribute to

Returns

0 if successful, negative errno code if failure.

sensor_chan_spec_eq()

static bool sensor_chan_spec_eq ( struct sensor_chan_spec  chan_spec0, struct sensor_chan_spec  chan_spec1  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Check if channel specs are equivalent.

Parameters

chan_spec0	First chan spec
chan_spec1	Second chan spec

Return values

true	If equivalent
false	If not equivalent

sensor_channel_get()

int sensor_channel_get	(	const struct device *	dev,
		enum sensor_channel	chan,
		struct sensor_value *	val
	)

#include <include/zephyr/drivers/sensor.h>

Get a reading from a sensor device.

Return a useful value for a particular channel, from the driver's internal data. Before calling this function, a sample must be obtained by calling sensor_sample_fetch or sensor_sample_fetch_chan. It is guaranteed that two subsequent calls of this function for the same channels will yield the same value, if sensor_sample_fetch or sensor_sample_fetch_chan has not been called in the meantime.

For vectorial data samples you can request all axes in just one call by passing the specific channel with _XYZ suffix. The sample will be returned at val[0], val[1] and val[2] (X, Y and Z in that order).

Parameters

dev	Pointer to the sensor device
chan	The channel to read
val	Where to store the value

Returns

0 if successful, negative errno code if failure.

sensor_decode()

static int sensor_decode ( struct sensor_decode_context *  ctx, void *  out, uint16_t  max_count  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Decode N frames using a sensor_decode_context.

Parameters

[in,out]	ctx	The context to use for decoding
[out]	out	The output buffer
[in]	max_count	Maximum number of frames to decode

Returns

The decode result from sensor_decoder_api's decode function

sensor_degrees_to_rad()

static void sensor_degrees_to_rad ( int32_t  d, struct sensor_value *  rad  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting degrees to radians.

Parameters

d	The value (in degrees) to be converted.
rad	A pointer to a sensor_value struct, where the result is stored.

sensor_g_to_ms2()

static void sensor_g_to_ms2 ( int32_t  g, struct sensor_value *  ms2  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function to convert acceleration from Gs to m/s^2.

Parameters

g	The G value to be converted.
ms2	A pointer to a sensor_value struct, where the result is stored.

sensor_get_decoder()

int sensor_get_decoder	(	const struct device *	dev,
		const struct sensor_decoder_api **	decoder
	)

#include <include/zephyr/drivers/sensor.h>

Get the sensor's decoder API.

Parameters

[in]	dev	The sensor device
[in]	decoder	Pointer to the decoder which will be set upon success

Returns

0 on success

< 0 on error

sensor_ms2_to_g()

static int32_t sensor_ms2_to_g ( const struct sensor_value *  ms2 )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function to convert acceleration from m/s^2 to Gs.

Parameters

ms2	A pointer to a sensor_value struct holding the acceleration, in m/s^2.

Returns

The converted value, in Gs.

sensor_ms2_to_ug()

static int32_t sensor_ms2_to_ug ( const struct sensor_value *  ms2 )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function to convert acceleration from m/s^2 to micro Gs.

Parameters

ms2	A pointer to a sensor_value struct holding the acceleration, in m/s^2.

Returns

The converted value, in micro Gs.

sensor_natively_supported_channel_size_info()

int sensor_natively_supported_channel_size_info	(	struct sensor_chan_spec	channel,
		size_t *	base_size,
		size_t *	frame_size
	)

#include <include/zephyr/drivers/sensor.h>

sensor_processing_with_callback()

void sensor_processing_with_callback	(	struct rtio *	ctx,
		sensor_processing_callback_t	cb
	)

#include <include/zephyr/drivers/sensor.h>

Helper function for common processing of sensor data.

This function can be called in a blocking manner after sensor_read() or in a standalone thread dedicated to processing. It will wait for a cqe from the RTIO context, once received, it will decode the userdata and call the cb. Once the cb returns, the buffer will be released back into ctx's mempool if available.

Parameters

[in]	ctx	The RTIO context to wait on
[in]	cb	Callback to call when data is ready for processing

sensor_rad_to_10udegrees()

static int32_t sensor_rad_to_10udegrees ( const struct sensor_value *  rad )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting radians to 10 micro degrees.

When the unit is 1 micro degree, the range that the int32_t can represent is +/-2147.483 degrees. In order to increase this range, here we use 10 micro degrees as the unit.

Parameters

rad	A pointer to a sensor_value struct, holding the value in radians.

Returns

The converted value, in 10 micro degrees.

sensor_rad_to_degrees()

static int32_t sensor_rad_to_degrees ( const struct sensor_value *  rad )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting radians to degrees.

Parameters

rad	A pointer to a sensor_value struct, holding the value in radians.

Returns

The converted value, in degrees.

sensor_read()

static int sensor_read ( struct rtio_iodev *  iodev, struct rtio *  ctx, uint8_t *  buf, size_t  buf_len  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Blocking one shot read of samples from a sensor into a buffer.

Using cfg, read data from the device by using the provided RTIO context ctx. This call will generate a rtio_sqe that will be given the provided buffer. The call will wait for the read to complete before returning to the caller.

Parameters

[in]	iodev	The iodev created by SENSOR_DT_READ_IODEV
[in]	ctx	The RTIO context to service the read
[in]	buf	Pointer to memory to read sample data into
[in]	buf_len	Size in bytes of the given memory that are valid to read into

Returns

0 on success

< 0 on error

sensor_read_async_mempool()

static int sensor_read_async_mempool ( struct rtio_iodev *  iodev, struct rtio *  ctx, void *  userdata  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

One shot non-blocking read with pool allocated buffer.

Using cfg, read one snapshot of data from the device by using the provided RTIO context ctx. This call will generate a rtio_sqe that will leverage the RTIO's internal mempool when the time comes to service the read.

Parameters

[in]	iodev	The iodev created by SENSOR_DT_READ_IODEV
[in]	ctx	The RTIO context to service the read
[in]	userdata	Optional userdata that will be available when the read is complete

Returns

0 on success

< 0 on error

sensor_reconfigure_read_iodev()

int sensor_reconfigure_read_iodev	(	struct rtio_iodev *	iodev,
		const struct device *	sensor,
		const struct sensor_chan_spec *	channels,
		size_t	num_channels
	)

#include <include/zephyr/drivers/sensor.h>

Reconfigure a reading iodev.

Allows a reconfiguration of the iodev associated with reading a sample from a sensor.

Important: If the iodev is currently servicing a read operation, the data will likely be invalid. Please be sure the flush or wait for all pending operations to complete before using the data after a configuration change.

It is also important that the data field of the iodev is a sensor_read_config.

Parameters

[in]	iodev	The iodev to reconfigure
[in]	sensor	The sensor to read from
[in]	channels	One or more channels to read
[in]	num_channels	The number of channels in channels

Returns

0 on success

< 0 on error

sensor_sample_fetch()

int sensor_sample_fetch

(

const struct device *

dev

)

#include <include/zephyr/drivers/sensor.h>

Fetch a sample from the sensor and store it in an internal driver buffer.

Read all of a sensor's active channels and, if necessary, perform any additional operations necessary to make the values useful. The user may then get individual channel values by calling sensor_channel_get.

The function blocks until the fetch operation is complete.

Since the function communicates with the sensor device, it is unsafe to call it in an ISR if the device is connected via I2C or SPI.

Parameters

dev	Pointer to the sensor device

Returns

0 if successful, negative errno code if failure.

sensor_sample_fetch_chan()

int sensor_sample_fetch_chan	(	const struct device *	dev,
		enum sensor_channel	type
	)

#include <include/zephyr/drivers/sensor.h>

Fetch a sample from the sensor and store it in an internal driver buffer.

Read and compute compensation for one type of sensor data (magnetometer, accelerometer, etc). The user may then get individual channel values by calling sensor_channel_get.

This is mostly implemented by multi function devices enabling reading at different sampling rates.

The function blocks until the fetch operation is complete.

Since the function communicates with the sensor device, it is unsafe to call it in an ISR if the device is connected via I2C or SPI.

Parameters

dev	Pointer to the sensor device
type	The channel that needs updated

Returns

0 if successful, negative errno code if failure.

sensor_stream()

static int sensor_stream ( struct rtio_iodev *  iodev, struct rtio *  ctx, void *  userdata, struct rtio_sqe **  handle  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

sensor_trigger_set()

static int sensor_trigger_set ( const struct device *  dev, const struct sensor_trigger *  trig, sensor_trigger_handler_t  handler  )

inlinestaticsupervisor

#include <include/zephyr/drivers/sensor.h>

Activate a sensor's trigger and set the trigger handler.

The handler will be called from a thread, so I2C or SPI operations are safe. However, the thread's stack is limited and defined by the driver. It is currently up to the caller to ensure that the handler does not overflow the stack.

The user-allocated trigger will be stored by the driver as a pointer, rather than a copy, and passed back to the handler. This enables the handler to use CONTAINER_OF to retrieve a context pointer when the trigger is embedded in a larger struct and requires that the trigger is not allocated on the stack.

Function properties (list may not be complete)

Parameters

dev	Pointer to the sensor device
trig	The trigger to activate
handler	The function that should be called when the trigger fires

Returns

0 if successful, negative errno code if failure.

sensor_ug_to_ms2()

static void sensor_ug_to_ms2 ( int32_t  ug, struct sensor_value *  ms2  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function to convert acceleration from micro Gs to m/s^2.

Parameters

ug	The micro G value to be converted.
ms2	A pointer to a sensor_value struct, where the result is stored.

sensor_value_from_double()

static int sensor_value_from_double ( struct sensor_value *  val, double  inp  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting double to struct sensor_value.

Parameters

val	A pointer to a sensor_value struct.
inp	The converted value.

Returns

0 if successful, negative errno code if failure.

sensor_value_from_float()

static int sensor_value_from_float ( struct sensor_value *  val, float  inp  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting float to struct sensor_value.

Parameters

val	A pointer to a sensor_value struct.
inp	The converted value.

Returns

0 if successful, negative errno code if failure.

sensor_value_from_micro()

static int sensor_value_from_micro ( struct sensor_value *  val, int64_t  micro  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting integer micro units to struct sensor_value.

Parameters

val	A pointer to a sensor_value struct.
micro	The converted value.

Returns

0 if successful, negative errno code if failure.

sensor_value_from_milli()

static int sensor_value_from_milli ( struct sensor_value *  val, int64_t  milli  )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting integer milli units to struct sensor_value.

Parameters

val	A pointer to a sensor_value struct.
milli	The converted value.

Returns

0 if successful, negative errno code if failure.

sensor_value_to_double()

static double sensor_value_to_double ( const struct sensor_value *  val )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to double.

Parameters

val	A pointer to a sensor_value struct.

Returns

The converted value.

sensor_value_to_float()

static float sensor_value_to_float ( const struct sensor_value *  val )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to float.

Parameters

val	A pointer to a sensor_value struct.

Returns

The converted value.

sensor_value_to_micro()

static int64_t sensor_value_to_micro ( const struct sensor_value *  val )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to integer micro units.

Parameters

val	A pointer to a sensor_value struct.

Returns

The converted value.

sensor_value_to_milli()

static int64_t sensor_value_to_milli ( const struct sensor_value *  val )

inlinestatic

#include <include/zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to integer milli units.

Parameters

val	A pointer to a sensor_value struct.

Returns

The converted value.