include/zh_encoder.h - main - esp_components/zh_encoder

include/zh_encoder.h
207 строк8 KB
Alexey Zholtikov
refactor: refactored by pvs-studio
28 янв 2026, 19:32
28 янв 2026, 19:3236e200b
/**
 * @file zh_encoder.h
 */

#pragma once

#include "esp_log.h"
#include "driver/gpio.h"
#include "driver/pulse_cnt.h"
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_event.h"

/**
 * @brief Encoder initial default values.
 */
#define ZH_ENCODER_INIT_CONFIG_DEFAULT()        \
    {                                           \
        .task_priority = 1,                     \
        .stack_size = configMINIMAL_STACK_SIZE, \
        .queue_size = 1,                        \
        .a_gpio_number = GPIO_NUM_MAX,          \
        .b_gpio_number = GPIO_NUM_MAX,          \
        .s_gpio_number = GPIO_NUM_MAX,          \
        .s_gpio_debounce_time = 10,             \
        .pullup = true,                         \
        .encoder_min_value = -10,               \
        .encoder_max_value = 10,                \
        .encoder_step = 1,                      \
        .encoder_number = 0}

#ifdef __cplusplus
extern "C"
{
#endif

    extern TaskHandle_t zh_encoder; /*!< Encoder Task Handle. */

    /**
     * @brief Structure for initial initialization of encoder.
     */
    typedef struct
    {
        float encoder_step;            /*!< Encoder step. @note Must be greater than 0. */
        float encoder_min_value;       /*!< Encoder min value. @note Must be less than encoder_max_value. */
        float encoder_max_value;       /*!< Encoder max value. @note Must be greater than encoder_min_value. */
        uint8_t task_priority;         /*!< Task priority for the encoder isr processing. @note Minimum value is 1. */
        uint8_t queue_size;            /*!< Queue size for task for the encoder processing. @note Minimum value is 1. */
        uint8_t a_gpio_number;         /*!< Encoder A GPIO number. */
        uint8_t b_gpio_number;         /*!< Encoder B GPIO number. */
        uint8_t s_gpio_number;         /*!< Encoder button GPIO number. */
        bool pullup;                   /*!< Pullup GPIO enable/disable. */
        uint16_t s_gpio_debounce_time; /*!< Encoder button debounce_time. @note In microseconds. */
        uint8_t encoder_number;        /*!< Unique encoder number. @note Must be greater than 0. */
        uint16_t stack_size;           /*!< Stack size for task for the encoder isr processing processing. @note The minimum size is configMINIMAL_STACK_SIZE. */
    } zh_encoder_init_config_t;

    /**
     * @brief Encoder handle.
     */
    typedef struct
    {
        bool s_gpio_status;                          /*!< Encoder button status. */
        bool is_initialized;                         /*!< Encoder initialization flag. */
        uint8_t encoder_number;                      /*!< Encoder unique number. */
        uint8_t s_gpio_number;                       /*!< Encoder button GPIO number. */
        uint16_t s_gpio_debounce_time;               /*!< Encoder button debounce_time. */
        uint64_t s_gpio_prev_time;                   /*!< Encoder button prev interrupt time. */
        float encoder_step;                          /*!< Encoder step. */
        float encoder_position;                      /*!< Encoder position. */
        float encoder_min_value;                     /*!< Encoder min value. */
        float encoder_max_value;                     /*!< Encoder max value. */
        pcnt_unit_handle_t pcnt_unit_handle;         /*!< Encoder unique pcnt unit handle. */
        pcnt_channel_handle_t pcnt_channel_a_handle; /*!< Encoder unique pcnt channel handle. */
        pcnt_channel_handle_t pcnt_channel_b_handle; /*!< Encoder unique pcnt channel handle. */

    } zh_encoder_handle_t;

    /**
     * @brief Structure for error statistics storage.
     */
    typedef struct
    {
        uint32_t event_post_error;     /*!< Number of event post error. */
        uint32_t queue_overflow_error; /*!< Number of queue overflow error. */
        uint32_t min_stack_size;       /*!< Minimum free stack size. */
    } zh_encoder_stats_t;

    /**
     * @brief Enumeration of encoder event ID.
     */
    typedef enum
    {
        ZH_BUTTON_EVENT, /*!< Button event. */
        ZH_ENCODER_EVENT /*!< Encoder event. */
    } zh_encoder_event_id_t;

    ESP_EVENT_DECLARE_BASE(ZH_ENCODER);

    /**
     * @brief Structure for sending data to the event handler when cause encoder interrupt.
     *
     * @note Should be used with ZH_ENCODER event base and ZH_ENCODER_EVENT event ID.
     */
    typedef struct
    {
        float encoder_position; /*!< Encoder current position. */
        uint8_t encoder_number; /*!< Encoder unique number. */
    } zh_encoder_event_on_isr_t;

    /**
     * @brief Structure for sending data to the event handler when cause encoder button interrupt.
     *
     * @note Should be used with ZH_ENCODER event base and ZH_BUTTON_EVENT event ID.
     */
    typedef struct
    {
        uint8_t encoder_number; /*!< Encoder unique number. */
        bool button_status;     /*!< Encoder button status. */
    } zh_encoder_button_event_on_isr_t;

    /**
     * @brief Initialize encoder.
     *
     * @note The encoder will be set to the position (encoder_min_value + encoder_max_value)/2.
     *
     * @param[in] config Pointer to encoder initialized configuration structure. Can point to a temporary variable.
     * @param[out] handle Pointer to unique encoder handle.
     *
     * @note Before initialize the encoder recommend initialize zh_encoder_init_config_t structure with default values.
     *
     * @code zh_encoder_init_config_t config = ZH_ENCODER_INIT_CONFIG_DEFAULT() @endcode
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_init(const zh_encoder_init_config_t *config, zh_encoder_handle_t *handle);

    /**
     * @brief Deinitialize encoder.
     *
     * @param[in, out] handle Pointer to unique encoder handle.
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_deinit(zh_encoder_handle_t *handle);

    /**
     * @brief Reinitialize encoder (change min, max and step values).
     *
     * @note The encoder will be set to the position (encoder_min_value + encoder_max_value)/2.
     *
     * @param[in, out] handle Pointer to unique encoder handle.
     * @param[in] min Encoder min value. @note Must be less than encoder_max_value.
     * @param[in] max Encoder max value. @note Must be greater than encoder_min_value.
     * @param[in] step Encoder step. @note Must be greater than 0.
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_reinit(zh_encoder_handle_t *handle, float min, float max, float step);

    /**
     * @brief Set encoder position.
     *
     * @param[in, out] handle Pointer to unique encoder handle.
     * @param[in] position Encoder position (must be between encoder_min_value and encoder_max_value).
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_set(zh_encoder_handle_t *handle, float position);

    /**
     * @brief Get encoder position.
     *
     * @param[in] handle Pointer to unique encoder handle.
     * @param[out] position Encoder position.
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_get(const zh_encoder_handle_t *handle, float *position);

    /**
     * @brief Reset encoder position.
     *
     * @note The encoder will be set to the position (encoder_min_value + encoder_max_value)/2.
     *
     * @param[in, out] handle Pointer to unique encoder handle.
     *
     * @return ESP_OK if success or an error code otherwise.
     */
    esp_err_t zh_encoder_reset(zh_encoder_handle_t *handle);

    /**
     * @brief Get error statistics.
     *
     * @return Pointer to the statistics structure.
     */
    const zh_encoder_stats_t *zh_encoder_get_stats(void);

    /**
     * @brief Reset error statistics.
     */
    void zh_encoder_reset_stats(void);

#ifdef __cplusplus
}
#endif