Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Sensor Interface

Sensor Interface. More...

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 int(* 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_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_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, void *userdata)
 Read data from a sensor.
 
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 <zephyr/drivers/sensor.h>

Value:
((chan) == SENSOR_CHAN_ACCEL_XYZ || (chan) == SENSOR_CHAN_GYRO_XYZ || \
@ SENSOR_CHAN_ACCEL_XYZ
Acceleration on the X, Y and Z axes.
Definition: sensor.h:69
@ SENSOR_CHAN_GYRO_XYZ
Angular velocity around the X, Y and Z axes.
Definition: sensor.h:77
@ SENSOR_CHAN_MAGN_XYZ
Magnetic field on the X, Y and Z axes.
Definition: sensor.h:85

checks if a given channel is a 3-axis channel

Parameters
[in]chanThe channel to check
Return values
trueif chan is any of SENSOR_CHAN_ACCEL_XYZ, SENSOR_CHAN_GYRO_XYZ, or SENSOR_CHAN_MAGN_XYZ
falseotherwise

◆ SENSOR_DECODE_CONTEXT_INIT

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

#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 <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);
#define DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api,...)
Create a device object from a devicetree node identifier and set it up for boot time initialization.
Definition: device.h:194
Runtime PM info for device with generic PM.
Definition: device.h:163

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_idThe devicetree node identifier.
init_fnName of the init function of the driver.
pm_devicePM device resources reference (NULL if device does not use PM).
data_ptrPointer to the device's private data.
cfg_ptrThe address to the structure containing the configuration information for this instance of the driver.
levelThe initialization level. See SYS_INIT() for details.
prioPriority within the selected initialization level. See SYS_INIT() for details.
api_ptrProvides 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 <zephyr/drivers/sensor.h>

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

Parameters
instinstance 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 <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 DEVICE_DT_GET(node_id)
Get a device reference from a devicetree node identifier.
Definition: device.h:245
#define ARRAY_SIZE(array)
Number of elements in the given array.
Definition: util.h:127
Sensor Channel Specification.
Definition: sensor.h:429
Definition: sensor.h:620

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),
int main(void) {
sensor_read(&icm42688_accelgyro, &rtio);
}
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:200
#define SENSOR_DT_READ_IODEV(name, dt_node,...)
Define a reading instance of a sensor.
Definition: sensor.h:646
static int sensor_read(struct rtio_iodev *iodev, struct rtio *ctx, void *userdata)
Read data from a sensor.
Definition: sensor.h:1040
An RTIO context containing what can be viewed as a pair of queues.
Definition: rtio.h:327

◆ SENSOR_DT_STREAM_IODEV

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

#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))
Definition: sensor.h:606

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)
int main(void) {
struct rtio_sqe *handle;
sensor_stream(&imu_stream, &rtio, NULL, &handle);
k_msleep(1000);
rtio_sqe_cancel(handle);
}
#define DT_ALIAS(alias)
Get a node identifier from /aliases.
Definition: devicetree.h:240
int rtio_sqe_cancel(struct rtio_sqe *sqe)
Attempt to cancel an SQE.
#define SENSOR_DT_STREAM_IODEV(name, dt_node,...)
Define a stream instance of a sensor.
Definition: sensor.h:676
static int sensor_stream(struct rtio_iodev *iodev, struct rtio *ctx, void *userdata, struct rtio_sqe **handle)
Definition: sensor.h:1004
@ SENSOR_TRIG_FIFO_FULL
Trigger fires when the FIFO becomes full.
Definition: sensor.h:263
@ SENSOR_TRIG_FIFO_WATERMARK
Trigger fires when the FIFO watermark has been reached.
Definition: sensor.h:260
@ SENSOR_STREAM_DATA_INCLUDE
Include whatever data is associated with the trigger.
Definition: sensor.h:599
@ SENSOR_STREAM_DATA_NOP
Do nothing with the associated trigger data, it may be consumed later.
Definition: sensor.h:601
static int32_t k_msleep(int32_t ms)
Put the current thread to sleep.
Definition: kernel.h:489
A submission queue event.
Definition: rtio.h:232

◆ SENSOR_G

#define SENSOR_G   9806650LL

#include <zephyr/drivers/sensor.h>

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

◆ SENSOR_INFO_DEFINE

#define SENSOR_INFO_DEFINE (   name,
  ... 
)

◆ SENSOR_INFO_DT_DEFINE

#define SENSOR_INFO_DT_DEFINE (   node_id)

◆ SENSOR_PI

#define SENSOR_PI   3141592LL

#include <zephyr/drivers/sensor.h>

The value of constant PI in micros.

◆ SENSOR_STREAM_TRIGGER_PREP

#define SENSOR_STREAM_TRIGGER_PREP (   _trigger,
  _opt 
)

#include <zephyr/drivers/sensor.h>

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

Typedef Documentation

◆ sensor_attr_get_t

sensor_attr_get_t

#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 <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 <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 <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 <zephyr/drivers/sensor.h>

Callback function used with the helper processing function.

See also
sensor_processing_with_callback
Parameters
[in]resultThe result code of the read (0 being success)
[in]bufThe data buffer holding the sensor data
[in]buf_lenThe length (in bytes) of the buf
[in]userdataThe optional userdata passed to sensor_read()

◆ sensor_sample_fetch_t

sensor_sample_fetch_t

#include <zephyr/drivers/sensor.h>

Callback API for fetching data from a sensor.

See sensor_sample_fetch() for argument description

◆ sensor_submit_t

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

◆ sensor_trigger_handler_t

sensor_trigger_handler_t

#include <zephyr/drivers/sensor.h>

Callback API upon firing of a trigger.

Parameters
devPointer to the sensor device
triggerThe trigger

◆ sensor_trigger_set_t

sensor_trigger_set_t

#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

#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_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

#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_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

#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

#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 <zephyr/drivers/sensor.h>

Helper function for converting 10 micro degrees to radians.

Parameters
dThe value (in 10 micro degrees) to be converted.
radA 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 <zephyr/drivers/sensor.h>

Get an attribute for a sensor.

Parameters
devPointer to the sensor device
chanThe channel the attribute belongs to, if any. Some attributes may only be set for all channels of a device, depending on device capabilities.
attrThe attribute to get
valPointer 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 <zephyr/drivers/sensor.h>

Set an attribute for a sensor.

Parameters
devPointer to the sensor device
chanThe channel the attribute belongs to, if any. Some attributes may only be set for all channels of a device, depending on device capabilities.
attrThe attribute to set
valThe 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 <zephyr/drivers/sensor.h>

Check if channel specs are equivalent.

Parameters
chan_spec0First chan spec
chan_spec1Second chan spec
Return values
trueIf equivalent
falseIf not equivalent

◆ sensor_channel_get()

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

#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
devPointer to the sensor device
chanThe channel to read
valWhere 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 <zephyr/drivers/sensor.h>

Decode N frames using a sensor_decode_context.

Parameters
[in,out]ctxThe context to use for decoding
[out]outThe output buffer
[in]max_countMaximum 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 <zephyr/drivers/sensor.h>

Helper function for converting degrees to radians.

Parameters
dThe value (in degrees) to be converted.
radA 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 <zephyr/drivers/sensor.h>

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

Parameters
gThe G value to be converted.
ms2A 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 <zephyr/drivers/sensor.h>

Get the sensor's decoder API.

Parameters
[in]devThe sensor device
[in]decoderPointer 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 <zephyr/drivers/sensor.h>

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

Parameters
ms2A 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 <zephyr/drivers/sensor.h>

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

Parameters
ms2A 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 
)

◆ sensor_processing_with_callback()

void sensor_processing_with_callback ( struct rtio ctx,
sensor_processing_callback_t  cb 
)

#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]ctxThe RTIO context to wait on
[in]cbCallback 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 <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
radA 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 <zephyr/drivers/sensor.h>

Helper function for converting radians to degrees.

Parameters
radA 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,
void *  userdata 
)
inlinestatic

#include <zephyr/drivers/sensor.h>

Read data from a sensor.

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]iodevThe iodev created by SENSOR_DT_READ_IODEV
[in]ctxThe RTIO context to service the read
[in]userdataOptional 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 <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]iodevThe iodev to reconfigure
[in]sensorThe sensor to read from
[in]channelsOne or more channels to read
[in]num_channelsThe number of channels in channels
Returns
0 on success
< 0 on error

◆ sensor_sample_fetch()

int sensor_sample_fetch ( const struct device dev)

#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
devPointer 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 <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
devPointer to the sensor device
typeThe 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

◆ sensor_trigger_set()

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

#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)
supervisor
Parameters
devPointer to the sensor device
trigThe trigger to activate
handlerThe 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 <zephyr/drivers/sensor.h>

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

Parameters
ugThe micro G value to be converted.
ms2A 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 <zephyr/drivers/sensor.h>

Helper function for converting double to struct sensor_value.

Parameters
valA pointer to a sensor_value struct.
inpThe 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 <zephyr/drivers/sensor.h>

Helper function for converting float to struct sensor_value.

Parameters
valA pointer to a sensor_value struct.
inpThe 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 <zephyr/drivers/sensor.h>

Helper function for converting integer micro units to struct sensor_value.

Parameters
valA pointer to a sensor_value struct.
microThe 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 <zephyr/drivers/sensor.h>

Helper function for converting integer milli units to struct sensor_value.

Parameters
valA pointer to a sensor_value struct.
milliThe 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 <zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to double.

Parameters
valA 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 <zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to float.

Parameters
valA 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 <zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to integer micro units.

Parameters
valA 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 <zephyr/drivers/sensor.h>

Helper function for converting struct sensor_value to integer milli units.

Parameters
valA pointer to a sensor_value struct.
Returns
The converted value.