Sensor Hub 简介

[English]

Sensor Hub 是一个传感器管理组件，可以实现对传感器设备的硬件抽象、设备管理和数据分发。基于 Sensor Hub 开发应用程序时，用户无需处理复杂的传感器实现，只需要对传感器的工作方式、采集间隔、量程等进行简单的选择，然后向关心的事件消息注册回调函数，即可在传感器状态切换或者数据采集好时收到通知。

Sensor Hub 编程模型

Sensor Hub 支持以组件方式加载传感器驱动，用户在添加传感器时只需填入注册到 Sensor Hub 的传感器名称即可直接获取对应的传感器驱动。此外，该组件由于实现了对传感器的集中管理，在简化操作的同时也提高了运行效率，可作为传感器应用的基础组件，应用在环境感知、运动感知、健康管理等更多智能化场景中。

Sensor Hub 驱动

Sensor Hub 使用方法

sensor_hub 采用 链接器脚本生成机制 将传感器驱动注册到特定的目标文件段中。对于应用开发者而言，无需关注传感器驱动的具体实现，只需添加对应的传感器组件即可加载对应的驱动。

驱动开发者：

以 ShT3X 温湿度传感器为例，驱动开发者需要将与传感器相关的操作填入到 humiture_impl_t，并创建传感器检测函数。sensor_hub 提供了用于传感器注册接口：SENSOR_HUB_DETECT_FN，驱动开发者可以直接将对应的函数填入到注册接口中。

static humiture_impl_t sht3x_impl = {
    .init = humiture_sht3x_init,
    .deinit = humiture_sht3x_deinit,
    .test = humiture_sht3x_test,
    .acquire_humidity = humiture_sht3x_acquire_humidity,
    .acquire_temperature = humiture_sht3x_acquire_temperature,
};

SENSOR_HUB_DETECT_FN(HUMITURE_ID, sht3x, &sht3x_impl);

同时，在组件的 CMakeLists.txt 中添加接口依赖：

target_link_libraries(${COMPONENT_LIB} INTERFACE "-u humiture_sht3x_init")

应用开发者：

1. 在工程的 idf_component.yml 中添加 sensor_hub 与所需的传感器组件。

2. 创建一个传感器实例：使用 iot_sensor_create() 创建一个传感器实例，参数包括传感器名称、传感器配置项和传感器句柄指针。传感器名称用于查找和加载注册到 sensor_hub 中的传感器的驱动，若传感器支持地址可配置，则可以多次创建该名称的传感器。配置项中 bus 用于指定传感器挂载到的总线位置；addr 用于指定传感器对应的地址；type 用于指定传感器对应的类型；mode 用于指定传感器的工作模式；min_delay 用于指定传感器的采集间隔，其它均为非必须项。创建成功之后，获得该传感器句柄；

sensor_config_t sht3x_config = {
    .bus = i2c0_bus_handle,
    .addr = 0x44,
    .mode = MODE_POLLING,
    .min_delay = SENSOR_PERIOD,
};
iot_sensor_create("sht3x", &sht3x_config, &sht3x_handle)

3. 注册传感器事件回调函数：在传感器事件发生时，回调函数将会被依次调用，注册回调函数的方法有以下两种，注册成功之后将返回事件回调函数实例句柄：

   • 使用 iot_sensor_handler_register() 通过传感器句柄注册回调函数

   • 使用 iot_sensor_handler_register_with_type() 通过传感器类型注册回调函数

4. 启动传感器：使用 iot_sensor_start() 启动指定的传感器，传感器启动之后将发出 SENSOR_STARTED 事件，之后将以设定的周期持续采集传感器数据，并发送 SENSOR_XXXX_DATA_READY 事件。事件回调函数可通过 event_data 参数获取每一个事件的具体数据；

5. 停止传感器：使用 iot_sensor_stop() 可临时关闭指定的传感器，传感器关闭之后将发出 SENSOR_STOPED 事件，之后采集工作将停止。如果该传感器驱动支持电源管理，传感器将被设置为睡眠模式;

6. 取消注册传感器事件回调函数：用户程序可在任意时刻使用事件回调函数实例句柄取消对事件的注册，之后该事件发生时，该回调函数将不再被调用。取消注册的方法对应也有两种：

   • 使用 iot_sensor_handler_unregister() 通过传感器句柄取消已注册的回调函数

   • 使用 iot_sensor_handler_unregister_with_type() 通过传感器类型取消已经注册的回调函数

7. 删除传感器：使用 iot_sensor_delete() 可删除对应的传感器，释放已分配的内存等资源。

示例程序

1. 温湿度传感器控制 LED 开关示例：sensors/sensor_control_led。

2. 传感器监测示例：sensors/sensor_hub_monitor。

API 参考

Header File

• components/sensors/sensor_hub/include/sensor_type.h

Structures

struct sensor_data_t

sensor data type

Public Members

int64_t timestamp

timestamp

const char *sensor_name

sensor name

sensor_type_t sensor_type

sensor type

uint8_t sensor_addr

sensor addr

int32_t event_id

reserved for future use

uint32_t min_delay

minimum delay between two events, unit: ms

axis3_t acce

Accelerometer. unit: G

axis3_t gyro

Gyroscope. unit: dps

axis3_t mag

Magnetometer. unit: Gauss

float temperature

Temperature. unit: dCelsius

float humidity

Relative humidity. unit: percentage

float baro

Pressure. unit: pascal (Pa)

float light

Light. unit: lux

rgbw_t rgbw

Color. unit: lux

uv_t uv

ultraviole unit: lux

float proximity

Distance. unit: centimeters

float hr

Heat rate. unit: HZ

float tvoc

TVOC. unit: permillage

float noise

Noise Loudness. unit: HZ

float step

Step sensor. unit: 1

float force

Force sensor. unit: mN

float current

Current sensor unit: mA

float voltage

Voltage sensor unit: mV

float data[4]

for general use

struct sensor_data_group_t

sensor data group type

Public Members

uint8_t number

effective data number

sensor_data_t sensor_data[SENSOR_DATA_GROUP_MAX_NUM]

data buffer

Macros

SENSOR_EVENT_ANY_ID

register handler for any event id

Type Definitions

typedef void *sensor_device_impl_t

typedef void *sensor_driver_handle_t

hal level sensor driver handle

typedef void *bus_handle_t

i2c/spi bus handle

Enumerations

enum sensor_type_t

sensor type

Values:

enumerator NULL_ID

NULL

enumerator HUMITURE_ID

humidity or temperature sensor

enumerator IMU_ID

gyro or acc sensor

enumerator LIGHT_SENSOR_ID

light illumination or uv or color sensor

enumerator SENSOR_TYPE_MAX

max sensor type

enum sensor_command_t

sensor operate command

Values:

enumerator COMMAND_SET_MODE

set measure mode

enumerator COMMAND_SET_RANGE

set measure range

enumerator COMMAND_SET_ODR

set output rate

enumerator COMMAND_SET_POWER

set power mode

enumerator COMMAND_SELF_TEST

sensor self test

enumerator COMMAND_MAX

max sensor command

enum sensor_power_mode_t

sensor power mode

Values:

enumerator POWER_MODE_WAKEUP

wakeup from sleep

enumerator POWER_MODE_SLEEP

set to sleep

enumerator POWER_MAX

max sensor power mode

enum sensor_mode_t

sensor acquire mode

Values:

enumerator MODE_DEFAULT

default work mode

enumerator MODE_POLLING

polling acquire with a interval time

enumerator MODE_INTERRUPT

interrupt mode, acquire data when interrupt comes

enumerator MODE_MAX

max sensor mode

enum sensor_range_t

sensor acquire range

Values:

enumerator RANGE_DEFAULT

default range

enumerator RANGE_MIN

minimum range for high-speed or high-precision

enumerator RANGE_MEDIUM

medium range for general use

enumerator RANGE_MAX

maximum range for full scale

enum sensor_event_id_t

sensor general events

Values:

enumerator SENSOR_STARTED

sensor started, data acquire will be started

enumerator SENSOR_STOPED

sensor stopped, data acquire will be stopped

enumerator SENSOR_EVENT_COMMON_END

max common events id

enum sensor_data_event_id_t

sensor data ready events

Values:

enumerator SENSOR_ACCE_DATA_READY

Accelerometer data ready

enumerator SENSOR_GYRO_DATA_READY

Gyroscope data ready

enumerator SENSOR_MAG_DATA_READY

Magnetometer data ready

enumerator SENSOR_TEMP_DATA_READY

Temperature data ready

enumerator SENSOR_HUMI_DATA_READY

Relative humidity data ready

enumerator SENSOR_BARO_DATA_READY

Pressure data ready

enumerator SENSOR_LIGHT_DATA_READY

Light data ready

enumerator SENSOR_RGBW_DATA_READY

Color data ready

enumerator SENSOR_UV_DATA_READY

ultraviolet data ready

enumerator SENSOR_PROXI_DATA_READY

Distance data ready

enumerator SENSOR_HR_DATA_READY

Heat rate data ready

enumerator SENSOR_TVOC_DATA_READY

TVOC data ready

enumerator SENSOR_NOISE_DATA_READY

Noise Loudness data ready

enumerator SENSOR_STEP_DATA_READY

Step data ready

enumerator SENSOR_FORCE_DATA_READY

Force data ready

enumerator SENSOR_CURRENT_DATA_READY

Current data ready

enumerator SENSOR_VOLTAGE_DATA_READY

Voltage data ready

enumerator SENSOR_EVENT_ID_END

max common events id

Header File

• components/sensors/sensor_hub/include/iot_sensor_hub.h

Functions

esp_err_t iot_sensor_create(const char *sensor_name, const sensor_config_t *config, sensor_handle_t *p_sensor_handle)

Create a sensor instance with specified name and desired configurations.

参数

• sensor_name – sensor’s name. Sensor information will be registered by ESP_SENSOR_DETECT_FN

• config – sensor’s configurations detailed in sensor_config_t

• p_sensor_handle – return sensor handle if succeed, NULL if failed.

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_start(sensor_handle_t sensor_handle)

start sensor acquisition, post data ready events when data acquired. if start succeed, sensor will start to acquire data with desired mode and post events in min_delay(ms) intervals SENSOR_STARTED event will be posted.

参数

sensor_handle – sensor handle for operation

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_stop(sensor_handle_t sensor_handle)

stop sensor acquisition, and stop post data events. if stop succeed, SENSOR_STOPED event will be posted.

参数

sensor_handle – sensor handle for operation

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_delete(sensor_handle_t p_sensor_handle)

delete and release the sensor resource.

参数

p_sensor_handle – sensor handle, will set to NULL if delete succeed.

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

int iot_sensor_scan()

Scan for valid sensors attached on bus.

Scan for valid sensors registered in the system

参数

• bus – bus handle

• buf – Pointer to a buffer to save sensors’ information, if NULL no information will be saved.

• num – Maximum number of sensor information to save, invalid if buf set to NULL, latter sensors will be discarded if num less-than the total number found on the bus.

返回

uint8_t total number of valid sensors found on the bus

返回

int number of valid sensors

esp_err_t iot_sensor_handler_register(sensor_handle_t sensor_handle, sensor_event_handler_t handler, sensor_event_handler_instance_t *context)

Register a event handler to a sensor’s event with sensor_handle.

参数

• sensor_handle – sensor handle for operation

• handler – the handler function which gets called when the sensor’s any event is dispatched

• context – An event handler instance object related to the registered event handler and data, can be NULL. This needs to be kept if the specific callback instance should be unregistered before deleting the whole event loop. Registering the same event handler multiple times is possible and yields distinct instance objects. The data can be the same for all registrations. If no unregistration is needed but the handler should be deleted when the event loop is deleted, instance can be NULL.

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_handler_unregister(sensor_handle_t sensor_handle, sensor_event_handler_instance_t context)

Unregister a event handler from a sensor’s event.

参数

• sensor_handle – sensor handle for operation

• context – the instance object of the registration to be unregistered

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_handler_register_with_type(sensor_type_t sensor_type, int32_t event_id, sensor_event_handler_t handler, sensor_event_handler_instance_t *context)

Register a event handler with sensor_type instead of sensor_handle. the api only care about the event type, don’t care who post it.

参数

• sensor_type – sensor type declared in sensor_type_t.

• event_id – sensor event declared in sensor_event_id_t and sensor_data_event_id_t

• handler – the handler function which gets called when the event is dispatched

• context – An event handler instance object related to the registered event handler and data, can be NULL. This needs to be kept if the specific callback instance should be unregistered before deleting the whole event loop. Registering the same event handler multiple times is possible and yields distinct instance objects. The data can be the same for all registrations. If no unregistration is needed but the handler should be deleted when the event loop is deleted, instance can be NULL.

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

esp_err_t iot_sensor_handler_unregister_with_type(sensor_type_t sensor_type, int32_t event_id, sensor_event_handler_instance_t context)

Unregister a event handler from a event. the api only care about the event type, don’t care who post it.

参数

• sensor_type – sensor type declared in sensor_type_t.

• event_id – sensor event declared in sensor_event_id_t and sensor_data_event_id_t

• context – the instance object of the registration to be unregistered

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

Structures

struct sensor_info_t

sensor information, written by the driver developer.

Public Members

const char *name

sensor name

sensor_type_t sensor_type

sensor type

struct sensor_config_t

sensor initialization parameter

Public Members

bus_handle_t bus

i2c/spi bus handle

uint8_t addr

set addr of sensor

sensor_type_t type

sensor type

sensor_mode_t mode

set acquire mode detiled in sensor_mode_t

sensor_range_t range

set measuring range

uint32_t min_delay

set minimum acquisition interval

int intr_pin

set interrupt pin

int intr_type

set interrupt type

struct sensor_hub_detect_fn_t

Detection function interface for sensors.

Public Members

void *(*fn)(sensor_info_t *sensor_info)

Function pointer for sensor detection.

This function detects a sensor based on the provided sensor information.

Param sensor_info

Pointer to the sensor information structure

Return

void* Pointer to the detected sensor instance, or NULL if detection failed

Macros

SENSOR_HUB_DETECT_FN(type_id, name_id, impl)

Defines a sensor detection function to be executed automatically in the application layer.

This macro defines a function and its corresponding metadata to facilitate automatic sensor detection and initialization. The function must return the implementation (impl) on success; otherwise, an error is logged, and the automatic detection process in the application layer will be aborted.

To prevent the linker from optimizing out the sensor driver, the driver must include at least one undefined symbol that is explicitly referenced during the linking phase. This ensures that the linker retains the driver, even if no other files directly depend on its symbols.

For example, in the sensor driver’s CMakeLists.txt, include the following to force the linker to keep the required symbol:

target_link_libraries(${COMPONENT_LIB} INTERFACE “-u <symbol_name>”)

Replace <symbol_name> with an appropriate symbol, such as sht3x_init, defined in the driver.

参数

• type_id – The sensor type identifier.

• name_id – The unique name identifier for the sensor.

• impl – The implementation returned on successful detection.

Type Definitions

typedef void *sensor_handle_t

sensor handle

typedef void *sensor_event_handler_instance_t

sensor event handler handle

typedef void (*sensor_event_handler_t)(void *event_handler_arg, sensor_event_base_t event_base, int32_t event_id, void *event_data)

function called when an event is posted to the queue

提供有关此文档的反馈