Sensor Hub

[中文]

Sensor Hub is a sensor management component that can realize hardware abstraction, device management and data distribution for sensor devices. When developing applications based on Sensor Hub, users do not have to deal with complex sensor implementations, but only need to make simple selections for sensor operation, acquisition interval, range, etc. and then register callback functions to the event messages of your interests. By doing so, users can receive notifications when sensor states are switched or when data is collected.

../_images/sensor_hub_diagram.png

Sensor Hub Programming Model

The Sensor Hub provides hardware abstraction for common sensor categories, based on which users can switch sensor models without modifying the upper layer of the application. And it allows adding new sensors to the Sensor Hub by implementing their corresponding sensor interface at hardware abstraction layer. This component can be used as a basic component for sensor applications in various intelligent scenarios such as environment monitoring, motion detection, health management and etc. as it simplifies operation and improves operating efficiency by centralized management of sensors.

../_images/sensor_hub.png

Sensor Hub Driver

Instructions

  1. Create a sensor instance: use iot_sensor_create() to create a sensor instance. The related parameters include the sensor ID defined in sensor_id_t, configuration options for the sensor and its handler pointer. The sensor ID is used to find and load the corresponding driver, and each ID can only be used for one sensor instance. In configuration options, bus is used to specify the bus location on which the sensor is mounted; mode is used to specify the operating mode of the sensor; min_delay is used to specify the acquisition interval of the sensor, while other items inside are all non-required options. After the instance is created, the sensor handler is obtained;

  2. Register callback functions for sensor events: when a sensor event occurs, the callback functions will be called in sequence. There are two ways to register a callback function, and the instance handler of the event callback function will be returned after the registration succeed:

  3. Start a sensor: use iot_sensor_start() to start a specific sensor. After started, it will trigger a SENSOR_STARTED event, then it will collect the sensor data continuously with a set of period and trigger SENSOR_XXXX_DATA_READY event. The event callback function can obtain the specific data of each event via the event_data parameter;

  4. Stop a sensor: use iot_sensor_stop() to stop a specified sensor temporarily. After stopped, the sensor will send out a SENSOR_STOPED event and then stop the data collecting work. If the driver of this sensor supports power management, the sensor will be set to sleep mode in this stage;

  5. Unregister callback functions for sensor events: the user program can unregister an event at any time using the instance handler of this event callback function, and this callback function will not be called again when this event occurs afterwards. There are also two ways to do so:

  6. Delete sensors: use iot_sensor_delete() to delete the corresponding sensor to release the allocated memory and other resources.

Examples

  1. Sensor control LED example: sensors/sensor_control_led.

  2. Sensor hub monitor example: sensors/sensor_hub_monitor.

API Reference

Header File

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

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.

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.

Returns

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.

Parameters

sensor_handle – sensor handle for operation

Returns

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.

Parameters

sensor_handle – sensor handle for operation

Returns

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.

Parameters

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

Returns

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.

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.

Returns

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.

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.

Returns

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.

Parameters

  • sensor_handle – sensor handle for operation

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

Returns

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.

Parameters

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

Returns

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.

Parameters

  • 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

Returns

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:

Provide feedback about this document