242 lines
16 KiB
Markdown
242 lines
16 KiB
Markdown
# Описание компонента 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"
|
||
```
|