doc: added wiki

README.md

@@ -12,7 +12,7 @@
 
 ## Using
 
-In an existing project, run the following command to install the components:
+In an existing project, run the following command to install the component:
 
 ```bash
 cd ../your_project/components
@@ -25,7 +25,9 @@ In the application, add the component:
 #include "zh_tachometer.h"
 ```
 
-## Example
+## Examples
+
+### Basic Example
 
 ```c
 #include "zh_tachometer.h"
@@ -39,13 +41,22 @@ void app_main(void)
     config.a_gpio_number = GPIO_NUM_26;
     config.b_gpio_number = GPIO_NUM_27;
     config.encoder_pulses = 3600;
-    zh_tachometer_init(&config, &tachometer_handle);
+    esp_err_t ret = zh_tachometer_init(&config, &tachometer_handle);
+    if (ret != ESP_OK)
+    {
+        printf("Tachometer initialization error\n");
+        return;
+    }
     for (;;)
     {
         uint16_t value = 0;
-        zh_tachometer_get(&tachometer_handle, &value);
+        ret = zh_tachometer_get(&tachometer_handle, &value);
-        printf("Tachometer value is %d rpm.\n", value);
+        if (ret == ESP_OK)
+        {
+            printf("Tachometer value is %u rpm.\n", value);
+        }
         vTaskDelay(100 / portTICK_PERIOD_MS);
     }
+    zh_tachometer_deinit(&tachometer_handle);
 }
 ```

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"
+```