Sensor Hub 简介¶

[English]

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

../_images/sensor_hub_diagram.png — Sensor Hub 编程模型¶

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

../_images/sensor_hub.png — Sensor Hub 驱动¶

Sensor Hub 使用方法¶

创建一个传感器实例：使用 iot_sensor_create() 创建一个传感器实例，参数包括 sensor_id_t 中定义的传感器 ID、传感器配置项和传感器句柄指针。传感器 ID 用于查找和加载对应的驱动，一个 ID 只能对应创建一个实例。配置项中 bus 用于指定传感器挂载到的总线位置；mode 用于指定传感器的工作模式；min_delay 用于指定传感器的采集间隔，其它均为非必须项。创建成功之后，获得该传感器句柄；
注册传感器事件回调函数：在传感器事件发生时，回调函数将会被依次调用，注册回调函数的方法有以下两种，注册成功之后将返回事件回调函数实例句柄：
- 使用 iot_sensor_handler_register() 通过传感器句柄注册回调函数
- 使用 iot_sensor_handler_register_with_type() 通过传感器类型注册回调函数
启动传感器：使用 iot_sensor_start() 启动指定的传感器，传感器启动之后将发出 SENSOR_STARTED 事件，之后将以设定的周期持续采集传感器数据，并发送 SENSOR_XXXX_DATA_READY 事件。事件回调函数可通过 event_data 参数获取每一个事件的具体数据；
停止传感器：使用 iot_sensor_stop() 可临时关闭指定的传感器，传感器关闭之后将发出 SENSOR_STOPED 事件，之后采集工作将停止。如果该传感器驱动支持电源管理，传感器将被设置为睡眠模式;
取消注册传感器事件回调函数：用户程序可在任意时刻使用事件回调函数实例句柄取消对事件的注册，之后该事件发生时，该回调函数将不再被调用。取消注册的方法对应也有两种：
- 使用 iot_sensor_handler_unregister() 通过传感器句柄取消已注册的回调函数
- 使用 iot_sensor_handler_unregister_with_type() 通过传感器类型取消已经注册的回调函数
删除传感器：使用 iot_sensor_delete() 可删除对应的传感器，释放已分配的内存等资源。

示例程序¶

光照传感器控制 LED 开关示例：sensors/sensor_control_led。
传感器监测示例：sensors/sensor_hub_monitor。

API 参考¶

Header File¶

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:

NULL_ID¶: NULL

HUMITURE_ID¶: humidity or temperature sensor

IMU_ID¶: gyro or acc sensor

LIGHT_SENSOR_ID¶: light illumination or uv or color sensor

SENSOR_TYPE_MAX¶: max sensor type

enum sensor_command_t¶

sensor operate command

Values:

COMMAND_SET_MODE¶: set measure mdoe

COMMAND_SET_RANGE¶: set measure range

COMMAND_SET_ODR¶: set output rate

COMMAND_SET_POWER¶: set power mode

COMMAND_SELF_TEST¶: sensor self test

COMMAND_MAX¶: max sensor command

enum sensor_power_mode_t¶

sensor power mode

Values:

POWER_MODE_WAKEUP¶: wakeup from sleep

POWER_MODE_SLEEP¶: set to sleep

POWER_MAX¶: max sensor power mode

enum sensor_mode_t¶

sensor acquire mode

Values:

MODE_DEFAULT¶: default work mode

MODE_POLLING¶: polling acquire with a interval time

MODE_INTERRUPT¶: interrupt mode, acquire data when interrupt comes

MODE_MAX¶: max sensor mode

enum sensor_range_t¶

sensor acquire range

Values:

RANGE_DEFAULT¶: default range

RANGE_MIN¶: minimum range for high-speed or high-precision

RANGE_MEDIUM¶: medium range for general use

RANGE_MAX¶: maximum range for full scale

enum sensor_event_id_t¶

sensor general events

Values:

SENSOR_STARTED¶: sensor started, data acquire will be started

SENSOR_STOPED¶: sensor stoped, data acquire will be stoped

SENSOR_EVENT_COMMON_END = 9¶: max common events id

enum sensor_data_event_id_t¶

sensor data ready events

Values:

SENSOR_ACCE_DATA_READY = 10¶: Accelerometer data ready

SENSOR_GYRO_DATA_READY¶: Gyroscope data ready

SENSOR_MAG_DATA_READY¶: Magnetometer data ready

SENSOR_TEMP_DATA_READY¶: Temperature data ready

SENSOR_HUMI_DATA_READY¶: Relative humidity data ready

SENSOR_BARO_DATA_READY¶: Pressure data ready

SENSOR_LIGHT_DATA_READY¶: Light data ready

SENSOR_RGBW_DATA_READY¶: Color data ready

SENSOR_UV_DATA_READY¶: ultraviolet data ready

SENSOR_PROXI_DATA_READY¶: Distance data ready

SENSOR_HR_DATA_READY¶: Heat rate data ready

SENSOR_TVOC_DATA_READY¶: TVOC data ready

SENSOR_NOISE_DATA_READY¶: Noise Loudness data ready

SENSOR_STEP_DATA_READY¶: Step data ready

SENSOR_FORCE_DATA_READY¶: Force data ready

SENSOR_CURRENT_DATA_READY¶: Current data ready

SENSOR_VOLTAGE_DATA_READY¶: Voltage data ready

SENSOR_EVENT_ID_END¶: max common events id

Header File¶

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.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

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

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

sensor_handle: sensor handle for operation

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.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

sensor_handle: sensor handle for operation

esp_err_t iot_sensor_delete(sensor_handle_t *p_sensor_handle)¶

delete and release the sensor resource.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

p_sensor_handle: point to sensor handle, will set to NULL if delete suceed.

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

Scan for valid sensors attached on bus.

Return

uint8_t total number of valid sensors found on the bus

Parameters

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.

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.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

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 iot_sensor_handler_unregister(sensor_handle_t sensor_handle, sensor_event_handler_instance_t context)¶

Unregister a event handler from a sensor’s event.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

sensor_handle: sensor handle for operation
context: the instance object of the registration to be unregistered

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.

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

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

Return

esp_err_t

ESP_OK Success
ESP_FAIL Fail

Parameters

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

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 const char *sensor_event_base_t¶: unique pointer to a subsystem that exposes events

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:

提供有关此文档的反馈