旋钮
Knob 是提供软件 PCNT 的组件，可以用在没有 PCNT 硬件功能的芯片（esp32c2, esp32c3）上。使用 Knob 可以快速适配物理编码器，如 EC11 编码器。
适用的场景
适用于每秒脉冲数小于 30 个的低速旋钮计数场景。例如 EC11 编码器。 适用于对脉冲数不要求 100% 准确的场景。
备注
如需精确或快速的脉冲计数，请使用 硬件 PCNT 功能 。硬件 PCNT 支持的芯片 ESP32, ESP32-C6, ESP32-H2, ESP32-S2, ESP32-S3。
硬件设计
旋转编码器的参考设计如下：
旋钮事件
每个旋钮拥有下表的 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.
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
-
enumerator KNOB_LEFT