传感器

传感器驱动 API 提供统一的接口，用于读取和配置以具有实际意义的单位测量现实世界物理量的设备，并为其设置事件处理。

传感器种类繁多，既有采用固定比例系数、必须通过轮询读取的简单温度测量设备，也有接收多个传感器的读数，并自行推导出步数、存在检测、朝向等新传感器数据的复杂设备。

支持如此广泛的设备是一项艰巨的任务，传感器 API 力求为这些设备提供统一的接口。

使用传感器

在应用中使用传感器时，了解一些 API 和术语会有所帮助。Zephyr 中的传感器由 传感器通道、传感器属性 和 传感器触发器 组成。属性和触发器可能针对特定设备或通道。

备注

目前，可以通过两种方式使用传感器 API 获取传感器采样数据：一种是稳定且已长期使用的 API 采集与获取，另一种是较新但正在迅速趋于稳定的 API 读取与解码。预计在不久的将来，采集与获取 将被弃用，转而采用 读取与解码。采集与获取 和 读取与解码 对触发器的处理方式完全不同，各自的章节中说明了这些差异。

• 传感器属性
• 传感器通道
• 传感器触发器
• 电源管理
• 设备树
• 采集与获取
• 读取与解码

实现传感器驱动

备注

实现传感器 API 的驱动端需要了解这些 API 的使用方式。请先通读 使用传感器！

实现属性

• 应以阻塞方式实现属性设置。

• 如果设备支持，应提供获取和设置通道比例系数的能力。

• 如果设备支持，应提供获取和设置通道采样率的能力。

实现采集与获取

• 应将 sensor_sample_fetch_t 实现为阻塞调用，将指定通道（或所有传感器通道）的采样数据暂存为驱动实例数据。

• 应实现 sensor_channel_get_t，使其返回暂存的传感器读数，且不产生修改驱动状态的副作用。

• 实现 sensor_trigger_set_t 时，应存储 sensor_trigger 的地址，而不是复制其内容。这样便可使用 CONTAINER_OF 获取触发器回调的上下文。

实现读取与解码

• 必须将 sensor_submit_t 实现为非阻塞调用。

• 实现 sensor_submit_t 时，应尽可能使用 实时 I/O（RTIO） 进行非阻塞总线传输。

• 如果总线不支持 实时 I/O（RTIO），可以使用工作队列实现 sensor_submit_t。

• 实现 sensor_submit_t 时，应检查 rtio_sqe 的类型是否为 RTIO_SQE_RX （读取请求）。

• 实现 sensor_submit_t 时，应检查是否支持所有请求的通道；如果不支持，则返回错误。

• 实现 sensor_submit_t 时，应检查提供的缓冲区是否足够容纳所请求通道的数据。

• 实现 sensor_submit_t 时，除少数例外情况外，应将数据直接读入提供的缓冲区，避免任何形式的复制。

• 必须使用无状态的纯函数实现 sensor_decoder_api。将原始传感器读数转换为以国际单位制（SI）单位表示的定点数值所需的全部状态，都必须包含在提供的缓冲区中。

• 必须实现 sensor_get_decoder_t，使其返回对应设备类型的 sensor_decoder_api。

API 参考

Sensor

Related code samples

• 6dof device FIFO streamingGet accelerometer/gyroscope/temperature FIFO data frames from a sensor using SENSOR_TRIG_FIFO_WATERMARK as a trigger.
• 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.
• Barometric pressure and temperature sensor interrupt exampleManage interrupts from a barometric pressure and temperature sensor.
• Barometric pressure and temperature sensor polling exampleGet barometric pressure and temperature data from a sensor.
• BME280 humidity and pressure sensorGet temperature, pressure, and humidity data from a BME280 sensor.
• BMG160 3-axis gyroscopeGet temperature, and angular velocity data from a BMG160 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).
• ESP32 qdec per-unit threshold triggerInstall per-unit threshold callbacks on the ESP32 PCNT driver.
• FDC2X1X Capacitance-to-Digital ConverterGet capacitance and frequency data from a FDC2X1X sensor (polling & trigger).
• Flow MeterRead flow rate and volume from a Hall-effect pulse-output flow meter.
• FXAS21002 Gyroscope SensorGet gyroscope data synchronously from an FXAS21002 sensor.
• Generic 3-Axis accelerometer pollingGet 3-Axis accelerometer data from a sensor (polling mode).
• Generic 3-Axis accelerometer streamingGet 3-Axis accelerometer data from a sensor (stream mode).
• Generic 6DOF Motion DatareadyGet 6-Axis accelerometer and gyroscope data from a sensor (data ready interrupt mode).
• Generic CO2 polling sampleGet CO2 data from a sensor (polling mode).
• Generic device sample streaming using Data Ready triggerGet accelerometer data frames from a sensor using SENSOR_TRIG_DATA_READY.
• Generic digital humidity temperature sensor pollingGet temperature and humidity data from a DHT sensor (polling mode).
• Generic distance measurementMeasure distance to an object using a distance sensor
• Generic Light Sensor PollingGet illuminance data from a 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.
• Heart Rate SensorGet heart rate data from a sensor (polling/interrupt mode).
• 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.
• Iclegend S3KM1110 mmWave sensorRead standard and custom channels from an Iclegend S3KM1110 mmWave radar 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).
• LPS22HH Temperature and Pressure SensorGet pressure and temperature data from an LPS22HH sensor (polling & trigger mode).
• LPS22HH 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).
• MAX32664C + MAX86141 Sensor Hub
• MAX6675 K-thermocouple to digital converterGet temperature from a MAX6675 K-thermocouple to digital converter (polling mode).
• 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).
• MTCH9010 Liquid Leak Detector TestbenchConfigure an MTCH9010 and receive data from it periodically.
• Multi-unit quadrature decoderRead several quadrature encoders from a single sensor device using the Read-and-Decode API.
• 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).
• PAJ7620 Gesture SensorGet hand gesture data from PAJ7620 sensor.
• 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 ClockTest and debug Sensor Clock functionality.
• 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).
• SX9500 SAR proximity sensorGet proximity data from an SX9500 SAR proximity sensor.
• TDK Advanced Pedometer and Event Detection (APEX)Get TDK APEX event detection (trigger mode).
• TDK integrated angle sensor with TMR (Tunnel Magneto Resistance)Get angle and temperature data from a TDK TAD2144 sensor using SPI, I2C and Encoder(angle data only).
• 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.
• VEML6031 High Accuracy Ambient Light SensorGet ambient light data from a VEML4040 sensor (polling mode).
• VEML6046 RGBIR Color SensorGet red, green, blue and IR light data from a VEML6046 sensor (polling mode).
• 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.
• X-NUCLEO-IKS4A1 shield - SensorHub (Mode 2)Interact with all the sensors of an X-NUCLEO-IKS4A1 shield using SHUB2 (mode 2).
• X-NUCLEO-IKS4A1 shield - SensorHub (Mode 3)Interact with all the sensors of an X-NUCLEO-IKS4A1 shield using SHUB1 (mode 3).
• X-NUCLEO-IKS4A1 shield - Standard (Mode 1)Interact with all the sensors of an X-NUCLEO-IKS4A1 shield using Standard mode.

Sensor emulator backend API