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.

Hardware Design

The reference design for the rotary encoder is shown below:

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, "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);

Low Power Support

In light_sleep mode, the esp_timer wakes up the CPU, resulting in high power consumption. The Knob component offers a low power solution through GPIO level wake-up.

Required Configuration:

Enable the enable_power_save option in knob_config_t.

Power Consumption Comparison:

Without low power mode, one rotation within 250ms
With low power mode, one rotation within 250ms
With low power mode, ten rotations within 4.5s

The knob is responsive and consumes less power in low power mode.

Enable and Disable

The component supports enabling and disabling at any time.

// Stop knob
iot_knob_stop();
// Resume knob
iot_knob_resume();

API Reference

Header File

components/knob/include/iot_knob.h

Functions

knob_handle_t iot_knob_create(const knob_config_t *config)

create a knob

Parameters: config – pointer of knob configuration
Returns: A handle to the created knob

esp_err_t iot_knob_delete(knob_handle_t knob_handle)

Delete a knob.

Parameters

knob_handle – A knob handle to delete

Returns

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.

Parameters

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

Returns

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.

Parameters

knob_handle – A knob handle to register
event – Knob event

Returns

ESP_OK Success
ESP_FAIL Failure

knob_event_t iot_knob_get_event(knob_handle_t knob_handle)

Get knob event.

Parameters: knob_handle – A knob handle to register
Returns: knob_event_t Knob event

int iot_knob_get_count_value(knob_handle_t knob_handle)

Get knob count value.

Parameters: knob_handle – A knob handle to register
Returns: int count_value

esp_err_t iot_knob_clear_count_value(knob_handle_t knob_handle)

Clear knob cout value to zero.

Parameters

knob_handle – A knob handle to register

Returns

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.

Returns

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.

Returns

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

Provide feedback about this document