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

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