feat(sensors): Add sensor hub API to the ESP-BOX-3 and create an usage example

Author: PetrESP

.github/ci/update_readme_dependencies.py

@@ -48,6 +48,7 @@
     # 'AUDIO_MIC' : r'',
     'SDCARD': r'(^idf$)',  # SD card driver is native to ESP-IDF
     'IMU': r'(icm42670$|mpu6050$|qma6100p$)',
+    'HUMITURE': r'(aht30$)',
     'LED': r'(led_indicator$|^idf$)',  # Provided by led_indicator or idf
     'BAT': r'(^idf$)',  # Battery (ADC driver) is native to ESP-IDF
     'CAMERA': r'(esp32-camera$)',  # esp32-camera component
@@ -68,6 +69,7 @@
     "AUDIO_SPEAKER": ":speaker:",
     "SDCARD": ":floppy_disk:",
     "IMU": ":video_game:",
+    "HUMITURE": ":thermometer:",
     "USB": ":electric_plug:",
     "BUTTONS": ":radio_button:",
     "LED": ":bulb:",

.github/ci/update_supported_boards.py

@@ -141,6 +141,7 @@ def extract_board_info(board_path):
         "AUDIO_SPEAKER": ":speaker:",
         "SDCARD": ":floppy_disk:",
         "IMU": ":video_game:",
+        "HUMITURE": ":thermometer:",
         "USB": ":electric_plug:",
         "BUTTONS": ":radio_button:",
         "LED": ":bulb:",
@@ -158,6 +159,7 @@ def extract_board_info(board_path):
         "AUDIO_SPEAKER": "Audio Speaker",
         "SDCARD": "uSD Card",
         "IMU": "IMU",
+        "HUMITURE": "Temperature and Humidity",
         "USB": "USB-OTG",
         "BUTTONS": "Button",
         "LED": "LED",

README.md

@@ -27,7 +27,7 @@ The following table shows the compatibility of this BSP with different ESP-IDF v
 
 | Board name | SoC | Supported Features | Photo |
 |:----------:|:---:|:-------------------|:-----:|
-| [ESP-BOX-3](bsp/esp-box-3) | esp32s3 | :musical_note: Audio <br/>:microphone: Audio Microphone  (es7210)<br/>:speaker: Audio Speaker  (es8311)<br/>:radio_button: Button <br/>:pager: LCD Display  (st7789, ili9341)<br/>:video_game: IMU <br/>:floppy_disk: uSD Card <br/>:point_up: Display Touch  (tt21100, gt911)<br/> | <img src="bsp/esp-box-3/doc/esp-box-3.webp" width="150"> |
+| [ESP-BOX-3](bsp/esp-box-3) | esp32s3 | :musical_note: Audio <br/>:microphone: Audio Microphone  (es7210)<br/>:speaker: Audio Speaker  (es8311)<br/>:radio_button: Button <br/>:pager: LCD Display  (st7789, ili9341)<br/>:thermometer: Temperature and Humidity <br/>:video_game: IMU <br/>:floppy_disk: uSD Card <br/>:point_up: Display Touch  (tt21100, gt911)<br/> | <img src="bsp/esp-box-3/doc/esp-box-3.webp" width="150"> |
 | [ESP32-C3-LCDKit](bsp/esp32_c3_lcdkit) | esp32c3 | :musical_note: Audio <br/>:speaker: Audio Speaker <br/>:pager: LCD Display  (gc9a01)<br/>:white_circle: Knob <br/>:bulb: LED <br/> | <img src="bsp/esp32_c3_lcdkit/doc/esp32_c3_lcdkit.webp" width="150"> |
 | [ESP32-LyraT](bsp/esp32_lyrat) | esp32 | :musical_note: Audio <br/>:microphone: Audio Microphone  (es8388)<br/>:speaker: Audio Speaker  (es8388)<br/>:radio_button: Button <br/>:bulb: LED <br/>:floppy_disk: uSD Card <br/> | <img src="bsp/esp32_lyrat/doc/esp32_lyrat.webp" width="150"> |
 | [ESP32-P4-EYE](bsp/esp32_p4_eye) | esp32p4 | :musical_note: Audio <br/>:microphone: Audio Microphone <br/>:battery: Battery <br/>:radio_button: Button <br/>:camera: Camera  (OV2710)<br/>:pager: LCD Display  (st7789)<br/>:white_circle: Knob <br/>:bulb: LED <br/>:floppy_disk: uSD Card <br/> | <img src="bsp/esp32_p4_eye/doc/esp32_p4_eye.webp" width="150"> |
@@ -82,6 +82,7 @@ Here is a summary of the available examples:
 | [USB HID Example](examples/display_usb_hid) | USB HID demo (keyboard, mouse, or gamepad visualization using LVGL) | <details><summary>3 boards</summary>[esp32_p4_function_ev_board](bsp/esp32_p4_function_ev_board)<br/>[esp32_s3_usb_otg](bsp/esp32_s3_usb_otg)<br/>[m5stack_tab5](bsp/m5stack_tab5)</details> | - |
 | [Generic Button and LED Example](examples/generic_button_led) | Minimal example using the Generic BSP: button and LED control | <details><summary>2 boards</summary>[esp_bsp_devkit](bsp/esp_bsp_devkit)<br/>[esp_bsp_generic](bsp/esp_bsp_generic)</details> | - |
 | [MQTT Example](examples/mqtt_example) | Collect sensor data and publish to an MQTT server | <details><summary>1 board</summary>[esp32_azure_iot_kit](bsp/esp32_azure_iot_kit)</details> | - |
+| [Sensors Example](examples/sensors) | Acquire sensor data using the sensor hub component | <details><summary>1 board</summary>[esp-box-3](bsp/esp-box-3)</details> | [Flash Example](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-bsp/config.toml&app=sensors) |
 
 <!-- EXAMPLES_TABLE_END -->
 
@@ -123,4 +124,4 @@ idf.py -B build/wrover_kit -D SDKCONFIG_DEFAULTS=sdkconfig.bsp.esp_wrover_kit bu
 
 ## Copyrights and License
 
-All original source code in this repository is Copyright (c) Espressif Systems (Shanghai) Co. Ltd., and is licensed under the Apache 2.0 license.
+All original source code in this repository is Copyright (c) Espressif Systems (Shanghai) Co. Ltd., and is licensed under the Apache 2.0 license.

bsp/esp-box-3/API.md

@@ -5,8 +5,8 @@
 
 
 
-| :1234: [CAPABILITIES](#1234-capabilities) | :floppy_disk: [SD CARD AND SPIFFS](#floppy_disk-sd-card-and-spiffs) | :musical_note: [AUDIO](#musical_note-audio) | :pager: [DISPLAY AND TOUCH](#pager-display-and-touch) | :radio_button: [BUTTONS](#radio_button-buttons) | :electric_plug: [USB](#electric_plug-usb) | 
-| :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | 
+| :1234: [CAPABILITIES](#1234-capabilities) | :floppy_disk: [SD CARD AND SPIFFS](#floppy_disk-sd-card-and-spiffs) | :musical_note: [AUDIO](#musical_note-audio) | :pager: [DISPLAY AND TOUCH](#pager-display-and-touch) | :radio_button: [BUTTONS](#radio_button-buttons) | :electric_plug: [USB](#electric_plug-usb) | :video_game: [SENSORS](#video_game-sensors) | 
+| :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | 
 
 </div>
 
@@ -149,6 +149,7 @@ You can use these macros to conditionally compile code depending on feature avai
 | define  | [**BSP\_CAPS\_AUDIO\_SPEAKER**](#define-bsp_caps_audio_speaker)  1<br> |
 | define  | [**BSP\_CAPS\_BUTTONS**](#define-bsp_caps_buttons)  1<br> |
 | define  | [**BSP\_CAPS\_DISPLAY**](#define-bsp_caps_display)  1<br> |
+| define  | [**BSP\_CAPS\_HUMITURE**](#define-bsp_caps_humiture)  1<br> |
 | define  | [**BSP\_CAPS\_IMU**](#define-bsp_caps_imu)  1<br> |
 | define  | [**BSP\_CAPS\_SDCARD**](#define-bsp_caps_sdcard)  1<br> |
 | define  | [**BSP\_CAPS\_TOUCH**](#define-bsp_caps_touch)  1<br> |
@@ -213,6 +214,8 @@ You can use these macros to conditionally compile code depending on feature avai
 
 | Type | Name |
 | ---: | :--- |
+| define  | [**BSP\_I2C\_DOCK\_SCL**](#define-bsp_i2c_dock_scl)  (GPIO\_NUM\_40)<br> |
+| define  | [**BSP\_I2C\_DOCK\_SDA**](#define-bsp_i2c_dock_sda)  (GPIO\_NUM\_41)<br> |
 | define  | [**BSP\_I2C\_NUM**](#define-bsp_i2c_num)  CONFIG\_BSP\_I2C\_NUM<br> |
 | define  | [**BSP\_I2C\_SCL**](#define-bsp_i2c_scl)  (GPIO\_NUM\_18)<br> |
 | define  | [**BSP\_I2C\_SDA**](#define-bsp_i2c_sda)  (GPIO\_NUM\_8)<br> |
@@ -1467,3 +1470,107 @@ For more USB-related APIs and configuration options, check the corresponding BSP
 
 
 
+
+
+
+## :video_game: Sensors
+
+Boards with integrated sensors (e.g., IMUs, environmental sensors) are abstracted using the sensor hub component.
+The BSP project provides APIs for initializing each sensor and it is up to the integrating platform to provide configuration of the data acquisition and callback handlers.
+
+For practical usage examples and supported sensors on your board, refer to the relevant examples in the BSP repository, such as:
+- `sensors` (for reading sensor data)
+- TODO: `display_rotation` (for IMU setup and orientation control)
+
+### Usage
+
+Create a handler function for sensor hub events
+``` c
+void sensor_event_handler(void *handler_args, esp_event_base_t base, int32_t id, void *event_data)
+{
+    ...
+}
+```
+
+Set up a sensor configuration and initialize it
+``` c
+bsp_sensor_config_t imu_config = {
+    .type = IMU_ID,
+    .mode = MODE_POLLING,
+    .period = 1000
+};
+ESP_ERROR_CHECK(bsp_sensor_init(&imu_config, &imu_sensor_handle));
+```
+
+Associate an event handler with the configured sensor
+``` c
+iot_sensor_handler_register(imu_sensor_handle, sensor_event_handler, NULL);
+```
+
+Start the sensor data acquisition
+``` c
+iot_sensor_start(imu_sensor_handle);
+```
+
+**Notes:**
+- More information can be found in [sensor hub documentation page](https://docs.espressif.com/projects/esp-iot-solution/en/latest/sensors/sensor_hub.html).
+
+### Sensors API Reference
+
+## Structures and Types
+
+| Type | Name |
+| ---: | :--- |
+| struct | [**bsp\_sensor\_config\_t**](#struct-bsp_sensor_config_t) <br>_BSP sensor configuration structure._ |
+
+## Functions
+
+| Type | Name |
+| ---: | :--- |
+|  esp\_err\_t | [**bsp\_sensor\_init**](#function-bsp_sensor_init) (const [**bsp\_sensor\_config\_t**](#struct-bsp_sensor_config_t) \*cfg, sensor\_handle\_t \*sensor\_handle) <br>_Initialize a sensor._ |
+
+
+
+## Structures and Types Documentation
+
+### struct `bsp_sensor_config_t`
+
+_BSP sensor configuration structure._
+
+Variables:
+
+-  sensor\_mode\_t mode  
+
+-  uint16\_t period  
+
+-  sensor\_type\_t type  
+
+
+## Functions Documentation
+
+### function `bsp_sensor_init`
+
+_Initialize a sensor._
+```c
+esp_err_t bsp_sensor_init (
+    const bsp_sensor_config_t *cfg,
+    sensor_handle_t *sensor_handle
+) 
+```
+
+
+**Parameters:**
+
+
+* `cfg` Pointer to the sensor configuration 
+* `sensor_handle` Pointer to the outgoing sensor handle 
+
+
+**Returns:**
+
+
+
+* ESP\_OK on success, otherwise returns ESP\_ERR\_xxx
+
+
+

bsp/esp-box-3/README.md

@@ -37,6 +37,7 @@ ESP32-S3-BOX-3 also uses a Type-C USB connector that provides 5 V of power input
 |:heavy_check_mark:| :microphone: AUDIO_MIC |     es7210     |                                                                                                                                                                                                                             |                |
 |:heavy_check_mark:|  :floppy_disk: SDCARD  |                |                                                                                                             idf                                                                                                             |      >=5.3     |
 |:heavy_check_mark:|    :video_game: IMU    |                |                                                                     [espressif/icm42670](https://components.espressif.com/components/espressif/icm42670)                                                                    |     ^2.0.2     |
+|:heavy_check_mark:| :thermometer: HUMITURE |                |                                                                        [espressif/aht30](https://components.espressif.com/components/espressif/aht30)                                                                       |     ^1.0.0     |
 
 <!-- END_DEPENDENCIES -->
 </div>
@@ -54,6 +55,7 @@ ESP32-S3-BOX-3 also uses a Type-C USB connector that provides 5 V of power input
 | [LVGL Demos Example](https://github.com/espressif/esp-bsp/tree/master/examples/display_lvgl_demos) | Run the LVGL demo player - all LVGL examples are included (LVGL) | [Flash Example](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-bsp/config.toml&app=display_lvgl_demos-) |
 | [Display Rotation Example](https://github.com/espressif/esp-bsp/tree/master/examples/display_rotation) | Rotate screen using buttons or an accelerometer (`BSP_CAPS_IMU`, if available) | [Flash Example](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-bsp/config.toml&app=display_rotation-) |
 | [Display SD card Example](https://github.com/espressif/esp-bsp/tree/master/examples/display_sdcard) | Example of mounting an SD card using SD-MMC/SPI with display interaction. This example is also supported on boards without a display. | [Flash Example](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-bsp/config.toml&app=display_sdcard) |
+| [Sensors Example](https://github.com/espressif/esp-bsp/tree/master/examples/sensors) | Acquire sensor data using the sensor hub component | [Flash Example](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-bsp/config.toml&app=sensors) |
 
 <!-- END_EXAMPLES -->
 </div>

bsp/esp-box-3/esp-box-3.c

@@ -28,8 +28,13 @@
 #include "bsp_err_check.h"
 #include "esp_codec_dev_defaults.h"
 
+#include "icm42670.h"
+#include "aht30.h"
+
 static const char *TAG = "ESP-BOX-3";
 
+#define I2C_CLK_SPEED 400000
+
 /** @cond */
 _Static_assert(CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0, "Touch buttons must be supported for this BSP");
 /** @endcond */
@@ -73,6 +78,7 @@ static bool spi_sd_initialized = false;
  * For IDF 5.2 and 5.3 you must call bsp_i2c_get_handle()
  */
 static i2c_master_bus_handle_t i2c_handle = NULL;
+static i2c_master_bus_handle_t i2c_dock_handle = NULL;
 static bool i2c_initialized = false;
 
 // This is just a wrapper to get function signature for espressif/button API callback
@@ -132,13 +138,32 @@ esp_err_t bsp_i2c_init(void)
     };
     BSP_ERROR_CHECK_RETURN_ERR(i2c_new_master_bus(&i2c_config, &i2c_handle));
 
+    const i2c_master_bus_config_t i2c_dock_config = {
+#if BSP_I2C_NUM == 1
+        .i2c_port = 0,
+#else
+        .i2c_port = 1,
+#endif
+        .sda_io_num = BSP_I2C_DOCK_SDA,
+        .scl_io_num = BSP_I2C_DOCK_SCL,
+        .clk_source = I2C_CLK_SRC_DEFAULT,
+    };
+
+    esp_err_t ret = i2c_new_master_bus(&i2c_dock_config, &i2c_dock_handle);
+    if (ret != ESP_OK) {
+        i2c_del_master_bus(i2c_handle);
+        i2c_handle = NULL;
+        return ret;
+    }
+
     i2c_initialized = true;
     return ESP_OK;
 }
 
 esp_err_t bsp_i2c_deinit(void)
 {
     BSP_ERROR_CHECK_RETURN_ERR(i2c_del_master_bus(i2c_handle));
+    BSP_ERROR_CHECK_RETURN_ERR(i2c_del_master_bus(i2c_dock_handle));
     i2c_initialized = false;
     return ESP_OK;
 }
@@ -842,3 +867,36 @@ esp_err_t bsp_iot_button_create(button_handle_t btn_array[], int *btn_cnt, int b
     }
     return ret;
 }
+
+esp_err_t bsp_sensor_init(const bsp_sensor_config_t *cfg, sensor_handle_t *sensor_handle)
+{
+    ESP_RETURN_ON_FALSE(cfg != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to the sensor config can't be NULL");
+    ESP_RETURN_ON_FALSE(sensor_handle != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to the sensor handle can't be NULL");
+
+    esp_err_t err = ESP_OK;
+
+    BSP_ERROR_CHECK_RETURN_ERR(bsp_i2c_init());
+
+    sensor_config_t config = {
+        .type = cfg->type,
+        .mode = cfg->mode,
+        .min_delay = cfg->period
+    };
+
+    switch (cfg->type) {
+    case IMU_ID:
+        config.bus = i2c_handle;
+        config.addr = ICM42670_I2C_ADDRESS;
+        err = iot_sensor_create("sensor_hub_icm42670", &config, sensor_handle);
+        break;
+    case HUMITURE_ID:
+        config.bus = i2c_dock_handle;
+        config.addr = AHT30_I2C_ADDRESS;
+        err = iot_sensor_create("sensor_hub_aht30", &config, sensor_handle);
+        break;
+    default:
+        return ESP_FAIL;
+    }
+
+    return err;
+}

bsp/esp-box-3/idf_component.yml

@@ -1,4 +1,4 @@
-version: 3.0.3
+version: 3.1.0
 description: Board Support Package (BSP) for ESP32-S3-BOX-3
 url: https://github.com/espressif/esp-bsp/tree/master/bsp/esp-box-3
 
@@ -38,10 +38,15 @@ dependencies:
     public: true
     override_path: ../../components/sensors/icm42670
 
+  aht30:
+    version: '^1.0.0'
+    override_path: ../../components/sensors/aht30
+
 examples:
 - path: ../../examples/display
 - path: ../../examples/display_rotation
 - path: ../../examples/display_audio_photo
 - path: ../../examples/display_lvgl_demos
 - path: ../../examples/display_lvgl_benchmark
 - path: ../../examples/display_sdcard
+- path: ../../examples/sensors

bsp/esp-box-3/include/bsp/esp-box-3.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -23,6 +23,8 @@
 #include "bsp/config.h"
 #include "bsp/display.h"
 
+#include "iot_sensor_hub.h"
+
 #if (BSP_CONFIG_NO_GRAPHIC_LIB == 0)
 #include "lvgl.h"
 #include "esp_lvgl_port.h"
@@ -55,6 +57,7 @@
 #define BSP_CAPS_AUDIO_MIC      1
 #define BSP_CAPS_SDCARD         1
 #define BSP_CAPS_IMU            1
+#define BSP_CAPS_HUMITURE       1
 /** @} */ // end of capabilities
 
 /**************************************************************************************************
@@ -67,6 +70,8 @@
  */
 #define BSP_I2C_SCL           (GPIO_NUM_18)
 #define BSP_I2C_SDA           (GPIO_NUM_8)
+#define BSP_I2C_DOCK_SCL      (GPIO_NUM_40)
+#define BSP_I2C_DOCK_SDA      (GPIO_NUM_41)
 /** @} */ // end of i2c
 
 /** @defgroup g03_audio Audio
@@ -617,6 +622,33 @@ esp_err_t bsp_iot_button_create(button_handle_t btn_array[], int *btn_cnt, int b
 /** @} */ // end of buttons
 
 
+/** @defgroup g10_sensors Sensors
+ *  @brief BSP API for sensors
+ *  @{
+ */
+
+/**
+ * @brief BSP sensor configuration structure
+ */
+typedef struct {
+    sensor_type_t type;
+    sensor_mode_t mode;
+    uint16_t period;
+} bsp_sensor_config_t;
+
+/**
+ * @brief Initialize a sensor
+ *
+ * @param[in]  cfg              Pointer to the sensor configuration
+ * @param[out] sensor_handle    Pointer to the outgoing sensor handle
+ * @return
+ *     - ESP_OK on success, otherwise returns ESP_ERR_xxx
+ */
+esp_err_t bsp_sensor_init(const bsp_sensor_config_t *cfg, sensor_handle_t *sensor_handle);
+
+/** @} */ // end of sensors
+
+
 #ifdef __cplusplus
 }
 #endif