Sensors

The sensor driver API provides functionality to uniformly read, configure, and setup event handling for devices that take real world measurements in meaningful units.

Sensors range from very simple temperature-reading devices that must be polled with a fixed scale to complex devices taking in readings from multitudes of sensors and themselves producing new inferred sensor data such as step counts, presence detection, orientation, and more.

Supporting this wide breadth of devices is a demanding task and the sensor API attempts to provide a uniform interface to them.

Using Sensors

Using sensors from an application there are some APIs and terms that are helpful to understand. Sensors in Zephyr are composed of Sensor Channels, Sensor Attributes, and Sensor Triggers. Attributes and triggers may be device or channel specific.

Note

Getting samples from sensors using the sensor API today can be done in one of two ways. A stable and long-lived API Fetch and Get, or a newer but rapidly stabilizing API Read and Decode. It’s expected that in the near future Fetch and Get will be deprecated in favor of Read and Decode. Triggers are handled entirely differently for Fetch and Get or Read and Decode and the differences are noted in each of those sections.

Implementing Sensor Drivers

Note

Implementing the driver side of the sensor API requires an understanding how the sensor APIs are used. Please read through Using Sensors first!

Implementing Attributes

SHOULD implement attribute setting in a blocking manner.
SHOULD provide the ability to get and set channel scale if supported by the device.
SHOULD provide the ability to get and set channel sampling rate if supported by the device.

Implementing Fetch and Get

SHOULD implement sensor_sample_fetch_t as a blocking call that stashes the specified channels (or all sensor channels) as driver instance data.
SHOULD implement sensor_channel_get_t without side effects manipulating driver state returning stashed sensor readings.
SHOULD implement sensor_trigger_set_t storing the address of the sensor_trigger rather than copying the contents. This is so CONTAINER_OF may be used for trigger callback context.

Implementing Read and Decode

MUST implement sensor_submit_t as a non-blocking call.
SHOULD implement sensor_submit_t using Real Time I/O (RTIO) to do non-blocking bus transfers if possible.
MAY implement sensor_submit_t using a work queue if Real Time I/O (RTIO) is unsupported by the bus.
SHOULD implement sensor_submit_t checking the rtio_sqe is of type RTIO_SQE_RX (read request).
SHOULD implement sensor_submit_t checking all requested channels supported or respond with an error if not.
SHOULD implement sensor_submit_t checking the provided buffer is large enough for the requested channels.
SHOULD implement sensor_submit_t in a way that directly reads into the provided buffer avoiding copying of any kind, with few exceptions.
MUST implement sensor_decoder_api with pure stateless functions. All state needed to convert the raw sensor readings into fixed point SI united values must be in the provided buffer.
MUST implement sensor_get_decoder_t returning the sensor_decoder_api for that device type.

API Reference

Sensor Interface

Related code samples

ADT7420 high-accuracy digital I2C temperature sensorGet temperature data from an ADT7420 sensor using polling and window mode.
AMG88XX infrared array sensorGet temperature data from an AMG88XX 8x8 thermal camera sensor.
ams iAQcore indoor air quality sensorGet CO2 equivalent and VOC data from an ams iAQcore sensor.
APDS9960 RGB, ambient light, and gesture sensorGet ambient light, RGB, and proximity/gesture data from an APDS9960 sensor.
BME280 humidity and pressure sensorGet temperature, pressure, and humidity data from a BME280 sensor.
BMI270 6-axis IMU sensorConfigure and read accelerometer and gyroscope data from a BMI270 sensor.
BQ274XX fuel gauge sensorGet various fuel gauge parameters from a BQ274XX sensor.
CCS811 indoor air quality sensorGet CO2 equivalent and VOC data from a CCS811 sensor.
CPU die temperature pollingGet CPU die temperature data from a sensor using polling.
DS18B20 1-Wire Temperature SensorGet ambient temperature data from a DS18B20 sensor (polling mode).
FDC2X1X Capacitance-to-Digital ConverterGet capacitance and frequency data from a FDC2X1X sensor (polling & trigger).
FXAS21002 Gyroscope SensorGet gyroscope data synchronously from an FXAS21002 sensor.
FXOS8700 Accelerometer/Magnetometer SensorGet accelerometer and magnetometer data from an FXOS8700 sensor (polling & trigger mode).
Generic 3-Axis accelerometer pollingGet 3-Axis accelerometer data from a sensor (polling mode).
Generic CO2 polling sampleGet CO2 data from a sensor (polling mode).
Generic digital humidity temperature sensor pollingGet temperature and humidity data from a DHT sensor (polling mode).
Grove Light SensorGet illuminance data from a Grove Light Sensor.
Grove Temperature SensorGet temperature data from a Grove temperature sensor and display it on an LCD display.
GROW R502-A Fingerprint SensorStore and match fingerprints using the GROW R502-A fingerprint sensor.
HTS221 Temperature and Humidity MonitorGet temperature and humidity data from an HTS221 sensor (polling & trigger mode).
I3G4250D 3-axis gyroscope sensorGet gyroscope data from an I3G4250D sensor.
INA219 Bidirectional Power/Current MonitorGet shunt voltage, bus voltage, power and current from an INA219 sensor.
ISL29035 Digital Light SensorGet light intensity data from an ISL29035 sensor (polling & trigger mode).
JEDEC JC 42.4 compliant Temperature SensorGet ambient temperature from a JEDEC JC 42.4 compliant temperature sensor (polling & trigger mode).
LIS2DH Motion SensorGet accelerometer data from an LIS2DH sensor (polling & trigger mode).
LPS22HB Temperature and Pressure SensorGet pressure and temperature data from an LPS22HB sensor (polling mode).
LPSS22HH Temperature and Pressure SensorGet pressure and temperature data from an LPS22HH sensor (polling & trigger mode).
LPSS22HH Temperature and Pressure Sensor (I3C)Get pressure and temperature data from an LPS22HH sensor over I3C (polling & trigger mode).
LSM303DLHC Magnetometer and Accelerometer sensorGet magnetometer and accelerometer data from an LSM303DLHC sensor (polling mode).
LSM6DSL IMU sensorGet accelerometer and gyroscope data from an LSM6DSL sensor (polling & trigger mode).
LSM6DSO IMU sensorGet accelerometer and gyroscope data from an LSM6DSO sensor (polling & trigger mode).
LSM6DSO IMU sensor (I2C on I3C bus)Get accelerometer and gyroscope data from an LSM6DSO sensor using I2C on I3C bus (polling & trigger mode).
LVGL line chart with accelerometer dataDisplay acceleration data on a real-time chart using LVGL.
Magnetometer SensorGet magnetometer data from a magnetometer sensor (polling mode).
MAX17262 Fuel Gauge SensorGet voltage, current and temperature data from a MAX17262 sensor (polling mode).
MAX30101 Heart Rate SensorGet heart rate data from a MAX30101 sensor (polling mode).
MAX6675 K-thermocouple to digital converterGet temperature from a MAX6675 K-thermocouple to digital converter (polling mode).
MPR Pressure SensorGet atmospheric pressure data from an MPR pressure sensor.
MPU6050 Invensense Motion Tracking DeviceGet temperature, acceleration, and angular velocity from an ICM42605 sensor (polling & trigger mode).
MPU6050 motion tracking deviceGet temperature, acceleration, and angular velocity from an MPU6050 sensor (polling & trigger mode).
MS5837 Digital Pressure SensorGet pressure and temperature data from an MS5837 sensor (polling mode).
NPCX ADC ComparatorDetect upper/lower voltage limits using NPCX ADC Comparator driver.
NXP MCUX Analog Comparator (ACMP)Get analog comparator data from an NXP MCUX Analog Comparator (ACMP).
NXP MCUX Low-power Analog Comparator (LPCMP)Get analog comparator data from an NXP MCUX Low-power Analog Comparator (LPCMP).
Proximity sensorGet proximity data from up to 10 proximity sensors (polling mode).
Quadrature Decoder SensorGet rotation data from a quadrature decoder sensor.
Secure MQTT Sensor/ActuatorImplement an MQTT-based IoT sensor/actuator device
Sensor shellInteract with sensors using the shell module.
SGP40 and SHT4X digital humidity and multipixel gas sensorGet temperature, humidity and gas sensor data from SGP40 and SHT4X sensors (polling mode).
SHT3XD humidity sensorGet temperature and humidity from a SHT3XD sensor (polling & trigger mode).
SM351LT Magnetoresistive SensorDetect a magnet's presence using the SM351LT magnetoresistive sensor (polling & trigger mode).
SoC Voltage SensorGet voltage data from an SoC's voltage sensor(s).
TH02 Temperature and Humidity SensorGet temperature and humidity data from a TH02 sensor (polling mode).
ThermometerGet ambient temperature data from a temperature sensor and get alerts when temperature drifts above a threshold. (polling & trigger mode).
TMP108 Temperature SensorGet temperature data from a TMP108 sensor (polling & trigger mode).
TMP112 Temperature SensorGet temperature data from a TMP112 sensor (polling & trigger mode).
VCNL4040 Proximity and Ambient Light SensorGet proximity and ambient light data from a VCNL4040 sensor (polling & trigger mode).
VEAA-X-3 proportional pressure control valveControl a VEAA-X-3 proportional pressure control valve.
VL53L0X Time Of Flight sensorGet distance data from a VL53L0X sensor (polling mode).
X-NUCLEO-53L0A1 shieldInteract with the 7-segment display and VL53L0X ranging sensor of an X-NUCLEO-53L0A1 shield.
X-NUCLEO-IKS01A1 shieldInteract with all the sensors of an X-NUCLEO-IKS01A1 shield.
X-NUCLEO-IKS01A2 shield - SensorHub (Mode 2)Interact with all the sensors of an X-NUCLEO-IKS01A2 shield using Sensor Hub mode.
X-NUCLEO-IKS01A2 shield - Standard (Mode 1)Interact with all the sensors of an X-NUCLEO-IKS01A2 shield using Standard Mode.
X-NUCLEO-IKS01A3 shield - SensorHub (Mode 2)Interact with all the sensors of an X-NUCLEO-IKS01A3 shield using Sensor Hub mode.
X-NUCLEO-IKS01A3 shield - Standard (Mode 1)Interact with all the sensors of an X-NUCLEO-IKS01A3 shield using Standard mode.
X-NUCLEO-IKS02A1 shield - SensorHub (Mode 2)Interact with all the sensors of an X-NUCLEO-IKS02A1 shield using Sensor Hub mode.
X-NUCLEO-IKS02A1 shield - Standard (Mode 1)Interact with all the sensors of an X-NUCLEO-IKS02A1 shield using Standard mode.

Sensor emulator backend API