From 9150b0537384aaa2310e6d9b29a316e556764c13 Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Tue, 3 Nov 2026 19:23:03 +0300 Subject: [PATCH] doc: added wiki --- wiki_ru.md | 241 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 wiki_ru.md diff --git a/wiki_ru.md b/wiki_ru.md new file mode 100644 index 0000000..6a9c27e --- /dev/null +++ b/wiki_ru.md @@ -0,0 +1,241 @@ +# Описание компонента zh_tachometer + +**zh_tachometer** — драйвер для ESP-IDF, измеряющий скорость вращения на основе квадратурного энкодера. Компонент использует периферийный модуль PCNT ESP32 в режиме квадратурного декодера для подсчёта импульсов энкодера и ESP-Timer, работающего с частотой 100 Гц, для периодического считывания накопленного значения и вычисления оборотов в минуту (RPM). Результатом является неблокирующий, совместимый с RTOS интерфейс, подходящий для мониторинга скорости двигателей. + +Компонент поддерживает одновременную работу нескольких тахометров, каждый из которых использует собственный модуль PCNT и таймер. + +## Основные возможности + +- **Поддержка квадратурного энкодера** — подсчёт импульсов по двум фазам (A/B) через периферийный модуль PCNT в режиме квадратурного декодера. +- **Автоматический расчёт RPM** — вычисление оборотов в минуту на основе настраиваемого количества импульсов на полный оборот энкодера. +- **Периодическое дискретное считывание** — ESP-Timer запускается с частотой 100 Гц (интервал 10 мс) для чтения накопленного счёта PCNT и перевода в RPM. +- **Настраиваемые подтягивающие резисторы GPIO** — возможность включения или отключения внутренних подтягивающих резисторов для линий A и B энкодера. +- **Фильтр глитчей PCNT** — подавление ложных переходов с настройкой 1000 нс через встроенный фильтр PCNT. +- **Поддержка нескольких тахометров** — каждый тахометр использует отдельный модуль PCNT и таймер ESP-Timer. + +## Внутреннее устройство + +### Структура `zh_tachometer_handle_t` + +Внутренняя структура тахометра содержит ссылки на все используемые периферийные модули, последнее вычисленное значение RPM и конфигурацию энкодера. + +| Поле | Тип | Описание | +| ------ | ----- | ---------- | +| `pcnt_unit_handle` | `pcnt_unit_handle_t` | Управляющий объект модуля PCNT для квадратурного декодирования | +| `pcnt_channel_a_handle` | `pcnt_channel_handle_t` | Управляющий объект канала PCNT A (детектор фронтов) | +| `pcnt_channel_b_handle` | `pcnt_channel_handle_t` | Управляющий объект канала PCNT B (детектор фронтов) | +| `esp_timer_handle` | `esp_timer_handle_t` | Управляющий объект ESP-Timer для дискретного считывания RPM (100 Гц) | +| `value` | `volatile uint16_t` | Последнее вычисленное значение RPM (абсолютное, направление отбрасывается) | +| `encoder_pulses` | `uint16_t` | Количество импульсов на один полный оборот энкодера | + +Структура является непрозрачной для вызывающего кода — доступ осуществляется только через публичные функции API. + +### Структура конфигурации `zh_tachometer_init_config_t` + +Передаётся в функцию `zh_tachometer_init()` для настройки пин GPIO, подтягивающих резисторов и коэффициента импульсов на оборот. + +| Поле | Тип | Описание | +| ------ | ----- | ---------- | +| `a_gpio_number` | `gpio_num_t` | Номер GPIO линии фазы A энкодера | +| `b_gpio_number` | `gpio_num_t` | Номер GPIO линии фазы B энкодера | +| `pullup` | `bool` | Включение или отключение подтягивающих резисторов GPIO | +| `encoder_pulses` | `uint16_t` | Количество импульсов на один полный оборот энкодера | + +По умолчанию `ZH_TACHOMETER_INIT_CONFIG_DEFAULT()` устанавливает GPIO в `GPIO_NUM_MAX`, подтягивание в `true`, а импульсы в `0`. + +### Управление памятью + +Память для структуры `zh_tachometer_handle_t` выделяется через `heap_caps_calloc()` с флагом `MALLOC_CAP_8BIT` при вызове `zh_tachometer_init()` и освобождается через `heap_caps_free()` при вызове `zh_tachometer_deinit()`. Управляющие объекты PCNT и ESP-Timer освобождаются через соответствующие функции ESP-IDF API (`pcnt_del_unit()`, `pcnt_del_channel()`, `esp_timer_delete()`). + +## API (интерфейс) + +### Инициализация и освобождение + +| Функция | Описание | +|---------|----------| +| `zh_tachometer_init()` | Создаёт объект тахометра, настраивает ESP-Timer (100 Гц) и периферийный модуль PCNT в режиме квадратурного декодера с фильтром глитчей | +| `zh_tachometer_deinit()` | Останавливает модуль PCNT, удаляет каналы и точки наблюдения, удаляет ESP-Timer и освобождает память объекта | + +### Получение данных + +| Функция | Описание | +|---------|----------| +| `zh_tachometer_get()` | Возвращает последнее вычисленное значение RPM. Значение является абсолютным (направление вращения отбрасывается), функция не блокирует выполнение и не обращается к периферийному модулю PCNT напрямую | + +## Потокобезопасность + +1. **Общий доступ к данным** — последнее значение RPM хранится в поле `value` с квалификатором `volatile`, что обеспечивает корректное чтение из любого контекса. Функция `zh_tachometer_get()` просто копирует значение из структуры, не требуя блокировок. + +2. **Контекст таймера** — обратный вызов ESP-Timer выполняется в контексте задачи `esp_timer service task` (метод диспетчеризации `ESP_TIMER_TASK` по умолчанию), а не из прерывания. Блокирующие или длительные операции в обратном вызове следует избегать. + +## Алгоритмы + +### Формула расчёта RPM + +Обратный вызов ESP-Timer выполняется каждые 10 мс (100 Гц). За этот интервал считывается накопленное значение PCNT, обнуляется и преобразуется в RPM по формуле: + +``` +RPM = (count * 100.0 / (4.0 * pulses_per_rev)) * 60.0 +``` + +Где: + +- `count` — накопленное значение PCNT за 10 мс. +- `100.0` — масштабный коэффициент для перевода 10 мс в секунду (1000 мс / 10 мс). +- `4.0` — коэффициент квадратурного кодирования: 4 фронта за один цикл (фазы A и B имеют сдвиг 90°). +- `pulses_per_rev` — количество импульсов на полный оборот энкодера, задаётся в конфигурации. +- `60.0` — перевод оборотов в секунду в обороты в минуту. + +Результат берётся по модулю (`fabsf()`) — направление вращения игнорируется, возвращается абсолютное значение RPM. + +### Конфигурация PCNT + +Модуль PCNT настраивается в режиме квадратурного декодера: + +- Канал A: фронт по фазе A вызывает увеличение (`INCREASE`) или уменьшение (`DECREASE`) счётчика в зависимости от уровня фазы B. +- Канал A: уровень фазы A удерживает счёт (`KEEP`) или инвертирует направление (`INVERSE`). +- Канал B: фронт по фазе B вызывает увеличение или уменьшение счётчика в зависимости от уровня фазы A (обратное каналу A). +- Канал B: уровень фазы B удерживает или инвертирует направление (обратное каналу A). +- Фильтр глитчей: 1000 нс. +- Точки наблюдения: ±32767 для обнаружения переполнения. +- Накопление: включено (`accum_count = true`). + +### Процесс деинициализации + +При вызове `zh_tachometer_deinit()` ресурсы освобождаются в строгом порядке: + +1. Остановка ESP-Timer (`esp_timer_stop`). +2. Удаление ESP-Timer (`esp_timer_delete`). +3. Остановка PCNT (`pcnt_unit_stop`). +4. Отключение PCNT (`pcnt_unit_disable`). +5. Удаление точек наблюдения: +32767, затем -32767. +6. Удаление каналов A и B (`pcnt_del_channel`). +7. Удаление модуля PCNT (`pcnt_del_unit`). +8. Освобождение памяти объекта (`heap_caps_free`). +9. Обнуление указателя на объект. + +Все шаги используют `ZH_ERROR_CHECK_CONT` — ошибка логируется, но процесс деинициализации продолжается до полного освобождения ресурсов. + +## Примеры использования + +### Базовое использование + +```c +#include "zh_tachometer.h" + +zh_tachometer_handle_t *tachometer_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_tachometer", ESP_LOG_ERROR); + + zh_tachometer_init_config_t config = ZH_TACHOMETER_INIT_CONFIG_DEFAULT(); + config.a_gpio_number = GPIO_NUM_26; + config.b_gpio_number = GPIO_NUM_27; + config.encoder_pulses = 3600; + + esp_err_t ret = zh_tachometer_init(&config, &tachometer_handle); + if (ret != ESP_OK) + { + printf("Tachometer initialization error: %s\n", esp_err_to_name(ret)); + return; + } + + for (;;) + { + uint16_t value = 0; + ret = zh_tachometer_get(&tachometer_handle, &value); + if (ret == ESP_OK) + { + printf("Current RPM: %u\n", value); + } + vTaskDelay(pdMS_TO_TICKS(100)); + } + + zh_tachometer_deinit(&tachometer_handle); +} +``` + +### Настройка с отключёнными подтягивающими резисторами + +```c +#include "zh_tachometer.h" + +zh_tachometer_handle_t *tachometer_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_tachometer", ESP_LOG_ERROR); + + zh_tachometer_init_config_t config = ZH_TACHOMETER_INIT_CONFIG_DEFAULT(); + config.a_gpio_number = GPIO_NUM_12; + config.b_gpio_number = GPIO_NUM_13; + config.pullup = false; + config.encoder_pulses = 1800; + + esp_err_t ret = zh_tachometer_init(&config, &tachometer_handle); + if (ret != ESP_OK) + { + printf("Tachometer initialization error: %s\n", esp_err_to_name(ret)); + return; + } + + uint16_t rpm_value = 0; + ret = zh_tachometer_get(&tachometer_handle, &rpm_value); + if (ret == ESP_OK) + { + printf("RPM value: %u\n", rpm_value); + } + + zh_tachometer_deinit(&tachometer_handle); +} +``` + +## Логирование + +Компонент использует ESP-IDF логирование с тегом `"zh_tachometer"`. + +```c +esp_log_level_set("zh_tachometer", ESP_LOG_ERROR); +``` + +Доступные уровни: `ESP_LOG_ERROR`, `ESP_LOG_INFO`. Макрос `ZH_LOGI` выводит информационные сообщения о начале и завершении операций. Макрос `ZH_LOGE` выводит сообщения об ошибках с указанием файла, строки и имени кода ошибки. + +## Ошибки + +| Код | Описание | +| ----- | ---------- | +| `ESP_OK` | Успешное выполнение | +| `ESP_ERR_INVALID_ARG` | Неверный аргумент: `config` или `handle` равен NULL, `encoder_pulses` равен нулю, номера GPIO недействительны или совпадают, `*handle` или `value` равен NULL | +| `ESP_ERR_INVALID_STATE` | Объект тахометра уже инициализирован (`*handle` не равен NULL) | +| `ESP_ERR_NO_MEM` | Не удалось выделить память для объекта тахометра | +| `ESP_FAIL` | Ошибка инициализации или конфигурации PCNT, ошибка создания или запуска ESP-Timer | + +## Ограничения + +1. **Переполнение PCNT счётчика** — модуль PCNT использует точки наблюдения на ±32767. При высоких значениях RPM накопленный счётчик может переполниться. Необходимо убедиться, что комбинация количества импульсов на оборот и ожидаемого диапазона RPM остаётся в безопасных пределах. + +2. **Абсолютное значение RPM** — направление вращения игнорируется. Компонент возвращает только модуль скорости, без информации о направлении. + +3. **16-битное значение RPM** — возвращаемое значение имеет тип `uint16_t`, максимальное значение — 65535. При очень высоких скоростях вращения значение может не поместиться. + +4. **Один GPIO на фазу** — каждая фаза энкодера (A и B) должна быть назначена на отдельный GPIO. Назначение одинакового номера GPIO на обе фазы вернёт ошибку `ESP_ERR_INVALID_ARG`. + +## Требования для сборки + +- ESP-IDF (фреймворк для ESP32) +- FreeRTOS (входит в состав ESP-IDF) +- Компонент ESP-IDF `pulse_cnt` (драйвер PCNT) +- Компонент ESP-IDF `esp_timer` (ESP-Timer) +- Компонент ESP-IDF `driver` (GPIO driver) + +## Установка + +```bash +cd ваш_проект/components +git clone https://github.com/aZholtikov/zh_tachometer +``` + +```c +#include "zh_tachometer.h" +```