feat!: main structure of handle changed to double pointer
This commit is contained in:
aZholtikov committed
1 parent
e8c79cf078
commit
e534465f8c
8 files changed
+207
-274
No files matched your search
+35
-44
@@ -16,7 +16,7 @@
|
||||
|
||||
## Обзор
|
||||
|
||||
`zh_aht` - это легковесный компонент ESP-IDF для датчиков влажности и температуры AHT10/AHT15/AHT20/AHT21/AHT25/AHT30. Он предоставляет простой API для считывания значений влажности от 0 до 100% и температуры от -40 до +85°C. Компонент поддерживает несколько датчиков на одной шине I2C с использованием I2C мультиплексатора [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a).
|
||||
`zh_aht` - это легковесный компонент ESP-IDF для датчиков влажности и температуры AHT10/AHT15/AHT20/AHT21/AHT25/AHT30/AHT40. Он предоставляет простой API для считывания значений влажности от 0 до 100% и температуры от -40 до +85°C. Компонент поддерживает несколько датчиков на одной шине I2C с использованием I2C мультиплексатора [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a).
|
||||
|
||||
Компонент разработан специально для микроконтроллеров ESP32 и использует API драйвера I2C ESP-IDF v5.0+.
|
||||
|
||||
@@ -26,8 +26,8 @@
|
||||
|
||||
1. **Измерение влажности и температуры**: Считывание значений влажности от 0 до 100% и температуры от -40 до +85°C
|
||||
2. **Интерфейс I2C**: Использует стандартный протокол I2C (макс. частота 400 кГц)
|
||||
3. **Настраиваемый адрес I2C**: Поддерживает адреса 0x38 и 0x39
|
||||
4. **Поддержка нескольких моделей**: AHT10, AHT15, AHT20, AHT21, AHT25, AHT30
|
||||
3. **Настраиваемый адрес I2C**: Поддерживает адреса 0x38, 0x39 и 0x44
|
||||
4. **Поддержка нескольких моделей**: AHT10, AHT15, AHT20, AHT21, AHT25, AHT30, AHT40
|
||||
5. **Статистика ошибок**: Встроенный счетчик ошибок драйвера I2C
|
||||
6. **Низкое энергопотребление**: Работает с системой управления питанием ESP-IDF
|
||||
7. **Потокобезопасность**: Использует драйвер I2C ESP-IDF (потокобезопасен)
|
||||
@@ -75,13 +75,15 @@ I2C_MASTER_ISR_HANDLER_IN_IRAM
|
||||
|
||||
## Справочник API
|
||||
|
||||
Все функции в этой библиотеке используют двойной указатель (`zh_aht_handle_t **`) для дескриптора датчика, чтобы обеспечить правильное управление памятью и потокобезопасность.
|
||||
|
||||
### Структура zh_aht_init_config_t
|
||||
|
||||
```c
|
||||
typedef struct
|
||||
{
|
||||
i2c_master_bus_handle_t i2c_handle; // Уникальный дескриптор шины I2C
|
||||
uint8_t i2c_address; // Адрес устройства датчика I2C (0x38 или 0x39)
|
||||
uint8_t i2c_address; // Адрес устройства датчика I2C (0x38, 0x39 или 0x44)
|
||||
uint32_t i2c_frequency; // Частота I2C датчика (макс. 400000 Гц)
|
||||
} zh_aht_init_config_t;
|
||||
```
|
||||
@@ -95,13 +97,13 @@ typedef struct
|
||||
|
||||
### Структура zh_aht_handle_t
|
||||
|
||||
```c
|
||||
typedef struct
|
||||
{
|
||||
bool is_initialized; // Флаг инициализации датчика
|
||||
i2c_master_dev_handle_t dev_handle; // Уникальный дескриптор устройства I2C
|
||||
} zh_aht_handle_t;
|
||||
```
|
||||
Структура объявляется как `typedef struct _zh_aht_handle_t zh_aht_handle_t;` и инкапсулирует детали внутренней реализации.
|
||||
|
||||
**Поля (внутренние):**
|
||||
|
||||
| Поле | Тип | Описание |
|
||||
|------|-----|----------|
|
||||
| `i2c_master_dev_handle_t` | `dev_handle` | Указатель на дескриптор устройства I2C. |
|
||||
|
||||
---
|
||||
|
||||
@@ -123,18 +125,21 @@ typedef struct
|
||||
**Параметры:**
|
||||
|
||||
- `config` - Указатель на структуру конфигурации инициализации AHT
|
||||
- `handle` - Указатель на уникальный дескриптор AHT
|
||||
- `handle` - Двойной указатель на уникальный дескриптор AHT (`zh_aht_handle_t **`). Если указатель NULL, память будет выделена.
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config или handle)
|
||||
- `ESP_FAIL` - Ошибка инициализации (проверка конфигурации или добавление устройства I2C)
|
||||
- `ESP_ERR_INVALID_STATE` - Датчик уже инициализирован
|
||||
- `ESP_ERR_NO_MEM` - Ошибка выделения памяти
|
||||
- `ESP_FAIL` - Ошибка инициализации устройства I2C
|
||||
- `ESP_ERR_NOT_FOUND` - Датчик не отвечает
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
zh_aht_handle_t aht_handle = {0};
|
||||
zh_aht_handle_t *aht_handle = NULL;
|
||||
zh_aht_init_config_t config = ZH_AHT_INIT_CONFIG_DEFAULT();
|
||||
config.i2c_handle = i2c_bus_handle;
|
||||
zh_aht_init(&config, &aht_handle);
|
||||
@@ -144,17 +149,16 @@ zh_aht_init(&config, &aht_handle);
|
||||
|
||||
### zh_aht_deinit()
|
||||
|
||||
Деинициализирует датчик AHT и удаляет его из шины I2C.
|
||||
Деинициализирует датчик AHT и удаляет его из шины I2C. Память для handle автоматически освобождается, а указатель устанавливается в NULL.
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `handle` - Указатель на уникальный дескриптор AHT
|
||||
- `handle` - Двойной указатель на уникальный дескриптор AHT (`zh_aht_handle_t **`). Не должен быть NULL.
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle)
|
||||
- `ESP_ERR_INVALID_STATE` - Датчик не инициализирован
|
||||
- `ESP_FAIL` - Ошибка удаления устройства I2C
|
||||
|
||||
---
|
||||
@@ -165,7 +169,7 @@ zh_aht_init(&config, &aht_handle);
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `handle` - Указатель на уникальный дескриптор AHT
|
||||
- `handle` - Двойной указатель на уникальный дескриптор AHT (`zh_aht_handle_t **`). Не должен быть NULL.
|
||||
- `humidity` - Указатель для хранения значения влажности (в %)
|
||||
- `temperature` - Указатель для хранения значения температуры (в °C)
|
||||
|
||||
@@ -173,10 +177,9 @@ zh_aht_init(&config, &aht_handle);
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, humidity или temperature)
|
||||
- `ESP_ERR_NOT_FOUND` - Датчик не инициализирован
|
||||
- `ESP_FAIL` - Ошибка связи I2C
|
||||
- `ESP_ERR_TIMEOUT` - Превышено время ожидания готовности данных
|
||||
- `ESP_ERR_INVALID_CRC` - Неверная CRC контрольная сумма
|
||||
- `ESP_FAIL` - Ошибка связи I2C
|
||||
|
||||
**Примечание:** Функция выполняет измерение и ожидает ~80 мс готовности данных.
|
||||
|
||||
@@ -188,13 +191,12 @@ zh_aht_init(&config, &aht_handle);
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `handle` - Указатель на уникальный дескриптор AHT
|
||||
- `handle` - Двойной указатель на уникальный дескриптор AHT (`zh_aht_handle_t **`). Не должен быть NULL.
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle)
|
||||
- `ESP_ERR_NOT_FOUND` - Датчик не инициализирован
|
||||
- `ESP_FAIL` - Ошибка связи I2C
|
||||
|
||||
---
|
||||
@@ -207,25 +209,12 @@ zh_aht_init(&config, &aht_handle);
|
||||
|
||||
- Указатель на структуру статистики
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
const zh_aht_stats_t *stats = zh_aht_get_stats();
|
||||
printf("Ошибки I2C: %ld\n", stats->i2c_driver_error);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### zh_aht_reset_stats()
|
||||
|
||||
Сбрасывает счетчик статистики ошибок.
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
zh_aht_reset_stats();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Примеры использования
|
||||
@@ -237,7 +226,7 @@ zh_aht_reset_stats();
|
||||
|
||||
#define I2C_PORT (I2C_NUM_MAX - 1)
|
||||
|
||||
zh_aht_handle_t aht_handle = {0};
|
||||
zh_aht_handle_t *aht_handle = NULL;
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
@@ -280,9 +269,9 @@ void app_main(void)
|
||||
#define I2C_PORT (I2C_NUM_MAX - 1)
|
||||
|
||||
zh_pca9548a_handle_t pca9548a_handle = {0};
|
||||
zh_aht_handle_t aht_handle_chan_0 = {0};
|
||||
zh_aht_handle_t aht_handle_chan_1 = {0};
|
||||
zh_aht_handle_t aht_handle_chan_2 = {0};
|
||||
zh_aht_handle_t *aht_handle_chan_0 = NULL;
|
||||
zh_aht_handle_t *aht_handle_chan_1 = NULL;
|
||||
zh_aht_handle_t *aht_handle_chan_2 = NULL;
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
@@ -346,10 +335,10 @@ void app_main(void)
|
||||
| **Диапазон температуры** | -40 - +85°C |
|
||||
| **Разрешение измерения влажности** | 0.01% |
|
||||
| **Разрешение измерения температуры** | 0.01°C |
|
||||
| **Адрес I2C** | 0x38, 0x39 |
|
||||
| **Адрес I2C** | 0x38, 0x39, 0x44 |
|
||||
| **Частота I2C** | До 400 кГц |
|
||||
| **Время измерения** | ~80 мс |
|
||||
| **Поддерживаемые модели** | AHT10, AHT15, AHT20, AHT21, AHT25, AHT30 |
|
||||
| **Поддерживаемые модели** | AHT10, AHT15, AHT20, AHT21, AHT25, AHT30, AHT40 |
|
||||
| **Версия ESP-IDF** | >= 5.0 |
|
||||
| **Платформа** | Семейство ESP32 |
|
||||
| **Язык** | C (C99) |
|
||||
@@ -362,8 +351,9 @@ void app_main(void)
|
||||
|------------|----------|
|
||||
| `ESP_OK` | Операция выполнена успешно |
|
||||
| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или неверная конфигурация) |
|
||||
| `ESP_ERR_INVALID_STATE` | Датчик не инициализирован |
|
||||
| `ESP_ERR_NOT_FOUND` | Датчик не инициализирован или не отвечает |
|
||||
| `ESP_ERR_INVALID_STATE` | Датчик уже инициализирован |
|
||||
| `ESP_ERR_NO_MEM` | Ошибка выделения памяти |
|
||||
| `ESP_ERR_NOT_FOUND` | Датчик не отвечает |
|
||||
| `ESP_ERR_TIMEOUT` | Превышено время ожидания готовности данных |
|
||||
| `ESP_ERR_INVALID_CRC` | Неверная CRC контрольная сумма |
|
||||
| `ESP_FAIL` | Общая ошибка (ошибка связи I2C) |
|
||||
@@ -412,7 +402,8 @@ void app_main(void)
|
||||
- **Время измерения**: Датчик требует ~80 мс для каждого измерения
|
||||
- **I2C_ISR_IRAM_SAFE**: Для правильной работы включите `I2C_ISR_IRAM_SAFE` и `I2C_MASTER_ISR_HANDLER_IN_IRAM` в menuconfig
|
||||
- **Потокобезопасность**: Компонент использует драйвер I2C ESP-IDF, который является потокобезопасным
|
||||
- **Управление памятью**: Все функции API теперь используют двойные указатели для handle, что позволяет автоматически управлять памятью (освобождение при деинициализации, установка в NULL)
|
||||
|
||||
---
|
||||
|
||||
*Сгенерировано для zh_aht v3.4.0*
|
||||
*Сгенерировано для zh_aht v4.0.0*
|
||||
Reference in new issue
Block a user