doc: added wiki
This commit is contained in:
aZholtikov committed
1 parent
10cb89b02b
commit
2ac63a930c
3 files changed
+794
No files matched your search
+395
@@ -0,0 +1,395 @@
|
||||
# zh_bh1750 - Компонент датчика освещенности BH1750 для ESP-IDF
|
||||
|
||||
## Содержание
|
||||
|
||||
- [Обзор](#обзор)
|
||||
- [Возможности](#возможности)
|
||||
- [Установка](#установка)
|
||||
- [Справочник API](#справочник-api)
|
||||
- [Примеры использования](#примеры-использования)
|
||||
- [Технические характеристики](#технические-характеристики)
|
||||
- [Коды ошибок](#коды-ошибок)
|
||||
- [Вклад в проект](#вклад-в-проект)
|
||||
- [Лицензия](#лицензия)
|
||||
|
||||
---
|
||||
|
||||
## Обзор
|
||||
|
||||
`zh_bh1750` - это легковесный компонент ESP-IDF для датчика освещенности BH1750. Он предоставляет простой API для считывания значений освещенности от 1 до 65535 люкс. Компонент поддерживает несколько датчиков на одной шине I2C с использованием I2C мультиплексатора [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a).
|
||||
|
||||
Компонент разработан специально для микроконтроллеров ESP32 и использует API драйвера I2C ESP-IDF v5.0+.
|
||||
|
||||
---
|
||||
|
||||
## Возможности
|
||||
|
||||
1. **Измерение освещенности**: Считывание значений освещенности от 1 до 65535 люкс
|
||||
2. **Интерфейс I2C**: Использует стандартный протокол I2C (макс. частота 400 кГц)
|
||||
3. **Настраиваемый адрес I2C**: Поддерживает адреса 0x23 и 0x5C
|
||||
4. **Статистика ошибок**: Встроенный счетчик ошибок драйвера I2C
|
||||
5. **Низкое энергопотребление**: Работает с системой управления питанием ESP-IDF
|
||||
6. **Потокобезопасность**: Использует драйвер I2C ESP-IDF (потокобезопасен)
|
||||
7. **Минимальные накладные расходы**: Низкие накладные расходы на память и процессор
|
||||
8. **Поддержка нескольких датчиков**: Совместим с I2C мультиплексатором (zh_pca9548a)
|
||||
|
||||
---
|
||||
|
||||
## Установка
|
||||
|
||||
1. Перейдите в каталог компонентов вашего проекта:
|
||||
|
||||
```bash
|
||||
cd ../ваш_проект/components
|
||||
```
|
||||
|
||||
2. Клонируйте репозиторий:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/aZholtikov/zh_bh1750.git
|
||||
```
|
||||
|
||||
3. В вашем приложении подключите заголовочный файл:
|
||||
|
||||
```c
|
||||
#include "zh_bh1750.h"
|
||||
```
|
||||
|
||||
4. Компонент будет автоматически собран вместе с вашим проектом.
|
||||
|
||||
### Опционально: Использование с I2C мультиплексатором (zh_pca9548a)
|
||||
|
||||
Для использования нескольких датчиков BH1750 на одной шине I2C, также установите компонент [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a).
|
||||
|
||||
---
|
||||
|
||||
## Справочник API
|
||||
|
||||
### Структура zh_bh1750_init_config_t
|
||||
|
||||
```c
|
||||
typedef struct
|
||||
{
|
||||
i2c_master_bus_handle_t i2c_handle; // Уникальный дескриптор шины I2C
|
||||
uint8_t i2c_address; // Адрес устройства датчика I2C (0x23 или 0x5C)
|
||||
uint32_t i2c_frequency; // Частота I2C датчика (макс. 400000 Гц)
|
||||
} zh_bh1750_init_config_t;
|
||||
```
|
||||
|
||||
Используйте макрос `ZH_BH1750_INIT_CONFIG_DEFAULT()` для инициализации значениями по умолчанию:
|
||||
|
||||
- `i2c_frequency`: 400000 Гц
|
||||
- `i2c_address`: 0x23
|
||||
|
||||
---
|
||||
|
||||
### Структура zh_bh1750_handle_t
|
||||
|
||||
```c
|
||||
typedef struct
|
||||
{
|
||||
bool is_initialized; // Флаг инициализации датчика
|
||||
i2c_master_dev_handle_t dev_handle; // Уникальный дескриптор устройства I2C
|
||||
} zh_bh1750_handle_t;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Структура zh_bh1750_stats_t
|
||||
|
||||
```c
|
||||
typedef struct
|
||||
{
|
||||
uint32_t i2c_driver_error; // Количество ошибок драйвера I2C
|
||||
} zh_bh1750_stats_t;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### zh_bh1750_init()
|
||||
|
||||
Инициализирует датчик BH1750.
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `config` - Указатель на структуру конфигурации инициализации BH1750
|
||||
- `handle` - Указатель на уникальный дескриптор BH1750
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config или handle)
|
||||
- `ESP_FAIL` - Ошибка инициализации (проверка конфигурации или добавление устройства I2C)
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
zh_bh1750_handle_t bh1750_handle = {0};
|
||||
zh_bh1750_init_config_t config = ZH_BH1750_INIT_CONFIG_DEFAULT();
|
||||
config.i2c_handle = i2c_bus_handle;
|
||||
zh_bh1750_init(&config, &bh1750_handle);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### zh_bh1750_deinit()
|
||||
|
||||
Деинициализирует датчик BH1750 и удаляет его из шины I2C.
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `handle` - Указатель на уникальный дескриптор BH1750
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle)
|
||||
- `ESP_ERR_INVALID_STATE` - Датчик не инициализирован
|
||||
- `ESP_FAIL` - Ошибка удаления устройства I2C
|
||||
|
||||
---
|
||||
|
||||
### zh_bh1750_read()
|
||||
|
||||
Считывает значение освещенности с датчика.
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `handle` - Указатель на уникальный дескриптор BH1750
|
||||
- `data` - Указатель для хранения значения освещенности (в люксах)
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- `ESP_OK` - Успех
|
||||
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или data)
|
||||
- `ESP_ERR_NOT_FOUND` - Датчик не инициализирован
|
||||
- `ESP_FAIL` - Ошибка связи I2C
|
||||
|
||||
**Примечание:** Функция выполняет измерение и ожидает ~180 мс готовности данных.
|
||||
|
||||
---
|
||||
|
||||
### zh_bh1750_get_stats()
|
||||
|
||||
Получает статистику ошибок с момента последнего сброса.
|
||||
|
||||
**Возвращает:**
|
||||
|
||||
- Указатель на структуру статистики
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
const zh_bh1750_stats_t *stats = zh_bh1750_get_stats();
|
||||
printf("Ошибки I2C: %ld\n", stats->i2c_driver_error);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### zh_bh1750_reset_stats()
|
||||
|
||||
Сбрасывает счетчик статистики ошибок.
|
||||
|
||||
**Пример:**
|
||||
|
||||
```c
|
||||
zh_bh1750_reset_stats();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Базовый пример: Один датчик
|
||||
|
||||
```c
|
||||
#include "zh_bh1750.h"
|
||||
|
||||
#define I2C_PORT (I2C_NUM_MAX - 1)
|
||||
|
||||
zh_bh1750_handle_t bh1750_handle = {0};
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
esp_log_level_set("zh_bh1750", 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_master_bus_handle_t i2c_bus_handle;
|
||||
i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
|
||||
|
||||
zh_bh1750_init_config_t config = ZH_BH1750_INIT_CONFIG_DEFAULT();
|
||||
config.i2c_handle = i2c_bus_handle;
|
||||
|
||||
zh_bh1750_init(&config, &bh1750_handle);
|
||||
|
||||
float lux = 0.0;
|
||||
for (;;)
|
||||
{
|
||||
zh_bh1750_read(&bh1750_handle, &lux);
|
||||
printf("Освещенность: %.2f люкс\n", lux);
|
||||
|
||||
const zh_bh1750_stats_t *stats = zh_bh1750_get_stats();
|
||||
printf("Ошибки I2C: %ld\n", stats->i2c_driver_error);
|
||||
|
||||
vTaskDelay(5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Несколько датчиков: Использование I2C мультиплексатора (zh_pca9548a)
|
||||
|
||||
```c
|
||||
#include "zh_pca9548a.h"
|
||||
#include "zh_bh1750.h"
|
||||
|
||||
#define I2C_PORT (I2C_NUM_MAX - 1)
|
||||
|
||||
zh_pca9548a_handle_t pca9548a_handle = {0};
|
||||
zh_bh1750_handle_t bh1750_handle_chan_0 = {0};
|
||||
zh_bh1750_handle_t bh1750_handle_chan_1 = {0};
|
||||
zh_bh1750_handle_t bh1750_handle_chan_2 = {0};
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
esp_log_level_set("zh_pca9548a", ESP_LOG_ERROR);
|
||||
esp_log_level_set("zh_bh1750", 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_master_bus_handle_t i2c_bus_handle = NULL;
|
||||
i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
|
||||
|
||||
// Инициализация I2C мультиплексатора
|
||||
zh_pca9548a_init_config_t pca_config = ZH_PCA9548A_INIT_CONFIG_DEFAULT();
|
||||
pca_config.i2c_handle = i2c_bus_handle;
|
||||
pca_config.i2c_address = 0x70;
|
||||
zh_pca9548a_init(&pca_config, &pca9548a_handle);
|
||||
|
||||
// Инициализация датчиков BH1750 на разных каналах
|
||||
zh_bh1750_init_config_t bh1750_config = ZH_BH1750_INIT_CONFIG_DEFAULT();
|
||||
bh1750_config.i2c_handle = i2c_bus_handle;
|
||||
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_0);
|
||||
zh_bh1750_init(&bh1750_config, &bh1750_handle_chan_0);
|
||||
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_1);
|
||||
zh_bh1750_init(&bh1750_config, &bh1750_handle_chan_1);
|
||||
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_2);
|
||||
zh_bh1750_init(&bh1750_config, &bh1750_handle_chan_2);
|
||||
|
||||
float lux = 0.0;
|
||||
for (;;)
|
||||
{
|
||||
// Считывание с датчика на канале 0
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_0);
|
||||
zh_bh1750_read(&bh1750_handle_chan_0, &lux);
|
||||
printf("Датчик 1. Освещенность: %.2f люкс\n", lux);
|
||||
|
||||
// Считывание с датчика на канале 1
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_1);
|
||||
zh_bh1750_read(&bh1750_handle_chan_1, &lux);
|
||||
printf("Датчик 2. Освещенность: %.2f люкс\n", lux);
|
||||
|
||||
// Считывание с датчика на канале 2
|
||||
zh_pca9548a_set(&pca9548a_handle, ZH_PCA9548A_CHAN_NUM_2);
|
||||
zh_bh1750_read(&bh1750_handle_chan_2, &lux);
|
||||
printf("Датчик 3. Освещенность: %.2f люкс\n", lux);
|
||||
|
||||
vTaskDelay(5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Технические характеристики
|
||||
|
||||
| Параметр | Значение |
|
||||
|----------|----------|
|
||||
| **Диапазон освещенности** | 1 - 65535 люкс |
|
||||
| **Разрешение измерения** | 1 люкс |
|
||||
| **Адрес I2C** | 0x23, 0x5C |
|
||||
| **Частота I2C** | До 400 кГц |
|
||||
| **Время измерения** | ~180 мс |
|
||||
| **Версия ESP-IDF** | >= 5.0 |
|
||||
| **Платформа** | Семейство ESP32 |
|
||||
| **Язык** | C (C99) |
|
||||
|
||||
---
|
||||
|
||||
## Коды ошибок
|
||||
|
||||
| Код ошибки | Описание |
|
||||
|------------|----------|
|
||||
| `ESP_OK` | Операция выполнена успешно |
|
||||
| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или неверная конфигурация) |
|
||||
| `ESP_ERR_INVALID_STATE` | Датчик не инициализирован |
|
||||
| `ESP_ERR_NOT_FOUND` | Датчик не инициализирован или не отвечает |
|
||||
| `ESP_FAIL` | Общая ошибка (ошибка связи I2C) |
|
||||
|
||||
---
|
||||
|
||||
## Вклад в проект
|
||||
|
||||
Вклад приветствуется! Чтобы внести свой вклад:
|
||||
|
||||
1. Сделайте форк репозитория
|
||||
2. Создайте ветку функции (`git checkout -b feature/AmazingFeature`)
|
||||
3. Закоммитьте ваши изменения (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Отправьте в ветку (`git push origin feature/AmazingFeature`)
|
||||
5. Откройте Pull Request
|
||||
|
||||
Пожалуйста, убедитесь, что ваш код следует существующему стилю и включает соответствующую документацию.
|
||||
|
||||
---
|
||||
|
||||
## Лицензия
|
||||
|
||||
Этот проект лицензирован по лицензии Apache, версия 2.0 - см. файл [LICENSE](LICENSE) для подробной информации.
|
||||
|
||||
### Apache License, Version 2.0
|
||||
|
||||
Авторское право (c) 2026 Алексей Жолтиков
|
||||
|
||||
Лицензировано по лицензии Apache License, Version 2.0 (далее — "Лицензия");
|
||||
вы не можете использовать этот файл, кроме случаев, предусмотренных Лицензией.
|
||||
Копию Лицензии можно получить по адресу:
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Если иное не требуется действующим законодательством или не согласовано в письменном виде,
|
||||
программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ",
|
||||
БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии
|
||||
ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
|
||||
Смотрите Лицензию для получения конкретных прав и ограничений.
|
||||
|
||||
---
|
||||
|
||||
## Дополнительные заметки
|
||||
|
||||
- **Подтягивающие резисторы I2C**: Убедитесь, что к линиям SDA и SCL подключены соответствующие подтягивающие резисторы
|
||||
- **Время измерения**: Датчик требует ~180 мс для каждого измерения
|
||||
- **I2C_ISR_IRAM_SAFE**: Для правильной работы включите `I2C_ISR_IRAM_SAFE` и `I2C_MASTER_ISR_HANDLER_IN_IRAM` в menuconfig
|
||||
- **Потокобезопасность**: Компонент использует драйвер I2C ESP-IDF, который является потокобезопасным
|
||||
|
||||
---
|
||||
|
||||
*Сгенерировано для zh_bh1750 v1.0.0*
|
||||
Reference in new issue
Block a user