旋钮

[English]

Knob 是提供软件 PCNT 的组件,可以用在没有 PCNT 硬件功能的芯片(esp32c2, esp32c3)上。使用 Knob 可以快速适配物理编码器,如 EC11 编码器。

适用的场景

适用于每秒脉冲数小于 30 个的低速旋钮计数场景。例如 EC11 编码器。 适用于对脉冲数不要求 100% 准确的场景。

备注

如需精确或快速的脉冲计数,请使用 硬件 PCNT 功能 。硬件 PCNT 支持的芯片 ESP32, ESP32-C6, ESP32-H2, ESP32-S2, ESP32-S3。

硬件设计

旋转编码器的参考设计如下:

../_images/knob_hardware.png

旋钮事件

每个旋钮拥有下表的 5 个事件:

事件

触发条件

KNOB_LEFT

左旋

KNOB_RIGHT

右旋

KNOB_H_LIM

计数达到最高限制

KNOB_L_LIM

计数达到最低限制

KNOB_ZERO

计数变成零

每个旋钮都可以有 回调 的使用方式:

  • 回调:一个旋钮的每个事件都可以为其注册一个回调函数,产生事件时回调函数将会被调用。这种方式的效率和实时性高,不会丢失事件。

注意

回调函数中不能有 TaskDelay 等阻塞的操作

配置项

  • KNOB_PERIOD_TIME_MS : 扫描周期

  • KNOB_DEBOUNCE_TICKS : 消抖次数

  • KNOB_HIGH_LIMIT : 旋钮所能计数的最高数字

  • KNOB_LOW_LIMIT : 旋钮所能计数的最低数字

应用示例

创建旋钮

// create knob
knob_config_t cfg = {
    .default_direction =0,
    .gpio_encoder_a = GPIO_KNOB_A,
    .gpio_encoder_b = GPIO_KNOB_B,
};
s_knob = iot_knob_create(&cfg);
if(NULL == s_knob) {
    ESP_LOGE(TAG, "knob create failed");
}

注册回调函数

static void _knob_left_cb(void *arg, void *data)
{
    ESP_LOGI(TAG, "KNOB: KNOB_LEFT,count_value:%"PRId32"",iot_knob_get_count_value((button_handle_t)arg));
}
iot_knob_register_cb(s_knob, KNOB_LEFT, _knob_left_cb, NULL);

低功耗支持

在 light_sleep 模式下,esp_timer 定时器会唤醒 CPU,导致功耗居高不下,Knob 组件提供了通过 GPIO 电平唤醒的低功耗方案。

所需配置:

  • knob_config_t 中打开 enable_power_save 选项

功耗对比:

  • 未开启低功耗模式,在 250ms 内旋转一次

    未开启低功耗模式,一次旋转
  • 开启低功耗模式,在 250ms 内旋转一次

    开启低功耗模式,旋转一次
  • 开启低功耗模式,在 4.5s 内旋转十次

    开启低功耗模式,旋转十次

低功耗模式下的旋钮响应迅速,且功耗更低

开启和关闭

组件支持在任意时刻开启和关闭。

// stop knob
iot_knob_stop();
// resume knob
iot_knob_resume();

API Reference

Header File

Functions

knob_handle_t iot_knob_create(const knob_config_t *config)

create a knob

参数

config – pointer of knob configuration

返回

A handle to the created knob

esp_err_t iot_knob_delete(knob_handle_t knob_handle)

Delete a knob.

参数

knob_handle – A knob handle to delete

返回

  • ESP_OK Success

  • ESP_FAIL Failure

esp_err_t iot_knob_register_cb(knob_handle_t knob_handle, knob_event_t event, knob_cb_t cb, void *usr_data)

Register the knob event callback function.

参数
  • knob_handle – A knob handle to register

  • event – Knob event

  • cb – Callback function

  • usr_data – user data

返回

  • ESP_OK Success

  • ESP_FAIL Failure

esp_err_t iot_knob_unregister_cb(knob_handle_t knob_handle, knob_event_t event)

Unregister the knob event callback function.

参数
  • knob_handle – A knob handle to register

  • event – Knob event

返回

  • ESP_OK Success

  • ESP_FAIL Failure

knob_event_t iot_knob_get_event(knob_handle_t knob_handle)

Get knob event.

参数

knob_handle – A knob handle to register

返回

knob_event_t Knob event

int iot_knob_get_count_value(knob_handle_t knob_handle)

Get knob count value.

参数

knob_handle – A knob handle to register

返回

int count_value

esp_err_t iot_knob_clear_count_value(knob_handle_t knob_handle)

Clear knob cout value to zero.

参数

knob_handle – A knob handle to register

返回

  • ESP_OK Success

  • ESP_FAIL Failure

esp_err_t iot_knob_resume(void)

resume knob timer, if knob timer is stopped. Make sure iot_knob_create() is called before calling this API.

返回

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE timer state is invalid.

esp_err_t iot_knob_stop(void)

stop knob timer, if knob timer is running. Make sure iot_knob_create() is called before calling this API.

返回

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE timer state is invalid

Structures

struct knob_config_t

Knob config.

Public Members

uint8_t default_direction

0:positive increase 1:negative increase

uint8_t gpio_encoder_a

Encoder Pin A

uint8_t gpio_encoder_b

Encoder Pin B

bool enable_power_save

Enable power save mode

Type Definitions

typedef void (*knob_cb_t)(void*, void*)
typedef void *knob_handle_t

Enumerations

enum knob_event_t

Knob events.

Values:

enumerator KNOB_LEFT

EVENT: Rotate to the left

enumerator KNOB_RIGHT

EVENT: Rotate to the right

enumerator KNOB_H_LIM

EVENT: Count reaches maximum limit

enumerator KNOB_L_LIM

EVENT: Count reaches the minimum limit

enumerator KNOB_ZERO

EVENT: Count back to 0

enumerator KNOB_EVENT_MAX

EVENT: Number of events

enumerator KNOB_NONE

EVENT: No event