From f18ee9ba7745021de69215151c65e9356ab09eb4 Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sat, 13 Jun 2026 08:26:41 +0300 Subject: [PATCH] doc: added wiki --- README.md | 4 + WIKI_EN.md | 350 +++++++++++++++++++++++++++++++++++++++++++++++++++++ WIKI_RU.md | 350 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 704 insertions(+) create mode 100644 WIKI_EN.md create mode 100644 WIKI_RU.md diff --git a/README.md b/README.md index d9968bb..dbe869b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # ESP32 ESP-IDF component for AC dimmer 115V/400Hz +## Wiki + +[EN](WIKI_EN.md) | [RU](WIKI_RU.md) + ## Tested on 1. [ESP32 ESP-IDF v6.0.0](https://docs.espressif.com/projects/esp-idf/en/v6.0/esp32/index.html) diff --git a/WIKI_EN.md b/WIKI_EN.md new file mode 100644 index 0000000..e11b0d0 --- /dev/null +++ b/WIKI_EN.md @@ -0,0 +1,350 @@ +# zh_ac_dimmer - AC Dimmer Component for ESP-IDF + +## Table of Contents + +- [Overview](#overview) +- [Features](#features) +- [Installation](#installation) +- [API Reference](#api-reference) +- [Usage Examples](#usage-examples) +- [Technical Specifications](#technical-specifications) +- [Error Codes](#error-codes) +- [Contributing](#contributing) +- [License](#license) + +--- + +## Overview + +`zh_ac_dimmer` is a lightweight ESP-IDF component for AC dimmer control. It provides a simple API to control AC load power using zero-crossing detection and TRIAC control. The component is designed specifically for ESP32 microcontrollers and uses ESP-IDF v5.0+ drivers (GPTimer, GPIO). + +The component supports AC frequency 400Hz only and uses hardware timers for precise timing control. + +--- + +## Features + +1. **AC Power Control**: Controls AC load power from 0% to 100% +2. **Zero-Crossing Detection**: Uses GPIO interrupt for precise timing +3. **TRIAC Control**: Controls TRIAC gate with precise timing +4. **Hardware Timer**: Uses GPTimer for accurate dimming control +5. **Error Handling**: Comprehensive error checking and validation +6. **Thread-Safe**: Uses ESP-IDF drivers (thread-safe) +7. **Low Memory**: Minimal memory footprint +8. **Simple API**: Easy-to-use interface + +--- + +## Installation + +1. Navigate to your project's components directory: + +```bash +cd ../your_project/components +``` + +2. Clone the repository: + +```bash +git clone https://github.com/aZholtikov/zh_ac_dimmer.git +``` + +3. In your application, include the header: + +```c +#include "zh_ac_dimmer.h" +``` + +4. The component will be automatically built with your project. + +### Required Configuration + +For correct operation, please enable the following settings in menuconfig: + +```text +GPIO_CTRL_FUNC_IN_IRAM +CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM +CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM +CONFIG_GPTIMER_ISR_CACHE_SAFE +``` + +--- + +## API Reference + +### zh_ac_dimmer_init_config_t Structure + +```c +typedef struct +{ + gpio_num_t zero_cross_gpio; // Zero cross GPIO + gpio_num_t triac_gpio; // Triac GPIO +} zh_ac_dimmer_init_config_t; +``` + +Use `ZH_AC_DIMMER_INIT_CONFIG_DEFAULT()` macro to initialize with default values: + +- `zero_cross_gpio`: GPIO_NUM_MAX +- `triac_gpio`: GPIO_NUM_MAX + +--- + +### zh_ac_dimmer_init() + +Initializes the AC dimmer. + +**Parameters:** + +- `config` - Pointer to AC dimmer initialization configuration structure + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL config or invalid GPIO) +- `ESP_ERR_INVALID_STATE` - AC dimmer is already initialized +- `ESP_FAIL` - Initialization failed (GPIO or timer initialization) + +**Example:** + +```c +zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); +config.zero_cross_gpio = GPIO_NUM_16; +config.triac_gpio = GPIO_NUM_17; +zh_ac_dimmer_init(&config); +``` + +--- + +### zh_ac_dimmer_deinit() + +Deinitializes the AC dimmer and releases resources. + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_STATE` - AC dimmer is not initialized +- `ESP_FAIL` - Deinitialization failed (GPIO or timer deinitialization) + +--- + +### zh_ac_dimmer_start() + +Starts AC dimmer operation. + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_STATE` - AC dimmer is not initialized + +--- + +### zh_ac_dimmer_stop() + +Stops AC dimmer operation. + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_STATE` - AC dimmer is not initialized + +--- + +### zh_ac_dimmer_set() + +Sets AC dimmer dimming value. + +**Parameters:** + +- `value` - Dimming value (0 to 100, where 0 = off, 100 = full power) + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_STATE` - AC dimmer is not initialized +- `ESP_ERR_INVALID_ARG` - Invalid dimming value + +--- + +### zh_ac_dimmer_get() + +Gets current AC dimmer dimming value. + +**Parameters:** + +- `value` - Pointer to store the dimming value + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_STATE` - AC dimmer is not initialized +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL value) + +--- + +## Usage Examples + +### Basic Example: Dimmer Control + +```c +#include "zh_ac_dimmer.h" + +void app_main(void) +{ + esp_log_level_set("zh_ac_dimmer", ESP_LOG_ERROR); + zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); + config.zero_cross_gpio = GPIO_NUM_16; + config.triac_gpio = GPIO_NUM_17; + zh_ac_dimmer_init(&config); + zh_ac_dimmer_start(); + uint8_t value = 0; + for (uint8_t i = 0; i <= 100; ++i) + { + zh_ac_dimmer_set(i); + zh_ac_dimmer_get(&value); + printf("Dimmer value: %d.\\n", value); + vTaskDelay(100 / portTICK_PERIOD_MS); + } + for (uint8_t i = 100; i > 0; --i) + { + zh_ac_dimmer_set(i); + zh_ac_dimmer_get(&value); + printf("Dimmer value: %d.\\n", value); + vTaskDelay(100 / portTICK_PERIOD_MS); + } + zh_ac_dimmer_stop(); + zh_ac_dimmer_deinit(); +} +``` + +--- + +### Example: Dimmer with Button Control + +```c +#include "zh_ac_dimmer.h" + +#define ZERO_CROSS_GPIO GPIO_NUM_16 +#define TRIAC_GPIO GPIO_NUM_17 +#define BUTTON_GPIO GPIO_NUM_0 + +static uint8_t dimmer_value = 50; + +static void IRAM_ATTR button_isr_handler(void *arg) +{ + dimmer_value = (dimmer_value + 10) % 110; + if (dimmer_value > 100) + { + dimmer_value = 0; + } + zh_ac_dimmer_set(dimmer_value); + printf("Dimmer value: %d\\n", dimmer_value); +} + +void app_main(void) +{ + esp_log_level_set("zh_ac_dimmer", ESP_LOG_ERROR); + // Initialize dimmer + zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); + config.zero_cross_gpio = ZERO_CROSS_GPIO; + config.triac_gpio = TRIAC_GPIO; + zh_ac_dimmer_init(&config); + // Initialize button + gpio_config_t button_config = { + .intr_type = GPIO_INTR_POSEDGE, + .mode = GPIO_MODE_INPUT, + .pin_bit_mask = (1ULL << BUTTON_GPIO), + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .pull_up_en = GPIO_PULLUP_ENABLE, + }; + gpio_config(&button_config); + gpio_install_isr_service(ESP_INTR_FLAG_DEFAULT); + gpio_isr_handler_add(BUTTON_GPIO, button_isr_handler, NULL); + // Start dimmer + zh_ac_dimmer_start(); + printf("Dimmer initialized. Button on GPIO %d changes dimmer value.\\n", BUTTON_GPIO); + for (;;) + { + vTaskDelay(1000 / portTICK_PERIOD_MS); + uint8_t current_value; + zh_ac_dimmer_get(¤t_value); + printf("Current dimmer value: %d\\n", current_value); + } +} +``` + +--- + +## Technical Specifications + +| Parameter | Value | +|-----------|-------| +| **Dimming Range** | 0 - 100% | +| **AC Frequency** | 400 Hz (supported only) | +| **Zero-Crossing Detection** | GPIO interrupt (positive edge) | +| **TRIAC Control** | GPIO output | +| **Timer Resolution** | 1 MHz (1 µs) | +| **Measurement Time** | ~1250 µs per cycle | +| **ESP-IDF Version** | >= 5.0 | +| **Platform** | ESP32 series | +| **Language** | C (C99) | + +--- + +## Error Codes + +| Error Code | Description | +|------------|-------------| +| `ESP_OK` | Operation successful | +| `ESP_ERR_INVALID_ARG` | Invalid argument (NULL pointer, invalid GPIO, or invalid dimming value) | +| `ESP_ERR_INVALID_STATE` | AC dimmer is not initialized | +| `ESP_FAIL` | General failure (GPIO or timer initialization/deinitialization) | + +--- + +## Contributing + +Contributions are welcome! To contribute: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/AmazingFeature`) +3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + +Please ensure your code follows the existing style and includes appropriate documentation. + +--- + +## License + +This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details. + +### Apache License, Version 2.0 + +Copyright (c) 2026 Alexey Zholtikov + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +--- + +## Additional Notes + +- **AC Frequency**: Currently supports 400Hz frequency only +- **Zero-Crossing Timing**: 1250 µs period (400Hz) with 330 µs compensation for timer delay +- **GPIO Interrupt**: Zero-crossing detection uses positive edge interrupt +- **IRAM Requirements**: For correct operation, enable `GPIO_CTRL_FUNC_IN_IRAM`, `CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM`, `CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM`, and `CONFIG_GPTIMER_ISR_CACHE_SAFE` in menuconfig +- **Thread Safety**: The component uses ESP-IDF drivers which are thread-safe + +--- + +*Generated for zh_ac_dimmer v1.0.0* diff --git a/WIKI_RU.md b/WIKI_RU.md new file mode 100644 index 0000000..3d42fce --- /dev/null +++ b/WIKI_RU.md @@ -0,0 +1,350 @@ +# zh_ac_dimmer - Компонент управления освещением переменного тока для ESP-IDF + +## Содержание + +- [Обзор](#обзор) +- [Возможности](#возможности) +- [Установка](#установка) +- [Справочник API](#справочник-api) +- [Примеры использования](#примеры-использования) +- [Технические характеристики](#технические-характеристики) +- [Коды ошибок](#коды-ошибок) +- [Вклад в проект](#вклад-в-проект) +- [Лицензия](#лицензия) + +--- + +## Обзор + +`zh_ac_dimmer` - это легковесный компонент ESP-IDF для управления освещением переменного тока. Он предоставляет простой API для управления мощностью нагрузки переменного тока с использованием детекции перехода через ноль и управления TRIAC. Компонент разработан специально для микроконтроллеров ESP32 и использует драйверы ESP-IDF v5.0+ (GPTimer, GPIO). + +Компонент поддерживает частоту переменного тока 400Гц и использует аппаратные таймеры для точного управления временем. + +--- + +## Возможности + +1. **Управление мощностью переменного тока**: Управление мощностью нагрузки от 0% до 100% +2. **Детекция перехода через ноль**: Использует прерывание GPIO для точного тайминга +3. **Управление TRIAC**: Управление затвором TRIAC с точным таймингом +4. **Аппаратный таймер**: Использует GPTimer для точного управления затуханием +5. **Обработка ошибок**: Комплексная проверка ошибок и валидация +6. **Потокобезопасность**: Использует драйверы ESP-IDF (потокобезопасно) +7. **Минимальный объем памяти**: Низкие накладные расходы на память +8. **Простой API**: Легкое в использовании интерфейс + +--- + +## Установка + +1. Перейдите в каталог компонентов вашего проекта: + +```bash +cd ../ваш_проект/components +``` + +2. Клонируйте репозиторий: + +```bash +git clone https://github.com/aZholtikov/zh_ac_dimmer.git +``` + +3. В вашем приложении подключите заголовочный файл: + +```c +#include "zh_ac_dimmer.h" +``` + +4. Компонент будет автоматически собран вместе с вашим проектом. + +### Необходимая конфигурация + +Для правильной работы включите следующие настройки в menuconfig: + +```text +GPIO_CTRL_FUNC_IN_IRAM +CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM +CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM +CONFIG_GPTIMER_ISR_CACHE_SAFE +``` + +--- + +## Справочник API + +### Структура zh_ac_dimmer_init_config_t + +```c +typedef struct +{ + gpio_num_t zero_cross_gpio; // GPIO детекции перехода через ноль + gpio_num_t triac_gpio; // GPIO управления TRIAC +} zh_ac_dimmer_init_config_t; +``` + +Используйте макрос `ZH_AC_DIMMER_INIT_CONFIG_DEFAULT()` для инициализации значениями по умолчанию: + +- `zero_cross_gpio`: GPIO_NUM_MAX +- `triac_gpio`: GPIO_NUM_MAX + +--- + +### zh_ac_dimmer_init() + +Инициализирует управление освещением переменного тока. + +**Параметры:** + +- `config` - Указатель на структуру конфигурации инициализации освещения переменного тока + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config или неверный GPIO) +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока уже инициализировано +- `ESP_FAIL` - Ошибка инициализации (GPIO или таймер) + +**Пример:** + +```c +zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); +config.zero_cross_gpio = GPIO_NUM_16; +config.triac_gpio = GPIO_NUM_17; +zh_ac_dimmer_init(&config); +``` + +--- + +### zh_ac_dimmer_deinit() + +Деинициализирует управление освещением переменного тока и освобождает ресурсы. + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока не инициализировано +- `ESP_FAIL` - Ошибка деинициализации (GPIO или деинициализация таймера) + +--- + +### zh_ac_dimmer_start() + +Запускает работу освещения переменного тока. + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока не инициализировано + +--- + +### zh_ac_dimmer_stop() + +Останавливает работу освещения переменного тока. + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока не инициализировано + +--- + +### zh_ac_dimmer_set() + +Устанавливает значение затухания освещения переменного тока. + +**Параметры:** + +- `value` - Значение затухания (0 до 100, где 0 = выкл, 100 = полная мощность) + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока не инициализировано +- `ESP_ERR_INVALID_ARG` - Неверное значение затухания + +--- + +### zh_ac_dimmer_get() + +Получает текущее значение затухания освещения переменного тока. + +**Параметры:** + +- `value` - Указатель для хранения значения затухания + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_STATE` - Освещение переменного тока не инициализировано +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL value) + +--- + +## Примеры использования + +### Базовый пример: Управление затуханием + +```c +#include "zh_ac_dimmer.h" + +void app_main(void) +{ + esp_log_level_set("zh_ac_dimmer", ESP_LOG_ERROR); + zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); + config.zero_cross_gpio = GPIO_NUM_16; + config.triac_gpio = GPIO_NUM_17; + zh_ac_dimmer_init(&config); + zh_ac_dimmer_start(); + uint8_t value = 0; + for (uint8_t i = 0; i <= 100; ++i) + { + zh_ac_dimmer_set(i); + zh_ac_dimmer_get(&value); + printf("Значение затухания: %d.\n", value); + vTaskDelay(100 / portTICK_PERIOD_MS); + } + for (uint8_t i = 100; i > 0; --i) + { + zh_ac_dimmer_set(i); + zh_ac_dimmer_get(&value); + printf("Значение затухания: %d.\n", value); + vTaskDelay(100 / portTICK_PERIOD_MS); + } + zh_ac_dimmer_stop(); + zh_ac_dimmer_deinit(); +} +``` + +--- + +### Пример: Управление затуханием с кнопкой + +```c +#include "zh_ac_dimmer.h" + +#define ZERO_CROSS_GPIO GPIO_NUM_16 +#define TRIAC_GPIO GPIO_NUM_17 +#define BUTTON_GPIO GPIO_NUM_0 + +static uint8_t dimmer_value = 50; + +static void IRAM_ATTR button_isr_handler(void *arg) +{ + dimmer_value = (dimmer_value + 10) % 110; + if (dimmer_value > 100) + { + dimmer_value = 0; + } + zh_ac_dimmer_set(dimmer_value); + printf("Значение затухания: %d\n", dimmer_value); +} + +void app_main(void) +{ + esp_log_level_set("zh_ac_dimmer", ESP_LOG_ERROR); + // Инициализация затухания + zh_ac_dimmer_init_config_t config = ZH_AC_DIMMER_INIT_CONFIG_DEFAULT(); + config.zero_cross_gpio = ZERO_CROSS_GPIO; + config.triac_gpio = TRIAC_GPIO; + zh_ac_dimmer_init(&config); + // Инициализация кнопки + gpio_config_t button_config = { + .intr_type = GPIO_INTR_POSEDGE, + .mode = GPIO_MODE_INPUT, + .pin_bit_mask = (1ULL << BUTTON_GPIO), + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .pull_up_en = GPIO_PULLUP_ENABLE, + }; + gpio_config(&button_config); + gpio_install_isr_service(ESP_INTR_FLAG_DEFAULT); + gpio_isr_handler_add(BUTTON_GPIO, button_isr_handler, NULL); + // Запуск затухания + zh_ac_dimmer_start(); + printf("Затухание инициализировано. Кнопка на GPIO %d меняет значение затухания.\n", BUTTON_GPIO); + for (;;) + { + vTaskDelay(1000 / portTICK_PERIOD_MS); + uint8_t current_value; + zh_ac_dimmer_get(¤t_value); + printf("Текущее значение затухания: %d\n", current_value); + } +} +``` + +--- + +## Технические характеристики + +| Параметр | Значение | +|----------|----------| +| **Диапазон затухания** | 0 - 100% | +| **Частота переменного тока** | 400 Гц (поддерживается только) | +| **Детекция перехода через ноль** | Прерывание GPIO (положительный фронт) | +| **Управление TRIAC** | Выход GPIO | +| **Разрешение таймера** | 1 МГц (1 мкс) | +| **Время измерения** | ~1250 мкс на цикл | +| **Версия ESP-IDF** | >= 5.0 | +| **Платформа** | Семейство ESP32 | +| **Язык** | C (C99) | + +--- + +## Коды ошибок + +| Код ошибки | Описание | +|------------|----------| +| `ESP_OK` | Операция выполнена успешно | +| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель, неверный GPIO или неверное значение затухания) | +| `ESP_ERR_INVALID_STATE` | Освещение переменного тока не инициализировано | +| `ESP_FAIL` | Общая ошибка (GPIO или инициализация/деинициализация таймера) | + +--- + +## Вклад в проект + +Вклад приветствуется! Чтобы внести свой вклад: + +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 + +Если иное не требуется действующим законодательством или не согласовано в письменном виде, +программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ", +БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии +ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. +Смотрите Лицензию для получения конкретных прав и ограничений. + +--- + +## Дополнительные заметки + +- **Частота переменного тока**: В настоящее время поддерживается только частота 400Гц +- **Тайминг перехода через ноль**: 1250 мкс период (400Гц) с компенсацией 330 мкс для задержки таймера +- **Прерывание GPIO**: Детекция перехода через ноль использует прерывание положительного фронта +- **Требования IRAM**: Для правильной работы включите `GPIO_CTRL_FUNC_IN_IRAM`, `CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM`, `CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` и `CONFIG_GPTIMER_ISR_CACHE_SAFE` в menuconfig +- **Потокобезопасность**: Компонент использует драйверы ESP-IDF, которые являются потокобезопасными + +--- + +*Сгенерировано для zh_ac_dimmer v1.0.0*