Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
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_driver_api
 

Macros

#define SENSOR_G   9806650LL
 The value of gravitational constant in micro m/s^2. More...
 
#define SENSOR_PI   3141592LL
 The value of constant PI in micros. More...
 

Typedefs

typedef void(* sensor_trigger_handler_t) (const struct device *dev, struct sensor_trigger *trigger)
 Callback API upon firing of a trigger. More...
 
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. More...
 
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. More...
 
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. More...
 
typedef int(* sensor_sample_fetch_t) (const struct device *dev, enum sensor_channel chan)
 Callback API for fetching data from a sensor. More...
 
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. More...
 

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_VOC , SENSOR_CHAN_GAS_RES , SENSOR_CHAN_VOLTAGE , 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_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_COMMON_COUNT , SENSOR_ATTR_PRIV_START = SENSOR_ATTR_COMMON_COUNT ,
  SENSOR_ATTR_MAX = INT16_MAX
}
 Sensor attribute types. More...
 

Functions

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. More...
 
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. More...
 
static int sensor_trigger_set (const struct device *dev, struct sensor_trigger *trig, sensor_trigger_handler_t handler)
 Activate a sensor's trigger and set the trigger handler. More...
 
int sensor_sample_fetch (const struct device *dev)
 Fetch a sample from the sensor and store it in an internal driver buffer. More...
 
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. More...
 
int sensor_channel_get (const struct device *dev, enum sensor_channel chan, struct sensor_value *val)
 Get a reading from a sensor device. More...
 
static int32_t sensor_ms2_to_g (const struct sensor_value *ms2)
 Helper function to convert acceleration from m/s^2 to Gs. More...
 
static void sensor_g_to_ms2 (int32_t g, struct sensor_value *ms2)
 Helper function to convert acceleration from Gs to m/s^2. More...
 
static int32_t sensor_rad_to_degrees (const struct sensor_value *rad)
 Helper function for converting radians to degrees. More...
 
static void sensor_degrees_to_rad (int32_t d, struct sensor_value *rad)
 Helper function for converting degrees to radians. More...
 
static double sensor_value_to_double (const struct sensor_value *val)
 Helper function for converting struct sensor_value to double. More...
 
static void sensor_value_from_double (struct sensor_value *val, double inp)
 Helper function for converting double to struct sensor_value. More...
 

Detailed Description

Sensor Interface.

Macro Definition Documentation

◆ SENSOR_G

#define SENSOR_G   9806650LL

#include <include/drivers/sensor.h>

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

◆ SENSOR_PI

#define SENSOR_PI   3141592LL

#include <include/drivers/sensor.h>

The value of constant PI in micros.

Typedef Documentation

◆ sensor_attr_get_t

sensor_attr_get_t

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

Callback API for getting a reading from a sensor.

See sensor_channel_get() for argument description

◆ sensor_sample_fetch_t

sensor_sample_fetch_t

#include <include/drivers/sensor.h>

Callback API for fetching data from a sensor.

See sensor_sample_fetch() for argument description

◆ sensor_trigger_handler_t

sensor_trigger_handler_t

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

Standy 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_trigger_type

#include <include/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_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_attr_get()

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

#include <include/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 <include/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_channel_get()

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

#include <include/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_degrees_to_rad()

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

#include <include/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 <include/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_ms2_to_g()

static int32_t sensor_ms2_to_g ( const struct sensor_value ms2)
inlinestatic

#include <include/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_rad_to_degrees()

static int32_t sensor_rad_to_degrees ( const struct sensor_value rad)
inlinestatic

#include <include/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_sample_fetch()

int sensor_sample_fetch ( const struct device dev)

#include <include/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.

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 <include/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.

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_trigger_set()

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

#include <include/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.

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_value_from_double()

static void sensor_value_from_double ( struct sensor_value val,
double  inp 
)
inlinestatic

#include <include/drivers/sensor.h>

Helper function for converting double to struct sensor_value.

Parameters
valA pointer to a sensor_value struct.
inpThe converted value.

◆ sensor_value_to_double()

static double sensor_value_to_double ( const struct sensor_value val)
inlinestatic

#include <include/drivers/sensor.h>

Helper function for converting struct sensor_value to double.

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