Sensor Hub 简介

[English]

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

Sensor Hub 编程模型

Sensor Hub 对常见的传感器类别进行了硬件抽象，用户在切换传感器型号时，无需修改上层应用程序， 也可以通过实现硬件抽象层的传感器接口添加新的传感器到 Sensor Hub 中。该组件由于实现了对传感器的集中管理，在简化操作的同时也提高了运行效率，可作为传感器应用的基础组件，应用在环境感知、运动感知、健康管理等更多智能化场景中。

Sensor Hub 驱动

Sensor Hub 使用方法

1. 创建一个传感器实例：使用 iot_sensor_create() 创建一个传感器实例，参数包括 sensor_id_t 中定义的传感器 ID、传感器配置项和传感器句柄指针。传感器 ID 用于查找和加载对应的驱动，一个 ID 只能对应创建一个实例。配置项中 bus 用于指定传感器挂载到的总线位置；mode 用于指定传感器的工作模式；min_delay 用于指定传感器的采集间隔，其它均为非必须项。创建成功之后，获得该传感器句柄；

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

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

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

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

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

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

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

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

6. 删除传感器：使用 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

uint8_t sensor_id

sensor id

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

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 stoped, data acquire will be stoped

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(sensor_id_t sensor_id, const sensor_config_t *config, sensor_handle_t *p_sensor_handle)

Create a sensor instance with specified sensor_id and desired configurations.

参数

• sensor_id – sensor’s id detailed in sensor_id_t.

• 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 – point to sensor handle, will set to NULL if delete suceed.

返回

esp_err_t

• ESP_OK Success

• ESP_FAIL Fail

uint8_t iot_sensor_scan(bus_handle_t bus, sensor_info_t *buf[], uint8_t num)

Scan for valid sensors attached on bus.

参数

• 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

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 decleared in sensor_type_t.

• event_id – sensor event decleared 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 decleared in sensor_type_t.

• event_id – sensor event decleared 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 type

Public Members

const char *name

sensor name

const char *desc

sensor descriptive message

sensor_id_t sensor_id

sensor id

const uint8_t *addrs

sensor address list

struct sensor_config_t

sensor initialization parameter

Public Members

bus_handle_t bus

i2c/spi bus handle

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

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

Enumerations

enum sensor_id_t

sensor id, used for iot_sensor_create

Values:

提供有关此文档的反馈