Knob¶

[English]

Knob is the component that provides the software PCNT, it can be used on chips(esp32c2, esp32c3) that do not have PCNT hardware capabilities. By using knob you can quickly use a physical encoder, such as the EC11 encoder.

Applicable Scenarios¶

This is suitable for low-speed rotary knob counting scenarios where the pulse rate is less than 30 pulses per second, such as the EC11 encoder. It is suitable for scenarios where 100% accuracy of pulse counting is not required.

Note

For precise or fast pulse counting, please use the hardware PCNT function. The hardware PCNT is supported by ESP32, ESP32-C6, ESP32-H2, ESP32-S2, ESP32-S3 chips.

Knob Event¶

Each knob has the 5 events in the following table.

Events	Trigger Conditions
KNOB_LEFT	Left
KNOB_RIGHT	Right
KNOB_H_LIM	Count reaches maximum limit
KNOB_L_LIM	Count reaches the minimum limit
KNOB_ZERO	Count back to 0

Each knob can have Callback usage.

Callbacks: Each event of a knob can have a callback function registered for it, and the callback function will be called when the event is generated. This approach is efficient and real-time, and no events are lost.

Attention

No blocking operations such as TaskDelay in the callback function

Configuration items¶

KNOB_PERIOD_TIME_MS : Scan cycle
KNOB_DEBOUNCE_TICKS : Number of de-shaking
KNOB_HIGH_LIMIT : The highest number that can be counted by the knob
KNOB_LOW_LIMIT : The lowest number that can be counted by the knob

Application Examples¶

Create Knob¶

// 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");
}

Register callback function¶

static void _knob_left_cb(void *arg, void *data)
{
    ESP_LOGI(TAG, "KONB: KONB_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);

API Reference¶

Header File¶

knob/iot_knob.h

Functions¶

knob_handle_t iot_knob_create(const knob_config_t *config)¶

create a knob

Return

A handle to the created knob

Parameters

config: pointer of knob configuration

esp_err_t iot_knob_delete(knob_handle_t knob_handle)¶

Delete a knob.

Return

ESP_OK Success
ESP_FAIL Failure

Parameters

knob_handle: A knob handle to delete

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.

Return

ESP_OK Success
ESP_FAIL Failure

Parameters

knob_handle: A knob handle to register
event: Knob event
cb: Callback function
usr_data: user data

esp_err_t iot_knob_unregister_cb(knob_handle_t knob_handle, knob_event_t event)¶

Unregister the knob event callback function.

Return

ESP_OK Success
ESP_FAIL Failure

Parameters

knob_handle: A knob handle to register
event: Knob event

knob_event_t iot_knob_get_event(knob_handle_t knob_handle)¶

Get knob event.

Return

knob_event_t Knob event

Parameters

knob_handle: A knob handle to register

int iot_knob_get_count_value(knob_handle_t knob_handle)¶

Get knob count value.

Return

int count_value

Parameters

knob_handle: A knob handle to register

esp_err_t iot_knob_clear_count_value(knob_handle_t knob_handle)¶

Clear knob cout value to zero.

Return

ESP_OK Success
ESP_FAIL Failure

Parameters

knob_handle: A knob handle to register

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

Type Definitions¶

typedef void (*knob_cb_t)(void *, void *)¶

typedef void *knob_handle_t¶

Enumerations¶

enum knob_event_t¶

Knob events.

Values:

KNOB_LEFT = 0¶: EVENT: Rotate to the left

KNOB_RIGHT¶: EVENT: Rotate to the right

KNOB_H_LIM¶: EVENT: Count reaches maximum limit

KNOB_L_LIM¶: EVENT: Count reaches the minimum limit

KNOB_ZERO¶: EVENT: Count back to 0

KNOB_EVENT_MAX¶: EVENT: Number of events

Provide feedback about this document