From a5bea1e3b91fc0e02c041c9d6831c02a0ed57daa Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Tue, 3 Nov 2026 13:32:44 +0300 Subject: [PATCH] doc: added wiki --- wiki_ru.md | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 wiki_ru.md diff --git a/wiki_ru.md b/wiki_ru.md new file mode 100644 index 0000000..1ee6de4 --- /dev/null +++ b/wiki_ru.md @@ -0,0 +1,294 @@ +# Описание компонента zh_inclinometer + +## Общие сведения + +**zh_inclinometer** — это компонент ESP-IDF для ESP32, реализующий измерение углового положения с помощью квадратурного оптического энкодера. Компонент использует аппаратный модуль счётчика импульсов (PCNT) из ESP-IDF для подсчёта импульсов с двух каналов энкодера и преобразования их в угол в градусах. + +Компонент предоставляет простой API для инициализации, получения текущего угла и сброса счётчика. Поддерживается настройка направлений вращения, режима подтяжки GPIO и разрешения энкодера в импульсах на оборот. + +## Основные возможности + +1. **Поддержка квадратурного энкодера** — аппаратное декодирование каналов A и B через PCNT. +2. **Настраиваемые GPIO-пины** — задание любых свободных GPIO для каналов A и B. +3. **Настраиваемая подтяжка** — включение или отключение внутренних подтягивающих резисторов. +4. **Настраиваемое направление вращения** — положительный угол для вращения по часовой или против часовой стрелки. +5. **Настраиваемое разрешение** — указание количества импульсов на полный оборот энкодера. +6. **Фильтр глитчей** — аппаратное отсечение помех длительностью менее 1000 нс. +7. **Поддержка нескольких экземпляров** — одновременная работа с несколькими энкодерами. + +## Внутреннее устройство + +### Структура `zh_inclinometer_handle_t` + +Публичный тип — непрозрачный указатель на внутреннюю структуру: + +| Поле | Тип | Описание | +| ------ | ----- | ---------- | +| `pcnt_unit_handle` | `pcnt_unit_handle_t` | Указатель на экземпляр PCNT для данного энкодера | +| `pcnt_channel_a_handle` | `pcnt_channel_handle_t` | Указатель на канал A PCNT (подключён к пину энкодера A) | +| `pcnt_channel_b_handle` | `pcnt_channel_handle_t` | Указатель на канал B PCNT (подключён к пину энкодера B) | +| `degrees_per_pulse` | `float` | Угол в градусах, приходящийся на один подсчитанный импульс | +| `rotation` | `bool` | Флаг направления вращения: `true` — положительный угол при вращении по часовой стрелке | + +### Структура конфигурации `zh_inclinometer_init_config_t` + +Структура передаётся в функцию `zh_inclinometer_init()` при создании экземпляра: + +| Поле | Тип | Описание | +| ------ | ----- | ---------- | +| `a_gpio_number` | `gpio_num_t` | Номер GPIO для канала A энкодера | +| `b_gpio_number` | `gpio_num_t` | Номер GPIO для канала B энкодера | +| `pullup` | `bool` | Включить подтягивающий резистор (true) или отключить (false) | +| `rotation` | `bool` | Направление: true — положительный угол при вращении по часовой стрелке | +| `encoder_pulses` | `uint16_t` | Количество импульсов энкодера на один полный оборот | + +### Управление памятью + +Экземпляр inclinometer выделяется в функции `zh_inclinometer_init()` через `heap_caps_calloc(1, sizeof(zh_inclinometer_handle_t), MALLOC_CAP_8BIT)` и полностью очищается в `zh_inclinometer_deinit()` через `heap_caps_free()`. Ресурсы PCNT (unit и каналы) освобождаются до освобождения самого handle. + +## API (интерфейс) + +### Инициализация и освобождение + +| Функция | Описание | +| --------- | ---------- | +| `zh_inclinometer_init()` | Выделяет память, проверяет конфигурацию, инициализирует PCNT с двумя каналами для квадратурного декодирования и запускает счётчик. | +| `zh_inclinometer_deinit()` | Останавливает и отключает PCNT, удаляет каналы и unit, освобождает память handle и устанавливает его в NULL. | +| `zh_inclinometer_reset()` | Очищает счётчик PCNT, устанавливая текущую позицию в 0 градусов. | + +### Получение данных + +| Функция | Описание | +|---------|----------| +| `zh_inclinometer_get()` | Считывает текущее значение счётчика PCNT и преобразует его в угол в градусах с учётом направления вращения. | + +## Алгоритмы + +### Расчёт угла + +При инициализации вычисляется коэффициент градусов на импульс: + +```text +degrees_per_pulse = 360.0 / (4 * encoder_pulses) +``` + +Множитель 4 обусловлен квадратурным декодированием: один полный шаг квадратурного энкодера содержит 4 изменения сигнала (по фронту и спаду на обоих каналах A и B), что увеличивает эффективное разрешение в 4 раза. + +Текущий угол вычисляется при каждом вызове `zh_inclinometer_get()`: + +```text +angle = pcnt_count * degrees_per_pulse +``` + +Если `rotation == false`, угол инвертируется: + +```text +angle = -angle +``` + +Отрицательный ноль приводится к положительному нулю (`0.0`). + +### Декодирование квадратурного сигнала + +Инициализация PCNT настраивает два канала для двунаправленного подсчёта. Каждый канал реагирует на фронты своего сигнала (edge action), а направление счёта определяется текущим уровнем второго сигнала (level action): + +| Канал | Edge action | Level action | +|-------|-------------|--------------| +| `A` (edge — пин A, level — пин B) | фронт — `DECREASE`, спад — `INCREASE` | `B == 1` — `KEEP`, `B == 0` — `INVERSE` | +| `B` (edge — пин B, level — пин A) | фронт — `INCREASE`, спад — `DECREASE` | `A == 1` — `KEEP`, `A == 0` — `INVERSE` | + +`INVERSE` меняет действие счётчика на противоположное, поэтому при одном направлении вращения все четыре перехода сигналов дают `+1`, при противоположном — `-1`. Так реализуется четырёхкратное увеличение разрешения относительно шага энкодера. + +Знак результата зависит от физически подключённой последовательности каналов. Параметр `rotation` компенсирует эту разницу: при `rotation == false` знак угла инвертируется при чтении, а конфигурация PCNT остаётся неизменной. + +### Фильтр глитчей + +Встроенный аппаратный фильтр отбрасывает импульсы длительностью менее 1000 нс (1 мкс). Фильтр настраивается функцией `pcnt_unit_set_glitch_filter()` и работает на уровне периферии, не создавая нагрузки на процессор. + +### Очистка при ошибках + +При инициализации PCNT реализована каскадная очистка ресурсов: при ошибке создания или настройки каждого последующего ресурса предыдущие удаляются в обратном порядке. Это гарантирует отсутствие утечек ресурсов при неудачной инициализации. + +## Примеры использования + +### Базовое чтение угла + +Пример чтения текущего угла энкодера с периодом 100 мс. + +```c +#include "zh_inclinometer.h" + +zh_inclinometer_handle_t *inclinometer_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_inclinometer", ESP_LOG_ERROR); + + zh_inclinometer_init_config_t config = ZH_INCLINOMETER_INIT_CONFIG_DEFAULT(); + config.a_gpio_number = GPIO_NUM_26; + config.b_gpio_number = GPIO_NUM_27; + config.encoder_pulses = 3600; + config.pullup = true; + config.rotation = true; + + esp_err_t ret = zh_inclinometer_init(&config, &inclinometer_handle); + if (ret != ESP_OK) + { + printf("Inclinometer initialization error: %s\n", esp_err_to_name(ret)); + return; + } + + for (int i = 0; i < 100; i++) + { + float angle = 0; + ret = zh_inclinometer_get(&inclinometer_handle, &angle); + if (ret == ESP_OK) + { + printf("Angle: %.2f deg\n", angle); + } + vTaskDelay(100 / portTICK_PERIOD_MS); + } + + zh_inclinometer_deinit(&inclinometer_handle); +} +``` + +### Сброс позиции и работа с разными конфигурациями + +Пример инициализации с отключённой подтяжкой, обратным направлением и периодическим сбросом позиции. + +```c +#include "zh_inclinometer.h" + +zh_inclinometer_handle_t *inclinometer_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_inclinometer", ESP_LOG_ERROR); + + zh_inclinometer_init_config_t config = ZH_INCLINOMETER_INIT_CONFIG_DEFAULT(); + config.a_gpio_number = GPIO_NUM_26; + config.b_gpio_number = GPIO_NUM_27; + config.encoder_pulses = 1800; + config.pullup = false; + config.rotation = false; + + esp_err_t ret = zh_inclinometer_init(&config, &inclinometer_handle); + if (ret != ESP_OK) + { + printf("Initialization error: %s\n", esp_err_to_name(ret)); + return; + } + + for (int i = 0; i < 10; i++) + { + float angle = 0; + ret = zh_inclinometer_get(&inclinometer_handle, &angle); + if (ret == ESP_OK) + { + printf("Angle before reset: %.2f deg\n", angle); + } + + ret = zh_inclinometer_reset(&inclinometer_handle); + if (ret == ESP_OK) + { + printf("Position reset to zero.\n"); + } + + vTaskDelay(1000 / portTICK_PERIOD_MS); + } + + zh_inclinometer_deinit(&inclinometer_handle); +} +``` + +### Ограничение на количество импульсов + +Пример с максимальным разрешением (encoder_pulses = 8191) и демонстрация обработки ошибок. + +```c +#include "zh_inclinometer.h" + +zh_inclinometer_handle_t *inclinometer_handle = NULL; + +void app_main(void) +{ + esp_log_level_set("zh_inclinometer", ESP_LOG_ERROR); + + zh_inclinometer_init_config_t config = ZH_INCLINOMETER_INIT_CONFIG_DEFAULT(); + config.a_gpio_number = GPIO_NUM_26; + config.b_gpio_number = GPIO_NUM_27; + config.encoder_pulses = 8191; + config.pullup = true; + config.rotation = true; + + esp_err_t ret = zh_inclinometer_init(&config, &inclinometer_handle); + if (ret != ESP_OK) + { + printf("Inclinometer initialization error: %s\n", esp_err_to_name(ret)); + return; + } + + float angle = 0; + ret = zh_inclinometer_get(&inclinometer_handle, &angle); + if (ret == ESP_OK) + { + printf("Current angle: %.2f deg\n", angle); + } + + ret = zh_inclinometer_reset(&inclinometer_handle); + if (ret == ESP_OK) + { + printf("Position reset.\n"); + } + + zh_inclinometer_deinit(&inclinometer_handle); +} +``` + +## Логирование + +Компонент использует ESP-IDF логирование с тегом `"zh_inclinometer"`. Уровень логирования настраивается через `esp_log_level_set()`: + +```c +esp_log_level_set("zh_inclinometer", ESP_LOG_ERROR); +``` + +Макросы логирования определены внутри компонента и не требуют отдельного подключения. Доступные уровни: `ESP_LOG_ERROR` и `ESP_LOGI`. + +## Ошибки + +| Код | Описание | +| ----- | ---------- | +| `ESP_OK` | Успешное выполнение операции | +| `ESP_ERR_INVALID_ARG` | Неверный аргумент: NULL-указатель, невалидный GPIO (>= GPIO_NUM_MAX), одинаковые пины A и B, `encoder_pulses` равно 0 | +| `ESP_ERR_INVALID_STATE` | Повторная инициализация: `*handle` уже не равен NULL | +| `ESP_ERR_NO_MEM` | Не удалось выделить память для handle | +| `ESP_FAIL` | Ошибка инициализации PCNT, GPIO, фильтра глитчей или других ресурсов | + +## Ограничения + +1. **Максимум 8191 импульс на оборот** — ограничено диапазоном счётчика PCNT (±32767), так как внутренний счётчик умножается на 4 при квадратурном декодировании (`4 * encoder_pulses <= 32767`). +2. **Сброс счётчика при достижении пределов** — аппаратный PCNT автоматически обнуляет счётчик при достижении high_limit или low_limit. Угол «зацикливается» в диапазоне приблизительно от -360° до 360°. При вращении за пределы одного оборота счётчик сбрасывается и угол начинается заново. +3. **Не потокобезопасен** — компонент не использует мьютексы или другие механизмы синхронизации. Одновременный доступ к handle из нескольких задач не поддерживается. +4. **Глитч-фильтр зафиксирован на 1000 нс** — значение не выносится в конфигурацию и не может быть изменено пользователем. +5. **GPIO_NUM_MAX не является допустимым значением** — оба GPIO должны быть явно заданы перед инициализацией. Значение `GPIO_NUM_MAX` в `ZH_INCLINOMETER_INIT_CONFIG_DEFAULT()` служит маркером «не задано». + +## Требования для сборки + +- ESP-IDF версии 5.0 или выше +- Компонент `driver` (ESP-IDF < 6) или `esp_driver_gpio` + `esp_driver_pcnt` (ESP-IDF 6) +- FreeRTOS (входит в состав ESP-IDF) +- Два свободных GPIO-пина для подключения энкодера +- Модуль PCNT периферии ESP32 (доступен на всех моделях ESP32) + +## Установка + +```bash +cd ваш_проект/components +git clone https://github.com/aZholtikov/zh_inclinometer +``` + +```c +#include "zh_inclinometer.h" +```