From 938eb7735d7afee281119fb3627a24afdc2ba47b Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sat, 17 Oct 2026 21:36:06 +0300 Subject: [PATCH] doc: updated readme --- README.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 184 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3b18ece..33be387 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,22 @@ -# ESP32 ESP-IDF component for AHT Series Humidity & Temperature Sensor +# ESP32 ESP-IDF component for AHT series humidity & temperature sensor (I2C) ## Features -1. Support of AHT10/AHT15/AHT20/AHT21/AHT25/AHT30/AHT40. -2. Support multiple sensors on one device with [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a). -3. CRC8 data integrity verification. -4. Error statistics tracking. +1. Support for the whole AHT family including AHT10, AHT15, AHT20, AHT21, AHT25, AHT30 and AHT40. +2. Measurement of relative humidity in range 0 to 100 percent and temperature in range -50 to 150 degrees Celsius. +3. Data integrity verification with CRC8 algorithm on every measurement frame. +4. Automatic sensor detection and initialization during setup. +5. Software reset of the sensor over I2C. +6. Tracking of I2C driver error statistics with a resettable counter. +7. I2C clock frequency up to 400000 Hz on addresses 0x38, 0x39 and 0x44. +8. Multiple sensors on one bus through external multiplexer zh_pca9548a. + +## Attention + +1. The component is not thread safe, one sensor handle must be served by a single task. +2. I2C bus is created by the user and the component does not manage it. +3. Statistics counters are global and shared between all sensor instances. +4. Read and reset functions contain blocking delays and cannot be called from a context without task switching. ## Using @@ -22,13 +33,16 @@ In the application, add the component: #include "zh_aht.h" ``` -## Example +## Examples + +### Basic Example: Read Humidity and Temperature ```c #include "zh_aht.h" #define I2C_PORT (I2C_NUM_MAX - 1) +i2c_master_bus_handle_t i2c_bus_handle = NULL; zh_aht_handle_t *aht_handle = NULL; void app_main(void) @@ -42,21 +56,176 @@ void app_main(void) .glitch_ignore_cnt = 7, .flags.enable_internal_pullup = true, }; - i2c_master_bus_handle_t i2c_bus_handle = NULL; i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); zh_aht_init_config_t config = ZH_AHT_INIT_CONFIG_DEFAULT(); config.i2c_handle = i2c_bus_handle; - zh_aht_init(&config, &aht_handle); + esp_err_t ret = zh_aht_init(&config, &aht_handle); + if (ret != ESP_OK) + { + printf("AHT initialization error: %s\n", esp_err_to_name(ret)); + return; + } float humidity = 0.0; float temperature = 0.0; - for (;;) + ret = zh_aht_read(&aht_handle, &humidity, &temperature); + if (ret == ESP_OK) { - zh_aht_read(&aht_handle, &humidity, &temperature); - printf("Humidity: %.2f%%\n", humidity); - printf("Temperature: %.2f°C\n", temperature); - const zh_aht_stats_t *stats = zh_aht_get_stats(); - printf("I2C errors: %ld\n", stats->i2c_driver_error); - vTaskDelay(5000 / portTICK_PERIOD_MS); + printf("Humidity: %.2f%%, Temperature: %.2f°C\n", humidity, temperature); } + else + { + printf("Read error: %s\n", esp_err_to_name(ret)); + } + zh_aht_deinit(&aht_handle); +} +``` + +--- + +### Read In A Loop Example + +```c +#include "zh_aht.h" + +#define I2C_PORT (I2C_NUM_MAX - 1) + +i2c_master_bus_handle_t i2c_bus_handle = NULL; +zh_aht_handle_t *aht_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_aht", ESP_LOG_ERROR); + i2c_master_bus_config_t i2c_bus_config = { + .clk_source = I2C_CLK_SRC_DEFAULT, + .i2c_port = I2C_PORT, + .scl_io_num = GPIO_NUM_22, + .sda_io_num = GPIO_NUM_21, + .glitch_ignore_cnt = 7, + .flags.enable_internal_pullup = true, + }; + i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); + zh_aht_init_config_t config = ZH_AHT_INIT_CONFIG_DEFAULT(); + config.i2c_handle = i2c_bus_handle; + esp_err_t ret = zh_aht_init(&config, &aht_handle); + if (ret != ESP_OK) + { + printf("AHT initialization error: %s\n", esp_err_to_name(ret)); + return; + } + float humidity = 0.0; + float temperature = 0.0; + for (int i = 0; i < 10; i++) + { + ret = zh_aht_read(&aht_handle, &humidity, &temperature); + if (ret == ESP_OK) + { + printf("Humidity: %.2f%%, Temperature: %.2f°C\n", humidity, temperature); + } + else + { + printf("Read error: %s\n", esp_err_to_name(ret)); + } + vTaskDelay(5000 / portTICK_PERIOD_MS); + } + zh_aht_deinit(&aht_handle); +} +``` + +--- + +### Reset Sensor Example + +```c +#include "zh_aht.h" + +#define I2C_PORT (I2C_NUM_MAX - 1) + +i2c_master_bus_handle_t i2c_bus_handle = NULL; +zh_aht_handle_t *aht_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_aht", ESP_LOG_ERROR); + i2c_master_bus_config_t i2c_bus_config = { + .clk_source = I2C_CLK_SRC_DEFAULT, + .i2c_port = I2C_PORT, + .scl_io_num = GPIO_NUM_22, + .sda_io_num = GPIO_NUM_21, + .glitch_ignore_cnt = 7, + .flags.enable_internal_pullup = true, + }; + i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); + zh_aht_init_config_t config = ZH_AHT_INIT_CONFIG_DEFAULT(); + config.i2c_handle = i2c_bus_handle; + esp_err_t ret = zh_aht_init(&config, &aht_handle); + if (ret != ESP_OK) + { + printf("AHT initialization error: %s\n", esp_err_to_name(ret)); + return; + } + ret = zh_aht_reset(&aht_handle); + if (ret == ESP_OK) + { + printf("Sensor reset ok\n"); + } + else + { + printf("Reset error: %s\n", esp_err_to_name(ret)); + } + float humidity = 0.0; + float temperature = 0.0; + ret = zh_aht_read(&aht_handle, &humidity, &temperature); + if (ret == ESP_OK) + { + printf("Humidity: %.2f%%, Temperature: %.2f°C\n", humidity, temperature); + } + zh_aht_deinit(&aht_handle); +} +``` + +--- + +### Error Statistics Example + +```c +#include "zh_aht.h" + +#define I2C_PORT (I2C_NUM_MAX - 1) + +i2c_master_bus_handle_t i2c_bus_handle = NULL; +zh_aht_handle_t *aht_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_aht", ESP_LOG_ERROR); + i2c_master_bus_config_t i2c_bus_config = { + .clk_source = I2C_CLK_SRC_DEFAULT, + .i2c_port = I2C_PORT, + .scl_io_num = GPIO_NUM_22, + .sda_io_num = GPIO_NUM_21, + .glitch_ignore_cnt = 7, + .flags.enable_internal_pullup = true, + }; + i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); + zh_aht_init_config_t config = ZH_AHT_INIT_CONFIG_DEFAULT(); + config.i2c_handle = i2c_bus_handle; + esp_err_t ret = zh_aht_init(&config, &aht_handle); + if (ret != ESP_OK) + { + printf("AHT initialization error: %s\n", esp_err_to_name(ret)); + return; + } + float humidity = 0.0; + float temperature = 0.0; + for (int i = 0; i < 10; i++) + { + zh_aht_read(&aht_handle, &humidity, &temperature); + } + const zh_aht_stats_t *stats = zh_aht_get_stats(); + printf("I2C errors: %lu\n", (unsigned long)stats->i2c_driver_error); + zh_aht_reset_stats(); + stats = zh_aht_get_stats(); + printf("I2C errors after reset: %lu\n", (unsigned long)stats->i2c_driver_error); + zh_aht_deinit(&aht_handle); } ```